playwrite/docs/MATERIAL_VALIDATION_REFACTOR.md

# 物料校验功能重构实现总结

## 实现概述

本文档总结了物料校验功能的重构实现，包括新增的 DAO、扩展的校验逻辑和重构的 UI 界面。

## 实现的文件

### 1. 新建文件

#### `db/materials_to_be_deleted_records_dao.py`
新增的 DAO 类，用于操作 `MaterialsToBeDeleted` 表（按 MaterialCode 精确匹配）。

**主要功能：**
- `upsert_material()` - 使用 MERGE 语句插入或更新单条记录
- `upsert_batch()` - 批量插入或更新记录
- `get_all_material_codes()` - 获取所有 MaterialCode（返回 Set 用于快速查找）
- `get_all_records()` - 获取所有记录
- `get_record_by_material_code()` - 按 MaterialCode 查询单条记录
- `get_materials_by_manager()` - 按负责人查询
- `delete_by_material_code()` - 删除指定记录
- `delete_by_manager()` - 删除指定负责人的所有记录
- `delete_by_material_codes()` - 批量删除
- `material_exists()` - 检查 MaterialCode 是否存在
- `count_all()` - 统计记录数
- `count_by_manager()` - 统计指定负责人的记录数
- `get_statistics()` - 获取综合统计信息

**关键特性：**
- 使用 SQL Server MERGE 语句实现原子性的 upsert 操作
- 自动记录 CreateTime 和 UpdateTime
- 参数验证和错误处理
- 批量操作支持

### 2. 修改文件

#### `utils/material_status_validator.py`
扩展了物料校验器，新增完整记录模式的支持。

**新增内容：**

1. **数据结构 `MaterialValidationResult`**
   ```python
   @dataclass
   class MaterialValidationResult:
       material_name: str
       material_code: str
       specification: Optional[str] = None
       model: Optional[str] = None
       manager_name: Optional[str] = None
       is_marked_for_deletion: bool = False
       matched_type_keyword: Optional[str] = None
   ```

2. **新增方法 `match_materials_detailed()`**
   - 从 `DiscreteMaterialPlanData` 完整记录进行匹配
   - 同时匹配 `MaterialsTypeToBeDeleted`（按 MaterialName）和 `MaterialsToBeDeleted`（按 MaterialCode）
   - 返回 `MaterialValidationResult` 对象列表

3. **新增方法 `validate_from_database_enhanced()`**
   - 支持全表模式和过滤模式
   - 返回完整的物料记录信息
   - 导出的 Excel 包含：材料名称、材料代码、规格、型号、负责人、已标记删除、匹配的关键词

#### `gui/material_validation_tab.py`
完全重构的 UI 界面，支持新的数据结构和交互方式。

**主要变更：**

1. **新增 `CheckboxTreeview` 组件**
   - 自定义 Treeview，支持 checkbox 列
   - 使用 Unicode 字符 `☐`（未选中）和 `☑`（选中）
   - 支持点击切换、全选/取消全选
   - 自动同步 checkbox 状态

2. **修改表格结构**
   - 旧列：材料名称、匹配的MaterialName、负责人、匹配状态
   - 新列：选择、材料名称、材料代码、规格、型号、负责人

3. **可编辑单元格**
   - 双击"负责人"单元格弹出编辑对话框
   - 使用 `simpledialog.askstring` 进行编辑
   - 实时更新 UI 和日志

4. **新增按钮**
   - 全选按钮：选中所有记录
   - 取消全选按钮：取消选中所有记录
   - 确认删除按钮：将选中记录写入数据库

5. **确认删除流程**
   ```
   1. 验证是否有选中记录
   2. 收集 MaterialCode 和 ManagerName
   3. 验证 ManagerName 不为空
   4. 显示确认对话框
   5. 后台线程执行数据库操作
   6. 完成后更新 UI 状态
   ```

6. **加载结果时设置 checkbox 状态**
   - 从 `MaterialsToBeDeleted` 表获取已标记的 MaterialCode
   - 自动设置对应记录的 checkbox 为选中状态

