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"
+      }
+    ]
+  }'
+```

docs/import_templates/area_monthly_metrics.csv

@@ -0,0 +1,2 @@
+area_id,month,transaction_count,transaction_price_psm,listing_count,listing_price_psm,median_days_on_market,rent_price_psm,new_supply_units,land_residential_gfa_sqm,mortgage_rate_pct,policy_signal,source
+qiantan,2026-05,93,122500,380,126500,53,192,60,0,3.35,1,manual_research

docs/import_templates/land_sales.csv

@@ -0,0 +1,2 @@
+parcel_id,area_id,transaction_date,parcel_name,residential_gfa_sqm,transaction_price_total_cny,floor_price_cny_psm,buyer,source_url,source
+sh-2026-001,zhangjiang,2026-05-28,张江示例住宅地块,36000,1800000000,50000,示例房企,https://example.com/land-sale,official_auction

docs/import_templates/neighborhood_monthly_metrics.csv

@@ -0,0 +1,2 @@
+neighborhood_id,month,transaction_count,transaction_price_psm,listing_count,listing_price_psm,rent_price_psm,median_days_on_market,available_units,source
+qiantan_a,2026-05,12,124000,38,128000,195,50,38,manual_research

docs/import_templates/policy_events.csv

@@ -0,0 +1,2 @@
+event_date,level,title,impact_direction,notes,source_url,source
+2026-05-17,shanghai,优化住房信贷政策,1,降低置换成本,https://example.com/policy,official_notice

docs/product_roadmap.md

@@ -77,6 +77,8 @@
 
 ### M1.3 CSV/Excel 导入模板
 
+状态：已完成。
+
 目标：
 
 - 建立真实数据的标准导入模板。
@@ -87,23 +89,27 @@
 - `docs/import_templates/`
 - 后端导入校验接口。
 - Python analytics 导入脚本。
+- `config/import_templates.json` 作为模板规格源。
 
 验收标准：
 
-- 模板字段和数据库字段一一对应。
+- 模板字段和现有研究表字段一一对应。
 - 错误数据能返回明确错误信息。
-- 导入结果写入 `raw`/`silver`/`audit`。
+- Python CLI 可以校验 CSV/Excel，并将已支持模板写入本地研究库。
+- API 可以校验导入行的表头、类型、值域、日期、枚举和敏感文本。
 
 ### M1.4 原始数据留存与文件哈希
 
 目标：
 
-- 每次导入都记录原始文件位置、哈希、大小和导入人。
+- 每次导入都记录原始文件位置、哈希、大小、导入人和入库批次。
+- 正式导入结果写入 `raw`/`silver`/`audit`，并与 `audit.ingestion_runs` 关联。
 
 交付物：
 
 - `audit.raw_artifacts`
 - 导入批次关联 raw artifact。
+- PostgreSQL 导入执行接口。
 
 验收标准：