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. 错误后页面仍可恢复继续操作