# 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.