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。