# 实现进度

> 快照日期：2026-08-04
> 分支：`src-clean`
> 版本：`0.0.1-alpha.1`（见 `config/config.yaml`）

本文按模块记录实现完成度。每个模块标注 ✅/🟡/🔴 及关键文件位置。

## 1. 启动与装配

| 模块 | 状态 | 关键文件 | 说明 |
|------|------|----------|------|
| 启动脚本 | ✅ | `start.sh` | 11 阶段：环境检查 → 依赖同步 → 调试库重建 → 启动 |
| 主入口 | ✅ | `src/certflow/main.py` | QApplication + DB 初始化 + 主窗口 |
| 应用装配 | ✅ | `src/certflow/bootstrap.py` | `AppContext` 统一会话/Service 装配 |
| 日志系统 | ✅ | `src/certflow/utils/logger.py` | loguru，支持 `debug_modules` 黑名单 |
| 高 DPI 适配 | ✅ | `main.py` | `QT_AUTO_SCALE_FACTOR=1` |

## 2. CLI 命令（共 24 个）

| 命令 | 状态 | 文件 | 说明 |
|------|------|------|------|
| `import-sales-plan` | ✅ | `cli/commands/import_sales_plan.py` | 对齐 GUI 全部参数 |
| `auto-number` | ✅ | `cli/commands/auto_number.py` | |
| `print-cert` | ✅ | `cli/commands/print_cert.py` | |
| `export-excel` | ✅ | `cli/commands/export_excel.py` | |
| `export-access` | 🟡 | `cli/commands/export_access.py` | 依赖 Access 驱动，跨平台受限 |
| `quick-query` | ✅ | `cli/commands/quick_query.py` | |
| `stats` | ✅ | `cli/commands/stats.py` | |
| `mark-shipped` | ✅ | `cli/commands/mark_shipped.py` | |
| `record-shipment` | ✅ | `cli/commands/record_shipment.py` | |
| `set-year-month` | ✅ | `cli/commands/set_year_month.py` | |
| `batch-update` | ✅ | `cli/commands/batch_update.py` | |
| `grade-import` | ✅ | `cli/commands/grade_import.py` | |
| `import-certs` | ✅ | `cli/commands/import_certs.py` | |
| `copy-cert-info` | ✅ | `cli/commands/copy_cert_info.py` | |
| `check-consistency` | ✅ | `cli/commands/check_consistency.py` | |
| `clean-duplicates` | ✅ | `cli/commands/clean_duplicates.py` | |
| `backfill-supply-type` | ✅ | `cli/commands/backfill_supply_type.py` | |
| `db-backup` | ✅ | `cli/commands/db_backup.py` | |
| `db-sync` | ✅ | `cli/commands/db_sync.py` | WebDAV push/pull/status |
| `db-reset` | ✅ | `cli/commands/db_reset.py` | 支持从基线库重建 |
| `bom` | ✅ | `cli/commands/bom_material.py` | |
| `report-gen` | ✅ | `cli/commands/report_gen.py` | |
| `watch` | ✅ | `cli/commands/watch.py` | watchdog 监控目录自动导入 |
| `serve` | 🔴 | `cli/commands/serve.py` | **占位命令**，Web 模块未实现 |

## 3. 业务流程模块（操作者视角）

详见 [`04-operator-guide.md`](./04-operator-guide.md) 各子文档。

### 3.1 销售计划导入

| 子流程 | 状态 | 关键文件 |
|--------|------|----------|
| Excel 读取（python-calamine） | ✅ | `handlers/styled_excel_importer.py` |
| 列映射解析 | ✅ | `services/sale_plan_service.py` |
| 撞键策略 | ✅ | `services/import_gate_service.py` |
| 隔离队列（quarantine） | ✅ | `services/correction_queue_service.py` |
| 占位目录预建（B0-4） | ⚙️ | `config/import.yaml` `create_placeholder_dirs`，默认 OFF |
| VBA 风格导入 | ✅ | `services/db_source_adapter.py` |

### 3.2 查询与字段补充

