sankey/APP_FLOW.md

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.