update at 2026-02-13 22:26:53

APP_FLOW.md

@@ -1,141 +1,124 @@
 # APP_FLOW.md
 
 ## 1. Scope
-This file defines every user-visible flow for the current product scope.
-Primary web route is `/` (single-page app). Miniapp flow is skeleton-only.
+本文件定义当前版本所有用户可见流程，覆盖 Web 与小程序两端。
 
-Related docs:
+关联文档：
 - PRD.md
 - FRONTEND_GUIDELINES.md
 - BACKEND_STRUCTURE.md
 
-## 2. Screen List and Route Map
-- `Web /` : Main Sankey workspace (header + mapping panels + chart preview).
-- `Miniapp /pages/index/index` : Layout skeleton only (not full feature parity).
+## 2. 页面与路由清单
+- `Web /`：主工作区（顶部工具栏 + 数据选择器 + 信息日志 + 桑基图预览）
+- `Miniapp /pages/index/index`：小程序可用页（上传、映射、预览、导出）
 
-## 3. Web Flow: Initial Page Load
-Trigger:
-- User opens `/`.
+## 3. Web 流程：首次加载
+触发条件：
+- 用户打开 `/`
 
-Steps:
-1. Render header, mapping panels, and chart container.
-2. Initialize ECharts instance.
-3. Try loading `/data/example0.xlsx`.
-4. Parse file and set default column mapping.
-5. Build Sankey data and render preview.
+步骤：
+1. 渲染页面结构并初始化 ECharts
+2. 尝试读取 `/data/example0.xlsx`
+3. 解析文件并应用默认列映射
+4. 构建 Sankey 数据并渲染预览
 
-Decision points:
-- If sample file request fails, show parse error text and keep page interactive.
+决策点：
+- 若样例文件加载失败，显示错误信息，但页面仍可继续上传文件
 
-Success result:
-- User sees a chart without manual upload.
+成功结果：
+- 用户无需上传即可看到可操作示例图
 
-Error result:
-- User sees a clear message and can still upload a file manually.
+失败结果：
+- 页面给出明确错误提示，保持可恢复
 
-## 4. Web Flow: File Upload (Click)
-Trigger:
-- User clicks upload icon and selects a local file.
+## 4. Web 流程：文件上传（点击/拖拽）
+触发条件：
+- 点击上传并选择文件，或将文件拖入上传区
 
-Steps:
-1. Validate extension (`csv/xls/xlsx`).
-2. Parse file to `RawTable`.
-3. Reset default mapping by column count.
-4. Rebuild Sankey data via reactive effect.
-5. Update upload message with filename and row count.
+步骤：
+1. 校验后缀：`csv/xls/xlsx`
+2. 解析为 `RawTable`
+3. 应用默认映射或恢复持久化映射
+4. 重建聚合并刷新图表
+5. 更新上传提示文案（文件名 + 行数）
 
-Decision points:
-- Unsupported file type.
-- Parse failure (CSV parser/XLSX parser errors).
+决策点：
+- 不支持的后缀直接报错
+- 解析异常显示错误并保留上一次有效状态
 
-Success result:
-- Mapping list updates to current headers and preview updates.
+## 5. Web 流程：列映射与预览配置
+触发条件：
+- 用户修改数据列、描述列、方向、gap、padding、主题、汇聚对齐等配置
 
-Error result:
-- Error message appears; previous valid state remains usable.
+步骤：
+1. 更新映射或显示配置
+2. 触发重建逻辑
+3. 刷新图表与信息日志
+4. 持久化配置到 localStorage
 
-## 5. Web Flow: File Upload (Drag and Drop)
-Trigger:
-- User drops one file into upload area.
+决策点：
+- `source data` 未选：阻断构建并提示
+- `target description` 为空：阻断构建并提示
+- 非法数值/空描述：跳过行并写入告警
 
-Steps:
-1. Read first file from drop payload.
-2. Reuse the same pipeline as click upload.
+## 6. Web 流程：导出
+触发条件：
+- 点击导出 `SVG` 或 `PNG`
 
