diff --git a/README.md b/README.md index 952745e..98886d0 100644 --- a/README.md +++ b/README.md @@ -116,3 +116,4 @@ docs/ 研究框架和数据字典 当前项目是研究内核 MVP,不是最终产品形态。完整方案见: - [系统架构与开发计划](docs/system_architecture_and_development_plan.md) +- [产品开发路线图](docs/product_roadmap.md) diff --git a/docs/product_roadmap.md b/docs/product_roadmap.md new file mode 100644 index 0000000..65a5e41 --- /dev/null +++ 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。