4.2 KiB
4.2 KiB
PRD.md
1. 文档目的
本文件定义「星程桑基图」的产品需求合同（v0.1），用于约束范围、功能验收标准与成功标准。
关联文档：
- APP_FLOW.md
- TECH_STACK.md
- FRONTEND_GUIDELINES.md
- BACKEND_STRUCTURE.md
- IMPLEMENTATION_PLAN.md
2. 产品概述
星程桑基图是一个本地优先的数据可视化工具，用户上传 csv/xls/xlsx 后，通过列映射规则生成桑基图，支持实时预览、主题切换与 PNG/SVG 导出。
3. 目标用户
- 数据分析师：快速从表格生成流向关系图。
- 业务运营人员：无需编程即可配置 source/target 映射。
- 演示与汇报人员：导出图用于文档与汇报。
4. 核心问题
- 表格到桑基图映射过程复杂，人工制作耗时。
- Excel 存在“合并单元格语义”（下方空值继承上方值），常规可视化工具处理不稳定。
- 需要稳定导出图像用于跨平台传播。
5. 产品目标（Goals）
- G1：用户可在 3 分钟内完成一次从上传到导出的全流程。
- G2：支持目标描述列的“向下补全”语义并正确聚合。
- G3：在映射配置变更后即时刷新预览，避免重复上传。
- G4：导出结果可直接用于 PPT/文档（PNG、SVG）。
6. 非目标（Non-Goals）
- 不做账号体系、登录、权限。
- 不做云端存储、多人协作、历史版本。
- 不做后端 API 与数据库（见 BACKEND_STRUCTURE.md）。
- 不做三级/多级桑基图编辑器（当前仅由列拼接形成单级 source->target 关系）。
- 不做 APP 端正式实现（仅保留小程序骨架）。
7. 功能范围与验收标准
F1 文件上传与默认样例
需求：支持点击与拖拽上传；首次进入自动加载样例文件。
验收标准：
- 支持扩展名：
.csv/.xls/.xlsx。 - 首次加载时，若用户未上传文件，自动读取
data/example0.xlsx。 - 上传成功后，显示文件名与行数。
- 上传失败时展示明确错误信息。
F2 列映射配置
需求：支持 source 数据列单选、source 描述列多选、target 描述列多选。
验收标准：
source data为单选且必选。source description可为空；为空时回退为 source data 单元格文本。target description为多选且至少选择 1 列。- 映射变更后无需点击“生成”，图表实时刷新。
F3 聚合规则
需求：按映射配置构建 nodes/links 并做容错。
验收标准：
- source 数值支持千分位解析，如
12,000。 - 非法 source 数值（空或非数字）跳过并记录告警。
- target 描述列支持“向下补全”（空值继承上一次非空值）。
- source/target 描述为空行跳过并记录告警。
- 相同
sourceName@@targetName累加值。
F4 预览与交互
需求：提供可视化预览并支持关键配置。
验收标准：
- 支持方向切换：
source->target/target->source（仅交换链接方向）。 - 支持节点间距（gap）与图内边距（padding）调整。
- 支持主题选择并应用到节点颜色。
- 支持“目标总和”显示开关（只影响 target 标签展示，不影响聚合值）。
F5 导出
需求：支持导出 SVG 与 PNG。
验收标准：
- 文件名格式：
sankey_YYYYMMDD_HHmmss.svg|png。 - PNG 使用
pixelRatio=2导出。 - 若 DOM 可获取
<svg>，优先序列化导出 SVG，否则使用图表实例导出。
F6 小程序骨架
需求：提供页面结构与视觉骨架，不承诺完整业务逻辑。
验收标准：
- 存在页面结构、列选择区、主题底部弹层。
- 明确标注为“骨架”，不作为完整功能验收对象。
8. 成功标准（Success Metrics）
- S1：核心单元测试稳定通过（
npm run test）。 - S2：类型检查与 lint 稳定通过（
npm run type-check && npm run lint）。 - S3：核心样例
data/example0.xlsx可在默认加载后正常出图。 - S4：导出文件在本地可打开且内容与当前视图一致。
9. 约束与依赖
- 技术实现必须遵循 TECH_STACK.md 固定版本。
- UI 实现必须遵循 FRONTEND_GUIDELINES.md 设计规范。
- 不得在未确认情况下引入新生产依赖。
10. 版本状态
- 当前合同版本：
v0.1 - 最后更新：
2026-02-13