125 lines
3.3 KiB
Markdown
125 lines
3.3 KiB
Markdown
# 上海房市投资研究系统
|
||
|
||
这是一个面向长期研究和投资判断的上海房市分析底座。第一版重点不是预测神谕式的涨跌，而是建立可复用的数据结构、指标口径和报告流程。
|
||
|
||
当前版本包含：
|
||
|
||
- 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/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/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)
|