docs(12): capture phase context
This commit is contained in:
curo1305
@@ -0,0 +1,118 @@
|
||||
# Phase 12: Cloud Resource Foundation - Context
|
||||
|
||||
**Gathered:** 2026-06-18
|
||||
**Status:** Ready for planning
|
||||
|
||||
<domain>
|
||||
## Phase Boundary
|
||||
|
||||
Phase 12 establishes the provider-neutral capability contract, durable owner-scoped cloud item metadata, and shared browser foundation needed for cloud resources to feel local without mirroring provider-owned file bytes. It defines connection identity, capability presentation, cached-first metadata browsing, and cloud row status semantics. Phase 13 implements the file mutations; Phase 14 implements byte hydration, analysis, and eviction.
|
||||
|
||||
</domain>
|
||||
|
||||
<decisions>
|
||||
## Implementation Decisions
|
||||
|
||||
### Cloud Navigation Identity
|
||||
- **D-01:** The Cloud Storage root shows every connected account as a top-level location in one unified browser.
|
||||
- **D-02:** A connection is a first-class identity independent of provider type. Users may connect multiple accounts from the same provider.
|
||||
- **D-03:** Each connection has a customizable display name. Its default is the plain provider label, such as `OneDrive`; duplicate default names must remain distinguishable until renamed.
|
||||
- **D-04:** Inside a connection, breadcrumbs begin with the connection display name, followed by the provider folder path. A cloud/source icon identifies the root without adding a separate `Cloud` breadcrumb segment.
|
||||
- **D-05:** The last visited folder is remembered only for the current browser session. A fresh session starts at the connection root.
|
||||
|
||||
### Provider Capabilities and Explanations
|
||||
- **D-06:** The shared browser keeps action controls in consistent positions. Structurally unsupported actions remain visible but greyed out rather than disappearing.
|
||||
- **D-07:** Hovering or focusing an unsupported action shows a simple, specific explanation. On touch devices, tapping the disabled control reveals the same explanation without executing it.
|
||||
- **D-08:** Capability support and explanation text are dynamic per connection, based on provider-advertised features, granted permissions, and safe read-only checks. Capability discovery must never create, rename, move, or delete user content as a probe.
|
||||
- **D-09:** Permanent limitations and temporary failures have different visual states: grey means structurally unsupported; warning styling means temporarily blocked by permissions, authentication, connection health, or another recoverable condition.
|
||||
- **D-10:** Temporary explanations should include a useful remedy when one exists, such as reconnecting with write access.
|
||||
|
||||
### Metadata Freshness
|
||||
- **D-11:** Opening a previously visited folder renders durable cached metadata immediately and reconciles with the provider in the background.
|
||||
- **D-12:** Background reconciliation uses a subtle folder-level indicator near the breadcrumb or toolbar. Cached rows remain usable while refresh is running.
|
||||
- **D-13:** Provider changes are reconciled silently in place. Preserve stable row identity, scroll position, and selection where possible; do not show routine change toasts.
|
||||
- **D-14:** If refresh fails, retain the cached listing, show a connection warning and last-successful-refresh time, and retry automatically with bounded exponential backoff.
|
||||
|
||||
### Cloud Item Presentation and Storage State
|
||||
- **D-15:** Cloud folders use the same row structure and ordinary metadata as local storage. Provider/connection badges are contextual: show them at connection roots and in future mixed-source views, not repeatedly on every row inside one connection.
|
||||
- **D-16:** The breadcrumb-level sync indicator has three states: refreshing, up to date, and connection warning. Its tooltip includes the last successful refresh time.
|
||||
- **D-17:** Per-file byte availability uses a compact status icon. Cloud-only items have no extra marker; items whose actual bytes are retained by DocuVault show a cache indicator with details in its tooltip.
|
||||
- **D-18:** Metadata and search/index records do not consume the user's document-storage quota. Actual cloud file bytes retained in DocuVault storage consume quota while present, and eviction releases that usage. Bytes streamed through memory and immediately discarded do not consume storage quota.
|
||||
|
||||
### Claude's Discretion
|
||||
- Choose the exact icons, tooltip wording, warning colors, subtle refresh animation, and duplicate-default-name disambiguation, while preserving accessibility and the state distinctions above.
|
||||
- Choose the bounded retry intervals and metadata persistence mechanics consistent with existing Celery and service patterns.
|
||||
|
||||
</decisions>
|
||||
|
||||
<canonical_refs>
|
||||
## Canonical References
|
||||
|
||||
**Downstream agents MUST read these before planning or implementing.**
|
||||
|
||||
### Milestone Scope
|
||||
- `.planning/ROADMAP.md` — Phase 12 goal, requirements, and success criteria; Phase 13 and 14 boundaries prevent operation/cache scope creep.
|
||||
- `.planning/REQUIREMENTS.md` — canonical definitions for CONN-04, CLOUD-01, CLOUD-08, CACHE-01, CACHE-02, and SYNC-01.
|
||||
- `.planning/PROJECT.md` — virtual-local cloud storage decision, privacy constraints, and shared-component architecture.
|
||||
- `.planning/research/SUMMARY.md` — milestone research synthesis and recommended virtual-document direction.
|
||||
- `.planning/research/ARCHITECTURE.md` — capability layer, cloud item index, shared browser, and byte-cache boundaries.
|
||||
|
||||
### Existing Backend
|
||||
- `backend/storage/base.py` — current object-storage contract; Phase 12 needs a cloud resource capability contract without forcing provider navigation into MinIO semantics.
|
||||
- `backend/services/cloud_cache.py` — current 60-second in-memory listing cache, to be superseded or complemented by durable owner-scoped metadata.
|
||||
- `backend/api/cloud.py` — current provider-keyed connection lookup and browse endpoints; multiple same-provider accounts require connection identity in routes and queries.
|
||||
- `backend/db/models.py` — current `CloudConnection` and `Document` models; cloud item metadata must remain owner scoped and independent of provider-owned bytes.
|
||||
|
||||
### Existing Frontend
|
||||
- `frontend/src/components/storage/StorageBrowser.vue` — the single shared file browser; capability-aware actions and status presentation belong here.
|
||||
- `frontend/src/views/CloudFolderView.vue` — thin cloud data provider that currently routes by provider and hides most local actions.
|
||||
- `frontend/src/views/FileManagerView.vue` — reference thin-view integration for local actions and shared browser behavior.
|
||||
- `frontend/src/utils/formatters.js` — shared provider labels and metadata formatting.
|
||||
|
||||
</canonical_refs>
|
||||
|
||||
<code_context>
|
||||
## Existing Code Insights
|
||||
|
||||
### Reusable Assets
|
||||
- `StorageBrowser.vue`: already renders local and cloud rows, breadcrumbs, search, upload progress, and action slots; extend it through capability/status props and generic events.
|
||||
- `BreadcrumbBar.vue`: existing shared breadcrumb presentation can host connection identity and folder-level sync state.
|
||||
- `cloud_cache.py`: existing owner/provider/folder cache keys and invalidation behavior provide a migration reference, though provider alone is no longer a unique connection key.
|
||||
- Cloud backend factory and provider adapters: existing provider-specific behavior can report normalized capabilities through a separate cloud resource contract.
|
||||
|
||||
### Established Patterns
|
||||
- `FileManagerView` and `CloudFolderView` remain thin data providers; neither should gain duplicate grid or action layout logic.
|
||||
- Smart components receive props and emit actions without calling stores directly.
|
||||
- Cloud credentials remain encrypted and never appear in responses; all connection and cloud item queries must enforce the authenticated owner.
|
||||
- Provider-owned bytes remain authoritative. Durable metadata, analysis placeholders, topics, and semantic-index state exist independently from byte cache entries.
|
||||
|
||||
### Integration Points
|
||||
- Replace provider-only route and lookup assumptions with stable connection IDs while retaining provider type as metadata.
|
||||
- Add durable cloud connection capability and cloud item metadata schemas, migrations, owner-scoped services, and API response models.
|
||||
- Feed normalized connection capabilities, explanations, freshness, and byte-availability state into `StorageBrowser.vue`.
|
||||
- Add ownership and admin-negative tests at API/service boundaries, plus frontend tests for disabled/warning/touch capability states.
|
||||
|
||||
</code_context>
|
||||
|
||||
<specifics>
|
||||
## Specific Ideas
|
||||
|
||||
- The intended feel is like a virtual filesystem: connected accounts are roots, folder navigation is immediate, and provider differences do not rearrange the browser.
|
||||
- A breadcrumb can read `Work OneDrive / Projects / 2026`, with a compact cloud/sync indicator rather than a redundant provider badge on every row.
|
||||
- Capability explanations should be concrete, such as `Rename is not supported by this server` or `Reconnect with write access`.
|
||||
- Actual retained bytes have visible quota consequences; metadata-only browsing does not.
|
||||
|
||||
</specifics>
|
||||
|
||||
<deferred>
|
||||
## Deferred Ideas
|
||||
|
||||
- Make capability tooltips link to relevant DocuVault documentation in a new window after an in-app documentation flow exists.
|
||||
- A user-controlled permanent `keep downloaded` or offline pin action remains future requirement `OFFLINE-01`/`IMPORT-01`; Phase 12 only models status needed by later cache work.
|
||||
|
||||
</deferred>
|
||||
|
||||
---
|
||||
|
||||
*Phase: 12-cloud-resource-foundation*
|
||||
*Context gathered: 2026-06-18*
|
||||
@@ -0,0 +1,71 @@
|
||||
# Phase 12: Cloud Resource Foundation - Discussion Log
|
||||
|
||||
> **Audit trail only.** Do not use as input to planning, research, or execution agents.
|
||||
> Decisions are captured in CONTEXT.md; this log preserves the alternatives considered.
|
||||
|
||||
**Date:** 2026-06-18
|
||||
**Phase:** 12-cloud-resource-foundation
|
||||
**Areas discussed:** Cloud navigation identity, Unsupported actions, Metadata freshness, Cloud item presentation
|
||||
|
||||
---
|
||||
|
||||
## Cloud Navigation Identity
|
||||
|
||||
| Question | Options considered | Selected |
|
||||
|----------|--------------------|----------|
|
||||
| First Cloud Storage screen | All connections as roots; provider picker; last-used connection | All connections as roots |
|
||||
| Connection naming | Customizable name; provider and account; provider only | Customizable, defaulting to provider |
|
||||
| Breadcrumb identity | Connection first; Cloud then connection; provider then connection | Connection first |
|
||||
| Reopening a connection | Last visited; root; remember during session | Remember during session |
|
||||
|
||||
**Notes:** Multiple accounts from the same provider must be supported. Each account is a separate customizable root. A new browser session starts at that connection's root.
|
||||
|
||||
---
|
||||
|
||||
## Unsupported Actions
|
||||
|
||||
| Question | Options considered | Selected |
|
||||
|----------|--------------------|----------|
|
||||
| Unsupported action visibility | Disabled in place; hidden; limitations menu | Disabled in place |
|
||||
| Touch explanation | Tap; adjacent info marker; long press | Tap |
|
||||
| Explanation detail | Exact reason/remedy; provider-level reason; generic | Exact dynamic reason/remedy |
|
||||
| Temporary versus permanent limits | Different states; same state; hide temporary | Different states |
|
||||
|
||||
**Notes:** Capability detection must be dynamic per connection. Use provider features, permissions, and safe checks; never mutate user files to test support. A future documentation link from tooltips was deferred.
|
||||
|
||||
---
|
||||
|
||||
## Metadata Freshness
|
||||
|
||||
| Question | Options considered | Selected |
|
||||
|----------|--------------------|----------|
|
||||
| Previously visited folder | Cached-first background refresh; wait for provider; manual refresh | Cached-first |
|
||||
| Refresh visibility | Subtle folder indicator; silent unless failed; mark every row | Subtle folder indicator |
|
||||
| External changes | Update with notice; update silently; ask before apply | Update silently |
|
||||
| Refresh failure | Keep cached with warning; replace with error; hide warning | Keep cached with warning |
|
||||
|
||||
**Notes:** Show the last successful refresh time after failures and keep retrying with bounded, increasing delays.
|
||||
|
||||
---
|
||||
|
||||
## Cloud Item Presentation
|
||||
|
||||
| Question | Options considered | Selected |
|
||||
|----------|--------------------|----------|
|
||||
| Source repetition | Contextual only; provider icon per row; connection badge per row | Contextual only |
|
||||
| Normal row metadata | Match local rows; analysis column; technical details | Match local rows |
|
||||
| Byte availability | Compact status icon; text label; dedicated column | Compact status icon |
|
||||
| Breadcrumb sync state | Three states; binary; activity only | Three states |
|
||||
|
||||
**Notes:** The breadcrumb shows refreshing, up-to-date, or warning state. Metadata does not consume document quota. Actual file bytes retained by DocuVault do consume quota until evicted; transient in-memory streaming does not.
|
||||
|
||||
---
|
||||
|
||||
## Claude's Discretion
|
||||
|
||||
- Exact iconography, accessible tooltip wording, warning styling, retry intervals, and duplicate-name disambiguation.
|
||||
|
||||
## Deferred Ideas
|
||||
|
||||
- Link capability tooltips to DocuVault documentation after a documentation flow exists.
|
||||
- Permanent offline/downloaded copies remain a future phase rather than Phase 12 scope.
|
||||
Reference in New Issue
Block a user