chore: bootstrap housing research platform
This commit is contained in:
543
docs/system_architecture_and_development_plan.md
Normal file
543
docs/system_architecture_and_development_plan.md
Normal file
@@ -0,0 +1,543 @@
|
||||
# 上海房市投资研究系统架构与开发计划
|
||||
|
||||
## 0. 当前状态
|
||||
|
||||
当前项目是一个纯 Python 的研究内核 MVP：
|
||||
|
||||
- SQLite 存储
|
||||
- 样例数据
|
||||
- 板块指标计算
|
||||
- Markdown 月报生成
|
||||
- 命令行入口
|
||||
|
||||
它的价值是验证研究口径和指标框架。它不是最终系统形态。后续应演进为一个具备数据采集、资产库、模型、API、前端看板、报告和预警能力的长期研究平台。
|
||||
|
||||
## 1. 系统定位
|
||||
|
||||
目标是搭建一个面向上海房市长期投资判断的研究操作系统。系统最终要回答：
|
||||
|
||||
- 市场处在什么周期位置？
|
||||
- 哪些板块值得重点跟踪？
|
||||
- 哪些小区具有流动性、租金和稀缺性支撑？
|
||||
- 合理买入价区间是多少？
|
||||
- 什么信号触发买入、观望、卖出或换仓？
|
||||
- 判断依据是否可复盘、可解释、可更新？
|
||||
|
||||
系统不追求单点预测“下月涨跌”，而追求持续形成稳定的投资判断流程。
|
||||
|
||||
## 2. 总体架构
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
A["数据源<br/>官方/市场/手工/文档"] --> B["采集层<br/>Ingestion"]
|
||||
B --> C["原始数据层<br/>Raw Lake"]
|
||||
C --> D["标准化层<br/>Normalized Store"]
|
||||
D --> E["特征与指标层<br/>Feature Mart"]
|
||||
E --> F["模型层<br/>Scoring/Forecast/Scenario"]
|
||||
F --> G["API 层<br/>Rust Axum"]
|
||||
G --> H["前端<br/>React + TypeScript + shadcn/ui"]
|
||||
F --> I["报告与预警<br/>周报/月报/观察池"]
|
||||
D --> J["研究工作台<br/>Notebook/CLI"]
|
||||
```
|
||||
|
||||
## 3. 推荐技术路线
|
||||
|
||||
### 3.1 推荐结论
|
||||
|
||||
长期看，推荐采用混合架构：
|
||||
|
||||
- 前端：TypeScript + React + shadcn/ui
|
||||
- API 后端：Rust Axum + SQLx
|
||||
- 分析与模型服务：Python，必要时引入 Rust 数据处理组件
|
||||
- 主数据库：PostgreSQL + PostGIS
|
||||
- 本地分析引擎：DuckDB + Parquet
|
||||
- 数据处理：Python Polars 起步，Rust Polars/DataFusion 用于稳定高性能任务
|
||||
- 后台任务：先用轻量 cron/脚本，后续升级 Prefect 或 Airflow
|
||||
|
||||
本项目按长期平台建设，因此不采用 FastAPI 过渡。API 层从第一版就采用 Rust Axum，Python 保留为分析、建模、数据实验和离线任务服务。
|
||||
|
||||
### 3.2 为什么不是纯 Python
|
||||
|
||||
纯 Python 很适合研究、建模和快速迭代，但当系统开始承载更多前端交互、权限、并发查询、任务调度和长期服务稳定性时，单体 Python 项目会逐渐变重。
|
||||
|
||||
更成熟的做法是：
|
||||
|
||||
- Python 专注数据、模型、研究逻辑。
|
||||
- Rust API 专注服务边界、权限、查询、任务编排。
|
||||
- 前端专注研究工作台和投资决策界面。
|
||||
|
||||
### 3.3 为什么不是纯 Rust
|
||||
|
||||
Rust 很适合高可靠服务和性能敏感 API，但房市研究最重的工作通常不是 API 性能，而是数据清洗、特征工程、统计建模、回测、报告解释和探索式分析。这些领域 Python 生态明显更成熟。
|
||||
|
||||
因此不建议把模型和研究逻辑全部用 Rust 重写。那会降低迭代速度。
|
||||
|
||||
## 4. Rust 后端 vs Python 后端
|
||||
|
||||
| 维度 | Rust 后端 | Python 后端 |
|
||||
| --- | --- | --- |
|
||||
| 性能 | 很强，适合高并发、低延迟、重查询网关 | 足够支撑早期和中等规模内部系统 |
|
||||
| 稳定性 | 编译期约束强，运行期类型错误少 | 依赖测试和类型检查，长期维护需更强纪律 |
|
||||
| 开发速度 | 初期慢，类型和生命周期成本更高 | 很快，尤其适合快速验证业务逻辑 |
|
||||
| 数据科学生态 | 可用但不如 Python 丰富 | 极强，Polars、pandas、statsmodels、sklearn 等成熟 |
|
||||
| API 工程 | Axum + SQLx 很稳，适合长期服务 | FastAPI 开发快，OpenAPI 友好 |
|
||||
| 团队门槛 | 较高 | 较低 |
|
||||
| 部署 | 单二进制优势明显 | 依赖环境和包管理，容器化后可控 |
|
||||
| 与模型集成 | 通常需要调用 Python 服务或共享数据库 | 原生集成最顺 |
|
||||
| 推荐阶段 | 从第一版开始承担主 API、权限、查询网关 | 只保留为模型服务、数据任务、研究实验 |
|
||||
|
||||
推荐策略：
|
||||
|
||||
1. 第一阶段：Rust Axum 建立主 API 和服务边界。
|
||||
2. Python 保持研究内核、数据处理、模型和报告生成。
|
||||
3. 前后端通过 OpenAPI 或共享 schema 对齐契约。
|
||||
4. 稳定、重复、高性能的数据处理任务可逐步迁入 Rust Polars/DataFusion。
|
||||
|
||||
本项目采用 Rust API + Python analytics 双服务作为默认路线。
|
||||
|
||||
## 4.1 Rust 数据处理 vs Python 数据处理
|
||||
|
||||
Rust 的数据处理能力并不弱。Polars 有 Rust 版本，DataFusion 本身就是基于 Rust 和 Apache Arrow 的高性能查询引擎，适合构建稳定、高性能、可嵌入的数据系统。
|
||||
|
||||
但对本系统来说，Python 仍然在以下方面更强：
|
||||
|
||||
- 探索式分析更快，交互式 Notebook、临时统计、画图、验证假设都更顺手。
|
||||
- 统计建模和机器学习生态更完整，尤其是回归、时间序列、聚类、解释性分析、模型评估。
|
||||
- 采集、清洗、Excel/CSV、报告、可视化周边库更丰富。
|
||||
- 研究逻辑经常变化，Python 的迭代成本低。
|
||||
|
||||
Rust 更适合：
|
||||
|
||||
- API 查询层和权限层。
|
||||
- 稳定的数据校验、标准化和导入管线。
|
||||
- 大批量 CSV/Parquet 扫描、聚合、特征预计算。
|
||||
- 需要长期运行、低内存占用、高并发的服务。
|
||||
- 已经沉淀稳定的数据处理逻辑。
|
||||
|
||||
因此判断不是“Rust 弱”，而是“Rust 更工程化，Python 更研究化”。本系统的最佳分工是：
|
||||
|
||||
```text
|
||||
Rust：API、数据库访问、权限、稳定导入、稳定特征计算、高性能查询
|
||||
Python：探索分析、模型实验、统计预测、报告解释、策略研究
|
||||
```
|
||||
|
||||
## 5. 前端方案
|
||||
|
||||
你的偏好是 TypeScript + React + shadcn/ui，这个方向适合本系统。
|
||||
|
||||
推荐栈：
|
||||
|
||||
- Next.js App Router 或 Vite + React
|
||||
- TypeScript
|
||||
- shadcn/ui
|
||||
- Tailwind CSS
|
||||
- TanStack Query
|
||||
- Recharts 或 ECharts
|
||||
- MapLibre GL，用于地图和板块空间分析
|
||||
- Zod，用于前端数据校验
|
||||
|
||||
选择建议：
|
||||
|
||||
- 如果要做完整产品、登录、路由、服务端渲染、报告页分享，选 Next.js。
|
||||
- 如果只是本地研究工作台和内部 SPA，选 Vite + React 更轻。
|
||||
|
||||
我建议采用 Next.js，因为后续报告页、板块详情页、观察池和权限体系会自然变复杂。
|
||||
|
||||
## 6. 前端信息架构
|
||||
|
||||
第一版前端应直接进入研究工作台，不做营销式首页。
|
||||
|
||||
核心页面：
|
||||
|
||||
1. 市场总览
|
||||
- 上海整体成交、挂牌、库存、租金、利率、政策事件
|
||||
- 周期状态判断
|
||||
- 关键风险提示
|
||||
|
||||
2. 板块地图
|
||||
- 按综合评分、供应压力、租售比、价格动量着色
|
||||
- 支持行政区、环线、地铁、产业标签筛选
|
||||
|
||||
3. 板块详情
|
||||
- 成交/挂牌/租金走势
|
||||
- 新房供应与土地成交
|
||||
- 小区排行
|
||||
- 相似板块对比
|
||||
|
||||
4. 小区观察池
|
||||
- 自定义关注小区
|
||||
- 合理买入价
|
||||
- 挂牌变化
|
||||
- 成交样本
|
||||
- 风险标签
|
||||
|
||||
5. 策略与情景
|
||||
- 利率变化情景
|
||||
- 政策松紧情景
|
||||
- 收入/租金/供应变化情景
|
||||
|
||||
6. 报告中心
|
||||
- 周报
|
||||
- 月报
|
||||
- 板块专题
|
||||
- 投资备忘录
|
||||
|
||||
## 7. 后端模块设计
|
||||
|
||||
### 7.1 API 模块
|
||||
|
||||
职责：
|
||||
|
||||
- 用户、权限、配置
|
||||
- 板块、小区、指标查询
|
||||
- 观察池管理
|
||||
- 报告查询
|
||||
- 模型结果查询
|
||||
- 任务触发和状态查询
|
||||
|
||||
典型接口：
|
||||
|
||||
- `GET /api/market/overview?month=YYYY-MM`
|
||||
- `GET /api/areas`
|
||||
- `GET /api/areas/{area_id}/scores`
|
||||
- `GET /api/areas/{area_id}/metrics`
|
||||
- `GET /api/neighborhoods/{id}`
|
||||
- `POST /api/watchlist`
|
||||
- `GET /api/reports/monthly/{month}`
|
||||
- `POST /api/jobs/ingest`
|
||||
|
||||
### 7.2 Analytics 模块
|
||||
|
||||
职责：
|
||||
|
||||
- 数据清洗
|
||||
- 特征生成
|
||||
- 板块评分
|
||||
- 小区评分
|
||||
- 异常检测
|
||||
- 情景推演
|
||||
- 报告生成
|
||||
|
||||
当前 Python 代码应逐步演进为这个模块。
|
||||
|
||||
### 7.3 Ingestion 模块
|
||||
|
||||
职责：
|
||||
|
||||
- 官方数据导入
|
||||
- 市场数据导入
|
||||
- 手工 CSV/Excel 导入
|
||||
- 数据源版本记录
|
||||
- 失败重试
|
||||
- 采集日志
|
||||
|
||||
所有采集结果必须保留原始文件或原始响应，不直接覆盖。
|
||||
|
||||
### 7.4 Report 模块
|
||||
|
||||
职责：
|
||||
|
||||
- 周报/月报
|
||||
- 板块专题
|
||||
- 小区备忘录
|
||||
- 组合观察报告
|
||||
|
||||
报告不应只是文本，应保留结构化结论，方便前端二次展示。
|
||||
|
||||
## 8. 数据架构
|
||||
|
||||
### 8.1 数据分层
|
||||
|
||||
```text
|
||||
raw 原始数据，保留来源、采集时间、文件哈希
|
||||
bronze 初步解析，字段类型基本清理
|
||||
silver 标准化实体，统一板块、小区、月份、口径
|
||||
gold 指标、特征、模型输出、报告结论
|
||||
```
|
||||
|
||||
### 8.2 核心实体
|
||||
|
||||
- `areas`：板块
|
||||
- `districts`：行政区
|
||||
- `neighborhoods`：小区
|
||||
- `transactions`：成交样本
|
||||
- `listings`：挂牌样本
|
||||
- `rents`：租赁样本
|
||||
- `new_projects`：新房项目
|
||||
- `land_sales`：土地成交
|
||||
- `policy_events`：政策事件
|
||||
- `rates`：利率
|
||||
- `area_monthly_features`：板块月度特征
|
||||
- `neighborhood_monthly_features`：小区月度特征
|
||||
- `model_runs`：模型运行版本
|
||||
- `watchlists`：观察池
|
||||
- `reports`：报告
|
||||
|
||||
### 8.3 数据治理要求
|
||||
|
||||
每条关键数据至少记录：
|
||||
|
||||
- 来源
|
||||
- 采集时间
|
||||
- 原始字段
|
||||
- 清洗规则版本
|
||||
- 是否估算
|
||||
- 是否人工修正
|
||||
- 置信度
|
||||
|
||||
这是系统长期可信的核心。
|
||||
|
||||
## 9. 模型体系
|
||||
|
||||
### 9.1 第一阶段：可解释评分
|
||||
|
||||
- 流动性评分
|
||||
- 价格动量评分
|
||||
- 成交动量评分
|
||||
- 租金支撑评分
|
||||
- 安全边际评分
|
||||
- 供应风险评分
|
||||
- 政策/信贷环境评分
|
||||
|
||||
输出：
|
||||
|
||||
- 重点研究
|
||||
- 观察池
|
||||
- 中性观望
|
||||
- 谨慎等待
|
||||
|
||||
### 9.2 第二阶段：相对估值
|
||||
|
||||
- 同板块小区比较
|
||||
- 相似小区比较
|
||||
- 同总价段比较
|
||||
- 同楼龄/地铁距离/物业类型比较
|
||||
- 历史价格分位
|
||||
|
||||
输出：
|
||||
|
||||
- 合理买入价区间
|
||||
- 溢价/折价解释
|
||||
- 替代标的推荐
|
||||
|
||||
### 9.3 第三阶段：预测与情景推演
|
||||
|
||||
先做情景推演，再做点预测。
|
||||
|
||||
情景变量：
|
||||
|
||||
- 利率
|
||||
- 首付比例
|
||||
- 限购/限贷政策
|
||||
- 新房供应
|
||||
- 租金变化
|
||||
- 板块产业兑现
|
||||
- 人口和就业变化
|
||||
|
||||
输出：
|
||||
|
||||
- 乐观/基准/谨慎情景
|
||||
- 价格压力区间
|
||||
- 流动性风险区间
|
||||
- 买入触发条件
|
||||
|
||||
## 10. 推荐仓库结构
|
||||
|
||||
```text
|
||||
apps/
|
||||
web/ React + TypeScript + shadcn/ui
|
||||
api/ Rust Axum + SQLx
|
||||
services/
|
||||
analytics/ Python 指标、模型、报告
|
||||
ingestion/ 数据采集与导入任务
|
||||
packages/
|
||||
contracts/ OpenAPI schema / shared types
|
||||
config/ 共享配置
|
||||
data/
|
||||
raw/
|
||||
bronze/
|
||||
silver/
|
||||
gold/
|
||||
sample/
|
||||
infra/
|
||||
docker-compose.yml
|
||||
migrations/
|
||||
docs/
|
||||
system_architecture_and_development_plan.md
|
||||
research_framework.md
|
||||
data_dictionary.md
|
||||
tests/
|
||||
```
|
||||
|
||||
当前 `src/shanghai_housing` 后续可以迁移到 `services/analytics`。
|
||||
|
||||
## 11. 开发路线
|
||||
|
||||
### Phase 0：研究内核验证，已开始
|
||||
|
||||
目标：
|
||||
|
||||
- 建立基本数据表
|
||||
- 建立板块评分
|
||||
- 生成月报
|
||||
- 验证指标口径
|
||||
|
||||
状态：
|
||||
|
||||
- 已完成 MVP。
|
||||
|
||||
### Phase 1：数据底座
|
||||
|
||||
目标：
|
||||
|
||||
- 引入 PostgreSQL/PostGIS
|
||||
- 建立 raw/bronze/silver/gold 数据分层
|
||||
- 建立数据源版本记录
|
||||
- 增加 CSV/Excel 导入
|
||||
- 增加官方数据手工导入模板
|
||||
|
||||
交付：
|
||||
|
||||
- 可导入真实数据
|
||||
- 可追踪数据来源
|
||||
- 可复跑指标
|
||||
|
||||
### Phase 2：API 与前端骨架
|
||||
|
||||
目标：
|
||||
|
||||
- 建立 API 服务
|
||||
- 建立 React 前端
|
||||
- 实现市场总览、板块列表、板块详情
|
||||
- 前端接入真实 API
|
||||
|
||||
推荐实现：
|
||||
|
||||
- 前端：Next.js + TypeScript + shadcn/ui
|
||||
- API：Rust Axum + SQLx
|
||||
- 数据库：PostgreSQL/PostGIS
|
||||
|
||||
交付：
|
||||
|
||||
- 可浏览市场总览
|
||||
- 可查看板块评分
|
||||
- 可生成并查看月报
|
||||
|
||||
### Phase 3：小区观察池
|
||||
|
||||
目标：
|
||||
|
||||
- 小区资产库
|
||||
- 小区评分
|
||||
- 合理买入价
|
||||
- 关注列表
|
||||
- 风险标签
|
||||
|
||||
交付：
|
||||
|
||||
- 小区筛选
|
||||
- 观察池
|
||||
- 标的对比
|
||||
- 投资备忘录
|
||||
|
||||
### Phase 4：模型与情景推演
|
||||
|
||||
目标：
|
||||
|
||||
- 历史分位
|
||||
- 相似资产比较
|
||||
- 异常成交检测
|
||||
- 利率/政策/供应情景推演
|
||||
|
||||
交付：
|
||||
|
||||
- 板块和小区估值解释
|
||||
- 买入价区间
|
||||
- 情景报告
|
||||
|
||||
### Phase 5：自动化与预警
|
||||
|
||||
目标：
|
||||
|
||||
- 定时数据更新
|
||||
- 指标重算
|
||||
- 报告自动生成
|
||||
- 预警规则
|
||||
|
||||
交付：
|
||||
|
||||
- 周报自动生成
|
||||
- 板块风险预警
|
||||
- 观察池价格变动提醒
|
||||
|
||||
## 12. 工程质量要求
|
||||
|
||||
### 12.1 数据质量
|
||||
|
||||
- 所有数据有来源和时间戳
|
||||
- 所有清洗规则版本化
|
||||
- 样本数据和真实数据严格隔离
|
||||
- 模型输出记录运行版本
|
||||
|
||||
### 12.2 API 质量
|
||||
|
||||
- OpenAPI 契约
|
||||
- 统一错误格式
|
||||
- 分页、排序、筛选
|
||||
- 请求日志
|
||||
- 慢查询追踪
|
||||
|
||||
### 12.3 前端质量
|
||||
|
||||
- 页面以研究工作流为中心
|
||||
- 表格、图表、地图是核心，不做装饰性首页
|
||||
- 所有图表口径可查看
|
||||
- 所有评分可解释
|
||||
- 重要结论可回溯到数据
|
||||
|
||||
### 12.4 测试
|
||||
|
||||
- 指标单元测试
|
||||
- 数据导入测试
|
||||
- API 契约测试
|
||||
- 前端组件测试
|
||||
- 端到端测试
|
||||
|
||||
## 13. 技术决策建议
|
||||
|
||||
推荐默认路线：
|
||||
|
||||
```text
|
||||
前端：Next.js + TypeScript + React + shadcn/ui
|
||||
API：Rust Axum + SQLx
|
||||
分析：Python + Polars + DuckDB
|
||||
数据库：PostgreSQL + PostGIS
|
||||
任务：先脚本/cron，后 Prefect 或 Airflow
|
||||
图表：Recharts 起步，复杂图表可加入 ECharts
|
||||
地图：MapLibre GL
|
||||
```
|
||||
|
||||
Python 分析服务保留为长期组件：
|
||||
|
||||
```text
|
||||
API：Rust Axum 负责在线服务
|
||||
Analytics：Python 负责研究、建模、报告和实验
|
||||
Stable ETL：Rust Polars/DataFusion 可逐步承接稳定高性能任务
|
||||
Contract：OpenAPI 或共享 schema
|
||||
```
|
||||
|
||||
这条路线从第一天就按强工程化平台建设，同时保留 Python 的研究效率。
|
||||
|
||||
## 14. 官方资料参考
|
||||
|
||||
- React TypeScript 文档：https://react.dev/learn/typescript
|
||||
- shadcn/ui 文档：https://ui.shadcn.com/
|
||||
- Next.js 文档：https://nextjs.org/docs
|
||||
- TanStack Query 文档：https://tanstack.com/query/latest/docs/framework/react/overview
|
||||
- Recharts 文档：https://recharts.org/en-US/
|
||||
- Axum 文档：https://docs.rs/axum/latest/axum/
|
||||
- SQLx 文档：https://docs.rs/sqlx/latest/sqlx/
|
||||
- Polars 文档：https://docs.pola.rs/
|
||||
- DataFusion 文档：https://datafusion.apache.org/user-guide/introduction.html
|
||||
- DuckDB 文档：https://duckdb.org/docs/
|
||||
- PostgreSQL 文档：https://www.postgresql.org/docs/
|
||||
Reference in New Issue
Block a user