huheng-research/docs/import_templates/README.md

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 校验

PYTHONPATH=src python3 -m shanghai_housing validate-import \
  --template area_monthly_metrics \
  --file docs/import_templates/area_monthly_metrics.csv

通过时输出行数和模板名；失败时逐行返回错误信息。

API 校验

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