update at 2026-02-13 08:42:56

PRD.md

@@ -0,0 +1,106 @@
+# 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`