沪衡 Huheng
沪衡是一个面向长期研究和投资判断的上海房市分析系统。名称取“沪”和“衡量、权衡”之意，目标是建立可复用的数据结构、指标口径、模型推演、报告和预警流程。
当前版本包含：
- SQLite 数据库 schema
- 官方/市场数据源目录
- 样例数据加载器
- 板块投资评分模型
- 月度 Markdown 报告生成
- Rust Axum API 骨架
- PostgreSQL migrations
- 单元测试
data/sample中的数据是演示样例，不代表真实行情。正式研究时应替换为可审计的数据源。
快速开始
PYTHONPATH=src python3 -m shanghai_housing init-db
PYTHONPATH=src python3 -m shanghai_housing load-sample
PYTHONPATH=src python3 -m shanghai_housing report --month 2026-05
生成报告位置：
reports/monthly-2026-05.md
运行测试：
PYTHONPATH=src python3 -m unittest discover -s tests
cargo test
API 开发
API 服务位于 apps/api，采用 Rust Axum + SQLx。环境变量配置见：
本地启动示例：
export DATABASE_URL="postgres://<user>:<password>@<host>:<port>/shanghai_housing_research_dev"
export RUN_MIGRATIONS=true
cargo run -p shanghai-housing-api
当前接口：
GET /health
GET /ready
GET /api/v1/data-sources
POST /api/v1/data-sources
GET /api/v1/ingestion-runs
POST /api/v1/ingestion-runs
PATCH /api/v1/ingestion-runs/{run_id}/finish
GET /api/v1/raw-artifacts
POST /api/v1/raw-artifacts
POST /api/v1/imports/validate
POST /api/v1/imports/execute
POST /api/v1/model-runs/area-scores
GET /api/v1/areas/{area_id}/score-lineage?month=2026-05
GET /api/v1/areas/scores?month=2026-05
GET /api/v1/market/overview?month=2026-05
GET /api/v1/neighborhoods
GET /api/v1/neighborhoods?area_id=zhangjiang
GET /api/v1/neighborhoods/{neighborhood_id}
GET /api/v1/neighborhoods/scores?month=2026-05
GET /api/v1/neighborhoods/scores?month=2026-05&area_id=zhangjiang
GET /api/v1/watchlist
POST /api/v1/watchlist
PATCH /api/v1/watchlist/{watchlist_item_id}
DELETE /api/v1/watchlist/{watchlist_item_id}
研究目标
系统要长期回答的不是单一“涨/跌”，而是：
- 当前上海市场处于什么周期位置？
- 哪些板块流动性更强？
- 哪些资产有租金和产业支撑？
- 哪些区域存在供应压力或价格压力？
- 哪些小区进入观察池？
- 触发买入、卖出、观望的条件是什么？
MVP 架构
config/source_catalog.json 数据源目录
data/sample/ 演示样例数据
src/shanghai_housing/schema.sql 数据库结构
src/shanghai_housing/db.py 初始化和加载数据
src/shanghai_housing/indicators.py 指标和评分模型
src/shanghai_housing/reporting.py 报告生成
src/shanghai_housing/cli.py 命令行入口
docs/ 研究框架和数据字典
第一版指标
- 成交活跃度
- 成交价格动量
- 挂牌库存压力
- 成交/挂牌折价
- 租金收益率
- 新增供应压力
- 信贷和政策环境
- 综合投资观察评分
下一步
- 接入真实月度数据源。
- 增加小区级评分和观察池。
- 建立板块历史分位和异常检测。
- 加入政策事件表和利率情景推演。
- 增加可视化看板。
长期架构
当前项目是研究内核 MVP，不是最终产品形态。完整方案见：