11 KiB
11 KiB
蔬菜价格指数平台 — 产品设计文档
版本：1.2
状态：与《架构设计》对齐的 MVP 基线
范围：价格查询、指数趋势、价格榜单、历史数据；兼顾普通用户与专业用户
1. 文档目的与边界
目的：为前台信息架构、页面逻辑、交互与迭代节奏提供可执行的产品基线，避免过度设计。
边界：
- 采集、治理、指算法实现细节以《架构设计》与数据契约为准；本文不重复技术实现，仅约定产品可见的数据契约（口径、粒度、更新频率、异常说明）。
- 展示层技术栈与架构一致：Vue 或 React + ECharts，请求 Java（Spring Boot）REST API；契约以 OpenAPI 为单一描述时可与研发对齐字段与版本。
非目标（MVP 不做）：复杂自定义 BI 看板、拖拽式报表编排、重社交/Feed、非必要的账号体系（除非合规或商业化明确要求）。
2. 演示数据与正式数据源策略
目标：演示阶段快速跑通流程与界面；接正式源时仅更换数据供给与治理实现，不重做前台信息架构与主路径（「演示可快、正式可换」）。
2.1 演示阶段
- 数据形态：优先 CSV / JSON 静态样例，或「一次性从公开渠道导出的快照」；可由 Java 提供
/demo类只读接口（与《架构设计》中「展示层请求 Spring Boot」一致）。页面须显著标注「演示数据，非实时」。 - 字段与粒度：样例的字段名、时间粒度、单位（如元/公斤）按正式接入目标 schema 设计后再造数，避免为演示单独发明一套键名，导致接正式源时前台与契约大面积返工。
- 能力取舍：查询、趋势、榜单、历史 四条主路径做全；导出、多源合并、复杂权限 可后放。
2.2 接正式源阶段
- 单一数据契约：前台只依赖稳定字段（示例）：标准品种 ID、市场/区域、业务日期、价格类型、单位、数据来源 code、数据/配置版本；新发地、部里信息系统、采购或合同数据等，均仅在 采集 / 治理层 映射到同一套结构。
- 实现边界（与《架构设计》一致）：Python 仅写 raw；Java 负责治理、指数与 REST；演示数据源将来替换为「读取同结构的 clean / 指标表」时，前台路由与页面逻辑保持不变。
- 合规与运维：正式源须落实 授权或条款（开放 API、采购数据协议、是否允许抓取等）；界面与文档固定展示 数据来源、更新时间、免责声明；多源并存时禁止在无前缀说明的情况下 静默混源。
- 上线门禁：生产环境 长期自动化 拉取须满足《数据源上线清单》中的授权、SLA、观测告警与降级话术。
2.3 来源标识约定（评审落地）
- 演示数据：
source_code = DEMO（或等价字段，以后端字典为准）。 - 正式源：按接入顺序增加可枚举 code（示例：
XFD、MOA_…，具体以后端维表为准）。 - API 与 UI 均须透传
source_code（及必要时的config_version），便于对账、审计与用户理解，避免混源时说不清口径。
3. 用户画像
| 角色 | 典型目标 | 关键行为 | 主要痛点 |
|---|---|---|---|
| 普通用户 | 判断「某菜今天贵不贵」、大致涨跌 | 搜索品种、扫榜单、看短期趋势 | 术语多、不知看哪个指标、要求快、易懂 |
| 专业用户 | 区域/时段对比、报告引用、假设验证 | 多条件筛选、历史区间、导出与可复现链接 | 口径不透明、缺元数据与版本、批量诉求 |
| 运营/内容（内部） | 榜单规则、公告、异常说明与前台一致 | 管理端配置与审核（能力随管理端分期开放） | 前后口径不一致、难追溯 |
合规与信任（产品侧必显式满足）：
- 默认最小化个人信息；无必要不登录。
- 前台固定提供：指标定义、单位、数据来源说明、更新频率、免责声明；指数与算法变更建议带 config_version 或等价说明（与后端域模型一致）。
- 若存在地域/市场级敏感粒度，展示与导出遵循组织脱敏与权限策略（与架构中的鉴权/审计一致）。
4. 产品架构（信息架构）
4.1 前台模块与核心业务映射
| 业务 | 用户价值 | 前台模块 |
|---|---|---|
| 蔬菜价格查询 | 单点现价/均价与指数快照 | 查询（搜索 + 结果详情） |
| 指数趋势 | 时间维度变化与对比 | 趋势（默认折线图，ECharts） |
| 价格榜单 | 横向比较涨跌与价位 | 榜单（Tab：涨幅 / 跌幅 / 均价等，与数据就绪度对齐） |
| 历史数据 | 长区间查阅与摘录 | 历史（表格为主，图为辅） |
4.2 横切能力
- 口径与帮助：图表/榜单旁统一「i」入口 → 指标定义、基期、滞后、异常值处理原则（文案与数据版本绑定）。
- 深度链接：筛选条件写入 URL Query（便于专业用户书签与协作）；首屏性能由后端分页/汇总与可选缓存保障（见架构）。
- 多端：同一套 IA；移动端遵循「一屏一任务」：查询 → 结果 → 下钻趋势/榜单。
4.3 与管理端的关系（分期）
- MVP 前台可依赖 Java 侧已落库的指标与维表 只读展示；榜单规则、别名映射等以后端当前生效配置为准。
- 运营配置界面随 管理端 分期上线；产品需约定「配置变更 → 前台展示延迟与版本提示」行为。
5. 页面逻辑与用户路径
5.1 首页
- 入口：搜索框（品种联想）、热门品种快捷入口、今日概览（少数字卡片，避免信息堆叠）。
- 出口：进入查询结果、榜单默认 Tab、或「数据说明/口径」页。
5.2 查询（品种详情骨架）
- 用户输入 → 联想列表（标准品种名 + 别名命中规则由维表决定）。
- 结果页：现价/均价/指数（以 API 实际字段为准）、最近更新时点、看趋势、在榜单中的位置（若榜单 API 支持锚点）。
- 子模块：趋势、历史 与详情共用同一品种上下文（路由或 Query 保持一致）。
5.3 趋势
- 默认展示 近 30 天（或与后端默认聚合粒度一致的可配置区间）。
- MVP：单品种为主；P1：多品种对比、同比/环比（数据与公式就绪后开放，未就绪时灰显并链到口径说明）。
- 图表类型默认 折线；大数据量时以后端降采样或聚合区间为准，前端避免一次渲染过量点。
5.4 榜单
- Tab：建议 MVP 含「涨幅榜」「均价榜」；「跌幅榜」与数据源同步上线。
- 筛选器：与查询共用维度（如区域、品类），Sticky 在列表顶部（桌面端）；移动端收折为抽屉。
- 行点击 → 进入与查询共用的品种详情。
5.5 历史数据
- 时间范围选择 → 表格 + 分页（或虚拟滚动，以后端分页契约为准）。
- 图/表切换：MVP 可二选一优先「表」；图用 ECharts 轻量折线即可。
- 导出（P1）：CSV 等能力依赖 Java API 与权限设计；MVP 可用「复制链接」替代部分场景。
5.6 异常与空态（统一文案策略）
区分并分别引导：无数据、维护/延迟、筛选过窄；避免笼统「加载失败」。必要时链到状态页或公告（若 API 提供）。
6. 交互与视觉
6.1 布局原则
- 上：筛选与控制；中：主视觉（图或表）；下：口径、数据来源、免责声明。
- 避免三栏复杂仪表盘；一屏一主任务。
6.2 图表与色彩（ECharts）
- 涨跌语义色全站统一（建议色盲友好调色板）；图例可开关系列。
- 坐标轴：单位与时间格式可读；专业用户需支持 tooltip 精确值 与 缩放/拖拽（P1） 按性能评估开启。
6.3 性能与感知
- 首屏 骨架屏；列表与图表请求失败可重试；长时间查询显式进度或预估（若后端支持）。
6.4 无障碍（在成本可控内）
- 关键趋势附 数据摘要 或表格式兜底；对比度符合规范；筛选控件尽量支持键盘操作（分期）。
7. 功能优先级
7.1 MVP（第一期必交付）
- 品种搜索 + 联想 + 详情页（价格/指数快照 + 更新时点）。
- 单品种趋势（默认区间 + ECharts 折线）。
- 榜单至少一类核心榜（涨幅或均价）+ 基础筛选。
- 历史数据表格 + 分页。
- 静态或半静态的 数据说明 / 口径 / 免责声明（可独立路由页 + 全局页脚入口）。
7.2 P1
- 多品种对比、同比环比；更多榜单 Tab。
- 地域/市场维度扩展（与维表与 API 同步）。
- CSV 导出、带参 URL 全量覆盖筛选态。
- 简单反馈入口（非登录）。
7.3 刻意延后
- 自定义拖拽看板、复杂告警订阅、重运营活动页（除非有明确业务订单）。
8. 迭代规划（建议节奏）
| 阶段 | 目标 | 产品交付物 |
|---|---|---|
| 迭代 0 | 契约对齐 | 与研发确认 OpenAPI 首版字段：品种、时间粒度、指数 code、版本号、分页约定、source_code 与演示/正式切换策略 |
| 迭代 1 | 前台闭环 MVP | 查询、趋势、榜单、历史、口径页、空/异常态；演示数据标注与来源透传 |
| 迭代 2 | 专业增强 | 对比、导出、URL 状态、（如需）登录与权限可见范围 |
| 持续 | 信任与运维体验 | 数据延迟说明自动化、口径版本 Release Note、监控状态对用户可见（只读） |
9. 成功指标（轻量）
| 指标 | 说明 |
|---|---|
| 搜索成功率 | 有结果点击 / 搜索发起 |
| 详情二次行为率 | 从详情进入趋势或历史的比例 |
| 榜单点击率 | 反映横向比较需求是否被满足 |
| 口径页跳出率 | 过高则提示主界面指标仍不清晰 |
| 导出次数（P1） | 专业渗透度 |
10. 与研发的协作清单（产品需在评审前带齐）
- 默认时间粒度（日/周）与各页面默认区间。
- 指数列表：
index_code与用户可见中文名映射表。 - 地域/市场层级是否 MVP 开放及枚举来源。
- 榜单排序定义（涨幅计算公式引用版本号）。
- 延迟容忍：API
updated_at与前台展示策略。 - 错误码与用户文案映射表（含维护态）。
source_code枚举与「演示 / 正式」环境或开关策略；多源时混排规则与 UI 展示。
11. 修订记录
| 版本 | 日期 | 说明 |
|---|---|---|
| 1.0 | 2026-04-23 | 初稿，与《架构设计》v1.1 对齐 |
| 1.1 | 2026-04-23 | 新增「演示数据与正式数据源策略」；协作清单与迭代 0/1 补充 source_code 与来源透传 |
| 1.2 | 2026-04-23 | 与《数据源上线清单》互链；正式源持续采集门禁引用 |