| 子流程 | 状态 | 关键文件 |
|--------|------|----------|
| 多条件查询构建器 | ✅ | `services/query_builder.py`、`query_service.py` |
| 查询视图（表格 + 快查） | ✅ | `views/query_view.py` |
| 字段批量编辑 | ✅ | `controllers/query_controller.py` |
| 合同信息复制到合格证 | ✅ | action `copy_cert_info` |
| 合格证字段编辑 | ✅ | action `edit_cert_fields` / `edit_certificate` |
| 生产状态推断 | ✅ | `services/workflow_service.py`（`StatusInference`） |
| 配置驱动状态/供货类型切换 | ✅ | `actions/registry.py`（`set_status_*` / `set_supply_type_*`） |

### 3.3 校正队列

| 子流程 | 状态 | 关键文件 |
|--------|------|----------|
| 隔离入队 | ✅ | `services/correction_queue_service.py` |
| 编辑后放行 | ✅ | `views/correction_queue_view.py` |
| 删除 | ✅ | action `delete`（danger） |

### 3.4 编号

| 子流程 | 状态 | 关键文件 |
|--------|------|----------|
| 自动编号 | ✅ | `services/cert_numbering.py`、`cert_numbering_policy.py` |
| 手动编号 | ✅ | action `manual_number` |
| 编号复制 | ✅ | action `copy_number` |
| 年月前缀设置 | ✅ | action `set_year_month` |
| 编号格式模板 | ⚙️ | `config/numbering.yaml`，支持 `{prefix}{date}{seq}` 占位符 |

### 3.5 合格证生成与打印

| 子流程 | 状态 | 关键文件 |
|--------|------|----------|
| 合格证记录生成 | ✅ | `services/certificate_service.py`、`certificate_number_service.py` |
| 合格证预览 | ✅ | `views/certificate_preview_painter.py` |
| 打印引擎 | ✅ | `services/cert_print_engine.py` |
| 打印服务 | ✅ | `services/certificate_print_service.py` |
| 打印队列 | ✅ | `controllers/print_queue_controller.py` |
| 打印机管理 | ✅ | `services/printer_manager.py`、`controllers/printer_controller.py` |
| 打印历史 | ✅ | `services/print_history_service.py`、`controllers/history_controller.py` |
| 双码（DN/PN）计算 | ✅ | `services/dn_service.py`、`pn_service.py`、`dual_code.py`、`pressure_calc_service.py` |

### 3.6 报告生成

| 子流程 | 状态 | 关键文件 |
|--------|------|----------|
| 质保书/试压/材质报告 | ✅ | `services/report_fill_service.py`、`report_output_service.py` |
| BOM 零件牌号匹配 | ✅ | `services/bom_material_service.py`、`bom_part_classifier.py` |
| BOM 富化 | ✅ | `services/report_bom_enricher.py` |
| 报告视图 | ✅ | `views/report_view.py`、`controllers/report_controller.py` |
| 报告模板 | ⚙️ | `config/report.yaml`、`config/templates/` |
| 迁移草稿区 | 🟡 | `services/report_migration/` | `material_provider.py` 抛 `NotImplementedError`，待并入 src 重写 |

### 3.7 导出

| 子流程 | 状态 | 关键文件 |
|--------|------|----------|
| Excel 导出 | ✅ | `handlers/csv_export.py`、`handlers/excel_handler.py`、`handlers/excel_styler.py` |
| 发货导出 | ✅ | `handlers/shipped_export_handler.py` |
| Access 导出 | 🟡 | `cli/commands/export_access.py` | 依赖 Windows Access 驱动 |
| 输出保护 | ✅ | `services/output_guard.py` |

### 3.8 同步与备份

| 子流程 | 状态 | 关键文件 |
|--------|------|----------|
| WebDAV 同步（坚果云） | ✅ | `cli/commands/db_sync.py`、`main.py::setup_webdav_config` |
| 数据库备份 | ✅ | `cli/commands/db_backup.py` |
| 四库模型（A/B/C/D） | ✅ | `start.sh` 阶段10 | A=主库 B=调试 C=本地基线 D=匿名基线（LFS） |

### 3.9 基础字典维护

| 子流程 | 状态 | 关键文件 |
|--------|------|----------|
| 材质牌号 | ✅ | `services/material_grade_service.py`、`views/material_grade_manager_view.py` |
| 型号参数映射 | ✅ | `services/model_param_mapping_service.py`、`views/model_param_mapping_manager_view.py` |
| 口径映射 | ✅ | `services/caliber_mapping_service.py`、`views/caliber_mapping_manager_view.py` |
| BOM 物料 | ✅ | `controllers/bom_material_controller.py`、`views/bom_material_query_view.py` |
| 字典 CSV 同步 | ✅ | `services/dict_csv_sync.py` |
| 空库自动播种 | ✅ | `main.py::_maybe_seed_base_data` → `scripts/data/seed_base_data.py` |

