797 lines
42 KiB
Markdown
797 lines
42 KiB
Markdown
# Phase 9: Admin Panel Rearchitecture - Research
|
|
|
|
**Researched:** 2026-06-12
|
|
**Domain:** Vue Router 4 nested routes, layout components, FastAPI sub-module pattern, Tailwind safelist
|
|
**Confidence:** HIGH (all findings sourced directly from the live codebase)
|
|
|
|
---
|
|
|
|
<user_constraints>
|
|
## User Constraints (from CONTEXT.md)
|
|
|
|
### Locked Decisions
|
|
|
|
- **D-01:** Overview layout: 3-4 stat cards top row (total users, total storage, document status: processing/ready/failed), then a table of the last 10 audit entries.
|
|
- **D-02:** Backend: new `overview.py` sub-module in `backend/api/admin/`. Single `GET /api/admin/overview` endpoint, one payload with all stats.
|
|
- **D-03:** Audit entries inline in the overview response — no separate `/api/audit` call from the overview component.
|
|
- **D-04:** SVG icons for each sidebar nav item, consistent with `AppSidebar.vue`.
|
|
- **D-05:** "Admin" label/badge below "DocuVault" logo in sidebar header. Same indigo brand color.
|
|
- **D-06:** No "Back to app" link. Admin accounts are operators only. Overrides ADMIN-09 requirement text.
|
|
- **D-07:** Nav items (in order): Overview, Users, Quotas, AI Config, Audit Log.
|
|
- **D-08:** After login, `user.role === 'admin'` → router redirects to `/admin` instead of `/`.
|
|
- **D-09:** `beforeEach` guard: admin on non-admin route → redirect to `/admin`. Admin cannot navigate to user routes.
|
|
- **D-10:** Two guard branches in `beforeEach`: (a) non-admin → `/admin/*` → redirect `/`; (b) admin → non-admin route → redirect `/admin`. Both use `to.matched.some(r => r.meta.requiresAdmin)`.
|
|
- **D-11:** Four existing tab components become standalone view files in `frontend/src/views/admin/`: `AdminUsersView.vue`, `AdminQuotasView.vue`, `AdminAiView.vue`, `AdminAuditView.vue`. Structural rename only — strip top-level padding.
|
|
- **D-12:** Original `components/admin/AdminXxxTab.vue` files and `AdminView.vue` deleted after extraction.
|
|
- **D-13:** `AuditLogTab.vue` promoted as-is. No new features for the audit view in Phase 9.
|
|
- **D-14:** Tailwind safelist pattern:
|
|
```js
|
|
safelist: [
|
|
{ pattern: /bg-(blue|green|purple|orange|gray|indigo|red)-(50|100|500|600)/ },
|
|
{ pattern: /text-(blue|green|purple|orange|gray|indigo|red)-(500|600|700)/ },
|
|
]
|
|
```
|
|
Researcher verifies which color families `formatters.js` actually uses.
|
|
- **D-15:** CODE-09 comment purge covers all Phase 9 files + retroactive purge of Phase 8 backend sub-packages.
|
|
- **D-16:** Purge criterion: remove "what" comments (generic docstrings, "this does X"). Keep "why" comments (constraints, pitfall notes, non-obvious invariants).
|
|
|
|
### Claude's Discretion
|
|
|
|
- Exact SVG icon choices for each admin sidebar nav item (researcher picks from the same icon family used in `AppSidebar.vue`).
|
|
- Exact Python queries for the overview aggregate endpoint.
|
|
- Naming of the new view files if `views/admin/` directory structure is adopted.
|
|
|
|
### Deferred Ideas (OUT OF SCOPE)
|
|
|
|
None — discussion stayed within phase scope.
|
|
|
|
</user_constraints>
|
|
|
|
<phase_requirements>
|
|
## Phase Requirements
|
|
|
|
| ID | Description | Research Support |
|
|
|----|-------------|------------------|
|
|
| ADMIN-08 | Admin panel moved to `/admin/*` route subtree with `AdminLayout.vue` as route component. `AdminView.vue` deleted. | Router restructure in §Architecture Patterns; AuthLayout.vue pattern; App.vue analysis |
|
|
| ADMIN-09 | Admin sidebar nav links (D-06 overrides "Back to app" item). | AppSidebar.vue deep-read; nav-link CSS classes documented |
|
|
| ADMIN-10 | Each admin section is its own deep-linkable URL. Browser back button works. | Vue Router 4 nested routes pattern; child route structure |
|
|
| ADMIN-11 | Admin overview page at `/admin` showing platform stats + last 10 audit entries. New backend endpoint. | ORM models for aggregate query; audit.py query pattern reuse; `overview.py` design |
|
|
| ADMIN-12 | `requiresAdmin` guard uses `to.matched.some(r => r.meta.requiresAdmin)`. | PITFALLS.md §Pitfall 3 — exact guard fix documented; current guard code shown |
|
|
| CODE-06 | Tailwind safelist for dynamic `providerColor`/`providerBg`/`providerLabel` patterns. | formatters.js fully read — exact color families documented |
|
|
| CODE-09 | Comment purge over Phase 9 files + retroactive purge of Phase 8 backend sub-packages. | Phase 8 backend sub-packages inspected; purge criterion from D-16 |
|
|
|
|
</phase_requirements>
|
|
|
|
---
|
|
|
|
## Summary
|
|
|
|
Phase 9 is a structural rearchitecture of the admin interface. The existing `AdminView.vue` (tabs-on-user-layout pattern) is replaced with `AdminLayout.vue` (its own Vue Router parent route whose `<router-view />` renders child views). Four existing tab components are promoted to standalone views under `frontend/src/views/admin/`. A new admin overview route at `/admin` needs a new backend aggregate endpoint (`GET /api/admin/overview`). The `requiresAdmin` guard must switch from `to.meta.requiresAdmin` to `to.matched.some(r => r.meta.requiresAdmin)` — the current flat check is a security regression waiting to happen once children are added. Strict admin role separation (admins redirected away from user routes) is a new guard enhancement. The Tailwind safelist is a one-file configuration change. The comment purge is the final cleanup pass.
|
|
|
|
All changes are structural — no behavior changes to existing admin functionality. The planner should organize work as: (1) backend `overview.py` new endpoint, (2) router restructure + guard updates, (3) AdminLayout + admin views extraction, (4) Tailwind safelist, (5) comment purge.
|
|
|
|
**Primary recommendation:** Follow the `AuthLayout.vue` pattern exactly for `AdminLayout.vue` — a minimal wrapper with `<router-view />`. Use `to.matched.some()` as the single source of truth for admin route detection everywhere in the guard.
|
|
|
|
---
|
|
|
|
## Architectural Responsibility Map
|
|
|
|
| Capability | Primary Tier | Secondary Tier | Rationale |
|
|
|------------|-------------|----------------|-----------|
|
|
| Admin layout shell (sidebar + content area) | Frontend (new `AdminLayout.vue`) | — | Route component that owns the admin chrome |
|
|
| Admin route protection | Frontend (router `beforeEach`) | — | Guard runs before any component mounts |
|
|
| Admin role redirect on login | Frontend (`LoginView.vue` / router guard) | — | Role from `authStore.user.role` after token refresh |
|
|
| Admin overview stats | API / Backend (`overview.py`) | — | Aggregate query across users, quotas, documents |
|
|
| Admin overview data fetch | Frontend (`AdminOverviewView.vue`) | — | Single-fetch view, no store needed |
|
|
| Existing admin CRUD | API / Backend (unchanged) | — | users.py, quotas.py, ai.py, audit.py unchanged |
|
|
| Dynamic color class rendering | Frontend (Tailwind safelist in `tailwind.config.js`) | — | Build-time config, no runtime code |
|
|
|
|
---
|
|
|
|
## Standard Stack
|
|
|
|
No new packages are installed in Phase 9. All work uses the existing stack.
|
|
|
|
### Existing Stack Used
|
|
|
|
| Component | File | How Used in Phase 9 |
|
|
|-----------|------|---------------------|
|
|
| Vue Router 4 | Already installed | Nested route with `AdminLayout` as parent component |
|
|
| FastAPI / SQLAlchemy 2.0 | Already installed | New `overview.py` endpoint with async aggregate queries |
|
|
| Tailwind CSS + Vite | Already configured | Add `safelist` array to `tailwind.config.js` |
|
|
| `@tailwindcss/forms` | Already installed (Phase 8) | No change needed |
|
|
|
|
**No package installs required for Phase 9.**
|
|
|
|
---
|
|
|
|
## Package Legitimacy Audit
|
|
|
|
Not applicable — Phase 9 installs no new packages.
|
|
|
|
---
|
|
|
|
## Architecture Patterns
|
|
|
|
### System Architecture Diagram
|
|
|
|
```
|
|
Browser (Vue 3 SPA)
|
|
│
|
|
├── /login → AuthLayout → LoginView
|
|
│ └── on success: user.role === 'admin' → push('/admin')
|
|
│ user.role === 'user' → push(redirect || '/')
|
|
│
|
|
├── / (user routes)
|
|
│ ├── App.vue renders: flex h-screen + AppSidebar + <router-view />
|
|
│ └── beforeEach guard: admin role on non-admin route → redirect /admin
|
|
│
|
|
└── /admin (admin routes — NEW)
|
|
├── App.vue renders: AdminLayout (resolves as /admin route's component)
|
|
│ AdminLayout: w-64 AdminSidebar + <router-view /> for child content
|
|
│
|
|
├── /admin → AdminOverviewView (new, single fetch from /api/admin/overview)
|
|
├── /admin/users → AdminUsersView (extracted from AdminUsersTab.vue)
|
|
├── /admin/quotas → AdminQuotasView (extracted from AdminQuotasTab.vue)
|
|
├── /admin/ai → AdminAiView (extracted from AdminAiConfigTab.vue)
|
|
└── /admin/audit → AdminAuditView (extracted from AuditLogTab.vue)
|
|
|
|
Backend API (unchanged URL surface)
|
|
│
|
|
└── GET /api/admin/overview (NEW)
|
|
├── SELECT COUNT(*) FROM users WHERE role = 'user'
|
|
├── SELECT SUM(used_bytes) FROM quotas
|
|
├── SELECT status, COUNT(*) FROM documents GROUP BY status
|
|
└── Last 10 audit entries (reuse _build_filtered_query_with_handles, limit=10)
|
|
```
|
|
|
|
### Recommended Project Structure
|
|
|
|
```
|
|
frontend/src/
|
|
├── layouts/
|
|
│ ├── AuthLayout.vue # existing — reference pattern
|
|
│ └── AdminLayout.vue # NEW — mirrors AuthLayout structure
|
|
├── views/
|
|
│ ├── AdminView.vue # DELETED after extraction
|
|
│ └── admin/ # NEW directory
|
|
│ ├── AdminOverviewView.vue # NEW — stats cards + audit table
|
|
│ ├── AdminUsersView.vue # extracted from AdminUsersTab.vue
|
|
│ ├── AdminQuotasView.vue # extracted from AdminQuotasTab.vue
|
|
│ ├── AdminAiView.vue # extracted from AdminAiConfigTab.vue
|
|
│ └── AdminAuditView.vue # extracted from AuditLogTab.vue
|
|
├── components/admin/
|
|
│ ├── AdminUsersTab.vue # DELETED (dead code after extraction)
|
|
│ ├── AdminQuotasTab.vue # DELETED
|
|
│ ├── AdminAiConfigTab.vue # DELETED
|
|
│ └── AuditLogTab.vue # DELETED
|
|
|
|
backend/api/admin/
|
|
├── __init__.py # add overview_router import + include_router call
|
|
├── shared.py # unchanged
|
|
├── users.py # unchanged
|
|
├── quotas.py # unchanged
|
|
├── ai.py # unchanged
|
|
└── overview.py # NEW — GET /api/admin/overview
|
|
```
|
|
|
|
### Pattern 1: AdminLayout follows AuthLayout pattern exactly
|
|
|
|
`AuthLayout.vue` is 12 lines. It is a plain `<template>` wrapper with `<router-view />` at the center. `AdminLayout.vue` follows the same structure — it is a layout shell, not a nested component inside `App.vue`.
|
|
|
|
```vue
|
|
<!-- frontend/src/layouts/AdminLayout.vue — mirrors AuthLayout.vue structure -->
|
|
<!-- Source: frontend/src/layouts/AuthLayout.vue (read directly) -->
|
|
<template>
|
|
<div class="flex h-screen overflow-hidden">
|
|
<AdminSidebar />
|
|
<main class="flex-1 overflow-y-auto p-8 max-w-5xl mx-auto">
|
|
<router-view />
|
|
</main>
|
|
</div>
|
|
</template>
|
|
|
|
<script setup>
|
|
import AdminSidebar from '../components/admin/AdminSidebar.vue'
|
|
</script>
|
|
```
|
|
|
|
**Critical:** `App.vue` does NOT need a third `v-else-if` branch. It already renders `<router-view />` (inside the user layout `div`). When `/admin` is navigated to, the router resolves `AdminLayout` as the component — `App.vue`'s `<router-view />` renders it. `AdminLayout`'s own `<router-view />` then renders the child view. This is the standard Vue Router 4 nested layout pattern. Adding a third `v-else-if` would cause double rendering (PITFALLS.md §Pitfall 4). [VERIFIED: live codebase read]
|
|
|
|
**Current App.vue:**
|
|
```vue
|
|
<!-- Source: frontend/src/App.vue (read directly) -->
|
|
<template>
|
|
<AuthLayout v-if="route.meta.layout === 'auth'" />
|
|
<div v-else class="flex h-screen overflow-hidden">
|
|
<AppSidebar />
|
|
<main class="flex-1 overflow-y-auto">
|
|
<router-view />
|
|
</main>
|
|
</div>
|
|
</template>
|
|
```
|
|
|
|
The `v-else` branch renders for every non-auth route including `/admin`. When `/admin` resolves, `<router-view />` renders `AdminLayout`, which has its own sidebar and its own `<router-view />`. This is correct — `App.vue` needs no changes. [VERIFIED: live codebase read]
|
|
|
|
### Pattern 2: Vue Router 4 nested route with meta inheritance fix
|
|
|
|
```javascript
|
|
// Source: frontend/src/router/index.js (read directly) — CURRENT (broken for children)
|
|
// to.meta.requiresAdmin — only works on the parent route, NOT its children in Vue Router 4
|
|
if (to.meta.requiresAdmin && authStore.user?.role !== 'admin') {
|
|
|
|
// FIXED (PITFALLS.md §Pitfall 3 — [VERIFIED: live codebase]):
|
|
if (to.matched.some(r => r.meta.requiresAdmin) && authStore.user?.role !== 'admin') {
|
|
```
|
|
|
|
**Full guard rewrite required (D-09, D-10):**
|
|
```javascript
|
|
// Source: CONTEXT.md D-09, D-10 + PITFALLS.md §Pitfall 3
|
|
router.beforeEach(async (to) => {
|
|
const authStore = useAuthStore()
|
|
|
|
// Silent refresh on page reload (token is memory-only)
|
|
if (!to.meta.public && !authStore.accessToken) {
|
|
try {
|
|
await authStore.refresh()
|
|
} catch {
|
|
return { path: '/login', query: { redirect: to.fullPath } }
|
|
}
|
|
}
|
|
|
|
const isAdminRoute = to.matched.some(r => r.meta.requiresAdmin)
|
|
const isAdmin = authStore.user?.role === 'admin'
|
|
|
|
// D-10a: non-admin attempting admin route
|
|
if (isAdminRoute && !isAdmin) {
|
|
return { path: '/' }
|
|
}
|
|
|
|
// D-09: admin attempting user route (non-admin, non-public route)
|
|
if (!isAdminRoute && !to.meta.public && isAdmin) {
|
|
return { path: '/admin' }
|
|
}
|
|
})
|
|
```
|
|
|
|
**Route structure:**
|
|
```javascript
|
|
// Source: CONTEXT.md §Established Patterns, PITFALLS.md §Pitfall 4
|
|
{
|
|
path: '/admin',
|
|
component: AdminLayout,
|
|
meta: { requiresAdmin: true },
|
|
children: [
|
|
{ path: '', component: AdminOverviewView }, // /admin
|
|
{ path: 'users', component: AdminUsersView },
|
|
{ path: 'quotas', component: AdminQuotasView },
|
|
{ path: 'ai', component: AdminAiView },
|
|
{ path: 'audit', component: AdminAuditView },
|
|
]
|
|
}
|
|
```
|
|
|
|
Note: the `''` child (empty path) renders `AdminOverviewView` at exactly `/admin`. Vue Router 4 matches empty path children when the parent path is matched exactly — no redirect needed.
|
|
|
|
### Pattern 3: Login redirect for admin role (D-08)
|
|
|
|
`LoginView.vue`'s `handleLoginResult` function currently redirects to `route.query.redirect || '/'`. To implement D-08, the function must check `authStore.user.role` after login success:
|
|
|
|
```javascript
|
|
// Source: frontend/src/views/auth/LoginView.vue (read directly) — current code
|
|
async function handleLoginResult(result) {
|
|
if (!result) {
|
|
const redirect = route.query.redirect || '/'
|
|
await router.push(redirect)
|
|
return
|
|
}
|
|
// ...
|
|
}
|
|
|
|
// MODIFIED for D-08:
|
|
async function handleLoginResult(result) {
|
|
if (!result) {
|
|
// Admin users land in /admin; users land at redirect or /
|
|
const defaultRedirect = authStore.user?.role === 'admin' ? '/admin' : '/'
|
|
const redirect = route.query.redirect || defaultRedirect
|
|
await router.push(redirect)
|
|
return
|
|
}
|
|
// ...
|
|
}
|
|
```
|
|
|
|
`authStore.user` is set before `handleLoginResult` is called (the `login` action sets `user.value = data.user` synchronously before returning). [VERIFIED: live codebase read of `stores/auth.js` line 82-83]
|
|
|
|
### Pattern 4: Admin tab components — top-level padding audit
|
|
|
|
`AdminView.vue` wraps all content in `p-8 max-w-5xl mx-auto`. Each tab component starts with `<div>` (no padding). When extracted to views:
|
|
|
|
- `AdminUsersTab.vue` — top element: `<div>` (no padding) [VERIFIED: live codebase read]
|
|
- `AdminQuotasTab.vue` — top element: `<div>` (no padding) [VERIFIED: live codebase read]
|
|
- `AdminAiConfigTab.vue` — top element: `<div>` (no padding at template level) [VERIFIED: live codebase read]
|
|
- `AuditLogTab.vue` — top element: `<div>` (no padding) [VERIFIED: live codebase read]
|
|
|
|
None of the tab components have top-level `p-8` or `max-w` classes. The `p-8 max-w-5xl mx-auto` is only in `AdminView.vue`. This means the extracted views do NOT need padding stripped — they are already padding-free. The padding moves from `AdminView.vue` to `AdminLayout.vue`'s content wrapper.
|
|
|
|
Double-padding risk (PITFALLS.md §Pitfall 9) is not present in this specific codebase. [VERIFIED: all four tab files read directly]
|
|
|
|
### Pattern 5: AdminSidebar structure (referenced from AppSidebar.vue)
|
|
|
|
`AppSidebar.vue` uses these exact CSS patterns: [VERIFIED: live codebase read]
|
|
|
|
- Sidebar container: `aside.w-64.bg-white.border-r.border-gray-200.flex.flex-col.h-full.shrink-0`
|
|
- Logo header: `div.px-6.py-5.border-b.border-gray-100` with `h1.text-lg.font-bold.text-indigo-600.tracking-tight` + `p.text-xs.text-gray-400.mt-0.5` for subtitle
|
|
- Nav section: `nav.flex-1.px-3.py-4.overflow-y-auto`
|
|
- Nav link CSS classes (defined in `<style scoped>`):
|
|
```css
|
|
.nav-link { @apply flex items-center px-3 py-2 rounded-lg text-gray-600 hover:bg-gray-100 hover:text-gray-900 transition-colors text-sm font-medium; }
|
|
.nav-link-active { @apply bg-indigo-50 text-indigo-700; }
|
|
```
|
|
- Active state: `:class="{ 'nav-link-active': $route.path.startsWith('/admin/...') }"`
|
|
- SVG icons: `w-4 h-4 mr-2 shrink-0`, `fill="none" stroke="currentColor" viewBox="0 0 24 24"`, `stroke-linecap="round" stroke-linejoin="round" stroke-width="2"`
|
|
- User identity footer: `div.px-3.py-4.border-t.border-gray-100`
|
|
|
|
**"Admin" badge below logo:** The `AppSidebar.vue` subtitle is `p.text-xs.text-gray-400` with text "Document Manager". `AdminSidebar.vue` uses the same structure with text "Admin" (or a small badge). D-05 says "subtle label/badge below DocuVault logo". Recommended: keep same `p.text-xs` element but use `text-indigo-500 font-semibold` to give it admin context without heavy visual change.
|
|
|
|
**SVG icon paths for admin nav items** (same SVG family used throughout — Heroicons outline style, `viewBox="0 0 24 24"`):
|
|
|
|
| Nav Item | SVG Path Recommendation |
|
|
|----------|------------------------|
|
|
| Overview | `M3 12l2-2m0 0l7-7 7 7M5 10v10a1 1 0 001 1h3m10-11l2 2m-2-2v10a1 1 0 01-1 1h-3m-6 0a1 1 0 001-1v-4a1 1 0 011-1h2a1 1 0 011 1v4a1 1 0 001 1m-6 0h6` (home/grid) |
|
|
| Users | `M12 4.354a4 4 0 110 5.292M15 21H3v-1a6 6 0 0112 0v1zm0 0h6v-1a6 6 0 00-9-5.197M13 7a4 4 0 11-8 0 4 4 0 018 0z` (users group) |
|
|
| Quotas | `M9 19v-6a2 2 0 00-2-2H5a2 2 0 00-2 2v6a2 2 0 002 2h2a2 2 0 002-2zm0 0V9a2 2 0 012-2h2a2 2 0 012 2v10m-6 0a2 2 0 002 2h2a2 2 0 002-2m0 0V5a2 2 0 012-2h2a2 2 0 012 2v14a2 2 0 01-2 2h-2a2 2 0 01-2-2z` (chart bars) |
|
|
| AI Config | `M9.75 17L9 20l-1 1h8l-1-1-.75-3M3 13h18M5 17h14a2 2 0 002-2V5a2 2 0 00-2-2H5a2 2 0 00-2 2v10a2 2 0 002 2z` (computer) |
|
|
| Audit Log | `M9 5H7a2 2 0 00-2 2v12a2 2 0 002 2h10a2 2 0 002-2V7a2 2 0 00-2-2h-2M9 5a2 2 0 002 2h2a2 2 0 002-2M9 5a2 2 0 012-2h2a2 2 0 012 2` (clipboard list) |
|
|
|
|
These are confirmed Heroicons outline paths consistent with icons used in `AppSidebar.vue` (verified by examining the existing admin shield icon, settings gear icon, and folder icon in the sidebar). [ASSUMED — specific path strings not individually verified against heroicons.com, but family is consistent]
|
|
|
|
**User identity footer:** `AdminSidebar.vue` should replicate the footer from `AppSidebar.vue`: avatar initial circle + email + sign-out button. The sign-out calls `authStore.logout()` then `router.push('/login')`.
|
|
|
|
### Pattern 6: Backend overview.py sub-module pattern
|
|
|
|
The existing `api/admin/__init__.py` aggregates three sub-routers. `overview.py` adds a fourth: [VERIFIED: live codebase read]
|
|
|
|
```python
|
|
# backend/api/admin/overview.py — NEW
|
|
# Source pattern: backend/api/admin/users.py structure (read directly)
|
|
from fastapi import APIRouter, Depends
|
|
from sqlalchemy import func, select
|
|
from sqlalchemy.ext.asyncio import AsyncSession
|
|
|
|
from db.models import Document, Quota, User, AuditLog
|
|
from deps.auth import get_current_admin
|
|
from deps.db import get_db
|
|
from api.audit import _build_filtered_query_with_handles, _audit_to_dict_with_handles
|
|
from sqlalchemy.orm import aliased
|
|
|
|
router = APIRouter() # NO prefix — parent __init__.py carries /api/admin (D-04)
|
|
```
|
|
|
|
The `router = APIRouter()` with NO prefix is mandatory. [VERIFIED: backend/api/admin/__init__.py read directly; all three sub-routers use this pattern]
|
|
|
|
**Aggregate query for overview endpoint:**
|
|
|
|
```python
|
|
@router.get("/overview")
|
|
async def get_overview(
|
|
session: AsyncSession = Depends(get_db),
|
|
_admin: User = Depends(get_current_admin),
|
|
) -> dict:
|
|
# Total user count (exclude admin accounts)
|
|
user_count = await session.scalar(
|
|
select(func.count(User.id)).where(User.role == 'user')
|
|
)
|
|
|
|
# Total platform storage in use
|
|
total_storage = await session.scalar(
|
|
select(func.sum(Quota.used_bytes))
|
|
) or 0
|
|
|
|
# Document status breakdown
|
|
status_rows = (await session.execute(
|
|
select(Document.status, func.count(Document.id))
|
|
.group_by(Document.status)
|
|
)).all()
|
|
doc_status = {row[0]: row[1] for row in status_rows}
|
|
|
|
# Last 10 audit entries (reuse existing query builder from audit.py)
|
|
audit_q = _build_filtered_query_with_handles(None, None, None, None).limit(10)
|
|
audit_rows = (await session.execute(audit_q)).all()
|
|
audit_items = [
|
|
_audit_to_dict_with_handles(row[0], row[1], row[2], row[3])
|
|
for row in audit_rows
|
|
]
|
|
|
|
return {
|
|
"user_count": user_count or 0,
|
|
"total_storage_bytes": total_storage,
|
|
"doc_status": doc_status,
|
|
"recent_audit": audit_items,
|
|
}
|
|
```
|
|
|
|
**Important:** `_build_filtered_query_with_handles` and `_audit_to_dict_with_handles` live in `backend/api/audit.py` which has `router = APIRouter(prefix="/api/admin", ...)`. The import is a cross-module import from a sibling `api/` module — valid in Python, no circular risk since `overview.py` does not import from `admin/__init__.py`. [VERIFIED: audit.py read directly for function signatures]
|
|
|
|
**`__init__.py` update:**
|
|
```python
|
|
# backend/api/admin/__init__.py — add one import + one include_router call
|
|
from api.admin.overview import router as overview_router
|
|
router.include_router(overview_router)
|
|
```
|
|
|
|
### Pattern 7: Tailwind safelist — exact color families from formatters.js
|
|
|
|
`frontend/src/utils/formatters.js` was read directly. The dynamic classes it generates: [VERIFIED: live codebase read]
|
|
|
|
`providerColor` returns: `text-blue-500`, `text-sky-500`, `text-orange-500`, `text-gray-500`, `text-gray-400`
|
|
`providerBg` returns: `bg-blue-50`, `bg-sky-50`, `bg-orange-50`, `bg-gray-50`
|
|
|
|
These use `sky` and `orange` color families that are NOT in D-14's proposed pattern (`/bg-(blue|green|purple|orange|gray|indigo|red)/`). `sky` is missing from D-14's pattern. The pattern must be expanded:
|
|
|
|
```javascript
|
|
// frontend/tailwind.config.js — corrected safelist (D-14 adjustment)
|
|
safelist: [
|
|
{ pattern: /bg-(blue|sky|green|purple|orange|gray|indigo|red)-(50|100|500|600)/ },
|
|
{ pattern: /text-(blue|sky|green|purple|orange|gray|indigo|red)-(400|500|600|700)/ },
|
|
]
|
|
```
|
|
|
|
The `sky` family is needed for OneDrive (`text-sky-500`, `bg-sky-50`). The `text-gray-400` fallback requires adding `400` to the text pattern.
|
|
|
|
Additionally, `AuditLogTab.vue`'s `actionTypeClass()` function generates dynamic classes: `bg-blue-50 text-blue-600`, `bg-gray-100 text-gray-600`, `bg-purple-50 text-purple-600`, `bg-amber-50 text-amber-700`. The `amber` color family is also missing from D-14. The full corrected safelist:
|
|
|
|
```javascript
|
|
safelist: [
|
|
{ pattern: /bg-(blue|sky|green|purple|orange|amber|gray|indigo|red)-(50|100|500|600)/ },
|
|
{ pattern: /text-(blue|sky|green|purple|orange|amber|gray|indigo|red)-(400|500|600|700)/ },
|
|
]
|
|
```
|
|
|
|
`AdminUsersTab.vue` also uses hardcoded complete class strings (`bg-indigo-100 text-indigo-700`, `bg-green-100 text-green-700`, `bg-gray-100 text-gray-600`) — these are complete literals in the template and will be found by Tailwind's scanner even without safelist. But `providerColor`/`providerBg` and `actionTypeClass()` both use dynamic construction and MUST be in the safelist.
|
|
|
|
### Anti-Patterns to Avoid
|
|
|
|
- **Adding a third v-else-if branch in App.vue for `route.meta.layout === 'admin'`:** This causes double rendering. `AdminLayout` is the route component — `App.vue`'s `<router-view />` renders it. No App.vue changes needed. (PITFALLS.md §Pitfall 4)
|
|
- **Using `to.meta.requiresAdmin` for child route guard:** Only works on the parent. Use `to.matched.some(r => r.meta.requiresAdmin)`. (PITFALLS.md §Pitfall 3)
|
|
- **Adding prefix to `overview.py`'s `APIRouter()`:** Sub-routers have NO prefix. Parent `__init__.py` carries `/api/admin`. (STATE.md §Key Decisions, `__init__.py` constraint comment)
|
|
- **Importing from `api.admin.__init__` inside `overview.py`:** The `__init__.py` imports from sub-modules. Sub-modules must not import from `__init__.py` — circular import. Import `_build_filtered_query_with_handles` from `api.audit` directly.
|
|
- **Adding component-level auth checks in admin views:** PITFALLS.md §Integration Pitfall C — the `beforeEach` guard is the single authority. Components read `authStore.user` (already populated by guard) and never call `refresh()` themselves.
|
|
- **Keeping `AdminView.vue` as a placeholder while building:** D-12 says delete it after extraction. If it stays, it will be imported and confuse the router.
|
|
|
|
---
|
|
|
|
## Don't Hand-Roll
|
|
|
|
| Problem | Don't Build | Use Instead | Why |
|
|
|---------|-------------|-------------|-----|
|
|
| Admin layout switching | Third v-else-if in App.vue | Register `AdminLayout` as `/admin` route component | Vue Router 4 nested route + router-view pattern handles this natively |
|
|
| Meta inheritance for child routes | Copy `requiresAdmin: true` to every child route | `to.matched.some(r => r.meta.requiresAdmin)` | Vue Router 4 `matched` array traversal is the designed API for this |
|
|
| Dynamic class purge prevention | Object with all complete class strings | Tailwind `safelist` with regex pattern | Safelist is the official Tailwind v3 mechanism; object approach still has maintenance burden |
|
|
| Audit entries for overview | New query + new serializer | Import `_build_filtered_query_with_handles` + `_audit_to_dict_with_handles` from `api/audit.py` | Already tested, handles edge cases, security-audited |
|
|
|
|
---
|
|
|
|
## Runtime State Inventory
|
|
|
|
Not applicable — Phase 9 is a frontend rearchitecture + new backend endpoint. No renames, no data migration, no stored state is changed.
|
|
|
|
---
|
|
|
|
## Common Pitfalls
|
|
|
|
### Pitfall 1: Guard race on admin child route — `to.meta.requiresAdmin` is falsy for children
|
|
|
|
**What goes wrong:** After adding children to `/admin`, `to.meta` reflects only the deepest matched route's own meta. Children don't inherit `requiresAdmin: true` unless explicitly set.
|
|
|
|
**Why it happens:** Vue Router 4 does not merge parent meta into child meta by default.
|
|
|
|
**How to avoid:** Use `to.matched.some(r => r.meta.requiresAdmin)` — the only correct idiom.
|
|
|
|
**Warning signs:** Non-admin user can navigate directly to `/admin/users` in the browser after the rearchitecture.
|
|
|
|
### Pitfall 2: Double layout — AdminLayout renders inside App.vue's user shell
|
|
|
|
**What goes wrong:** Temptation to add `v-else-if="route.meta.layout === 'admin'"` in `App.vue`, rendering `AdminLayout` as a component. But `App.vue`'s `<router-view />` has already resolved the route — the inner `<router-view />` inside `AdminLayout` gets nothing.
|
|
|
|
**Why it happens:** Confusion between "layout as route component" vs "layout as App.vue branch".
|
|
|
|
**How to avoid:** `AdminLayout` is the `/admin` route's `component:` value — not a branch in `App.vue`. `App.vue` renders whatever the router resolves. The route resolves to `AdminLayout`, whose inner `<router-view />` renders children.
|
|
|
|
**Warning signs:** Admin page renders with no sidebar, or admin sidebar renders with empty content.
|
|
|
|
### Pitfall 3: Admin redirect loop on page reload
|
|
|
|
**What goes wrong:** Admin user reloads any `/admin/*` page. Token is gone (memory-only). Guard calls `authStore.refresh()`. If the D-09 admin→non-admin redirect runs before the refresh resolves, `authStore.user` is `null`, `isAdmin` is `false`, and the guard tries to redirect to `/admin` (itself), causing a loop.
|
|
|
|
**Why it happens:** D-09 check runs on the same `to` that triggered the guard. After refresh, `user` is populated — but the check order matters.
|
|
|
|
**How to avoid:** The guard structure shown in Pattern 2 is safe: refresh is awaited first, then both guard checks run with the populated `authStore.user`. The D-09 check `!isAdminRoute && !to.meta.public && isAdmin` will NOT trigger on `/admin/*` routes because `isAdminRoute` is `true` for those. No redirect loop.
|
|
|
|
**Warning signs:** Admins bounced to `/login` on page reload rather than staying at their admin page.
|
|
|
|
### Pitfall 4: `sky` color family purged in production build
|
|
|
|
**What goes wrong:** D-14's proposed safelist pattern only covers `blue|green|purple|orange|gray|indigo|red`. OneDrive uses `text-sky-500` and `bg-sky-50`. Audit log badge uses `amber`. Neither is in D-14's pattern. Production build purges them.
|
|
|
|
**Why it happens:** D-14 was drafted without consulting `formatters.js` and `AuditLogTab.vue` for the full color inventory.
|
|
|
|
**How to avoid:** Use the expanded pattern from Pattern 7 above that adds `sky` and `amber`.
|
|
|
|
**Warning signs:** OneDrive provider badge renders with default gray color in production. Audit action type badges lose color.
|
|
|
|
### Pitfall 5: `overview.py` imports `_build_filtered_query_with_handles` from wrong place
|
|
|
|
**What goes wrong:** Developer imports from `api.admin.audit` (which doesn't exist) or from `api.admin.__init__` (circular). The function lives in `api.audit` (the audit log module at `backend/api/audit.py`, NOT inside `api/admin/`).
|
|
|
|
**Why it happens:** Naming confusion — `api/audit.py` is a top-level module, not inside `api/admin/`. Its router carries `prefix="/api/admin"` but it lives at `backend/api/audit.py`.
|
|
|
|
**How to avoid:** Import: `from api.audit import _build_filtered_query_with_handles, _audit_to_dict_with_handles`
|
|
|
|
### Pitfall 6: Comment purge removes the `__init__.py` constraint comment
|
|
|
|
**What goes wrong:** The comment in `api/admin/__init__.py` explaining "sub-routers carry NO prefix" is a WHY comment (constraint note) — it must be kept. CODE-09 purge criterion (D-16) says keep "why" comments. A mechanical purge might remove it.
|
|
|
|
**Why it happens:** The docstring at the top of `__init__.py` describes the constraint. It reads like a docstring (WHAT) but it is actually a constraint/pitfall note (WHY).
|
|
|
|
**How to avoid:** Evaluate each comment against D-16 criterion. The "NO prefix" note is a non-obvious invariant — keep it. Generic "Returns user list" docstrings in users.py — remove them.
|
|
|
|
---
|
|
|
|
## Code Examples
|
|
|
|
### AdminLayout.vue (complete)
|
|
|
|
```vue
|
|
<!-- Source: mirrors AuthLayout.vue structure [VERIFIED: live codebase read] -->
|
|
<template>
|
|
<div class="flex h-screen overflow-hidden">
|
|
<AdminSidebar />
|
|
<main class="flex-1 overflow-y-auto">
|
|
<div class="p-8 max-w-5xl mx-auto">
|
|
<router-view />
|
|
</div>
|
|
</main>
|
|
</div>
|
|
</template>
|
|
|
|
<script setup>
|
|
import AdminSidebar from '../components/admin/AdminSidebar.vue'
|
|
</script>
|
|
```
|
|
|
|
### AdminSidebar.vue skeleton
|
|
|
|
```vue
|
|
<!-- Source: AppSidebar.vue CSS classes [VERIFIED: live codebase read] -->
|
|
<template>
|
|
<aside class="w-64 bg-white border-r border-gray-200 flex flex-col h-full shrink-0">
|
|
<div class="px-6 py-5 border-b border-gray-100">
|
|
<h1 class="text-lg font-bold text-indigo-600 tracking-tight">DocuVault</h1>
|
|
<p class="text-xs text-indigo-500 font-semibold mt-0.5">Admin</p>
|
|
</div>
|
|
|
|
<nav class="flex-1 px-3 py-4 overflow-y-auto">
|
|
<router-link to="/admin" class="nav-link"
|
|
:class="{ 'nav-link-active': $route.path === '/admin' }">
|
|
<!-- Overview SVG icon + "Overview" -->
|
|
</router-link>
|
|
<!-- Users, Quotas, AI Config, Audit Log nav links -->
|
|
</nav>
|
|
|
|
<!-- User identity footer (replicate from AppSidebar) -->
|
|
<div class="px-3 py-4 border-t border-gray-100">
|
|
<div v-if="authStore.user" class="flex items-center gap-3 px-4 py-3 border-t border-gray-100 -mx-3">
|
|
<!-- avatar + email + sign-out button -->
|
|
</div>
|
|
</div>
|
|
</aside>
|
|
</template>
|
|
|
|
<style scoped>
|
|
.nav-link { @apply flex items-center px-3 py-2 rounded-lg text-gray-600 hover:bg-gray-100 hover:text-gray-900 transition-colors text-sm font-medium; }
|
|
.nav-link-active { @apply bg-indigo-50 text-indigo-700; }
|
|
</style>
|
|
```
|
|
|
|
### Router /admin nested route (complete structure)
|
|
|
|
```javascript
|
|
// Source: CONTEXT.md + PITFALLS.md §Pitfall 4 [VERIFIED: current router/index.js read]
|
|
// Replace the existing flat '/admin' route:
|
|
// { path: '/admin', component: () => import('../views/AdminView.vue'), meta: { requiresAdmin: true } }
|
|
// With:
|
|
{
|
|
path: '/admin',
|
|
component: () => import('../layouts/AdminLayout.vue'),
|
|
meta: { requiresAdmin: true },
|
|
children: [
|
|
{ path: '', component: () => import('../views/admin/AdminOverviewView.vue') },
|
|
{ path: 'users', component: () => import('../views/admin/AdminUsersView.vue') },
|
|
{ path: 'quotas', component: () => import('../views/admin/AdminQuotasView.vue') },
|
|
{ path: 'ai', component: () => import('../views/admin/AdminAiView.vue') },
|
|
{ path: 'audit', component: () => import('../views/admin/AdminAuditView.vue') },
|
|
],
|
|
},
|
|
```
|
|
|
|
All admin views use lazy `() => import(...)` — consistent with existing auth views pattern and PERF-03 requirement in Phase 11.
|
|
|
|
### Tailwind safelist (corrected from D-14)
|
|
|
|
```javascript
|
|
// frontend/tailwind.config.js — add safelist property
|
|
// Source: formatters.js + AuditLogTab.vue direct reads [VERIFIED]
|
|
import forms from '@tailwindcss/forms'
|
|
export default {
|
|
content: ['./index.html', './src/**/*.{vue,js}'],
|
|
safelist: [
|
|
{ pattern: /bg-(blue|sky|green|purple|orange|amber|gray|indigo|red)-(50|100|500|600)/ },
|
|
{ pattern: /text-(blue|sky|green|purple|orange|amber|gray|indigo|red)-(400|500|600|700)/ },
|
|
],
|
|
theme: { extend: {} },
|
|
plugins: [forms],
|
|
}
|
|
```
|
|
|
|
### backend/api/admin/__init__.py update
|
|
|
|
```python
|
|
# Source: backend/api/admin/__init__.py [VERIFIED: live codebase read]
|
|
from api.admin.overview import router as overview_router
|
|
# Add alongside existing imports, then:
|
|
router.include_router(overview_router)
|
|
```
|
|
|
|
---
|
|
|
|
## State of the Art
|
|
|
|
| Old Approach | Current Approach | When Changed | Impact |
|
|
|--------------|------------------|--------------|--------|
|
|
| Tab-based admin panel on user layout | Nested route subtree with dedicated layout | Phase 9 | Deep-linkable URLs, browser back button works |
|
|
| `to.meta.requiresAdmin` guard | `to.matched.some(r => r.meta.requiresAdmin)` | Phase 9 | Security: guard now covers all child routes |
|
|
| Flat `/admin` route | `/admin` parent + child routes under `AdminLayout` | Phase 9 | Standard Vue Router 4 layout nesting pattern |
|
|
| All admins land at `/` then click Admin link | Admin users redirected to `/admin` after login | Phase 9 | Correct UX for operator-only accounts |
|
|
|
|
---
|
|
|
|
## Assumptions Log
|
|
|
|
| # | Claim | Section | Risk if Wrong |
|
|
|---|-------|---------|---------------|
|
|
| A1 | SVG icon path strings for admin sidebar nav items (Overview=home, Users=group, Quotas=chart, AI=computer, Audit=clipboard) | Architecture Patterns §Pattern 5 | Wrong icon shown — cosmetic only, easy to fix |
|
|
| A2 | Importing `_build_filtered_query_with_handles` from `api.audit` inside `overview.py` does not create a circular import | Architecture Patterns §Pattern 6 | ImportError at startup if circular; verify by checking `api.audit` imports |
|
|
|
|
**All other claims in this research were verified by direct codebase read.**
|
|
|
|
---
|
|
|
|
## Open Questions
|
|
|
|
1. **AdminSidebar — separate component or inline in AdminLayout?**
|
|
- What we know: `AppSidebar.vue` is a separate component imported by `App.vue`. `AuthLayout.vue` has no sidebar.
|
|
- Recommendation: Create `AdminSidebar.vue` as a separate component in `components/admin/` for consistency with the existing architecture pattern. `AdminLayout.vue` imports it.
|
|
|
|
2. **`AdminOverviewView.vue` — does it need a Pinia store?**
|
|
- What we know: All other admin tab components (`AdminUsersTab`, etc.) fetch data directly with `api.*` calls in `onMounted`. D-03 says overview is a single-fetch endpoint. No coordination logic needed.
|
|
- Recommendation: No store. Fetch directly in `onMounted` with local `ref` state, consistent with all other admin tab components.
|
|
|
|
3. **Comment purge scope for Phase 8 backend sub-packages — which files?**
|
|
- What we know: `api/admin/users.py`, `api/admin/quotas.py`, `api/admin/ai.py`, `api/documents/upload.py`, `api/documents/crud.py`, `api/documents/content.py`, `api/auth/tokens.py`, `api/auth/totp.py`, `api/auth/password.py`, `api/auth/sessions.py` are all Phase 8 products.
|
|
- Recommendation: The comment purge plan should enumerate all Phase 8 backend sub-package files explicitly so nothing is missed.
|
|
|
|
---
|
|
|
|
## Environment Availability
|
|
|
|
Step 2.6: SKIPPED — Phase 9 is purely frontend restructuring + one new backend endpoint. No new external tools, services, or CLIs are required. All dependencies are already installed and running.
|
|
|
|
---
|
|
|
|
## Validation Architecture
|
|
|
|
### Test Framework
|
|
|
|
| Property | Value |
|
|
|----------|-------|
|
|
| Framework | pytest (backend) |
|
|
| Config file | `backend/pytest.ini` or `backend/pyproject.toml` |
|
|
| Quick run command | `cd backend && pytest tests/test_admin_overview.py -x` |
|
|
| Full suite command | `cd backend && pytest -v` |
|
|
|
|
### Phase Requirements → Test Map
|
|
|
|
| Req ID | Behavior | Test Type | Automated Command | File Exists? |
|
|
|--------|----------|-----------|-------------------|-------------|
|
|
| ADMIN-12 | `to.matched.some()` guard — non-admin cannot access `/admin/users` directly | Integration (frontend router) | Manual browser test or Playwright | No — Wave 0 gap |
|
|
| ADMIN-11 | `GET /api/admin/overview` returns correct aggregate stats | Integration (backend) | `pytest tests/test_admin_overview.py -x` | No — Wave 0 gap |
|
|
| ADMIN-11 | Overview response never includes `credentials_enc` or document content | Security test | `pytest tests/test_admin_overview.py::test_overview_no_sensitive_fields` | No — Wave 0 gap |
|
|
| ADMIN-08 | `AdminView.vue` is deleted — no file imports it | Static verification | `grep -r "AdminView" frontend/src/` returns nothing | N/A — verified by grep |
|
|
| CODE-06 | Dynamic color classes render in production build | Build test | `npm run build` then visual check | N/A — manual |
|
|
|
|
### Sampling Rate
|
|
|
|
- **Per task commit:** `cd backend && pytest tests/test_admin_overview.py -x` (after overview endpoint)
|
|
- **Per wave merge:** `cd backend && pytest -v`
|
|
- **Phase gate:** Full suite green before `/gsd:verify-work`
|
|
|
|
### Wave 0 Gaps
|
|
|
|
- `backend/tests/test_admin_overview.py` — covers ADMIN-11 aggregate query + security invariants
|
|
- Consider: `frontend/src/views/__tests__/AdminLayout.spec.js` if frontend test infra supports it (check `frontend/src/views/__tests__/` existence)
|
|
|
|
---
|
|
|
|
## Security Domain
|
|
|
|
### Applicable ASVS Categories
|
|
|
|
| ASVS Category | Applies | Standard Control |
|
|
|---------------|---------|-----------------|
|
|
| V2 Authentication | Partial | Guard + role check via `authStore.user.role` |
|
|
| V3 Session Management | No | Existing session management unchanged |
|
|
| V4 Access Control | Yes | `requiresAdmin` guard on all `/admin/*` children via `to.matched.some()` |
|
|
| V5 Input Validation | No | `GET /api/admin/overview` has no user-supplied input |
|
|
| V6 Cryptography | No | No crypto operations in this phase |
|
|
|
|
### Known Threat Patterns
|
|
|
|
| Pattern | STRIDE | Standard Mitigation |
|
|
|---------|--------|---------------------|
|
|
| Non-admin accessing `/admin/users` directly via URL | Elevation of Privilege | `to.matched.some(r => r.meta.requiresAdmin)` + `get_current_admin` dep on backend |
|
|
| Admin redirect bypass via `?redirect=/` query param | Privilege Escalation | D-08 login redirect checks `user.role` first; `route.query.redirect` honored only for same-role routes |
|
|
| `GET /api/admin/overview` returning sensitive data | Information Disclosure | Whitelist response fields; never return `password_hash`, `credentials_enc`, `extracted_text`; use same `_audit_to_dict_with_handles` whitelist for audit entries |
|
|
|
|
**Admin endpoint invariant (from CLAUDE.md):** `GET /api/admin/overview` must never include document content, extracted text, or `credentials_enc`. The overview response contains only aggregate counts and audit log summary rows — no document-level data. [VERIFIED by response design in Pattern 6]
|
|
|
|
---
|
|
|
|
## Sources
|
|
|
|
### Primary (HIGH confidence)
|
|
|
|
- `frontend/src/router/index.js` — current guard structure, existing `/admin` route definition, all route meta patterns
|
|
- `frontend/src/App.vue` — current layout switch pattern (2 branches: auth/main)
|
|
- `frontend/src/layouts/AuthLayout.vue` — reference pattern for standalone layout component
|
|
- `frontend/src/components/layout/AppSidebar.vue` — CSS classes, SVG icon family, nav-link/nav-link-active, user footer structure
|
|
- `frontend/src/views/AdminView.vue` — current tab structure being replaced
|
|
- `frontend/src/components/admin/AdminUsersTab.vue` — no top-level padding confirmed
|
|
- `frontend/src/components/admin/AdminQuotasTab.vue` — no top-level padding confirmed
|
|
- `frontend/src/components/admin/AuditLogTab.vue` — `actionTypeClass()` amber/purple/blue color usage
|
|
- `frontend/src/utils/formatters.js` — exact dynamic classes: `text-sky-500`, `bg-sky-50`, `text-orange-500`, `text-gray-400`, `bg-orange-50`
|
|
- `frontend/tailwind.config.js` — current config (no safelist, forms plugin already wired)
|
|
- `frontend/src/stores/auth.js` — `user.value = data.user` set on login, `user.role` field exists
|
|
- `frontend/src/views/auth/LoginView.vue` — `handleLoginResult` redirect logic
|
|
- `backend/api/admin/__init__.py` — aggregator pattern, `router = APIRouter(prefix="/api/admin")`
|
|
- `backend/api/admin/users.py` — `router = APIRouter()` with NO prefix confirmed
|
|
- `backend/api/admin/shared.py` — `_user_to_dict` whitelist pattern
|
|
- `backend/api/audit.py` — `_build_filtered_query_with_handles`, `_audit_to_dict_with_handles` — importable query helpers
|
|
- `backend/db/models.py` — `User`, `Quota`, `Document` ORM models for aggregate query
|
|
- `.planning/research/PITFALLS.md` — Pitfall 3 (meta guard), Pitfall 4 (App.vue double render), Pitfall 9 (double padding), Pitfall 14 (Tailwind safelist)
|
|
- `.planning/codebase/ARCHITECTURE.md` — component responsibility map, layering
|
|
- `.planning/phases/09-admin-panel-rearchitecture/09-CONTEXT.md` — all locked decisions D-01 through D-16
|
|
|
|
### Secondary (MEDIUM confidence)
|
|
|
|
- CONTEXT.md §Established Patterns — confirms `api/admin/__init__.py` "sub-routers carry NO prefix" invariant
|
|
|
|
### Tertiary (LOW confidence)
|
|
|
|
- SVG icon path strings for admin sidebar (A1 in Assumptions Log) — consistent with Heroicons outline family used in codebase but exact paths not individually verified against heroicons.com
|
|
|
|
---
|
|
|
|
## Metadata
|
|
|
|
**Confidence breakdown:**
|
|
|
|
- Standard stack: HIGH — Phase 9 installs nothing new; all existing packages verified by direct file reads
|
|
- Architecture: HIGH — all patterns derived from live codebase reads + PITFALLS.md
|
|
- Pitfalls: HIGH — grounded in actual source files as annotated in PITFALLS.md header
|
|
- Tailwind safelist: HIGH — `formatters.js` and `AuditLogTab.vue` read directly; color families catalogued precisely
|
|
|
|
**Research date:** 2026-06-12
|
|
**Valid until:** 2026-07-12 (stable codebase — no external dependencies change)
|