sankey/PRD.md

PRD.md

1. 文档目的

本文件定义「星程桑基图」的产品需求合同（v0.2），用于约束范围、功能验收标准与成功标准。

关联文档：

• 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 关系）。
• 不做账号体系下的小程序云同步与跨端协作。
• 不追求 Web 与小程序像素级一致，只要求关键流程一致可用。

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）调整。
• 支持主题选择并应用到节点颜色。
• 支持标签位置、汇聚对齐等关键可视化配置。

F5 导出

需求：支持导出 SVG 与 PNG。

验收标准：

• 文件名格式：sankey_YYYYMMDD_HHmmss.svg|png。
• PNG 使用 pixelRatio=2 导出。
• 若 DOM 可获取 <svg>，优先序列化导出 SVG，否则使用图表实例导出。

F6 小程序可用版

需求：提供轻量可用的小程序版本，覆盖上传、映射、预览、导出主流程。

验收标准：

• 支持上传 csv/xls/xlsx 并完成解析。
• 支持默认映射、列选择、聚合构建与日志展示。
• 支持原生 canvas 预览。
• 支持导出 PNG（保存相册）与 SVG（生成文件并可访问路径）。

8. 成功标准（Success Metrics）

• S1：核心单元测试稳定通过（npm run test）。
• S2：类型检查与 lint 稳定通过（npm run type-check && npm run lint）。
• S3：核心样例 data/example0.xlsx 可在默认加载后正常出图。
• S4：导出文件在本地可打开且内容与当前视图一致。
• S5：小程序端可独立完成“上传 -> 映射 -> 预览 -> 导出”闭环。

9. 约束与依赖

• 技术实现必须遵循 TECH_STACK.md 固定版本。
• UI 实现必须遵循 FRONTEND_GUIDELINES.md 设计规范。
• 不得在未确认情况下引入新生产依赖。

10. 版本状态

• 当前合同版本：v0.2
• 最后更新：2026-02-13