update at 2026-02-13 08:42:56

APP_FLOW.md

@@ -0,0 +1,141 @@
+# 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.
+
+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).
+
+## 3. Web Flow: Initial Page Load
+Trigger:
+- User opens `/`.
+
+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.
+
+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.
+
+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.
+
+Decision points:
+- Unsupported file type.
+- Parse failure (CSV parser/XLSX parser errors).
+
+Success result:
+- Mapping list updates to current headers and preview updates.
+
+Error result:
+- Error message appears; previous valid state remains usable.
+
+## 5. Web Flow: File Upload (Drag and Drop)
+Trigger:
+- User drops one file into upload area.
+
+Steps:
+1. Read first file from drop payload.
+2. Reuse the same pipeline as click upload.
+
+Decision points:
+- No file in payload.
+
+Success and error behaviors:
+- Same as click upload.
+
+## 6. Web Flow: Mapping Configuration
+Trigger:
+- User changes any mapping item in the left panels.
+
+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.
+
+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.
+
+Success result:
+- Chart updates immediately.
+
+Error result:
+- Build error or warning list shown in preview panel.
+
+## 7. Web Flow: Preview Controls
+Trigger:
+- User changes direction, gap, padding, or theme.
+
+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.