-Decision points:
-- No file in payload.
+步骤：
+1. 检查图表实例是否可用
+2. 组装时间戳文件名
+3. SVG：临时创建 SVG 渲染器导出
+4. PNG：`pixelRatio=2` 导出
+5. 触发浏览器下载
 
-Success and error behaviors:
-- Same as click upload.
+## 7. 小程序流程：文件上传与默认映射
+触发条件：
+- 用户点击“文件上传”
 
-## 6. Web Flow: Mapping Configuration
-Trigger:
-- User changes any mapping item in the left panels.
+步骤：
+1. 选择 `csv/xls/xlsx` 文件
+2. 按后缀分流解析：
+   - `csv`：文本解析
+   - `xls/xlsx`：SheetJS 解析首个工作表
+3. 应用默认映射规则
+4. 重建 Sankey 聚合并更新日志
+5. 触发 canvas 重绘
 
-Steps:
-1. Select one source data column (radio).
-2. Toggle source description columns (checkbox list).
-3. Toggle target description columns (checkbox list).
-4. Optional: toggle target total label display.
-5. Reactive builder recomputes links and warnings.
+决策点：
+- 若 xlsx 模块不可用，提示先在开发者工具执行“构建 npm”
+- 解析失败显示错误，不会导致页面失效
 
-Decision points:
-- Missing source data column -> block build with message.
-- Empty target description selection -> block build with message.
-- Invalid numeric source value -> row dropped with warning.
-- Empty source/target name after rules -> row dropped with warning.
+## 8. 小程序流程：列映射与预览
+触发条件：
+- 用户点击任意列项调整 source/target 映射
 
-Success result:
-- Chart updates immediately.
+步骤：
+1. 更新映射状态
+2. 调用聚合构建
+3. 更新统计（节点数、连线数、跳过行）
+4. 更新“信息日志”
+5. 重绘 canvas 预览
 
-Error result:
-- Build error or warning list shown in preview panel.
+## 9. 小程序流程：导出
+触发条件：
+- 点击导出 PNG 或 SVG
 
-## 7. Web Flow: Preview Controls
-Trigger:
-- User changes direction, gap, padding, or theme.
+步骤：
+1. PNG：
+   - 将 canvas 导出临时图片
+   - 保存到系统相册
+2. SVG：
+   - 复用布局算法生成 SVG 字符串
+   - 写入用户目录 `.svg` 文件
+   - 优先尝试打开文档；若失败则复制文件路径
 
-Steps:
-1. Direction toggle swaps link direction (`source<->target`).
-2. Gap/padding sliders update chart series layout.
-3. Theme picker updates node palette.
-
-Decision points:
-- Theme popover closes on outside pointer down.
-
-Success result:
-- Chart visual changes apply in-place.
-
-## 8. Web Flow: Export
-Trigger:
-- User clicks `Export SVG` or `Export PNG`.
-
-Steps:
-1. Ensure chart instance exists.
-2. Build filename with timestamp.
-3. For SVG: prefer serializing DOM `<svg>`; fallback to `getDataURL`.
-4. For PNG: use `getDataURL(type='png', pixelRatio=2)`.
-5. Trigger browser download.
-
-Decision points:
-- No chart instance -> no action.
-
-Success result:
-- Downloaded file appears with expected naming.
-
-## 9. Miniapp Skeleton Flow (Current State)
-Trigger:
-- Open miniapp index page.
-
-Steps:
-1. Render static layout blocks.
-2. Allow opening/closing theme bottom sheet.
-
-Current limitations:
-- No real file parsing, no Sankey rendering, no export pipeline.
+决策点：
+- 无可用数据时阻断导出并提示
+- 相册权限不足时提示用户授权
 
 ## 10. Flow Completion Checklist
-A flow is considered complete only when:
-1. Success path works end-to-end.
-2. Error path shows deterministic message.
-3. UI state remains recoverable after errors.
+流程视为完成需满足：
+1. 成功路径可端到端执行
+2. 失败路径有明确且可定位的错误信息
+3. 错误后页面仍可恢复继续操作