Merge branch 'master' into wip/qa7920-rag-stream

2026-08-21 11:41:16 +08:00
parent 90033214b4 c59f346037
commit b8be4e4831
86 changed files with 12873 additions and 1185 deletions
@@ -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.
@@ -0,0 +1,25 @@
+# PPI/KaKs Unified Reference Dialogs Design
+
+## Goal
+
+Render the two PPI/KaKs reference-species messages inside the existing stage-confirmation dialog shell so their information is readable and visually consistent with the rest of the application.
+
+## Scope
+
+- Replace the raw STRING reference confirmation message box with a stage-confirmation dialog.
+- Replace the raw reference-data/Ortholog warning alert with a read-only stage-confirmation dialog.
+- Show reference candidates as an ordered list.
+- Group target species, requested stages, required/missing files, current reference species, and Ortholog mapping into the existing PPI reference panel layout.
+- Normalize both topology-candidate and downloaded-reference recommendation field names for display only.
+
+## Non-goals
+
+- No changes to PPI/KaKs download, Ortholog generation, identity, scheduling, API payloads, backend validation, or analysis execution.
+- No changes to which candidate is selected: the first ranked candidate remains the confirmed candidate.
+- No new automatic confirmation behavior.
+
+## Interaction contract
+
+- STRING candidate dialog: `Cancel PPI` resolves false; `Confirm top candidate` resolves true.
+- Reference status dialog: `OK` only acknowledges the message; the preflight remains blocked exactly as before.
+- Both dialogs use the existing queue, modal shell, title, progress header, and Element Plus components.