curo/kite
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
24a5cbc11222e6e39c81a83c5d926ecd5ec97226
kite/.planning/REQUIREMENTS.md
T
curo1305andClaude Sonnet 4.6 e6f5f2be3b test(phase-09): complete UAT — 9/9 tests passed; mark phase complete 
All 9 UAT items verified via live API + source inspection:
- GET /api/admin/overview live data (78 users, 8MB storage, 10 audit rows)
- Auth guard: 401 unauthenticated, 403 non-admin on all protected endpoints
- Admin login redirect (D-08) confirmed in LoginView.vue line 212
- Sidebar: 5 nav links, indigo Admin badge, no back-to-app link
- 4-stat-card overview + When/Event/Actor/Target/IP audit table
- 5 standalone admin views (Users, Quotas, AI, Audit) with no Pinia stores
- API key write-only invariant confirmed in AdminAiView.vue
- Color-coded audit badges (auth=blue, admin=amber, folder/share=purple)
- to.matched.some() guard covers all /admin/* child routes
- No sensitive fields (password_hash, credentials_enc) in any response

Phase 9 marked complete. STATE.md and PROJECT.md updated for Phase 10.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-06-13 11:32:19 +02:00

151 lines
10 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# DocuVault v0.2 — Requirements
**Milestone:** v0.2 — UI Overhaul and Optimization
**Created:** 2026-06-07
**Total requirements:** 40
---
## Quality Mandate (applies to all phases)
Every line of code written or modified in v0.2 must be:
- **Minimal:** smallest amount of code that correctly solves the problem. No speculative abstractions.
- **DRY:** if the same logic exists twice, extract it. Duplication is a defect.
- **Readable:** names things accurately. A reader should understand intent without comments.
- **No redundant comments:** comments exist only where the *why* is non-obvious. Never explain what the code does.
- **No dead code:** unreferenced files, components, or functions are deleted — not commented out.
---
## CODE — Codebase Quality
- [ ] **CODE-01**: Backend `api/admin.py` (934L) decomposed into `api/admin/` package with `users.py`, `quotas.py`, `ai.py`; `__init__.py` aggregates sub-routers under the existing `/api/admin` prefix. No URL changes, no behavior changes, all tests stay green.
- [ ] **CODE-02**: `api/documents.py` (852L) decomposed into focused sub-modules (upload flow, content proxy, document CRUD, search/listing) within `api/documents/` package. Prefix and behavior unchanged.
- [ ] **CODE-03**: `api/auth.py` (825L) decomposed into focused sub-modules (login/tokens, TOTP, password management, session management) within `api/auth/` package. Prefix and behavior unchanged.
- [x] **CODE-04**: Frontend `api/client.js` (635L) decomposed into domain modules (`documents.js`, `auth.js`, `admin.js`, `folders.js`, `shares.js`, `cloud.js`, `topics.js`); `client.js` becomes the HTTP transport layer and re-export barrel. Zero changes to any of the 35+ consumer files.
- [ ] **CODE-05**: All inline SVG blocks (~66 instances) replaced with `<AppIcon name="..." class="..." />`; all icon path data centralized in `components/ui/AppIcon.vue`. No duplicated path strings.
- [x] **CODE-06**: Tailwind `safelist` configured for all dynamic class name patterns in `formatters.js` (provider colors, backgrounds, badge text). Production builds render topic and provider colors correctly.
- [ ] **CODE-07**: All unreferenced files, components, stores, and unused imports deleted. No dead code retained.
- [x] **CODE-08**: No duplicated Pydantic model definitions or shared validators across router files. Shared schemas extracted to dedicated modules.
- [x] **CODE-09**: No comment in any file describes what the code does. Comments exist only where intent or constraint would not be obvious to a competent reader.
---
## ADMIN — Admin Panel
- [x] **ADMIN-08**: Admin panel moved to `/admin/*` route subtree with `AdminLayout.vue` as the route component. `AdminLayout` has its own sidebar with admin-specific nav only — no user quota bar, no folder tree, no topic list. `AdminView.vue` is deleted.
- [x] **ADMIN-09**: Admin sidebar nav links (in order): Overview, Users, Quotas, AI Config, Audit Log. "Back to app" link at the bottom returns to `/`.
- [x] **ADMIN-10**: Each admin section is its own deep-linkable URL (`/admin/users`, `/admin/quotas`, `/admin/ai`, `/admin/audit`). Browser back button works within the admin section.
- [x] **ADMIN-11**: Admin overview page (`/admin`) shows: total registered user count, total platform storage in use, document status breakdown (processing/ready/failed), last 10 audit log entries. Requires new backend aggregate query endpoints.
- [x] **ADMIN-12**: `requiresAdmin` guard enforced for all `/admin/*` child routes via `to.matched.some(r => r.meta.requiresAdmin)`. No admin child route is accessible to non-admin users.
---
## UX — UX and Interaction
- [ ] **UX-01**: Every zero-content context shows a contextually distinct empty state using a shared `EmptyState.vue` component (headline, subtext, optional CTA). Applied to: root file list, individual folder, search with no results, shared-with-me, topics list, audit log, cloud connections. No plain "No items" text remains.
- [ ] **UX-02**: Document list (`StorageBrowser`) displays 5-col skeleton grid rows during loading (matching actual grid layout, `animate-pulse`). "Loading..." text removed.
- [ ] **UX-03**: Sidebar folder tree and topics list display skeleton placeholder items during loading. "Loading..." text removed.
- [ ] **UX-04**: Admin user table and audit log table display skeleton table rows during loading.
- [ ] **UX-05**: Pressing `/` when no input is focused moves keyboard focus to the search bar.
- [ ] **UX-06**: Pressing `Escape` closes any open modal (`ShareModal`, `FolderDeleteModal`, `DocumentPreviewModal`) and clears active search. Handled at the overlay level, not only inside inputs.
- [ ] **UX-07**: Pressing `U` when no input is focused triggers the file upload picker.
- [ ] **UX-08**: Pressing `N` when no input is focused starts the new folder inline input in the file manager.
- [ ] **UX-09**: Dragging files from the OS anywhere onto the browser window shows a full-screen drop overlay. Releasing uploads the files via the existing upload flow. Only activates when `dataTransfer.types` includes `'Files'`.
- [ ] **UX-10**: Toast notification system shows transient messages (auto-dismiss 4 seconds, manual dismiss on click) for: upload complete, upload error, document deleted, share revoked, rename successful. Toasts stack vertically and do not block interaction.
- [ ] **UX-11**: Drag-to-move a document onto a folder row in `StorageBrowser` works correctly end-to-end. Drop highlight (`ring-2 ring-inset ring-amber-300`) renders on valid folder targets. "Move to folder" button remains as non-drag alternative.
- [ ] **UX-12**: All views display a breadcrumb reflecting the full current navigation path. Examples: `Folders › Reports › Q1`, `Cloud › Google Drive › Projects`, `Admin › Users`, `Settings › Account`, `Folders › Reports › document.pdf`. Breadcrumb updates on navigation. A single shared breadcrumb component is used across all view types — no per-view implementations.
- [ ] **UX-13**: All dropdown menus and modal dialogs render their full content within the viewport. No text or interactive element is clipped by a viewport edge or sibling element. Dropdowns that risk edge-clipping use fixed positioning computed from `getBoundingClientRect()` or `<Teleport to="body">`.
- [ ] **UX-14**: The inline "New" button next to the Folders section header in `AppSidebar.vue` is removed. Folder creation accessible only from within the file manager view.
---
## VISUAL — Visual Design
- [ ] **VISUAL-01**: Consistent spacing scale across all components using Tailwind utilities only. No arbitrary `px-[13px]` values or inline `style` margins.
- [ ] **VISUAL-02**: All form elements (inputs, selects, textareas, checkboxes, radio buttons) have consistent cross-browser baseline styling via `@tailwindcss/forms` plugin.
- [ ] **VISUAL-03**: All interactive elements (buttons, links, card rows) have consistent hover states, `focus-visible:` rings, and active states.
- [ ] **VISUAL-04**: Typography scale is consistent: one heading size per level, one body size, one label/caption size. No per-component font-size overrides.
---
## RESP — Responsive Layout
- [ ] **RESP-01**: Sidebar hidden below `lg` (1024px). Hamburger button in mobile-only header toggles a slide-in overlay drawer. Overlay closes on nav tap or backdrop tap.
- [ ] **RESP-02**: Document list hides Size column below `md` (768px) and Modified column below `sm` (640px). Icon, name, and actions always visible.
- [ ] **RESP-03**: Inline icon action buttons have minimum 36×36px touch target on viewports below `md`.
- [ ] **RESP-04**: All modal dialogs are scrollable on viewports below 640px. No modal content overflows the screen.
- [ ] **RESP-05**: Admin layout has the same responsive behavior as the user layout: admin sidebar hidden on mobile, hamburger shows admin nav drawer.
---
## PERF — Performance and Stack
- [ ] **PERF-01**: Frontend dependencies bumped/added: `vue@^3.5.0`, `vite@^6.4.3`, `@vueuse/core@^14.3.0`, `@vueuse/integrations@^14.3.0`, `sortablejs@^1.15.7`, `@tailwindcss/forms@^0.5.11`. Dev: `rollup-plugin-visualizer@^7.0.1`, `@types/sortablejs`.
- [ ] **PERF-02**: Bundle baseline measured with `rollup-plugin-visualizer` before optimizations begin. Second measurement taken after all refactoring is complete. Both reports committed to `.planning/`.
- [ ] **PERF-03**: All non-initial-render route components are lazy-loaded. Admin views explicitly lazy-loaded. No synchronous import for routes not on the critical render path.
---
## Future (deferred)
- Virtual scrolling — quota cap (100 MB/user) limits lists to hundreds of items; `v-for` is sufficient. Revisit with server-side pagination.
- Dark mode — coherent color token system must exist first.
- Folder reordering by drag — requires persistent `position` column in DB.
- Multi-select with batch operations — low frequency in a personal vault.
## Out of Scope
- Composition API migration — refactor within Options API; Composition API is a separate milestone.
- Component library switch (shadcn-vue, PrimeVue) — stay with Tailwind.
- SSO, billing, group roles — v0.x exclusions unchanged from v0.1.
- Document annotation or in-app editing — not planned.
---
## Traceability
| REQ-ID | Phase | Plan |
|--------|-------|------|
| PERF-01 | Phase 8 | Pending |
| CODE-01 | Phase 8 | Pending |
| CODE-02 | Phase 8 | Pending |
| CODE-03 | Phase 8 | Pending |
| CODE-04 | Phase 8 | Complete |
| CODE-08 | Phase 8 | Complete |
| ADMIN-08 | Phase 9 | Complete |
| ADMIN-09 | Phase 9 | Complete |
| ADMIN-10 | Phase 9 | Complete |
| ADMIN-11 | Phase 9 | Complete |
| ADMIN-12 | Phase 9 | Complete |
| CODE-06 | Phase 9 | Complete |
| CODE-09 | Phase 9 | Complete |
| UX-01 | Phase 10 | Pending |
| UX-02 | Phase 10 | Pending |
| UX-03 | Phase 10 | Pending |
| UX-04 | Phase 10 | Pending |
| UX-05 | Phase 10 | Pending |
| UX-06 | Phase 10 | Pending |
| UX-07 | Phase 10 | Pending |
| UX-08 | Phase 10 | Pending |
| UX-09 | Phase 10 | Pending |
| UX-10 | Phase 10 | Pending |
| UX-11 | Phase 10 | Pending |
| UX-12 | Phase 10 | Pending |
| UX-13 | Phase 10 | Pending |
| UX-14 | Phase 10 | Pending |
| CODE-05 | Phase 10 | Pending |
| VISUAL-01 | Phase 11 | Pending |
| VISUAL-02 | Phase 11 | Pending |
| VISUAL-03 | Phase 11 | Pending |
| VISUAL-04 | Phase 11 | Pending |
| RESP-01 | Phase 11 | Pending |
| RESP-02 | Phase 11 | Pending |
| RESP-03 | Phase 11 | Pending |
| RESP-04 | Phase 11 | Pending |
| RESP-05 | Phase 11 | Pending |
| CODE-07 | Phase 11 | Pending |
| PERF-02 | Phase 11 | Pending |
| PERF-03 | Phase 11 | Pending |
Reference in New Issue View Git Blame Copy Permalink