# 蔬菜价格指数平台 — 产品设计文档

> 版本：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、采购数据协议、是否允许抓取等）；界面与文档固定展示 **数据来源、更新时间、免责声明**；多源并存时禁止在无前缀说明的情况下 **静默混源**。
- **上线门禁**：生产环境 **长期自动化** 拉取须满足《[数据源上线清单](./数据源上线清单.md)》中的授权、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 查询（品种详情骨架）

1. 用户输入 → **联想列表**（标准品种名 + 别名命中规则由维表决定）。
2. **结果页**：现价/均价/指数（以 API 实际字段为准）、最近更新时点、**看趋势**、**在榜单中的位置**（若榜单 API 支持锚点）。
3. 子模块：**趋势**、**历史** 与详情共用同一品种上下文（路由或 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（第一期必交付）

1. 品种搜索 + 联想 + 详情页（价格/指数快照 + 更新时点）。
2. 单品种趋势（默认区间 + ECharts 折线）。
3. 榜单至少一类核心榜（涨幅或均价）+ 基础筛选。
4. 历史数据表格 + 分页。
5. 静态或半静态的 **数据说明 / 口径 / 免责声明**（可独立路由页 + 全局页脚入口）。

### 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 | 与《数据源上线清单》互链；正式源持续采集门禁引用 |