chore: bootstrap housing research platform

README.md

@@ -0,0 +1,109 @@
+# 上海房市投资研究系统
+
+这是一个面向长期研究和投资判断的上海房市分析底座。第一版重点不是预测神谕式的涨跌，而是建立可复用的数据结构、指标口径和报告流程。
+
+当前版本包含：
+
+- SQLite 数据库 schema
+- 官方/市场数据源目录
+- 样例数据加载器
+- 板块投资评分模型
+- 月度 Markdown 报告生成
+- Rust Axum API 骨架
+- PostgreSQL migrations
+- 单元测试
+
+> `data/sample` 中的数据是演示样例，不代表真实行情。正式研究时应替换为可审计的数据源。
+
+## 快速开始
+
+```bash
+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
+```
+
+生成报告位置：
+
+```bash
+reports/monthly-2026-05.md
+```
+
+运行测试：
+
+```bash
+PYTHONPATH=src python3 -m unittest discover -s tests
+cargo test
+```
+
+## API 开发
+
+API 服务位于 `apps/api`，采用 Rust Axum + SQLx。环境变量配置见：
+
+- [环境配置](docs/config/environment.md)
+
+本地启动示例：
+
+```bash
+export DATABASE_URL="postgres://<user>:<password>@<host>:<port>/shanghai_housing_research_dev"
+export RUN_MIGRATIONS=true
+cargo run -p shanghai-housing-api
+```
+
+当前接口：
+
+```text
+GET /health
+GET /ready
+GET /api/v1/areas/scores?month=2026-05
+GET /api/v1/market/overview?month=2026-05
+```
+
+## 研究目标
+
+系统要长期回答的不是单一“涨/跌”，而是：
+
+- 当前上海市场处于什么周期位置？
+- 哪些板块流动性更强？
+- 哪些资产有租金和产业支撑？
+- 哪些区域存在供应压力或价格压力？
+- 哪些小区进入观察池？
+- 触发买入、卖出、观望的条件是什么？
+
+## MVP 架构
+
+```text
+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/                           研究框架和数据字典
+```
+
+## 第一版指标
+
+- 成交活跃度
+- 成交价格动量
+- 挂牌库存压力
+- 成交/挂牌折价
+- 租金收益率
+- 新增供应压力
+- 信贷和政策环境
+- 综合投资观察评分
+
+## 下一步
+
+1. 接入真实月度数据源。
+2. 增加小区级评分和观察池。
+3. 建立板块历史分位和异常检测。
+4. 加入政策事件表和利率情景推演。
+5. 增加可视化看板。
+
+## 长期架构
+
+当前项目是研究内核 MVP，不是最终产品形态。完整方案见：
+
+- [系统架构与开发计划](docs/system_architecture_and_development_plan.md)