# 上海房市投资研究系统

这是一个面向长期研究和投资判断的上海房市分析底座。第一版重点不是预测神谕式的涨跌，而是建立可复用的数据结构、指标口径和报告流程。

当前版本包含：

- 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
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 架构

```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)
- [产品开发路线图](docs/product_roadmap.md)