docs: add product roadmap

2026-06-23 18:06:11 +08:00
parent 1d5138d118
commit 13510c94d4
2 changed files with 407 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -116,3 +116,4 @@ docs/                           研究框架和数据字典
 当前项目是研究内核 MVP，不是最终产品形态。完整方案见：

 - [系统架构与开发计划](docs/system_architecture_and_development_plan.md)
+- [产品开发路线图](docs/product_roadmap.md)
--- a/docs/product_roadmap.md
+++ b/docs/product_roadmap.md
@@ -0,0 +1,406 @@
+# 产品开发路线图
+
+本文档是上海房市投资研究系统的执行路线图。目标是把当前 MVP 演进为可长期依赖的成熟研究产品。
+
+## 当前阶段
+
+当前系统处于 Alpha 早期：
+
+- 已有 Rust Axum API、PostgreSQL schema、Next.js 工作台。
+- 已有板块评分、小区评分、观察池和基础工作台。
+- 数据仍以样例数据为主，真实数据管线、权限、自动化、部署和监控尚未成熟。
+
+成熟产品的第一原则：
+
+- 任何结论都要能回溯到数据源。
+- 任何数据都要有来源、采集时间、处理版本和置信度。
+- 任何模型结果都要能复跑、解释和比较版本。
+- 前端必须服务研究决策流程，而不是只展示图表。
+
+## 里程碑总览
+
+| 阶段 | 名称 | 目标 | 状态 |
+| --- | --- | --- | --- |
+| M0 | 工程与研究骨架 | API、数据库、前端、样例评分跑通 | 已完成 |
+| M1 | 数据底座 | 数据源、导入批次、原始数据留痕、导入中心 | 进行中 |
+| M2 | 资产研究工作台 | 板块详情、小区详情、对比、观察池增强 | 待开发 |
+| M3 | 模型与回测 | 评分模型版本化、历史分位、相似资产、情景推演 | 待开发 |
+| M4 | 报告与预警 | 周报/月报、专题报告、观察池触发器 | 待开发 |
+| M5 | 产品化与运维 | 权限、部署、CI、监控、备份、安全 | 待开发 |
+
+## M1 数据底座
+
+### M1.1 数据源登记与导入批次审计
+
+目标：
+
+- 建立数据源目录的后台 API。
+- 记录每次导入任务的状态、来源、原始文件位置、行数、错误信息。
+
+交付物：
+
+- `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`
+
+验收标准：
+
+- 可以创建、查看数据源。
+- 可以创建导入批次并标记成功或失败。
+- 所有字段不包含真实密码或本地绝对敏感路径。
+
+### M1.2 前端导入中心
+
+目标：
+
+- 在前端工作台中查看数据源和导入批次。
+- 手工登记数据源和导入记录。
+
+交付物：
+
+- 数据源表格。
+- 导入批次表格。
+- 新增数据源表单。
+- 导入状态 badge。
+
+验收标准：
+
+- 前端能展示 API 返回的数据源和批次。
+- 可以登记一个数据源。
+- 可以创建一个导入批次并完成状态更新。
+
+### M1.3 CSV/Excel 导入模板
+
+目标：
+
+- 建立真实数据的标准导入模板。
+- 支持板块月度指标、小区月度指标、政策事件、土地成交。
+
+交付物：
+
+- `docs/import_templates/`
+- 后端导入校验接口。
+- Python analytics 导入脚本。
+
+验收标准：
+
+- 模板字段和数据库字段一一对应。
+- 错误数据能返回明确错误信息。
+- 导入结果写入 `raw`/`silver`/`audit`。
+
+### M1.4 原始数据留存与文件哈希
+
+目标：
+
+- 每次导入都记录原始文件位置、哈希、大小和导入人。
+
+交付物：
+
+- `audit.raw_artifacts`
+- 导入批次关联 raw artifact。
+
+验收标准：
+
+- 同一文件重复导入可识别。
+- 任一指标可以追溯到原始数据批次。
+
+## M2 资产研究工作台
+
+### M2.1 板块详情页
+
+目标：
+
+- 从市场总览进入单个板块，查看成交、挂牌、租金、供应、小区排行。
+
+交付物：
+
+- 板块详情 API。
+- 板块详情前端视图。
+- 板块内小区排行和观察池入口。
+
+验收标准：
+
+- 选择任一板块可查看该板块完整指标。
+- 图表和表格口径明确。
+
+### M2.2 小区详情页
+
+目标：
+
+- 查看单个小区的资产画像、评分、历史指标和观察池状态。
+
+交付物：
+
+- 小区详情 API。
+- 小区详情前端视图。
+- 合理买入价区间占位。
+
+验收标准：
+
+- 小区详情能展示基础属性、月度指标、评分拆解。
+- 可从详情页加入观察池。
+
+### M2.3 对比工作台
+
+目标：
+
+- 支持板块对比、小区对比。
+
+交付物：
+
+- 对比选择器。
+- 对比表格。
+- 雷达图或指标矩阵。
+
+验收标准：
+
+- 至少支持 2-4 个小区并排比较。
+- 关键指标包括价格、流动性、租金、楼龄、地铁距离、供应压力。
+
+### M2.4 观察池增强
+
+目标：
+
+- 观察池从简单列表升级为投资跟踪工具。
+
+交付物：
+
+- 目标价、触发条件、状态、标签、备注。
+- 更新历史。
+- 观察池筛选。
+
+验收标准：
+
+- 可以区分 active、paused、archived。
+- 可以按板块、小区、状态筛选。
+
+## M3 模型与回测
+
+### M3.1 模型运行版本化
+
+目标：
+
+- 所有评分结果关联模型版本和运行批次。
+
+交付物：
+
+- `gold.model_runs`
+- 评分表关联 `model_run_id`
+- 模型参数记录。
+
+验收标准：
+
+- 可比较不同模型版本的评分差异。
+- 可复盘某次报告使用的模型版本。
+
+### M3.2 历史分位与异常检测
+
+目标：
+
+- 建立价格、成交量、租金收益率、库存压力的历史分位。
+- 识别异常成交和异常挂牌。
+
+交付物：
+
+- 历史分位 API。
+- 异常检测字段。
+
+验收标准：
+
+- 每个板块和小区可看到当前处于历史什么位置。
+- 异常样本不会污染核心评分。
+
+### M3.3 相似资产比较
+
+目标：
+
+- 根据板块、总价、楼龄、地铁距离、物业类型匹配相似小区。
+
+交付物：
+
+- 相似小区 API。
+- 相似资产前端视图。
+
+验收标准：
+
+- 单个小区能返回 5-10 个可解释相似标的。
+- 能显示相对溢价或折价。
+
+### M3.4 情景推演
+
+目标：
+
+- 评估利率、政策、供应、租金变化对价格和流动性的影响。
+
+交付物：
+
+- 情景参数表单。
+- 乐观、基准、谨慎三档结果。
+
+验收标准：
+
+- 输入参数可保存。
+- 输出有明确假设和风险解释。
+
+## M4 报告与预警
+
+### M4.1 报告中心
+
+目标：
+
+- 将 Markdown 报告产品化。
+
+交付物：
+
+- 报告表。
+- 报告 API。
+- 前端报告中心。
+
+验收标准：
+
+- 可查看月报、板块专题、小区备忘录。
+- 报告结论关联结构化指标。
+
+### M4.2 自动周报/月报
+
+目标：
+
+- 定时生成市场周报和月报。
+
+交付物：
+
+- 报告任务。
+- 报告模板。
+- 报告生成记录。
+
+验收标准：
+
+- 可手工触发。
+- 可查看生成状态和错误信息。
+
+### M4.3 观察池预警
+
+目标：
+
+- 对价格、挂牌、成交、评分变化进行提醒。
+
+交付物：
+
+- 预警规则表。
+- 预警事件表。
+- 前端预警列表。
+
+验收标准：
+
+- 观察池标的达到目标价或风险条件时生成事件。
+
+## M5 产品化与运维
+
+### M5.1 数据库账户与权限
+
+目标：
+
+- 拆分管理员、迁移、应用、只读账户。
+
+交付物：
+
+- 数据库 role migration。
+- 环境变量文档。
+
+验收标准：
+
+- API 不使用管理员账户。
+- 只读账户不能写入业务表。
+
+### M5.2 认证与授权
+
+目标：
+
+- 支持登录和角色权限。
+
+交付物：
+
+- 用户表。
+- Session/JWT 方案。
+- 前端登录态。
+
+验收标准：
+
+- 未登录不能访问内部 API。
+- 用户角色控制写入权限。
+
+### M5.3 Docker 与部署
+
+目标：
+
+- 支持稳定部署和本地一键启动。
+
+交付物：
+
+- `infra/docker-compose.yml`
+- API Dockerfile。
+- Web Dockerfile。
+- migration job。
+
+验收标准：
+
+- 新环境可按文档启动。
+- migration 独立执行。
+
+### M5.4 CI 与质量门禁
+
+目标：
+
+- 每次提交自动运行测试和构建。
+
+交付物：
+
+- CI workflow。
+- Rust test。
+- Python test。
+- Web typecheck/build。
+
+验收标准：
+
+- 任一测试失败不能合并。
+
+### M5.5 监控、日志和备份
+
+目标：
+
+- 系统可运维、可恢复。
+
+交付物：
+
+- 结构化日志。
+- 健康检查。
+- 数据库备份策略。
+- 错误追踪。
+
+验收标准：
+
+- API 错误能定位。
+- 数据库可按时间点恢复。
+
+## 当前推荐开发顺序
+
+1. M1.1 数据源登记与导入批次审计。
+2. M1.2 前端导入中心。
+3. M1.3 CSV/Excel 导入模板。
+4. M2.1 板块详情页。
+5. M2.2 小区详情页。
+6. M2.4 观察池增强。
+7. M3.1 模型运行版本化。
+8. M4.1 报告中心。
+9. M5.1 数据库账户与权限。
+10. M5.3 Docker 与部署。
+
+## 提交规则
+
+- 一个可验收功能一个 commit。
+- 文档变更可以独立 commit。
+- 不提交真实数据库密码、`.env`、本地构建产物。
+- 每个功能至少通过相关测试；涉及前端的功能需要浏览器验证。
+- 暂时只本地 commit，不 push。