huheng-research/docs/product_roadmap.md

产品开发路线图

本文档是上海房市投资研究系统的执行路线图。目标是把当前 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
• 模型参数记录。

验收标准：

• 可比较不同模型版本的评分差异。
• 可复盘某次报告使用的模型版本。

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。