142 lines
3.7 KiB
Markdown
142 lines
3.7 KiB
Markdown
# 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.
|