feat: add import templates

docs/import_templates/README.md

@@ -0,0 +1,74 @@
+# CSV/Excel 导入模板
+
+本目录定义真实数据进入系统前的标准格式。模板当前以 CSV 提供，Excel 可按相同列名保存为首行表头后再导出为 CSV。
+
+## 使用原则
+
+- 表头必须与模板完全一致。
+- 文件编码建议使用 UTF-8 或 UTF-8 with BOM。
+- 所有金额和面积字段只填写数字，不带单位、逗号或中文说明。
+- `source` 必须填写可识别的数据来源名称，不允许写数据库连接串、密码、本地敏感路径。
+- 单次导入必须先创建或关联一条 `audit.ingestion_runs` 记录。
+- 校验通过不代表数据一定正确，只代表结构、类型和值域满足入库前置条件。
+
+## 模板清单
+
+| 模板 | 目标表 | 主键 | 用途 |
+| --- | --- | --- | --- |
+| `area_monthly_metrics.csv` | `silver.area_monthly_metrics` | `area_id`, `month` | 板块月度成交、挂牌、租金、供应、信贷和政策信号 |
+| `neighborhood_monthly_metrics.csv` | `silver.neighborhood_monthly_metrics` | `neighborhood_id`, `month` | 小区月度成交、挂牌、租金和可售样本 |
+| `policy_events.csv` | `raw.policy_events` | `event_date`, `title` | 政策事件留痕和人工影响评分 |
+| `land_sales.csv` | `raw.land_sales` | `parcel_id` | 土地成交记录，用于供给压力研究 |
+
+## 字段规则
+
+字段规格的机器可读版本位于 `config/import_templates.json`。Python CLI 和 Rust API 均应以该文件为准。
+
+### 通用类型
+
+| 类型 | 规则 |
+| --- | --- |
+| `text` | 非空文本，若字段非必填则可为空 |
+| `integer` | 整数，可配置最小值和最大值 |
+| `decimal` | 数字，可配置最小值和最大值 |
+| `month` | `YYYY-MM`，月份必须是 01-12 |
+| `date` | `YYYY-MM-DD`，日期必须真实存在 |
+| `url` | 空值或 `http://` / `https://` URL |
+| `enum` | 必须属于规格中的 `allowed_values` |
+
+## CLI 校验
+
+```bash
+PYTHONPATH=src python3 -m shanghai_housing validate-import \
+  --template area_monthly_metrics \
+  --file docs/import_templates/area_monthly_metrics.csv
+```
+
+通过时输出行数和模板名；失败时逐行返回错误信息。
+
+## API 校验
+
+```bash
+curl -X POST http://127.0.0.1:8080/api/v1/imports/validate \
+  -H 'content-type: application/json' \
+  -d '{
+    "template_name": "area_monthly_metrics",
+    "rows": [
+      {
+        "area_id": "qiantan",
+        "month": "2026-05",
+        "transaction_count": "93",
+        "transaction_price_psm": "122500",
+        "listing_count": "380",
+        "listing_price_psm": "126500",
+        "median_days_on_market": "53",
+        "rent_price_psm": "192",
+        "new_supply_units": "60",
+        "land_residential_gfa_sqm": "0",
+        "mortgage_rate_pct": "3.35",
+        "policy_signal": "1",
+        "source": "manual_research"
+      }
+    ]
+  }'
+```