544 lines
14 KiB
Markdown
544 lines
14 KiB
Markdown
# 上海房市投资研究系统架构与开发计划
|
||
|
||
## 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/
|