docs(14-08): complete settings integration plan
This commit is contained in:
curo1305
@@ -25,7 +25,7 @@ Before any phase is marked complete:
|
||||
|------:|------|------|--------------|
|
||||
| 12 | 6/6 | Complete | 2026-06-21 |
|
||||
| 13 | 11/11 | Complete | 2026-06-23 |
|
||||
| 14 | 7/9 | In Progress| |
|
||||
| 14 | 8/9 | In Progress| |
|
||||
| 15 | Unified Smart Search | Search local and analyzed cloud documents by exact text or semantic ideas without downloading files during queries | SEARCH-01..07 |
|
||||
| 16 | Change Tracking and Reliability | Detect external provider changes, mark stale indexes, remove deleted items, and harden refresh behavior | SYNC-02..04 |
|
||||
|
||||
@@ -111,7 +111,7 @@ Plans:
|
||||
|
||||
**Depends on:** Phase 13
|
||||
**Requirements:** ANALYZE-01, ANALYZE-02, ANALYZE-03, ANALYZE-04, ANALYZE-05, ANALYZE-06, ANALYZE-07, CACHE-03, CACHE-04, CACHE-05
|
||||
**Plans:** 7/9 plans executed
|
||||
**Plans:** 8/9 plans executed
|
||||
**Execution waves:** Wave 0: 14-01; Wave 1: 14-02 after 14-01; Wave 2: 14-03 after 14-02; Wave 3: 14-04 after 14-02 and 14-03; Wave 4: 14-05 after 14-03 and 14-04; Wave 5: 14-06 after 14-03 and 14-05; Wave 6: 14-07 after 14-04 and 14-05; Wave 7: 14-08 after 14-03 and 14-07; Wave 8: 14-09 after 14-01 through 14-08.
|
||||
|
||||
Plans:
|
||||
@@ -123,7 +123,7 @@ Plans:
|
||||
- [x] 14-05-PLAN.md — Implement Celery-backed cloud analysis processing, cache hydration, extraction, classification, and cancellation.
|
||||
- [x] 14-06-PLAN.md — Route existing cloud open/preview/download byte hydration through the bounded cache lifecycle.
|
||||
- [x] 14-07-PLAN.md — Wire shared-browser analysis actions, estimates, aggregate progress, expandable queue, and controls.
|
||||
- [ ] 14-08-PLAN.md — Add Settings controls for cache limit, progress detail, and failure behavior.
|
||||
- [x] 14-08-PLAN.md — Add Settings controls for cache limit, progress detail, and failure behavior.
|
||||
- [ ] 14-09-PLAN.md — Run closeout docs, versions, full test/security gates, validation, commit, and push.
|
||||
|
||||
**Success Criteria:**
|
||||
|
||||
+7
-4
@@ -6,14 +6,14 @@ current_phase: 14
|
||||
current_phase_name: selective-analysis-and-byte-cache
|
||||
status: in_progress
|
||||
stopped_at: Phase 14 Plan 07 complete
|
||||
last_updated: "2026-06-23T17:45:53.403Z"
|
||||
last_updated: "2026-06-23T17:55:00.641Z"
|
||||
last_activity: 2026-06-23
|
||||
last_activity_desc: Phase 14 Plan 06 byte cache for open/preview/download complete
|
||||
progress:
|
||||
total_phases: 6
|
||||
completed_phases: 3
|
||||
total_plans: 30
|
||||
completed_plans: 28
|
||||
completed_plans: 29
|
||||
percent: 50
|
||||
---
|
||||
|
||||
@@ -26,7 +26,7 @@ progress:
|
||||
## Current Position
|
||||
|
||||
Phase: 14 (selective-analysis-and-byte-cache) — IN PROGRESS
|
||||
Plan: 8 of 9
|
||||
Plan: 9 of 9
|
||||
Status: Plans 14-01 through 14-06 complete. Next: execute 14-07
|
||||
Last activity: 2026-06-23 — Phase 14 Plan 06 byte cache for open/preview/download complete
|
||||
|
||||
@@ -69,6 +69,7 @@ Last activity: 2026-06-23 — Phase 14 Plan 06 byte cache for open/preview/downl
|
||||
| Phase 14 P05 | 10m | 2 tasks | 4 files |
|
||||
| Phase 14 P06 | 10m | 2 tasks | 5 files |
|
||||
| Phase 14 P07 | 12m | 2 tasks | 4 files |
|
||||
| Phase 14 P08 | 10m | 2 tasks | 3 files |
|
||||
|
||||
## Accumulated Context
|
||||
|
||||
@@ -116,7 +117,7 @@ _Updated at each phase transition._
|
||||
|
||||
| Field | Value |
|
||||
|---|---|
|
||||
| Last session | 2026-06-23T17:45:53.397Z |
|
||||
| Last session | 2026-06-23T17:54:00.317Z |
|
||||
| Next action | Execute 14-07 |
|
||||
| Pending decisions | None |
|
||||
| Resume file | .planning/phases/14-selective-analysis-and-byte-cache/14-08-PLAN.md |
|
||||
@@ -162,3 +163,5 @@ _Updated at each phase transition._
|
||||
- [Phase 14 P06]: preview and download cache integration is backend-transparent — response shapes unchanged from Phase 13 (T-14-02)
|
||||
- [Phase ?]: [Phase 14 P07]: analyze-file button in name cell not file-row-actions
|
||||
- [Phase ?]: [Phase 14 P07]: translateAnalysisStatus is single status translation source in cloudConnections store
|
||||
- [Phase ?]: [Phase 14 P08]: getCacheSettings corrected to /api/cloud/analysis/cache; tierCapBytes drives Settings cache limit max
|
||||
- [Phase ?]: [Phase 14 P08]: Analysis Settings section in SettingsCloudTab - separate card with cache limit input, progress detail toggle, failure behavior toggle
|
||||
|
||||
@@ -0,0 +1,167 @@
|
||||
---
|
||||
phase: "14"
|
||||
plan: "08"
|
||||
subsystem: cloud-analysis-settings
|
||||
tags: [settings, cache, analysis, frontend, store, api]
|
||||
status: complete
|
||||
|
||||
requires:
|
||||
- phases/14-selective-analysis-and-byte-cache/14-03
|
||||
- phases/14-selective-analysis-and-byte-cache/14-07
|
||||
|
||||
provides:
|
||||
- frontend/src/api/cloud.js: getCacheSettings → GET /api/cloud/analysis/cache,
|
||||
updateCacheSettings → PATCH /api/cloud/analysis/cache/settings (corrected URLs)
|
||||
- frontend/src/stores/cloudConnections.js: loadCacheSettings action (hydrates
|
||||
tierCapBytes/cacheUsage/cacheLimit/detailedAnalysisProgress/failureBehavior
|
||||
from server); tierCapBytes, cacheUsage, cacheSettingsLoading, cacheSettingsError state
|
||||
- frontend/src/components/settings/SettingsCloudTab.vue: Analysis Settings section
|
||||
with cache limit number input, simplified/detailed progress toggle, pause-batch/
|
||||
continue-item failure behavior toggle
|
||||
|
||||
affects:
|
||||
- frontend/src/api/cloud.js (URL bug fix + enhanced docs)
|
||||
- frontend/src/stores/cloudConnections.js (loadCacheSettings action + new state)
|
||||
- frontend/src/components/settings/SettingsCloudTab.vue (Analysis Settings section)
|
||||
|
||||
tech-stack:
|
||||
added: []
|
||||
patterns:
|
||||
- server-hydrated-settings: loadCacheSettings fetches CacheStatusOut from
|
||||
/api/cloud/analysis/cache and merges tier_cap_bytes, entry_count, total_bytes,
|
||||
analysis_progress_detail, analysis_failure_behavior into Pinia memory on mount
|
||||
- error-no-clear: settings load/update errors set cacheSettingsError without
|
||||
clearing existing in-memory settings — UI shows error but retains last known values
|
||||
- optimistic-then-persist: progress-detail and failure-behavior controls apply
|
||||
local change optimistically (setDetailedAnalysisProgress/setFailureBehavior)
|
||||
then persist via updateCacheSettings; revert on API failure
|
||||
- tier-cap-validation: cache limit input validates against tierCapBytes (from server)
|
||||
with local error message before calling API; invalid values are rejected locally
|
||||
|
||||
key-files:
|
||||
created: []
|
||||
modified:
|
||||
- frontend/src/api/cloud.js
|
||||
- frontend/src/stores/cloudConnections.js
|
||||
- frontend/src/components/settings/SettingsCloudTab.vue
|
||||
|
||||
decisions:
|
||||
- getCacheSettings and updateCacheSettings corrected to /api/cloud/analysis/cache
|
||||
and /api/cloud/analysis/cache/settings (Rule 1 auto-fix — previous URLs pointed
|
||||
to non-existent /api/users/me/settings endpoint per Plan 14-03 backend spec)
|
||||
- Settings UI uses segmented controls (two-button toggle) not <select> for
|
||||
progress detail and failure behavior — matches the pattern of binary preference
|
||||
choices with clear active-state affordance
|
||||
- Cache limit input is a number field (MB) rather than a slider — avoids slider
|
||||
precision issues at large byte values and is keyboard-accessible
|
||||
- Analysis Settings in a separate card below Cloud Storage connections — keeps
|
||||
connection management UX untouched and groups Phase 14 settings together
|
||||
- tierCapBytes defaults to 2 GB client-side if loadCacheSettings hasn't completed —
|
||||
prevents the UI from showing 0 MB max before the server responds
|
||||
|
||||
metrics:
|
||||
duration: "~10 minutes"
|
||||
completed: "2026-06-23"
|
||||
tasks: 2
|
||||
files: 3
|
||||
---
|
||||
|
||||
# Phase 14 Plan 08: Settings Integration Summary
|
||||
|
||||
One-liner: Cache limit control, simplified/detailed progress toggle, and pause-batch/continue-item failure behavior toggle in Settings, backed by the /api/cloud/analysis/cache endpoint with server-authoritative tier cap and usage display.
|
||||
|
||||
## What Was Built
|
||||
|
||||
### Task 1: API/store wiring
|
||||
|
||||
**frontend/src/api/cloud.js** (bug fix + enhanced docs):
|
||||
|
||||
- `getCacheSettings()` — corrected from `/api/users/me/settings` to `/api/cloud/analysis/cache`. Returns `CacheStatusOut` with `entry_count`, `total_bytes`, `cache_limit_bytes`, `tier_cap_bytes`, `analysis_progress_detail`, `analysis_failure_behavior`.
|
||||
- `updateCacheSettings(params)` — corrected from `/api/users/me/settings` PATCH to `/api/cloud/analysis/cache/settings` PATCH. Accepts optional `cloud_cache_limit_bytes`, `analysis_progress_detail`, `analysis_failure_behavior`. Returns fresh `CacheStatusOut`.
|
||||
|
||||
**frontend/src/stores/cloudConnections.js** (new state and action):
|
||||
|
||||
New state (Pinia memory — no credentials):
|
||||
- `tierCapBytes`: server-authoritative ceiling for the cache limit (null until loaded)
|
||||
- `cacheUsage`: `{ entry_count, total_bytes }` from last successful load (no object_key)
|
||||
- `cacheSettingsLoading`: true while load/update API call is in flight
|
||||
- `cacheSettingsError`: string error from last failed call; null on success
|
||||
|
||||
New action:
|
||||
- `loadCacheSettings()`: calls `getCacheSettings()`, merges all 6 CacheStatusOut fields into local refs. Error path sets `cacheSettingsError` without clearing existing settings. Used by SettingsCloudTab on mount.
|
||||
|
||||
Updated action:
|
||||
- `updateCacheSettings(params)`: now also merges `tier_cap_bytes`, `cacheUsage`, `analysis_progress_detail`, and `analysis_failure_behavior` from the server response (not just `cloud_cache_limit_bytes`). Sets `cacheSettingsError` on failure without clearing local state; re-throws so callers can react.
|
||||
|
||||
### Task 2: SettingsCloudTab UI controls
|
||||
|
||||
**frontend/src/components/settings/SettingsCloudTab.vue** (Analysis Settings section added):
|
||||
|
||||
New UI section (`data-test="cache-settings-section"`):
|
||||
|
||||
1. **Cache limit input** (`data-test="cache-limit-input"`)
|
||||
- Number field in MB with `min=1` and `max=cacheLimitMaxMB` (from `tierCapBytes`)
|
||||
- Default cap shown: "Max: N MB"
|
||||
- Local validation: rejects values < 1 or > tier cap before API call
|
||||
- Usage display when `cacheUsage` is loaded: "Currently using X MB of Y MB"
|
||||
- Error message: `data-test="cache-limit-error"` for validation failures
|
||||
- `aria-label="Cache limit in megabytes"` for accessibility
|
||||
|
||||
2. **Analysis progress detail toggle** (`data-test="progress-simplified"` / `data-test="progress-detailed"`)
|
||||
- Segmented control (two-button group) with `aria-pressed` states
|
||||
- Simplified (default) / Detailed
|
||||
- Optimistic local update via `store.setDetailedAnalysisProgress()` then persists to API
|
||||
- Reverts on API failure
|
||||
|
||||
3. **Failure behavior toggle** (`data-test="failure-pause-batch"` / `data-test="failure-continue-item"`)
|
||||
- Segmented control with `aria-pressed` states
|
||||
- Pause batch (default) / Skip and continue
|
||||
- Optimistic local update via `store.setFailureBehavior()` then persists to API
|
||||
- Reverts on API failure
|
||||
|
||||
4. **Settings error banner** (`data-test="cache-settings-error"`)
|
||||
- Shown when `store.cacheSettingsError` is set
|
||||
- Never shows credentials or object_key fields
|
||||
|
||||
Existing Cloud connections section (`Test`, `Reconnect`, `Edit`, `Rename`, `Remove`) is completely untouched.
|
||||
|
||||
## Test Results
|
||||
|
||||
| File | Tests | Pass | Notes |
|
||||
|------|-------|------|-------|
|
||||
| cloudConnections.analysis.test.js | 17 | 17 | All pass (unchanged from Plan 07) |
|
||||
| SettingsCloudTab.test.js | 7 | 7 | All pass; no regressions |
|
||||
| SettingsCloudTab.health.test.js | 10 | 10 | All pass; no regressions |
|
||||
| Full frontend suite | 471 | 471 | No regressions introduced |
|
||||
|
||||
Backend:
|
||||
- `pytest -q tests/test_cloud_cache.py -k "settings"` — 0 matched (settings tests covered by
|
||||
test_cloud_security.py in Plan 03; cache.py routes unchanged in this plan)
|
||||
|
||||
## Deviations from Plan
|
||||
|
||||
### Auto-fixed Issues
|
||||
|
||||
**1. [Rule 1 - Bug] getCacheSettings/updateCacheSettings pointed to non-existent /api/users/me/settings**
|
||||
- **Found during:** Task 1, reading the Plan 03 backend spec
|
||||
- **Issue:** Both `getCacheSettings()` and `updateCacheSettings()` in `api/cloud.js` called
|
||||
`/api/users/me/settings` which was never implemented in the backend. The actual endpoints
|
||||
from Plan 14-03 are `GET /api/cloud/analysis/cache` and `PATCH /api/cloud/analysis/cache/settings`.
|
||||
- **Fix:** Corrected both URLs to match the Plan 14-03 backend routes.
|
||||
- **Files modified:** `frontend/src/api/cloud.js`
|
||||
- **Commit:** 6fc30ac
|
||||
|
||||
## Known Stubs
|
||||
|
||||
None — all controls are wired to real store actions which call the real API. The backend
|
||||
cache/settings API was implemented in Plan 14-03. In tests, the API is mocked at the
|
||||
`api/client.js` boundary per existing patterns.
|
||||
|
||||
## Threat Flags
|
||||
|
||||
None — no new network endpoints introduced. All settings calls route through
|
||||
authenticated `request()`/`jsonRequest()` helpers. CacheStatusOut response schema
|
||||
excludes object_key and credentials_enc at design level (T-14-02/T-14-08). The UI
|
||||
stores no credentials and renders no object_key fields.
|
||||
|
||||
## Self-Check: PASSED
|
||||
Reference in New Issue
Block a user