Tools/huheng-research
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
c605541c8022783ff593ac13956233462ad0202a
huheng-research/docs/system_architecture_and_development_plan.md

14 KiB
Raw Blame History

上海房市投资研究系统架构与开发计划

0. 当前状态

当前项目是一个纯 Python 的研究内核 MVP：

  • SQLite 存储
  • 样例数据
  • 板块指标计算
  • Markdown 月报生成
  • 命令行入口

它的价值是验证研究口径和指标框架。它不是最终系统形态。后续应演进为一个具备数据采集、资产库、模型、API、前端看板、报告和预警能力的长期研究平台。

1. 系统定位

目标是搭建一个面向上海房市长期投资判断的研究操作系统。系统最终要回答：

  • 市场处在什么周期位置？
  • 哪些板块值得重点跟踪？
  • 哪些小区具有流动性、租金和稀缺性支撑？
  • 合理买入价区间是多少？
  • 什么信号触发买入、观望、卖出或换仓？
  • 判断依据是否可复盘、可解释、可更新？

系统不追求单点预测“下月涨跌”，而追求持续形成稳定的投资判断流程。

2. 总体架构

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 更研究化”。本系统的最佳分工是：

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 数据分层

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. 推荐仓库结构

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. 技术决策建议

推荐默认路线：

前端：Next.js + TypeScript + React + shadcn/ui
API：Rust Axum + SQLx
分析：Python + Polars + DuckDB
数据库：PostgreSQL + PostGIS
任务：先脚本/cron，后 Prefect 或 Airflow
图表：Recharts 起步，复杂图表可加入 ECharts
地图：MapLibre GL

Python 分析服务保留为长期组件：

API：Rust Axum 负责在线服务
Analytics：Python 负责研究、建模、报告和实验
Stable ETL：Rust Polars/DataFusion 可逐步承接稳定高性能任务
Contract：OpenAPI 或共享 schema

这条路线从第一天就按强工程化平台建设，同时保留 Python 的研究效率。

14. 官方资料参考