### 3.10 历史与归档

| 子流程 | 状态 | 关键文件 |
|--------|------|----------|
| 打印历史视图 | ✅ | `views/history_view.py` |
| 发货归档 | ✅ | action `shipped_archive` |
| 发货导出后删除 | ✅ | action `shipped_export_delete` |

## 4. 配置体系

| 配置文件 | 状态 | 用途 |
|----------|------|------|
| `config.yaml` | ✅ | 索引文件，!include 拼接子配置 |
| `paths.yaml` | ✅ | 路径配置（支持 `${ENV_VAR}` 与 `paths.local.yaml` 覆盖） |
| `sales_plan.yaml` | ✅ | 销售计划字段定义 |
| `grouping.yaml` | ✅ | 订单分组规则 |
| `certificate.yaml` | ✅ | 合格证模板字段 |
| `numbering.yaml` | ✅ | 编号规则 |
| `import.yaml` | ✅ | 导入参数（含占位目录开关 B0-4） |
| `database.yaml` | ✅ | 数据库连接 |
| `sync.yaml` | ✅ | WebDAV 同步 |
| `printer.yaml` / `print.yaml` | ✅ | 打印机与打印参数 |
| `report.yaml` | ✅ | 报告模板与命名 |
| `quarantine.yaml` | ✅ | 校正队列规则 |
| `production_status.yaml` | ✅ | 生产状态定义（驱动 `set_status_*`） |
| `field_rules.yaml` | ✅ | 字段校验规则 |
| `dictionaries.yaml` | ✅ | 字典表 |
| `ui.yaml` | ✅ | UI 布局、action、导航按钮 |
| 其余（colors/export/output/...） | ✅ | 见 `config/` 目录 |

配置加载器：`src/certflow/config/loader.py`、`settings.py`、`models.py`、`paths_override.py`。

## 5. 数据模型

全部位于 `src/certflow/models/`，共 17 个模型：

| 模型 | 状态 | 用途 |
|------|------|------|
| `sale_plan.py` | ✅ | 销售计划（核心表） |
| `sale_plan_shipped.py` | ✅ | 已发货归档 |
| `sale_plan_change.py` | ✅ | 变更记录 |
| `certificate.py` | ✅ | 合格证 |
| `print_job.py` / `print_log.py` | ✅ | 打印任务/日志 |
| `bom_material.py` | ✅ | BOM 物料 |
| `material_grade.py` | ✅ | 材质牌号 |
| `model_param_mapping.py` | ✅ | 型号参数映射 |
| `caliber_mapping.py` | ✅ | 口径映射 |
| `param_auto_learn_log.py` | ✅ | 参数自动学习日志 |
| `quarantine_sale_plan.py` | ✅ | 隔离队列 |
| `report_template.py` | ✅ | 报告模板 |
| `unmatched_certificate.py` | ✅ | 未匹配合格证 |
| `vba_mapping.py` | ✅ | VBA 字段映射 |
| `auto_number.py` | ✅ | 自动编号状态 |
| `base.py` | ✅ | SQLAlchemy Base |

## 6. 测试与质量

| 项 | 状态 | 说明 |
|----|------|------|
| 单元测试 | 🟡 | `tests/unit`，覆盖率由 `--cov=src/certflow` 统计 |
| Qt 测试 | 🟡 | `pytest-qt`，标记 `qt`，无头用 `QT_QPA_PLATFORM=offscreen` |
| 层纯度门禁 | ✅ | `scripts/check_layer_purity.py` |
| 类型检查 | ✅ | pyright（basic 模式）+ mypy |
| Lint | ✅ | ruff 0.15.15 |
| CI | ✅ | `ci/` 目录，16 个 yml |
| pre-commit | ✅ | `start.sh` 阶段7.5 自动安装 |

## 7. 打包与部署

| 项 | 状态 | 说明 |
|----|------|------|
| PyInstaller | ✅ | `scripts/builder/` |
| Nuitka | ✅ | 备选构建器 |
| 依赖组管理 | ✅ | `pyproject.toml` 依赖组：dev/lint/typing/test/docs/build/... |