# 04h 基础字典维护

> 状态：✅ 已实现 | ⚙️ 配置驱动

## 1. 操作入口

| 方式 | 入口 |
|------|------|
| GUI | 导航「基础数据维护」→ `LookupTablesDialog` → 各 `*_manager_view` |
| CLI | `certflow grade-import`（材质）、`certflow bom`（BOM） |

基础字典支撑全流程（导入列映射、编号、合格证双码、报告 BOM 匹配）。

## 2. 涉及配置文件

| 配置文件 | 用途 |
|----------|------|
| `config/dictionaries.yaml` | 字典表总定义 |
| `config/grade_aliases.yaml` | 材质牌号别名 |
| `config/imperial_rules.yaml` | 英制单位规则 |
| `config/field_rules.yaml` | 字段校验 |

## 3. 涉及代码文件

| 字典 | View | Controller | Service | Model |
|------|------|-----------|---------|-------|
| 材质牌号 | `material_grade_manager_view.py` | `material_grade_controller.py` | `material_grade_service.py` | `material_grade.py` |
| 型号参数映射 | `model_param_mapping_manager_view.py` | `model_param_mapping_controller.py` | `model_param_mapping_service.py` | `model_param_mapping.py` |
| 口径映射 | `caliber_mapping_manager_view.py` | `caliber_mapping_controller.py` | `caliber_mapping_service.py` | `caliber_mapping.py` |
| BOM 物料 | `bom_material_query_view.py` | `bom_material_controller.py` | `bom_material_service.py` | `bom_material.py` |
| 字典 CSV 同步 | - | - | `dict_csv_sync.py` | - |

## 4. 逐步流程

### 4.1 材质牌号维护

1. 导航「基础数据维护」→「材质牌号」
2. `MaterialGradeManagerView` 表格编辑
3. 支持别名（`grade_aliases.yaml`）
4. CLI 导入：

   ```bash
   certflow grade-import material_grades.csv
   ```

### 4.2 型号参数映射

1. 导航「基础数据维护」→「型号参数映射」
2. `ModelParamMappingManagerView` 维护 型号→压力/口径 映射
3. 支撑合格证双码计算与报告 BOM 匹配

### 4.3 口径映射

1. 导航「基础数据维护」→「口径映射」
2. `CaliberMappingManagerView` 维护 DN 映射
3. 支撑合格证 DN 计算

### 4.4 BOM 物料

1. 导航「基础数据维护」→「BOM 物料」
2. `BomMaterialQueryView` + `BomMaterialController`
3. CLI：

   ```bash
   certflow bom list
   certflow bom add <part_no> <grade>
   ```

## 5. 空库自动播种

首次启动（数据库为空）时，`main.py::_maybe_seed_base_data` 调用 `scripts/data/seed_base_data.py` 子进程自动填充：

- 材质
- 型号压力
- 口径

基础字典底座播种明细日志在 `VALVE_SEED_DEBUG=1 ./start.sh` 时输出。

## 6. 字典 CSV 同步

`DictCsvSync` 服务支持字典表与 CSV 双向同步，便于批量维护。

## 7. 常见问题

- **双码为 0**：检查「型号参数映射」「口径映射」是否覆盖该型号
- **材质识别失败**：检查「材质牌号别名」是否补充了别名写法
- **导入报错**：确认 CSV 列名与字典表结构一致