docs: design reference download progress indicator
This commit is contained in:
potaser
@@ -0,0 +1,102 @@
|
||||
# Reference Download Progress Indicator Design
|
||||
|
||||
## Objective
|
||||
|
||||
Make background reference-bundle downloads visible throughout execution so users can tell which species is being downloaded, how much data has arrived, whether the download completed, and why it failed.
|
||||
|
||||
The indicator will appear beside “💡 使用小Tip” in the analysis input toolbar. This change is presentation-only: it must not alter PPI, KaKs, Ortholog, planning, download selection, fallback decisions, or backend execution.
|
||||
|
||||
## Current Problem
|
||||
|
||||
The frontend already polls `/api/task/{task_id}` and stores download state in `referenceBundleDownloadState`. A progress block also exists, but it is rendered inside the batch-execution confirmation dialog. `startBatchExecute()` closes that dialog before execution begins, so the user cannot see the progress block during the actual background download.
|
||||
|
||||
The task API already supplies useful runtime information, including:
|
||||
|
||||
- species label;
|
||||
- task status and message;
|
||||
- percentage when the upstream source provides a total size;
|
||||
- `bytes_downloaded` and `total_bytes`;
|
||||
- terminal success or failure and the failure reason.
|
||||
|
||||
The missing piece is a visible consumer of that existing state.
|
||||
|
||||
## Chosen Design
|
||||
|
||||
### Placement and interaction
|
||||
|
||||
Add a compact “⬇️ 下载进度” status item immediately beside “💡 使用小Tip”. It is hidden when no reference download has been observed in the current page lifecycle.
|
||||
|
||||
While visible, its label reflects the current state:
|
||||
|
||||
- running: `⬇️ 下载中 8.0 MB`;
|
||||
- success: `✅ 下载完成`;
|
||||
- failed: `❌ 下载失败`.
|
||||
|
||||
Hovering over the item opens a compact detail panel using the existing Tip/Upload hover-panel visual pattern. The panel shows:
|
||||
|
||||
- reference species;
|
||||
- running/success/failed status;
|
||||
- determinate progress when total size is known;
|
||||
- indeterminate progress plus downloaded MB when total size is unknown;
|
||||
- backend progress or terminal error message;
|
||||
- a close action for terminal states.
|
||||
|
||||
The running state cannot be dismissed accidentally. Success and failure remain visible until the user closes them. Starting a new download replaces the previous terminal state and shows the new task immediately.
|
||||
|
||||
### State handling
|
||||
|
||||
Reuse `referenceBundleDownloadState`; do not introduce a second download-state authority.
|
||||
|
||||
Extend the state with only the display fields required by the indicator:
|
||||
|
||||
- `bytesDownloaded`;
|
||||
- `totalBytes`.
|
||||
|
||||
`updateReferenceBundleDownloadProgress()` will read these values from the existing task progress payload. If `totalBytes` is unavailable or zero, the progress bar remains indeterminate and the UI reports the downloaded byte count instead of inventing a percentage.
|
||||
|
||||
On success, update the existing state to a visible `success` terminal state at 100% rather than immediately clearing it. On failure, retain the visible `failed` state and its exact error message. `clearReferenceBundleDownloadProgress()` remains the single close/reset operation.
|
||||
|
||||
### Scope boundary
|
||||
|
||||
Only `apps/web/vue3/index.html` is expected to change:
|
||||
|
||||
- toolbar markup beside “使用小Tip”;
|
||||
- narrowly scoped styles matching existing hover components;
|
||||
- the existing `referenceBundleDownloadState` shape and progress updater;
|
||||
- success-state retention in the existing monitor path;
|
||||
- a small byte-formatting display helper if no equivalent helper already exists.
|
||||
|
||||
Explicitly out of scope:
|
||||
|
||||
- backend API changes;
|
||||
- download retry/resume implementation;
|
||||
- fallback-to-At behavior;
|
||||
- PPI, KaKs, or Ortholog execution and dependencies;
|
||||
- planning or stage identity;
|
||||
- cross-refresh persistence;
|
||||
- unrelated frontend refactoring.
|
||||
|
||||
## Error and Terminal-State Behavior
|
||||
|
||||
- Network/download failure: show a red terminal state, downloaded size, and the backend error text.
|
||||
- Unknown content length: show an indeterminate bar and downloaded MB; do not display a fabricated percentage.
|
||||
- Successful completion: show a green 100% state and completion message until closed.
|
||||
- Subsequent download: replace the old terminal state with the new running task.
|
||||
|
||||
The indicator reports state only. Existing confirmation dialogs remain responsible for retry, skip, reference choice, and At fallback decisions.
|
||||
|
||||
## Verification
|
||||
|
||||
Add focused frontend-source/Node tests that exercise the real state-update logic rather than mocking it away.
|
||||
|
||||
Acceptance checks:
|
||||
|
||||
1. A running task with unknown total bytes renders a visible indeterminate state and downloaded MB.
|
||||
2. A running task with known total bytes renders the backend percentage.
|
||||
3. Success remains visible and shows the terminal completion state until close.
|
||||
4. Failure remains visible and shows the exact failure reason until close.
|
||||
5. Close clears a terminal state; a subsequent progress event makes the indicator visible again.
|
||||
6. Existing PPI/KaKs scheduling and download-failure tests continue to pass.
|
||||
7. The rendered indicator sits beside “使用小Tip”, outside the batch confirmation dialog.
|
||||
|
||||
Validation will use the current real job/task payload as a fixture shape, including the observed `IncompleteRead` failure and unknown `total_bytes=0`. No PPI, KaKs, or Ortholog analysis rerun is required to validate this presentation-only change.
|
||||
Reference in New Issue
Block a user