# 产品开发路线图 本文档是上海房市投资研究系统的执行路线图。目标是把当前 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 导入脚本。 - `config/import_templates.json` 作为模板规格源。 验收标准： - 模板字段和现有研究表字段一一对应。 - 错误数据能返回明确错误信息。 - Python CLI 可以校验 CSV/Excel，并将已支持模板写入本地研究库。 - API 可以校验导入行的表头、类型、值域、日期、枚举和敏感文本。 ### M1.4 原始数据留存与文件哈希 状态：已完成。 目标： - 每次导入都记录原始文件位置、哈希、大小、导入人和入库批次。 - 将原始文件资产与 `audit.ingestion_runs` 关联，支持重复文件识别。 交付物： - `audit.raw_artifacts` - 导入批次关联 raw artifact。 - `GET /api/v1/raw-artifacts` - `POST /api/v1/raw-artifacts` - Python 文件指纹命令。 验收标准： - 同一文件重复导入可识别。 - 任一指标可以追溯到原始数据批次。 ### M1.5 PostgreSQL 导入执行接口 状态：已完成。 目标： - 将已校验模板数据正式写入 PostgreSQL 的 `raw`/`silver`/`audit`。 - 导入执行必须关联 `audit.ingestion_runs` 和 `audit.raw_artifacts`。 交付物： - `POST /api/v1/imports/execute` - `raw.import_rows` 原始行 JSON 留痕。 - 支持板块月度指标和小区月度指标的 upsert。 - 导入失败时写入明确错误并保留审计记录。 验收标准： - 校验失败不写入业务表。 - 导入成功后可通过批次追溯到原始文件哈希。 - 重复导入同一文件时能识别并提示。 - 当前执行范围：`area_monthly_metrics`、`neighborhood_monthly_metrics`。 ### M1.6 导入后评分重算与追溯闭环 状态：已完成。 目标： - 将导入后的 `silver.area_monthly_metrics` 重算为 `gold.area_scores`。 - 记录模型运行批次，支持评分版本追溯。 - 支持从评分追溯到指标、导入批次和原始文件哈希。 交付物： - `gold.model_runs` - `POST /api/v1/model-runs/area-scores` - `GET /api/v1/areas/{area_id}/score-lineage?month=YYYY-MM` - Rust 版板块评分模型，与 Python 研究内核保持同一口径。 验收标准： - 指定月份可重算板块评分。 - 每次评分关联 `model_run_id` 和 `model_version`。 - 单个板块评分可追溯到 `ingestion_run_id`、`raw_artifact_id` 和 `sha256`。 ## M2 资产研究工作台 ### M2.1 板块详情页 状态：已完成。 目标： - 从市场总览进入单个板块，查看成交、挂牌、租金、供应、小区排行。 交付物： - 板块详情 API。 - 板块详情前端视图。 - 板块内小区排行和观察池入口。 - 评分数据追溯展示。 验收标准： - 选择任一板块可查看该板块完整指标。 - 图表和表格口径明确。 ### M2.2 小区详情页 状态：已完成。 目标： - 查看单个小区的资产画像、评分、历史指标和观察池状态。 交付物： - `GET /api/v1/neighborhoods/{neighborhood_id}/detail?month=YYYY-MM`。 - 小区详情前端视图，包含资产画像、评分拆解、月度趋势和指标历史。 - 合理买入价区间占位，以观察价区间形式展示。 - 从小区排行和板块详情进入小区详情。 - 详情页可直接加入观察池，并展示当前观察池状态。 验收标准： - 小区详情能展示基础属性、月度指标、评分拆解。 - 可从详情页加入观察池。 - 小区历史指标可追溯到导入批次和原始文件。 ### M2.3 对比工作台 状态：已完成。 目标： - 支持板块对比、小区对比。 交付物： - `GET /api/v1/compare/areas?month=YYYY-MM&ids=a,b`。 - `GET /api/v1/compare/neighborhoods?month=YYYY-MM&ids=a,b`。 - 板块与小区对比选择器，支持 2-4 个标的。 - 对比矩阵与雷达图。 - 缺失标的提示。 验收标准： - 至少支持 2-4 个小区并排比较。 - 关键指标包括价格、流动性、租金、楼龄、地铁距离、供应压力。 - API 返回 requested、missing、items 和 metrics，前端按统一口径展示。 ### M2.4 观察池增强 状态：已完成。 目标： - 观察池从简单列表升级为投资跟踪工具。 交付物： - 目标价、触发条件、状态、标签、优先级、备注。 - `PATCH /api/v1/watchlist/{watchlist_item_id}` 支持状态、触发价、标签、复核时间更新。 - `GET/POST /api/v1/watchlist/{watchlist_item_id}/events` 更新历史。 - 观察池筛选：状态、板块、标签。 - 前端观察池增强表单、筛选器、状态切换、复核、历史展开。 验收标准： - 可以区分 active、paused、archived。 - 可以按板块、小区、状态筛选。 - 任一观察标的可记录人工事件和复核时间。 ## M3 模型与回测 ### M3.1 模型运行版本化 状态：已完成。 目标： - 所有评分结果关联模型版本和运行批次。 交付物： - `gold.model_runs` - 评分表关联 `model_run_id` - 模型参数记录。 - `GET /api/v1/model-runs` - `GET /api/v1/model-runs/area-scores/diff?base_run_id=&candidate_run_id=` - 前端模型运行中心，可触发板块评分重算并比较两个批次差异。 验收标准： - 可比较不同模型版本的评分差异。 - 可复盘某次报告使用的模型版本。 ### M3.2 历史分位与异常检测 状态：已完成。 目标： - 建立价格、成交量、租金收益率、库存压力的历史分位。 - 识别异常成交和异常挂牌。 交付物： - `GET /api/v1/areas/{area_id}/diagnostics?month=YYYY-MM`。 - 板块详情返回历史分位与异常检测字段。 - 前端板块详情展示成交均价、成交量、租金收益率、库存压力的历史分位。 验收标准： - 每个板块和小区可看到当前处于历史什么位置。 - 异常样本不会污染核心评分。 - 当前完成板块级诊断，小区级诊断进入 M3.3/M3 后续资产扩展。 ### M3.3 相似资产比较 状态：已完成。 目标： - 根据板块、总价、楼龄、地铁距离、物业类型匹配相似小区。 交付物： - `GET /api/v1/neighborhoods/{neighborhood_id}/similar?month=YYYY-MM&limit=8`。 - 小区详情返回 `similar_neighborhoods`。 - 前端小区详情展示相似度、相对溢价/折价、成交均价、综合分和匹配原因。 验收标准： - 单个小区能返回 5-10 个可解释相似标的。 - 能显示相对溢价或折价。 ### M3.4 情景推演 状态：已完成。 目标： - 评估利率、政策、供应、租金变化对价格和流动性的影响。 交付物： - `app.scenario_runs` 保存情景假设。 - `GET /api/v1/scenario-runs` 查看已保存假设。 - `POST /api/v1/scenario-runs` 保存假设并返回谨慎、基准、乐观三档板块推演结果。 - 前端情景参数表单、历史假设列表、三档结果表。 验收标准： - 输入参数可保存。 - 输出有明确假设、分数变化、价格变化、流动性、供应风险和风险解释。 - 当前完成板块级情景推演，小区级敏感性分析进入后续扩展。 ## M4 报告与预警 ### M4.1 报告中心 状态：已完成。 目标： - 将 Markdown 报告产品化。 交付物： - `app.reports` 报告表。 - `GET /api/v1/reports`、`GET /api/v1/reports/{report_id}`、`POST /api/v1/reports`。 - 前端报告中心，支持月报、板块专题、小区备忘录的草稿创建、列表过滤和 Markdown 查看。 验收标准： - 可查看月报、板块专题、小区备忘录。 - 报告结论关联结构化指标。 - 当前完成人工创建与查看，自动生成进入 M4.2。 ### M4.2 自动周报/月报 状态：已完成。 目标： - 定时生成市场周报和月报。 交付物： - `app.report_templates` 报告模板表。 - `app.report_generation_runs` 报告生成记录表。 - `GET /api/v1/report-templates`。 - `GET /api/v1/report-generation-runs`。 - `POST /api/v1/report-generation-runs` 手工触发市场月报和观察池周报生成。 - 前端报告中心支持选择模板、触发生成、查看生成状态和产出报告。 验收标准： - 可手工触发。 - 可查看生成状态和错误信息。 - 当前完成可手工触发的任务化生成，后续定时调度可复用同一 API。 ### 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。