chore: archive v0.2 phase directories to milestones/v0.2-phases/

Moves phases 08–11 execution artifacts from .planning/phases/ to .planning/milestones/v0.2-phases/ to keep .planning/phases/ clean for the next milestone. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-06-17 14:34:52 +02:00
parent e008bf7dae
commit 123ae5b29b
101 changed files with 759 additions and 4 deletions
@@ -0,0 +1,149 @@
+---
+phase: 09-admin-panel-rearchitecture
+verified: 2026-06-12T00:00:00Z
+status: human_needed
+score: 5/5 must-haves verified
+overrides_applied: 0
+human_verification:
+  - test: "Navigate to /admin/users, /admin/quotas, /admin/ai, /admin/audit as an admin user"
+    expected: "Each URL loads the correct admin view with the AdminSidebar visible on the left"
+    why_human: "Cannot run a browser to verify router-view renders the child component within AdminLayout at runtime"
+  - test: "Log in as a non-admin user and navigate directly to /admin/users"
+    expected: "Browser redirects to / without rendering any admin content"
+    why_human: "Guard logic is correct in code but runtime redirect behavior requires browser execution"
+  - test: "Navigate from /admin/users to /admin/quotas then press browser back button"
+    expected: "Returns to /admin/users — deep-link history works"
+    why_human: "Vue Router nested route history behavior requires browser verification; cannot test with static analysis"
+  - test: "Trigger a topic badge and a provider chip render in production build"
+    expected: "Color classes (e.g. bg-sky-100, bg-amber-50, text-indigo-600) appear correctly — not stripped by Tailwind purge"
+    why_human: "Tailwind safelist presence is verified in config, but visual rendering in a production bundle requires runtime check"
+---
+
+# Phase 09: Admin Panel Rearchitecture Verification Report
+
+**Phase Goal:** The admin interface is a standalone route subtree (/admin/*) with its own layout component and sidebar; each admin section is deep-linkable and browser-back-button works; the requiresAdmin navigation guard correctly protects all child routes; and the Tailwind safelist is configured so dynamic color classes render correctly in production builds.
+
+**Verified:** 2026-06-12
+**Status:** human_needed
+**Re-verification:** No — initial verification
+
+---
+
+## Goal Achievement
+
+### Observable Truths
+
+| # | Truth | Status | Evidence |
+|---|-------|--------|----------|
+| 1 | /admin/* subtree uses AdminLayout as route component with nested children | VERIFIED | `router/index.js` line 44-55: `/admin` has `component: AdminLayout.vue`, 5 named children (`''`, `users`, `quotas`, `ai`, `audit`) |
+| 2 | requiresAdmin guard uses `to.matched.some(r => r.meta.requiresAdmin)` | VERIFIED | `router/index.js` line 103: exact pattern present; old flat `to.meta.requiresAdmin` pattern absent (grep returned 0 hits) |
+| 3 | Non-admin redirected to `/` by beforeEach guard | VERIFIED | `router/index.js` line 107-109: `if (isAdminRoute && !isAdmin) return { path: '/' }` — guard fires on all matched routes via `to.matched.some()` |
+| 4 | AdminView.vue is deleted and no file imports it | VERIFIED | `ls frontend/src/views/AdminView.vue` returns DELETED; grep for `AdminView` in all `.vue`/`.js`/`.ts` (excluding tests) returns 0 hits |
+| 5 | Tailwind safelist covers dynamic color families | VERIFIED | `tailwind.config.js` lines 4-7: two regex patterns covering `bg-` and `text-` with families blue/sky/green/purple/orange/amber/gray/indigo/red |
+
+**Score:** 5/5 truths verified
+
+### Required Artifacts
+
+| Artifact | Expected | Status | Details |
+|----------|----------|--------|---------|
+| `frontend/src/router/index.js` | Nested /admin subtree + `to.matched.some()` guard | VERIFIED | Nested route at line 44, guard at line 103 |
+| `frontend/src/layouts/AdminLayout.vue` | `<AdminSidebar>` + `<router-view>` in flex shell | VERIFIED | 14-line file: flex container, AdminSidebar import, `<router-view />` inside `<main>` |
+| `frontend/src/components/admin/AdminSidebar.vue` | 5 nav links, no Back-to-app | VERIFIED | Exactly 5 `<router-link>` elements (Overview/Users/Quotas/AI Config/Audit Log); "Back to app" grep returns NOT FOUND |
+| `backend/api/admin/overview.py` | GET /api/admin/overview returning 4 keys | VERIFIED | Handler returns dict with `user_count`, `total_storage_bytes`, `doc_status`, `recent_audit`; protected by `get_current_admin` |
+| `frontend/src/views/admin/AdminOverviewView.vue` | Standalone view file | VERIFIED | Exists in `frontend/src/views/admin/` |
+| `frontend/src/views/admin/AdminUsersView.vue` | Standalone view file | VERIFIED | Exists in `frontend/src/views/admin/` |
+| `frontend/src/views/admin/AdminQuotasView.vue` | Standalone view file | VERIFIED | Exists in `frontend/src/views/admin/` |
+| `frontend/src/views/admin/AdminAiView.vue` | Standalone view file | VERIFIED | Exists in `frontend/src/views/admin/` |
+| `frontend/src/views/admin/AdminAuditView.vue` | Standalone view file | VERIFIED | Exists in `frontend/src/views/admin/` |
+| `frontend/tailwind.config.js` | safelist with sky + amber | VERIFIED | Regex patterns include `sky` and `amber` explicitly |
+| `frontend/src/views/AdminView.vue` | Must not exist | VERIFIED | File deleted; no imports remain |
+
+### Key Link Verification
+
+| From | To | Via | Status | Details |
+|------|----|-----|--------|---------|
+| `/admin` parent route | `AdminLayout.vue` | `component: () => import('../layouts/AdminLayout.vue')` | WIRED | `router/index.js` line 46 |
+| `AdminLayout.vue` | `AdminSidebar.vue` | `import AdminSidebar from '../components/admin/AdminSidebar.vue'` | WIRED | `AdminLayout.vue` line 13 |
+| `AdminLayout.vue` | child views | `<router-view />` | WIRED | `AdminLayout.vue` line 6 |
+| Parent route meta | child routes | `to.matched.some(r => r.meta.requiresAdmin)` | WIRED | Only parent carries `requiresAdmin: true`; guard walks `matched` array |
+| `backend/api/admin/__init__.py` | `overview.py` | `router.include_router(overview_router)` | WIRED | `__init__.py` line 17 + 22 |
+| `AdminSidebar` guard redirect | non-admin user | `isAdminRoute && !isAdmin → { path: '/' }` | WIRED | `router/index.js` lines 107-109 |
+
+### Data-Flow Trace (Level 4)
+
+| Artifact | Data Variable | Source | Produces Real Data | Status |
+|----------|---------------|--------|--------------------|--------|
+| `overview.py` | `user_count` | `select(func.count(User.id)).where(User.role == "user")` | Yes — live DB scalar | FLOWING |
+| `overview.py` | `total_storage_bytes` | `select(func.sum(Quota.used_bytes))` | Yes — live DB scalar | FLOWING |
+| `overview.py` | `doc_status` | `select(Document.status, func.count(...)).group_by(Document.status)` | Yes — live DB aggregation | FLOWING |
+| `overview.py` | `recent_audit` | `_build_filtered_query_with_handles(...).order_by(...).limit(10)` | Yes — live DB query via shared helper | FLOWING |
+
+### Requirements Coverage
+
+| Requirement | Description | Status | Evidence |
+|-------------|-------------|--------|----------|
+| ADMIN-08 | Admin panel at /admin/* with AdminLayout, AdminView.vue deleted | SATISFIED | Nested route with AdminLayout confirmed; AdminView.vue deleted with no remaining imports |
+| ADMIN-09 | Sidebar nav: Overview/Users/Quotas/AI Config/Audit Log; Back-to-app | PARTIAL | 5 nav links verified. ADMIN-09 requires a "Back to app" link at bottom returning to `/`; this is explicitly absent per D-06 decision. The plan documents this as intentional override — admin accounts are operators only. |
+| ADMIN-10 | Deep-linkable URLs, browser back works | VERIFIED (code) | Nested router with HTML5 history mode; each child is a distinct path; requires runtime human check |
+| ADMIN-11 | Overview page shows user count, storage, doc status, last 10 audit entries | SATISFIED | Backend returns all 4 fields; AdminOverviewView.vue renders 4-card grid + audit table |
+| ADMIN-12 | requiresAdmin guard via `to.matched.some()` for all /admin/* children | SATISFIED | `router/index.js` line 103 uses exact required pattern |
+| CODE-06 | Tailwind safelist for dynamic color classes | SATISFIED | `tailwind.config.js` safelist covers provider colors (sky/blue/orange/gray) and audit badge colors (amber/purple) |
+| CODE-09 | No what-comments; only why-comments | SATISFIED | Plan 05 purge applied; WHY comments (D-08/D-09/D-10/D-16/D-17, security invariants) preserved; WHAT comments removed |
+
+**ADMIN-09 deviation note:** The requirement explicitly states a "Back to app" link. The plan documents decision D-06 which intentionally removes this link on the grounds that admin accounts are operators only. This is a deliberate deviation from the requirement text, not an oversight. The requirement as written in REQUIREMENTS.md is not fully satisfied, but the deviation is documented and intentional.
+
+### Anti-Patterns Found
+
+| File | Line | Pattern | Severity | Impact |
+|------|------|---------|----------|--------|
+| None found | — | — | — | — |
+
+No TBD/FIXME/XXX markers found in phase files. No stub returns (empty arrays/objects with no data source). No placeholder content detected.
+
+### Human Verification Required
+
+#### 1. Admin route renders correct view with sidebar
+
+**Test:** As an admin user, navigate directly (type in address bar) to `/admin/users`, `/admin/quotas`, `/admin/ai`, `/admin/audit`
+**Expected:** Each URL loads the correct content view inside AdminLayout — admin sidebar visible on the left, correct view content on the right
+**Why human:** `<router-view />` rendering inside `AdminLayout` at runtime cannot be confirmed by static analysis
+
+#### 2. Non-admin redirect enforced at runtime
+
+**Test:** Log in as a regular (non-admin) user; navigate directly to `/admin/users`
+**Expected:** Browser redirects to `/` without flashing any admin content
+**Why human:** Navigation guard execution and redirect behavior requires a live browser session
+
+#### 3. Browser back button works between admin routes
+
+**Test:** As an admin, navigate to `/admin/users`, then to `/admin/quotas`, then press the browser back button
+**Expected:** Returns to `/admin/users`; pressing back again returns to pre-admin history
+**Why human:** Vue Router nested route history stack behavior requires runtime verification
+
+#### 4. Tailwind safelist prevents color purge in production
+
+**Test:** Run `npm run build`, deploy the built assets, render a document with a topic badge (e.g. indigo color) and a cloud provider chip (OneDrive = sky color)
+**Expected:** Color classes render with correct background and text colors — not defaulting to unstyled
+**Why human:** While safelist regex patterns are verified present in config, actual CSS output from the production build must be inspected to confirm no purge occurred
+
+---
+
+### Gaps Summary
+
+No blocking gaps found. All 5 success criteria are satisfied in the codebase:
+
+1. The /admin/* nested route subtree is wired with AdminLayout as its component — all 5 child routes exist and are lazy-loaded.
+2. The `to.matched.some(r => r.meta.requiresAdmin)` guard pattern is used correctly; the old flat `to.meta.requiresAdmin` pattern is absent.
+3. Deep-linking is structurally enabled via Vue Router 4 nested routes with HTML5 history mode.
+4. `AdminView.vue` is fully deleted with zero remaining imports anywhere in the frontend.
+5. Tailwind safelist is configured with regex patterns covering all dynamic color families used by `formatters.js` and `actionTypeClass()`.
+
+One documented deviation: ADMIN-09 requires a "Back to app" link in the sidebar. Decision D-06 in the plan intentionally removes this. The sidebar has exactly 5 nav links with no link to `/`. This is a product decision, not an implementation error — the planner accepted it.
+
+Four human verification items exist (runtime routing behavior and CSS output), which are not automatable by static analysis. All automated checks pass.
+
+---
+
+_Verified: 2026-06-12_
+_Verifier: Claude (gsd-verifier)_