# 中国机车图鉴 · 应用工程

对应 `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 导入
```bash
# 在 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 待复核。

## 运行测试
```bash
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 众包修订细化。
- **国别属性**：当前用启发式默认"国产"，字段已就位，等待圈层二（国外车型）数据与人工标注。