feat: add raw artifact audit trail

docs/import_templates/README.md

@@ -46,6 +46,17 @@ PYTHONPATH=src python3 -m shanghai_housing validate-import \
 
 通过时输出行数和模板名；失败时逐行返回错误信息。
 
+## 原始文件指纹
+
+导入前先计算文件指纹，用于登记 `audit.raw_artifacts` 并识别重复文件。
+
+```bash
+PYTHONPATH=src python3 -m shanghai_housing fingerprint-file \
+  --file docs/import_templates/area_monthly_metrics.csv
+```
+
+输出内容包含 `original_filename`、`raw_uri`、`sha256`、`size_bytes` 和 `mime_type`，可作为 `POST /api/v1/raw-artifacts` 的主要 payload。
+
 ## API 校验
 
 ```bash
@@ -72,3 +83,22 @@ curl -X POST http://127.0.0.1:8080/api/v1/imports/validate \
     ]
   }'
 ```
+
+## API 原始文件登记
+
+```bash
+curl -X POST http://127.0.0.1:8080/api/v1/raw-artifacts \
+  -H 'content-type: application/json' \
+  -d '{
+    "run_id": 1,
+    "source_id": 1,
+    "original_filename": "area_monthly_metrics.csv",
+    "raw_uri": "raw://sha256/<sha256>/area_monthly_metrics.csv",
+    "sha256": "<64-character-lowercase-sha256>",
+    "size_bytes": 2048,
+    "mime_type": "text/csv",
+    "uploaded_by": "researcher"
+  }'
+```
+
+同一个 `sha256` 重复登记时，API 返回已有 artifact，并可将新的导入批次关联到该 artifact。

docs/product_roadmap.md

@@ -100,22 +100,45 @@
 
 ### M1.4 原始数据留存与文件哈希
 
+状态：已完成。
+
 目标：
 
 - 每次导入都记录原始文件位置、哈希、大小、导入人和入库批次。
-- 正式导入结果写入 `raw`/`silver`/`audit`，并与 `audit.ingestion_runs` 关联。
+- 将原始文件资产与 `audit.ingestion_runs` 关联，支持重复文件识别。
 
 交付物：
 
 - `audit.raw_artifacts`
 - 导入批次关联 raw artifact。
-- PostgreSQL 导入执行接口。
+- `GET /api/v1/raw-artifacts`
+- `POST /api/v1/raw-artifacts`
+- Python 文件指纹命令。
 
 验收标准：
 
 - 同一文件重复导入可识别。
 - 任一指标可以追溯到原始数据批次。
 
+### M1.5 PostgreSQL 导入执行接口
+
+目标：
+
+- 将已校验模板数据正式写入 PostgreSQL 的 `raw`/`silver`/`audit`。
+- 导入执行必须关联 `audit.ingestion_runs` 和 `audit.raw_artifacts`。
+
+交付物：
+
+- PostgreSQL 导入执行 API。
+- 支持板块月度指标和小区月度指标的 upsert。
+- 导入失败时写入明确错误并保留审计记录。
+
+验收标准：
+
+- 校验失败不写入业务表。
+- 导入成功后可通过批次追溯到原始文件哈希。
+- 重复导入同一文件时能识别并提示。
+
 ## M2 资产研究工作台
 
 ### M2.1 板块详情页