# 星程桑基图（`todo.md`）详细实现方案

## 1. 目标与范围

### 1.1 项目目标
- 构建一个可在 `Web` 与 `微信小程序` 使用的桑基图制作工具。
- 支持用户上传 `Excel/CSV`，通过列映射配置自动生成桑基图节点与连线。
- 支持图表配置（方向、配色、间距）与导出（`PNG`、`SVG`）。
- 提供标准模板文件，降低数据准备成本。

### 1.2 本期范围（MVP）
- 文件上传与解析（`xlsx/csv`）。
- 列选择映射（`source data`、`source description`、`target description`）。
- 基于“合并单元格语义”的 target 聚合计算（按 target 描述聚合 source 数值）。
- 桑基图渲染与基础交互（缩放/悬浮提示）。
- 导出 `PNG/SVG`。
- 基础配置项：方向、配色、节点间距（gap/padding）。

### 1.3 暂不纳入本期
- 用户账号、云端存储、多人协作。
- 历史版本管理与回滚。
- 大屏动画编排、复杂主题系统。

## 2. 技术与工程方案

### 2.1 技术选型
- Web：`Vue 3 + TypeScript + Vite`。
- 图表：`ECharts Sankey`（Web 直接渲染；小程序可复用 ECharts 小程序适配方案）。
- 数据解析：
  - `csv`：轻量解析器（如 `papaparse`）或自研分隔处理（优先可维护方案）。
  - `xlsx`：`SheetJS (xlsx)`（仅用于读取，不引入重型扩展能力）。
- 导出：
  - `SVG`：图表实例导出或序列化容器 SVG。
  - `PNG`：基于 `canvas`/图表导出接口生成并下载。

### 2.2 架构分层（Web 与小程序共用核心）
- `core/`（可复用纯函数层）
  - 文件解析适配（CSV/XLSX -> 统一二维表结构）。
  - 列映射与数据清洗。
  - 节点/边构建算法（Sankey 输入结构）。
  - 校验与错误码。
- `web/`（Vue 页面）
  - 上传、映射配置、预览表格、图表渲染、导出。
- `miniapp/`（后续）
  - 复用 `core` 算法，仅替换 UI/上传/导出实现。

## 3. 数据模型与规则定义

### 3.1 输入数据统一模型
- `RawTable`
  - `headers: string[]`
  - `rows: string[][]`
- 列索引统一使用 `0-based`，UI 展示使用“列名 + 1-based 序号”。

### 3.2 用户映射配置模型
- `sourceDataColumn: number`（必填，数值列）
- `sourceDescriptionColumns: number[]`（可空，空则回退为 `sourceDataColumn`）
- `targetDescriptionColumns: number[]`（必填）
- `delimiter: string`（默认 `-`）

### 3.3 业务规则（来自 `todo.md`）
- `source`：
  - `value` 取 `sourceDataColumn`。
  - `name` 由 `sourceDescriptionColumns` 拼接；若未配置则使用 `sourceDataColumn` 文本。
- `target`：
  - `name` 由 `targetDescriptionColumns` 拼接。
  - 多行若 target 名称一致，视为“合并单元格语义”，其 `value` 为对应 source 数值求和。
- 空值处理：
  - 参与拼接时忽略空串，但保留字段顺序。
  - `source value` 非法（空/非数值）时记录错误并默认跳过该行。

### 3.4 输出结构（供桑基图渲染）
- `nodes: Array<{ name: string; kind: "source" | "target" }>`
- `links: Array<{ source: string; target: string; value: number }>`
- `meta: { droppedRows: number; warnings: string[] }`

## 4. 核心算法设计

### 4.1 处理流程
1. 读取文件 -> 统一 `RawTable`。
2. 基于映射配置遍历每一行，构造 `sourceName/sourceValue/targetName`。
3. 使用 `Map<string, number>` 以键 `sourceName@@targetName` 累加 `value`。
4. 从聚合结果提取 `nodes/links`，去重节点。
5. 输出告警信息（非法值、空 target、全空行等）。

### 4.2 关键细节
- 数值解析支持千分位、空格清理（如 `"12,000"` -> `12000`）。
- 统一字符串 `trim`，避免同名节点因空格被拆分。
- 当方向切换为 `target -> source` 时，仅交换链接方向，不改原始聚合逻辑。

