321 lines
16 KiB
Markdown
321 lines
16 KiB
Markdown
# 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.
|