sankey/APP_FLOW.md

# APP_FLOW.md

## 1. Scope
本文件定义当前版本所有用户可见流程，覆盖 Web 与小程序两端。

关联文档：
- PRD.md
- FRONTEND_GUIDELINES.md
- BACKEND_STRUCTURE.md

## 2. 页面与路由清单
- `Web /`：主工作区（顶部工具栏 + 数据选择器 + 信息日志 + 桑基图预览）
- `Miniapp /pages/index/index`：小程序可用页（上传、映射、预览、导出）

## 3. Web 流程：首次加载
触发条件：
- 用户打开 `/`

步骤：
1. 渲染页面结构并初始化 ECharts
2. 尝试读取 `/data/example0.xlsx`
3. 解析文件并应用默认列映射
4. 构建 Sankey 数据并渲染预览

决策点：
- 若样例文件加载失败，显示错误信息，但页面仍可继续上传文件

成功结果：
- 用户无需上传即可看到可操作示例图

失败结果：
- 页面给出明确错误提示，保持可恢复

## 4. Web 流程：文件上传（点击/拖拽）
触发条件：
- 点击上传并选择文件，或将文件拖入上传区

步骤：
1. 校验后缀：`csv/xls/xlsx`
2. 解析为 `RawTable`
3. 应用默认映射或恢复持久化映射
4. 重建聚合并刷新图表
5. 更新上传提示文案（文件名 + 行数）

决策点：
- 不支持的后缀直接报错
- 解析异常显示错误并保留上一次有效状态

## 5. Web 流程：列映射与预览配置
触发条件：
- 用户修改数据列、描述列、方向、gap、padding、主题、汇聚对齐等配置

步骤：
1. 更新映射或显示配置
2. 触发重建逻辑
3. 刷新图表与信息日志
4. 持久化配置到 localStorage

决策点：
- `source data` 未选：阻断构建并提示
- `target description` 为空：阻断构建并提示
- 非法数值/空描述：跳过行并写入告警

## 6. Web 流程：导出
触发条件：
- 点击导出 `SVG` 或 `PNG`

步骤：
1. 检查图表实例是否可用
2. 组装时间戳文件名
3. SVG：临时创建 SVG 渲染器导出
4. PNG：`pixelRatio=2` 导出
5. 触发浏览器下载

## 7. 小程序流程：文件上传与默认映射
触发条件：
- 用户点击“文件上传”

步骤：
1. 选择 `csv/xls/xlsx` 文件
2. 按后缀分流解析：
   - `csv`：文本解析
   - `xls/xlsx`：SheetJS 解析首个工作表
3. 应用默认映射规则
4. 重建 Sankey 聚合并更新日志
5. 触发 canvas 重绘

决策点：
- 若 xlsx 模块不可用，提示先在开发者工具执行“构建 npm”
- 解析失败显示错误，不会导致页面失效

## 8. 小程序流程：列映射与预览
触发条件：
- 用户点击任意列项调整 source/target 映射

步骤：
1. 更新映射状态
2. 调用聚合构建
3. 更新统计（节点数、连线数、跳过行）
4. 更新“信息日志”
5. 重绘 canvas 预览

## 9. 小程序流程：导出
触发条件：
- 点击导出 PNG 或 SVG

步骤：
1. PNG：
   - 将 canvas 导出临时图片
   - 保存到系统相册
2. SVG：
   - 复用布局算法生成 SVG 字符串
   - 写入用户目录 `.svg` 文件
   - 优先尝试打开文档；若失败则复制文件路径

决策点：
- 无可用数据时阻断导出并提示
- 相册权限不足时提示用户授权

## 10. Flow Completion Checklist
流程视为完成需满足：
1. 成功路径可端到端执行
2. 失败路径有明确且可定位的错误信息
3. 错误后页面仍可恢复继续操作