Train/app/README.md

中国机车图鉴 · 应用工程

对应 2-task.md 的实现代码。当前已完成 Phase 0（部分）+ Phase 1A（数据底座 ETL）。

目录结构

app/
  etl/
    field_dict.py   # 统一字段字典、同义表头映射、枚举、分类配置 (T-1.1)
    clean.py        # 清洗规则：单元格清理、数值+单位拆分、年代/状态/国别 (T-1.2)
    schema.sql      # 三层模型 schema：Category/Model/Unit + 关系表 (T-1.1)
    importer.py     # ETL 主流程：12 CSV -> SQLite + JSON + 报告 (T-1.2)
  tests/            # 单元/集成测试 (Jest 等价物，使用 Python unittest)
  data/             # 产物：machines.db / machines.json / import_report.md

运行 ETL 导入

# 在 Train/ 目录下
python3 -m app.etl.importer

输入：Train/csv/*.csv（由总表 xlsx 转出的 12 张分类表） 输出：app/data/machines.db、machines.json、import_report.md

当前导入结果：Model 540 / Unit 307，跳过 10（均为空行），0 待复核。

运行测试

python3 -m unittest discover -s app/tests -p "test_*.py" -v

覆盖：字段映射、单位拆分、年代/状态解析、向前填充、表头识别、全量导入幂等性。

设计说明与已知取舍

• 存储：开发期使用 SQLite（零依赖、可运行验证）。schema 按可移植到 PostgreSQL 设计， Phase 1B 接入 API 时可平滑迁移（数值+单位字段、外键、索引均兼容）。
• 保真：每条记录保留 raw_json，原始清洗后所有列不丢失，便于后续众包修订与字段补全。
• 复合数值（如电力机车 "2×92(100)"）：取首个数值入 *_value，完整原文存 raw_json， 待 Phase 2 众包修订细化。
• 国别属性：当前用启发式默认"国产"，字段已就位，等待圈层二（国外车型）数据与人工标注。