# 上海房市投资研究系统架构与开发计划
## 0. 当前状态
当前项目是一个纯 Python 的研究内核 MVP：
- SQLite 存储
- 样例数据
- 板块指标计算
- Markdown 月报生成
- 命令行入口
它的价值是验证研究口径和指标框架。它不是最终系统形态。后续应演进为一个具备数据采集、资产库、模型、API、前端看板、报告和预警能力的长期研究平台。
## 1. 系统定位
目标是搭建一个面向上海房市长期投资判断的研究操作系统。系统最终要回答：
- 市场处在什么周期位置？
- 哪些板块值得重点跟踪？
- 哪些小区具有流动性、租金和稀缺性支撑？
- 合理买入价区间是多少？
- 什么信号触发买入、观望、卖出或换仓？
- 判断依据是否可复盘、可解释、可更新？
系统不追求单点预测“下月涨跌”，而追求持续形成稳定的投资判断流程。
## 2. 总体架构
```mermaid
flowchart LR
A["数据源
官方/市场/手工/文档"] --> B["采集层
Ingestion"]
B --> C["原始数据层
Raw Lake"]
C --> D["标准化层
Normalized Store"]
D --> E["特征与指标层
Feature Mart"]
E --> F["模型层
Scoring/Forecast/Scenario"]
F --> G["API 层
Rust Axum"]
G --> H["前端
React + TypeScript + shadcn/ui"]
F --> I["报告与预警
周报/月报/观察池"]
D --> J["研究工作台
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/