# 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`