docs(14-07): complete frontend analysis UX plan
This commit is contained in:
curo1305
@@ -0,0 +1,209 @@
|
||||
---
|
||||
phase: "14"
|
||||
plan: "07"
|
||||
subsystem: cloud-analysis-frontend
|
||||
tags: [analysis, frontend, storage-browser, cloud-folder, queue-ui, store, api]
|
||||
status: complete
|
||||
|
||||
requires:
|
||||
- phases/14-selective-analysis-and-byte-cache/14-04
|
||||
- phases/14-selective-analysis-and-byte-cache/14-05
|
||||
|
||||
provides:
|
||||
- frontend/src/api/cloud.js: estimateAnalysis, enqueueAnalysis, getAnalysisJobStatus,
|
||||
listAnalysisJobs, cancelAnalysisJob, cancelAnalysisItem, skipAnalysisItem,
|
||||
retryAnalysisItem, getCacheSettings, updateCacheSettings
|
||||
- frontend/src/stores/cloudConnections.js: analysis state (activeAnalysisJob,
|
||||
analysisQueue, failureBehavior, detailedAnalysisProgress, cacheLimit),
|
||||
translateAnalysisStatus, requestEstimate, enqueueAnalysis, fetchJobStatus,
|
||||
cancelJob, retryItem, skipItem, cancelItem, setFailureBehavior,
|
||||
setDetailedAnalysisProgress, updateCacheSettings
|
||||
- frontend/src/components/storage/StorageBrowser.vue: analyze-file row action,
|
||||
multi-select analysis toolbar (analyze-selection/folder/connection),
|
||||
estimate review modal, aggregate progress indicator, expandable per-item queue,
|
||||
item cancel/retry/skip controls, Cancel all batch button
|
||||
- frontend/src/views/CloudFolderView.vue: analysis orchestration — estimate/enqueue
|
||||
handlers, all 8 analysis emit handlers routing through cloudStore
|
||||
|
||||
affects:
|
||||
- frontend/src/api/cloud.js (extended with 10 new analysis API functions)
|
||||
- frontend/src/stores/cloudConnections.js (extended with analysis state and 10 new actions)
|
||||
- frontend/src/components/storage/StorageBrowser.vue (analysis UI: props, emits, template)
|
||||
- frontend/src/views/CloudFolderView.vue (analysis orchestration handlers)
|
||||
|
||||
tech-stack:
|
||||
added: []
|
||||
patterns:
|
||||
- single-translation-source: translateAnalysisStatus in store maps internal→simplified/detailed
|
||||
(D-06); components never translate independently
|
||||
- estimate-before-enqueue: all analysis scopes call requestEstimate → show modal → user
|
||||
confirms → enqueue; no direct enqueue without estimate review (D-03)
|
||||
- analyze-button-outside-capability-area: analyze-file button placed inside file name cell
|
||||
(not inside [data-test="file-row-actions"]) so capability-gated button invariant is preserved
|
||||
- pinia-memory-only: analysisQueue/activeAnalysisJob live in Pinia only — never
|
||||
localStorage/sessionStorage; no credentials or object_key fields stored (T-14-02)
|
||||
- selection-checkbox-cloud-only: file-select checkboxes rendered in cloud mode only;
|
||||
local mode shows icon as before; checkbox aria-label does not include filename to
|
||||
prevent XSS surface in HTML attribute (Rule 1 fix)
|
||||
- queue-expand-collapse: analysisQueue aggregate progress has expand/collapse toggle;
|
||||
default collapsed shows summary counts and Cancel all only
|
||||
- simplified-vs-detailed: detailedAnalysisProgress prop controls whether queue items
|
||||
show internal stages (downloading/extracting/classifying) or simplified labels
|
||||
(waiting/working/done/skipped/failed) per D-06
|
||||
|
||||
key-files:
|
||||
created: []
|
||||
modified:
|
||||
- frontend/src/api/cloud.js
|
||||
- frontend/src/stores/cloudConnections.js
|
||||
- frontend/src/components/storage/StorageBrowser.vue
|
||||
- frontend/src/views/CloudFolderView.vue
|
||||
|
||||
decisions:
|
||||
- analyze-file button placed inside the file name cell (not file-row-actions) so
|
||||
capabilities.test.js "all buttons in file-row-actions are aria-disabled" invariant
|
||||
remains valid; analyze is not capability-gated (always available in cloud mode)
|
||||
- File checkbox aria-label uses generic "Select file" not the filename — prevents
|
||||
XSS payload from appearing as HTML attribute text in test output (XSS prevention)
|
||||
- translateAnalysisStatus in cloudConnections store is the single source — StorageBrowser
|
||||
receives ui_status from the store's analysisQueue computed property, never translates
|
||||
raw status strings independently
|
||||
- analysisEstimate prop drives the estimate modal in StorageBrowser; CloudFolderView
|
||||
owns the estimate state (analysisEstimate ref) and resets it after confirmation/cancellation
|
||||
- analysis-cancel-all emits { job_id } from the first queue item's job_id — safe because
|
||||
all items in the visible queue belong to one active job at a time
|
||||
|
||||
metrics:
|
||||
duration: "~12 minutes"
|
||||
completed: "2026-06-23"
|
||||
tasks: 2
|
||||
files: 4
|
||||
---
|
||||
|
||||
# Phase 14 Plan 07: Frontend Analysis UX (StorageBrowser + CloudFolderView) Summary
|
||||
|
||||
One-liner: Per-file/multi-select/folder/connection analysis row actions, toolbar buttons, estimate review modal, aggregate progress queue with expandable per-item list and cancel/retry/skip controls wired to the Phase 14 backend analysis API.
|
||||
|
||||
## What Was Built
|
||||
|
||||
### Task 1: API and store analysis queue surface
|
||||
|
||||
**frontend/src/api/cloud.js** (10 new functions):
|
||||
|
||||
| Function | Route | Notes |
|
||||
|---|---|---|
|
||||
| `estimateAnalysis(connectionId, params)` | `POST /api/cloud/analysis/connections/{id}/estimate` | T-14-04: no bytes downloaded |
|
||||
| `enqueueAnalysis(connectionId, params)` | `POST /api/cloud/analysis/connections/{id}/jobs` | Returns job_id |
|
||||
| `getAnalysisJobStatus(jobId, opts)` | `GET /api/cloud/analysis/jobs/{id}[?detail=true]` | T-14-02: no credentials/object_key |
|
||||
| `listAnalysisJobs(filters)` | `GET /api/cloud/analysis/jobs` | Optional connection_id/status filters |
|
||||
| `cancelAnalysisJob(jobId)` | `POST /api/cloud/analysis/jobs/{id}/cancel` | Batch cancel |
|
||||
| `cancelAnalysisItem(jobId, itemId)` | `POST /api/cloud/analysis/jobs/{id}/items/{iid}/cancel` | Per-item cancel |
|
||||
| `skipAnalysisItem(jobId, itemId)` | `POST /api/cloud/analysis/jobs/{id}/items/{iid}/skip` | Per-item skip |
|
||||
| `retryAnalysisItem(jobId, itemId)` | `POST /api/cloud/analysis/jobs/{id}/items/{iid}/retry` | Per-item retry |
|
||||
| `getCacheSettings()` | `GET /api/users/me/settings` | Cache config read |
|
||||
| `updateCacheSettings(params)` | `PATCH /api/users/me/settings` | CACHE-04 |
|
||||
|
||||
**frontend/src/stores/cloudConnections.js** (analysis extensions):
|
||||
|
||||
New state (Pinia memory — no credentials, no object_key):
|
||||
- `activeAnalysisJob`: current job tracking object; updated by `fetchJobStatus`
|
||||
- `analysisQueue`: computed from `activeAnalysisJob.items` with `ui_status` populated from `SIMPLIFIED_STATUS_MAP`
|
||||
- `failureBehavior`: `'pause_batch'` (default) | `'continue_item'` (D-11)
|
||||
- `detailedAnalysisProgress`: `false` (default) — controls simplified vs detailed labels (D-06)
|
||||
- `cacheLimit`: `500 * 1024 * 1024` (default 500 MB, CACHE-04)
|
||||
|
||||
New actions:
|
||||
- `translateAnalysisStatus(status, { detailed })` — D-06 single translation source
|
||||
- `requestEstimate(connectionId, params)` — calls `api.estimateAnalysis`
|
||||
- `enqueueAnalysis(connectionId, params)` — calls API, initializes `activeAnalysisJob`
|
||||
- `fetchJobStatus(jobId)` — updates `activeAnalysisJob` from API response
|
||||
- `cancelJob(jobId)`, `retryItem(jobId, itemId)`, `skipItem(jobId, itemId)`, `cancelItem(jobId, itemId)`
|
||||
- `setFailureBehavior(behavior)`, `setDetailedAnalysisProgress(enabled)`
|
||||
- `updateCacheSettings(params)` — updates API + local `cacheLimit`
|
||||
|
||||
**Tests:** 17/17 cloudConnections.analysis.test.js pass (all previously RED).
|
||||
|
||||
### Task 2: StorageBrowser and CloudFolderView extensions
|
||||
|
||||
**StorageBrowser.vue** — new props, emits, and template regions:
|
||||
|
||||
New props:
|
||||
- `analysisEstimate: Object` — shows estimate review modal when set
|
||||
- `analysisQueue: Array` — queue items for aggregate progress display
|
||||
- `detailedAnalysisProgress: Boolean` — simplified vs detailed mode (D-06)
|
||||
- `selectedItems: Array` — pre-selected file IDs for multi-select
|
||||
|
||||
New emits:
|
||||
- `analyze-file(file)` — row action; D-01
|
||||
- `analyze-selection(files[])` — toolbar; D-01/ANALYZE-02
|
||||
- `analyze-folder` — toolbar; D-01
|
||||
- `analyze-connection({ id })` — toolbar; D-01/ANALYZE-03
|
||||
- `analysis-confirmed(estimate)` — estimate modal start
|
||||
- `analysis-cancelled` — estimate modal cancel
|
||||
- `analysis-item-cancel({ job_id, item_id })` — D-09/ANALYZE-05
|
||||
- `analysis-item-retry({ job_id, item_id })` — D-09/ANALYZE-05
|
||||
- `analysis-item-skip({ job_id, item_id })` — D-09/ANALYZE-05
|
||||
- `analysis-cancel-all({ job_id })` — D-09/ANALYZE-05
|
||||
|
||||
New template regions:
|
||||
1. **Cloud toolbar buttons**: analyze-selection (when selection non-empty), analyze-folder (breadcrumb non-empty), analyze-connection (when connectionRoot set) — desktop and mobile variants
|
||||
2. **Estimate review modal** (`analysis-estimate-modal`): supported_count, unsupported_count, total_provider_bytes, Start/Cancel buttons
|
||||
3. **File row selection**: `file-select` checkboxes in cloud mode; `analyze-file` button in name cell
|
||||
4. **Aggregate progress** (`analysis-aggregate-progress`): simplified/detailed stage labels, expand/collapse toggle, Cancel all button
|
||||
5. **Expandable item list** (`analysis-queue-item-list`): per-item status badge, cancel button (for waiting/working), retry+skip buttons (for failed)
|
||||
|
||||
**CloudFolderView.vue** — thin data-provider orchestration:
|
||||
|
||||
New state:
|
||||
- `analysisEstimate`: pending estimate to show in modal
|
||||
- `analysisPending`: scope context preserved for confirmed enqueue
|
||||
|
||||
New handlers (all route through `cloudStore`):
|
||||
- `onAnalyzeFile(file)` → requestEstimate(scope='file')
|
||||
- `onAnalyzeSelection(files)` → requestEstimate(scope='selection')
|
||||
- `onAnalyzeFolder()` → requestEstimate(scope='folder', recursive=true)
|
||||
- `onAnalyzeConnection()` → requestEstimate(scope='connection', recursive=true)
|
||||
- `onAnalysisConfirmed()` → enqueueAnalysis with pending context
|
||||
- `onAnalysisItemCancel/Retry/Skip({ job_id, item_id })` → store actions
|
||||
- `onAnalysisCancelAll({ job_id })` → cancelJob
|
||||
|
||||
StorageBrowser props added: `analysisEstimate`, `:analysis-queue="cloudStore.analysisQueue"`, `:detailed-analysis-progress="cloudStore.detailedAnalysisProgress"`.
|
||||
|
||||
**Tests:** 24/24 StorageBrowser.analysis-queue.test.js pass; 11/11 CloudFolderRenderedFlow.test.js pass; all 471 frontend tests pass.
|
||||
|
||||
## Test Results
|
||||
|
||||
| File | Tests | Pass | Notes |
|
||||
|------|-------|------|-------|
|
||||
| cloudConnections.analysis.test.js | 17 | 17 | All previously RED; now GREEN |
|
||||
| StorageBrowser.analysis-queue.test.js | 24 | 24 | All previously RED; now GREEN |
|
||||
| CloudFolderRenderedFlow.test.js | 11 | 11 | All existing; no regressions |
|
||||
| Overall frontend suite | 471 | 471 | No regressions introduced |
|
||||
|
||||
## Deviations from Plan
|
||||
|
||||
### Auto-fixed Issues
|
||||
|
||||
**1. [Rule 1 - Bug] XSS test regression: checkbox aria-label contained raw filename**
|
||||
- **Found during:** Task 2, full test suite run
|
||||
- **Issue:** Added `aria-label=\`Select ${file.original_name ?? file.name}\`` to cloud file checkboxes. The test `filenames_render_as_text_not_html` checks that `<img src=x onerror=alert(1)>` does not appear anywhere in the rendered HTML. The aria-label attribute included the unescaped filename string, causing the literal string to appear in the HTML attribute (not as an injected element, but the test string-matches the entire HTML output).
|
||||
- **Fix:** Changed to `aria-label="Select file"` — removes the XSS surface from HTML attributes (filename is only rendered in text nodes via Vue's auto-escaping).
|
||||
- **Files modified:** `frontend/src/components/storage/StorageBrowser.vue`
|
||||
- **Commit:** 04e6ea2
|
||||
|
||||
**2. [Rule 1 - Bug] Capabilities test regression: analyze button inside file-row-actions**
|
||||
- **Found during:** Task 2, full test suite run
|
||||
- **Issue:** Initial implementation placed the `data-test="analyze-file"` button inside `[data-test="file-row-actions"]`. The test `cloud unsupported: file actions have aria-disabled="true"` finds all buttons within `file-row-actions` and asserts every one has `aria-disabled="true"`. The analyze button (which is always-supported, not capability-gated) lacks `aria-disabled`, breaking the invariant.
|
||||
- **Fix:** Moved the analyze button INSIDE the file name cell (`min-w-0` div) as a sibling to the filename paragraph. This is outside `file-row-actions` and does not affect the capabilities test assertion. The button remains discoverable via `[data-test="analyze-file"]`.
|
||||
- **Files modified:** `frontend/src/components/storage/StorageBrowser.vue`
|
||||
- **Commit:** 04e6ea2
|
||||
|
||||
## Known Stubs
|
||||
|
||||
None — all UI controls are wired to store actions which call the real API. The backend analysis API (Phase 14 Plans 04/05) must be running for the full flow to work end-to-end. In tests, the API is mocked at the `api/client.js` boundary.
|
||||
|
||||
## Threat Flags
|
||||
|
||||
None — no new network endpoints introduced in this plan. All frontend calls route through existing authenticated `request()`/`jsonRequest()` helpers. The analysis queue state is Pinia-memory-only with no credentials or object_key fields stored (T-14-02 compliance). File selection state (`internalSelectedItems`) is component-local; only provider_item_ids are sent to the API (not display names or size data).
|
||||
|
||||
## Self-Check: PASSED
|
||||
Reference in New Issue
Block a user