docs(admin): phase 3a spec + implementation plan

docs/superpowers/plans/2026-06-17-phase-3a-admin-panel.md

@@ -0,0 +1,320 @@
+# Phase 3a — Admin Panel (MVP) Implementation Plan
+
+> **For agentic workers:** Implement task-by-task with TDD. Steps use checkbox (`- [ ]`) syntax.
+> Spec: `docs/superpowers/specs/2026-06-17-phase-3a-admin-panel-design.md`.
+
+**Goal:** A new `apps/admin` desktop SPA where an admin logs in, watches who is working
+live (auto-refreshing, read-only), and manages handelingen — on existing endpoints plus
+`role` added to `/api/me`.
+
+**Architecture:** Vite + React 18 + TS client (dev port 5174) mirroring `apps/worker`'s
+toolchain. Bearer-token auth reused from worker; admin gate reads `role` from `/api/me`.
+Left-sidebar shell. Live view polls `/api/admin/sessions/active`; activities CRUD via
+`/api/activities`.
+
+**Tech Stack:** Vite 7, React 18.3, react-router-dom 6, @tanstack/react-query 5, vitest 3,
+@testing-library/react 16, TypeScript 5.7, `@solelog/shared` (zod contracts).
+
+## Global Constraints
+
+- **Reuse, don't reinvent:** `apps/worker` is the canonical template — copy `lib/api.ts`,
+  `lib/auth-storage.ts`, tsconfig/vite/vitest configs, `test/setup.ts`, `main.tsx`
+  structure verbatim, adjusting only names/title/port.
+- **Dutch UI strings** throughout (worker app is the reference for tone/terms).
+- **Lint/format:** oxlint + oxfmt — 2-space, single quotes, semicolons, width 100, **es5
+  trailing commas** (no trailing comma in function params or last call args). Run scoped to
+  changed files only; do **not** reformat unrelated files.
+- **TDD:** write the failing test, see it fail, implement minimally, see it pass, commit.
+- **Commit per task** with a conventional-commit message.
+- **No backend change beyond `role` on `/api/me`** (Task 1). Live view is **read-only**.
+- **Windows libsql lock trap:** any agent that starts the API server must kill the server
+  tree afterward (a lingering `tsx`/node holding `data/app.db` or port 3000 breaks the next
+  run). Prefer not starting the server unless verifying live.
+- Admin dev port **5174** (worker uses 5173).
+
+## File Structure
+
+```
+packages/shared/src/index.ts            MODIFY  add role to PublicUser
+apps/api/src/routes/me.ts               MODIFY  return role
+apps/api/test/me.test.ts                MODIFY  assert role present (create if absent)
+
+apps/admin/                             NEW workspace (mirror apps/worker)
+  package.json, index.html, .gitignore, README.md
+  tsconfig.json, tsconfig.app.json, tsconfig.node.json
+  vite.config.ts (port 5174), vitest.config.ts
+  src/
+    main.tsx, vite-env.d.ts, styles.css
+    test/setup.ts
+    lib/api.ts            (copied from worker)
+    lib/auth-storage.ts   (copied from worker)
+    lib/elapsed.ts        (formatTime ported from worker stopwatch)
+    auth/AuthContext.tsx  (signIn + admin-role gate)
+    api/me.ts             (useMe / fetchMe)
+    api/admin-sessions.ts (useActiveSessions, refetchInterval 5000)
+    api/activities.ts     (useActivities + create/update/delete)
+    components/Sidebar.tsx
+    screens/Login.tsx, Live.tsx, Activities.tsx
+    App.tsx
+```
+
+---
+
+### Task 1: Backend — `role` on `/api/me`
+
+**Files:**
+- Modify: `packages/shared/src/index.ts` (PublicUser)
+- Modify: `apps/api/src/routes/me.ts`
+- Test: `apps/api/test/me.test.ts` (extend; or `apps/api/src/routes/me.test.ts` — match
+  where existing route tests live)
+
+**Interfaces:**
+- Produces: `PublicUser` now has `role: Role`; `MeResponse.user.role` is `'worker' | 'admin'`.
+
+- [ ] **Step 1: Write/extend the failing test.** Using the test helpers
+  (`apps/api/test/helpers.ts`: `createTestUser`, `authToken`/`bearer`), assert that
+  `GET /api/me` with a worker token returns `user.role === 'worker'`, and with an admin
+  token returns `user.role === 'admin'`. (Create an admin via `auth.api.createUser` with
+  `role: 'admin'` — see `seed.ts` for the cast pattern.)
+- [ ] **Step 2: Run it, watch it fail** (`role` undefined).
+      `yarn workspace @solelog/api test` (filter to the me test).
+- [ ] **Step 3: Add `role` to `PublicUser`** in shared:
+
+```ts
+export const PublicUser = z.object({
+  id: z.string(),
+  email: z.string().email(),
+  name: z.string(),
+  role: Role,
+});
+```
+
+- [ ] **Step 4: Return `role` from the route.** In `apps/api/src/routes/me.ts`, add to the
+  `user` body: `role: ((session.user as { role?: string | null }).role ?? 'worker') as Role`
+  (import `Role`/`MeResponse` type from `@solelog/shared`). Keep the `MeResponse` typing.
+- [ ] **Step 5: Run tests — pass.** Also run `yarn workspace @solelog/api typecheck`.
+- [ ] **Step 6: Confirm worker app unaffected** — `yarn workspace @solelog/worker test`
+  still green (it ignores the extra field).
+- [ ] **Step 7: Commit** — `feat(api): include role in /api/me response`.
+
+---
+
+### Task 2: Scaffold `apps/admin` workspace
+
+**Files:** all new under `apps/admin/` (see File Structure). Copy from `apps/worker`.
+
+**Interfaces:**
+- Produces: an installable `@solelog/admin` workspace that builds and runs an empty app
+  shell; `apiFetch`, `signIn`, `getToken/setToken/clearToken` available.
+
+- [ ] **Step 1: Copy config + boilerplate from worker**, adjusting only identifiers:
+  - `package.json` → `"name": "@solelog/admin"`, same scripts/deps/devDeps as worker.
+  - `index.html` → `<title>SoleLog Admin</title>`.
+  - `tsconfig.json`, `tsconfig.app.json`, `tsconfig.node.json` → copy verbatim.
+  - `vite.config.ts` → `server: { host: true, port: 5174 }`.
+  - `vitest.config.ts`, `src/test/setup.ts`, `src/vite-env.d.ts` → copy verbatim.
+  - `.gitignore` → copy from worker.
+  - `src/lib/api.ts`, `src/lib/auth-storage.ts` → copy **verbatim** (token key
+    `solelog.token` is shared intentionally — same backend, same browser origin is fine;
+    admin runs on a different port so localStorage is separate anyway).
+- [ ] **Step 2: Minimal `src/main.tsx`** (copy worker's; renders `<App/>` inside
+  `QueryClientProvider`) and a placeholder `src/App.tsx` returning `<div>SoleLog Admin</div>`
+  and an empty `src/styles.css`.
+- [ ] **Step 3: Smoke test** `src/App.test.tsx`: renders App, expects "SoleLog Admin" text
+  (wrap in `QueryClientProvider`).
+- [ ] **Step 4: Install + verify** — from repo root `yarn install`, then
+  `yarn workspace @solelog/admin test` (smoke passes), `yarn workspace @solelog/admin typecheck`,
+  `yarn workspace @solelog/admin build`.
+- [ ] **Step 5: Commit** — `feat(admin): scaffold Vite+React admin workspace`.
+
+---
+
+### Task 3: Auth context + admin gate + Login screen
+
+**Files:**
+- Create: `apps/admin/src/api/me.ts`, `apps/admin/src/auth/AuthContext.tsx`,
+  `apps/admin/src/screens/Login.tsx`
+- Modify: `apps/admin/src/App.tsx`
+- Test: `apps/admin/src/auth/AuthContext.test.tsx` (or `Login.test.tsx`)
+
+**Interfaces:**
+- Consumes: `signIn` from `lib/api`, `getToken/clearToken` from `lib/auth-storage`,
+  `MeResponse` from `@solelog/shared`.
+- Produces: `useAuth(): { isAuthed, signIn, signOut }` where `signIn` rejects non-admins;
+  `fetchMe(): Promise<MeResponse>`.
+
+- [ ] **Step 1: Write failing tests** (mock `lib/api`):
+  - signing in as an admin (`/api/me` → `role: 'admin'`) sets `isAuthed` true;
+  - signing in as a worker (`role: 'worker'`) throws, clears the token, `isAuthed` false.
+- [ ] **Step 2: Run — fail** (`AuthContext` not implemented).
+- [ ] **Step 3: Implement `api/me.ts`:**
+
+```ts
+import type { MeResponse } from '@solelog/shared';
+import { apiFetch } from '../lib/api';
+
+export function fetchMe(): Promise<MeResponse> {
+  return apiFetch<MeResponse>('/api/me');
+}
+```
+
+- [ ] **Step 4: Implement `auth/AuthContext.tsx`** — mirror worker's, but `signIn` does:
+  call `apiSignIn(email,password)`; then `const me = await fetchMe()`; if
+  `me.user.role !== 'admin'` → `clearToken()` and `throw new Error('not-admin')`; else
+  `setIsAuthed(true)`. `signOut` clears token + sets false. Initial `isAuthed` =
+  `getToken() !== null` (a stale worker token is harmless — the admin endpoints 403 and the
+  next `/api/me`-backed screen can sign out; keep 3a simple).
+- [ ] **Step 5: Implement `screens/Login.tsx`** — copy worker's Login; change the catch to
+  set `'Geen toegang — alleen beheerders.'` when the error is the not-admin error, else
+  `'Inloggen mislukt'`. (Distinguish by error message/`instanceof`.)
+- [ ] **Step 6: Wire `App.tsx`** — `AuthProvider` + `Gate` (authed → shell placeholder,
+  else `<Login/>`), following worker's `App.tsx`.
+- [ ] **Step 7: Run tests — pass.** typecheck.
+- [ ] **Step 8: Commit** — `feat(admin): bearer auth with admin-only gate + login screen`.
+
+---
+
+### Task 4: Sidebar shell + routing
+
+**Files:**
+- Create: `apps/admin/src/components/Sidebar.tsx`
+- Modify: `apps/admin/src/App.tsx`, `apps/admin/src/styles.css`
+- Test: `apps/admin/src/App.test.tsx` (replace the Task-2 smoke test)
+
+**Interfaces:**
+- Consumes: `useAuth` (signOut), `useMe`/`fetchMe` for the signed-in email.
+- Produces: an authed shell with `<nav>` containing **Live** and **Handelingen** links, a
+  header with the signed-in email + logout button, and a content `<Routes>` outlet.
+
+- [ ] **Step 1: Write failing test** — with a token set and `apiFetch` mocked (`/api/me`
+  → admin), the authed app shows nav items "Live" and "Handelingen"; clicking logout clears
+  the token. (Mock `react-router` via `MemoryRouter` or render through `App`.)
+- [ ] **Step 2: Run — fail.**
+- [ ] **Step 3: Implement `Sidebar.tsx`** — `<aside>` with brand "SoleLog Admin",
+  `NavLink`s to `/` ("Live") and `/handelingen` ("Handelingen") using an `tab-active`-style
+  active class, a muted disabled group (Rapporten / Gebruikers / Handmatig — "binnenkort"),
+  and a header strip with the signed-in email + a logout `button` (aria-label "Uitloggen").
+- [ ] **Step 4: Update `App.tsx`** — authed shell = `<BrowserRouter>` with `Sidebar` +
+  `<main>` `<Routes>`: `/` → `Live` (placeholder for now is fine, real in Task 5),
+  `/handelingen` → `Activities` (placeholder, real in Task 6). Use placeholders that the
+  next tasks replace, OR sequence so Task 5/6 add the routes — either way keep tests green.
+- [ ] **Step 5: Add sidebar/header CSS** to `styles.css` (port worker tokens: `:root`
+  vars, base body; new `.admin-shell` grid `220px 1fr`, `.sidebar`, `.nav-link`,
+  `.nav-link-active`, `.nav-disabled`, `.topbar`, `.btn-logout`).
+- [ ] **Step 6: Run tests — pass.** typecheck + build.
+- [ ] **Step 7: Commit** — `feat(admin): sidebar shell + routing`.
+
+---
+
+### Task 5: Live active-work view
+
+**Files:**
+- Create: `apps/admin/src/api/admin-sessions.ts`, `apps/admin/src/lib/elapsed.ts`,
+  `apps/admin/src/screens/Live.tsx`
+- Modify: `apps/admin/src/App.tsx` (route), `apps/admin/src/styles.css`
+- Test: `apps/admin/src/screens/Live.test.tsx`, `apps/admin/src/lib/elapsed.test.ts`
+
+**Interfaces:**
+- Consumes: `apiFetch`, `WorkSession` from `@solelog/shared`.
+- Produces: `useActiveSessions()` (react-query, `refetchInterval: 5000`, queryKey
+  `['admin','sessions','active']`); `formatTime(seconds)` HH:MM:SS.
+
+- [ ] **Step 1: Write failing tests:**
+  - `elapsed.test.ts`: `formatTime(0)==='00:00:00'`, `formatTime(3661)==='01:01:01'`.
+  - `Live.test.tsx` (mock `apiFetch`): given two active sessions (with `user_name`,
+    `activity_name`, `insole_type`, `pair_count`, `start_time`), renders a card per session
+    showing the worker name + activity + type; header "Actief nu (2)". With `[]`, shows
+    "Niemand is nu aan het werk.".
+- [ ] **Step 2: Run — fail.**
+- [ ] **Step 3: Implement `lib/elapsed.ts`** — port `formatTime` from worker
+  `lib/stopwatch.ts` (verbatim).
+- [ ] **Step 4: Implement `api/admin-sessions.ts`:**
+
+```ts
+import { useQuery } from '@tanstack/react-query';
+import type { WorkSession } from '@solelog/shared';
+import { apiFetch } from '../lib/api';
+
+export function useActiveSessions() {
+  return useQuery({
+    queryKey: ['admin', 'sessions', 'active'],
+    queryFn: () => apiFetch<WorkSession[]>('/api/admin/sessions/active'),
+    refetchInterval: 5000,
+  });
+}
+```
+
+- [ ] **Step 5: Implement `screens/Live.tsx`** — `useActiveSessions()`; loading "Laden…",
+  error "Kon gegevens niet laden.", empty "Niemand is nu aan het werk.". Header
+  "Actief nu (N)". Per session, a `.live-card` with worker name (`user_name`), activity
+  (`activity_name`), an insole-type pill, pair count, and a ticking elapsed timer: a `now`
+  state updated by `setInterval(…, 1000)` in a `useEffect`; elapsed =
+  `formatTime((now - Date.parse(start_time)) / 1000)`.
+- [ ] **Step 6: Add route** `/` → `Live` in `App.tsx`; add `.live-card`/`.live-timer`/pill
+  CSS.
+- [ ] **Step 7: Run tests — pass.** typecheck + build.
+- [ ] **Step 8: Commit** — `feat(admin): live active-work view (5s refresh)`.
+
+---
+
+### Task 6: Activity management (port of legacy Settings)
+
+**Files:**
+- Create: `apps/admin/src/api/activities.ts`, `apps/admin/src/screens/Activities.tsx`
+- Modify: `apps/admin/src/App.tsx` (route), `apps/admin/src/styles.css`
+- Test: `apps/admin/src/screens/Activities.test.tsx`
+
+**Interfaces:**
+- Consumes: `apiFetch`, `Activity`/`CreateActivityInput`/`InsoleType` from `@solelog/shared`.
+- Produces: `useActivities()`, `useCreateActivity()`, `useUpdateActivity()`,
+  `useDeleteActivity()` (queryKey `['activities']`, mutations invalidate it).
+
+- [ ] **Step 1: Write failing tests** (mock `apiFetch`): adding a handeling POSTs
+  `/api/activities` with `{name, insole_types}`; editing PUTs `/api/activities/:id`;
+  deleting (confirm stubbed true) DELETEs `/api/activities/:id`. Render shows existing
+  activities from the mocked GET.
+- [ ] **Step 2: Run — fail.**
+- [ ] **Step 3: Implement `api/activities.ts`** — recreate the hooks removed from the
+  worker (reference git `decb158:apps/worker/src/api/activities.ts`): `useActivities`
+  (GET `/api/activities`), `useCreateActivity` (POST), `useUpdateActivity` (PUT
+  `/api/activities/${id}` with `{ id, input }`), `useDeleteActivity` (DELETE), all
+  invalidating `['activities']`.
+- [ ] **Step 4: Implement `screens/Activities.tsx`** — port `decb158:apps/worker/src/screens/Settings.tsx`
+  near-verbatim: `TypeToggles`/type pill helpers, add-form, list with inline edit, delete
+  with `window.confirm`. Title "Handelingen", subtitle "Beheer handelingen per zooltype".
+  Reuse the worker's `.activity-*`/`.btn-*`/`.field-*` class names (port the CSS).
+- [ ] **Step 5: Add route** `/handelingen` → `Activities`; port the activity-management CSS
+  block from worker `styles.css` into admin `styles.css`.
+- [ ] **Step 6: Run tests — pass.** typecheck + build.
+- [ ] **Step 7: Commit** — `feat(admin): activity management (handelingen CRUD)`.
+
+---
+
+### Task 7: Docs, lint, and verification
+
+**Files:**
+- Modify: `docs/roadmap.md`, `apps/admin/README.md`
+- Create: `docs/sessions/2026-06-17-phase-3a-admin-panel.md`
+
+- [ ] **Step 1: Lint/format** — `npx oxlint` clean; `npx oxfmt` **scoped to changed
+  files** (do not touch unrelated files); fix any es5-trailing-comma issues.
+- [ ] **Step 2: Full green** — `yarn workspace @solelog/api typecheck` + `test`;
+  `yarn workspace @solelog/admin typecheck` + `test` + `build`;
+  `yarn workspace @solelog/worker test` (regression).
+- [ ] **Step 3: Live smoke (optional but preferred)** — start the API, seed
+  (`worker@solelog.local` / `admin@solelog.local`), `curl` `/api/me` with an admin bearer
+  to confirm `role`, and `/api/admin/sessions/active`. **Kill the server tree afterward**
+  (Windows lock trap).
+- [ ] **Step 4: Docs** — update `docs/roadmap.md` (Phase 3 → "3a implemented; 3b
+  remaining"); write the session log; fill `apps/admin/README.md` (dev on :5174, admin-only
+  login, what 3a covers).
+- [ ] **Step 5: Commit** — `docs(admin): phase 3a session log + roadmap status`.
+
+## Self-Review notes
+
+- Type consistency: `formatTime` (Task 5) matches worker's name; `useActiveSessions` here
+  hits `/api/admin/sessions/active` (admin), distinct from worker's same-named hook on
+  `/api/sessions/active` — intentional, different app.
+- `PublicUser.role` (Task 1) is consumed by the admin gate (Task 3) — defined before use.
+- Activity hooks (Task 6) mirror the removed worker hooks exactly so the ported Settings
+  component compiles unchanged.