## 表关系说明

### 两个易混淆的表

| 表名 | 用途 | 匹配规则 | 字段 | DAO 类 |
|------|------|----------|------|--------|
| `MaterialsTypeToBeDeleted` | 物料类型表（已有） | MaterialName 包含匹配 | MaterialName, ManagerName | `MaterialsTypeToBeDeletedDAO` |
| `MaterialsToBeDeleted` | 物料记录表（新建） | MaterialCode 精确匹配 | ID, MaterialCode, ManagerName | `MaterialsToBeDeletedDAO` |

### 数据流程

```
ProductionID (总排号)
  ↓
[productionContractData].[26年压力表合同数据].[生产订单号] (SourceNumber)
  ↓
[dbo].[DiscreteMaterialPlanData].[SourceNumber]
  ↓
MaterialName, MaterialCode, Specification, Model
  ↓
匹配 [dbo].[MaterialsTypeToBeDeleted] (MaterialName 包含匹配) → 负责人
匹配 [dbo].[MaterialsToBeDeleted] (MaterialCode 精确匹配) → 已标记删除
```

## 使用说明

### 1. 数据库全表校验
1. 选择"数据库 - 全表校验"模式
2. 点击"开始校验"
3. 等待校验完成，结果会显示在表格中
4. 已标记删除的记录会自动勾选 checkbox

### 2. ProductionID 过滤校验
1. 选择"数据库 - ProductionID 过滤"模式
2. 选择 ProductionID.txt 文件
3. 点击"开始校验"
4. 等待校验完成

### 3. 编辑负责人
1. 双击表格中的"负责人"单元格
2. 在弹出对话框中输入新的负责人姓名
3. 点击确定保存

### 4. 确认删除
1. 勾选要删除的记录（使用 checkbox）
2. 可以使用"全选"或"取消全选"按钮
3. 点击"确认删除"按钮
4. 确认对话框中查看要删除的记录数
5. 点击"是"执行删除
6. 等待后台操作完成

## 错误处理

### 数据库错误
- 所有 DAO 方法都包含 try-except 错误处理
- 错误信息会打印到控制台
- UI 会显示错误消息框

### 输入验证
- MaterialCode 不能为空
- ManagerName 不能为空（确认删除前验证）
- 负责人姓名长度限制（最大 50 字符）

### 事务处理
- 使用 SQL Server MERGE 语句的原子性
- 要么全部成功，要么全部失败
- 批量操作时逐条处理，记录成功和失败数量

## 测试建议

### 功能测试
1. **全表校验**: 验证所有记录正确显示
2. **过滤校验**: 使用 ProductionID 文件，验证过滤逻辑
3. **Checkbox 操作**: 测试全选、取消全选、单独选择
4. **编辑负责人**: 双击单元格编辑，验证数据更新
5. **确认删除**: 选中记录点击确认删除，验证数据库写入
6. **重新加载**: 刷新数据，验证 checkbox 状态保持

### 边界测试
1. **空结果集**: 数据库无记录时的处理
2. **ManagerName 为空**: 确认删除时的验证
3. **MaterialCode 为空**: 是否正确过滤
4. **大数据集**: 1000+ 条记录的性能
5. **网络中断**: 数据库连接失败的处理

## 注意事项

1. **表名混淆**
   - `MaterialsTypeToBeDeleted` - 按材料名称模糊匹配
   - `MaterialsToBeDeleted` - 按材料代码精确匹配

2. **Unicode Checkbox**
   - 使用 `☐` 和 `☑` 字符模拟 checkbox
   - 不同操作系统/字体可能显示不一致

3. **线程安全**
   - 数据库操作在后台线程执行
   - UI 更新必须使用 `after()` 回调到主线程

4. **SQL Server 限制**
   - MERGE 语法兼容性
   - 参数数量限制（批量操作时分批处理）

5. **向后兼容**
   - 保留原有的校验方法（`validate_from_database`）
   - 新增增强方法（`validate_from_database_enhanced`）
   - 不破坏现有功能