## 5. 页面与交互方案（Web）

### 5.1 页面结构
- `上传区`：拖拽/点击上传，显示文件名与解析状态。
- `列映射区`：
  - 选择 `source data`（单选）。
  - 选择 `source description`（多选，可空）。
  - 选择 `target description`（多选，必填）。
  - 实时生成示例文本（如：`宁波北欧10-2582 -> 嘉兴四级算力池-11623-小模型`）。
- `图表区`：桑基图预览。
- `配置区`：方向、配色方案、节点间距（gap/padding）。
- `导出区`：下载 `PNG`、`SVG`、模板文件。

### 5.2 交互约束
- 未完成必填映射前禁用“生成图表”。
- 显示解析异常明细（行号 + 错误原因）。
- 切换配置时图表实时刷新，不重新解析文件。

## 6. 导出与模板方案

### 6.1 导出
- `SVG`：优先使用图表库原生导出能力，确保矢量质量。
- `PNG`：支持倍率参数（默认 `2x`）以保证清晰度。
- 文件命名：`sankey_YYYYMMDD_HHmmss.png|svg`。

### 6.2 模板
- 提供 `csv` 与 `xlsx` 两份模板，含示例数据与列说明。
- 模板首行固定列名，便于自动映射建议。

## 7. 小程序落地策略

### 7.1 复用策略
- `core` 代码以纯 TypeScript 编写，不依赖 DOM。
- 小程序端复用 `core`，仅替换：
  - 文件读取适配层。
  - 图表组件容器。
  - 导出能力（若受限，首期可仅支持图片保存）。

### 7.2 分阶段接入
- 第一期先完成 Web 全流程。
- 第二期迁移至小程序并补齐端差异。

## 8. 测试与质量保障

### 8.1 单元测试（核心）
- 文件解析：
  - CSV 基础解析、空值、引号、逗号场景。
  - XLSX 读取与表头提取。
- 业务聚合：
  - target 合并语义正确性。
  - source/target 描述回退逻辑。
  - 非法数值行过滤。
- 输出结构：
  - 节点去重、连线值聚合。

### 8.2 组件与集成测试
- 上传 -> 映射 -> 生成图 -> 导出全链路。
- 配置项修改触发图表更新。
- 错误提示可见性与可读性。

### 8.3 质量门禁
- `lint`、`type-check`、`test` 全通过后合并。
- 对关键样例建立快照（链接与节点数量、总流量）。

## 9. 里程碑与任务拆分

### M1：项目骨架与核心解析（2 天）
- 初始化 Vue3 + TS 工程结构。
- 完成 `core`：CSV/XLSX 解析、列映射模型、聚合算法。
- 输出可直接喂给 Sankey 的 `nodes/links`。

### M2：Web MVP 页面与图表（2 天）
- 完成上传区、映射区、图表区。
- 接入 Sankey 渲染与方向/间距配置。
- 增加错误提示与示例预览。

### M3：导出与模板（1 天）
- 实现 PNG/SVG 导出。
- 增加模板下载入口与示例文件。

### M4：测试完善与发布准备（1 天）
- 补齐单元测试与集成测试。
- 完成 lint/type-check/test，修复问题。
- 输出使用说明文档（含列映射示例）。

## 10. 风险与应对

- 风险：Excel“合并单元格”在导出为值时存在空白行语义差异。
  - 应对：按“target 描述拼接结果为空则跳过”的规则兜底，并提示行号。
- 风险：大文件渲染性能下降。
  - 应对：解析与聚合在 Worker（后续）或分段处理；图表数据量阈值预警。
- 风险：小程序导出能力受限。
  - 应对：先保障 Web 全能力；小程序阶段提供可替代导出链路。

## 11. 验收标准（Definition of Done）

- 能上传并解析 `csv/xlsx`。
- 能按映射生成正确桑基图（含示例中的聚合语义）。
- 可切换方向、配色、间距并实时预览。
- 可导出 `PNG` 与 `SVG`。
- 提供模板下载。
- 核心测试通过，且 lint/type-check/test 全绿。