AI Implementation feature(841): First-Start Create Admin Modal 1.00 (#3)

2026-07-21 15:07:44 +00:00
parent 9f67ec8c50
commit 960516a7bc
18 changed files with 518 additions and 112 deletions
@@ -0,0 +1,100 @@
+---
+type: guide
+title: Admin Shell & User Management
+description: How an authenticated admin navigates the post-login shell and reaches the admin user-management area.
+tags: [guide, admin, shell, navigation, tester]
+timestamp: 2026-07-21T15:05:00Z
+---
+
+# When this view is available
+
+The admin shell is the post-login UI for users with `role === 'admin'`.
+It is gated by:
+
+| Layer            | File                                                                                       | Check                              |
+|------------------|--------------------------------------------------------------------------------------------|------------------------------------|
+| Client route     | `frontend/src/app/app.routes.ts`                                                          | `/admin` uses `adminGuard`.        |
+| Client nav link  | `frontend/src/app/features/home/home.component.ts`                                         | Renders only when `showAdminNav()` is true. |
+| Client predicate | `frontend/src/app/features/home/home.shell.ts` (`shouldShowAdminNav`)                      | `isAuthenticated && role === 'admin'`. |
+| Server route     | `backend/src/modules/admin/admin.controller.ts` (mounted under `@UseGuards(AdminGuard)` + `@Roles('admin')`) | Requires admin JWT. |
+
+A non-admin (or unauthenticated) request to `/admin` is intercepted by
+the client guard *before* any HTTP call is made, so the page never
+renders.
+
+# How to access (tester steps)
+
+1. Ensure the instance is initialized (`/api/v1/bootstrap` returns
+   `initialized: true`). If not, follow [First-Run Bootstrap](/guides/bootstrap.md).
+2. Sign in as a user with `role === 'admin'` via `/login`.
+3. The browser lands on `/` and renders the **Home shell** with a
+   header containing the page title and a sign-in status line.
+4. Click the **Admin** nav link (`data-testid="nav-admin"`) in the
+   shell header, or navigate directly to `/admin`.
+5. The admin area renders inside the shell:
+   - **Heading:** "Admin area"
+   - **Loading state:** `Loading users...` (`data-testid="admin-loading"`)
+     while the GET is in flight.
+   - **User list:** an unordered list (`data-testid="admin-user-list"`)
+     showing one `<li>` per user with the username in bold and the role
+     in parentheses, e.g. `root (admin)`.
+   - **Error state:** a red message (`data-testid="admin-error"`) when
+     the request fails (e.g. backend down or auth expired).
+
+# Expected behavior
+
+| User role            | Visiting `/admin`                                       |
+|----------------------|---------------------------------------------------------|
+| Unauthenticated      | Redirected to `/login` by `adminGuard`.                 |
+| Authenticated player | Redirected to `/` by `adminGuard`.                      |
+| Authenticated admin  | Page renders, fetches `GET /api/v1/admin/users`, lists users. |
+
+* When `BootstrapService.initialized()` is still `false` the guard
+  redirects to `/bootstrap` instead of `/login`, so the first admin
+  flow is honored.
+* The Admin nav link is hidden for non-admin users — there is no
+  visible UI affordance to reach `/admin` without the role.
+* The list endpoint uses the existing `authInterceptor` + `csrfInterceptor`,
+  so no extra plumbing is required.
+
+# Visual elements
+
+| Element              | Selector                          | Purpose                                      |
+|----------------------|-----------------------------------|----------------------------------------------|
+| Shell header         | `.shell-header`                   | Page title + signed-in identity.             |
+| Admin nav link       | `[data-testid="nav-admin"]`       | RouterLink to `/admin`; shown to admins only. |
+| Shell body           | `.shell-body`                     | Holds `<router-outlet>` for child routes.    |
+| Admin heading        | `h2` inside `.admin-area`         | "Admin area".                                |
+| Loading message      | `[data-testid="admin-loading"]`   | "Loading users...".                          |
+| Error message        | `[data-testid="admin-error"]`     | Red text; renders `error().error.message` or fallback. |
+| User list            | `[data-testid="admin-user-list"]` | Renders one `<li>` per `AdminUser`.          |
+
+# Architecture map
+
+| Step | Where                                              | What happens                                                          |
+|------|----------------------------------------------------|-----------------------------------------------------------------------|
+| 1    | `frontend/src/app/app.routes.ts`                   | `/` is a parent route with `authGuard`; `/admin` child uses `adminGuard` + lazy-loads `AdminUsersComponent`. |
+| 2    | `frontend/src/app/core/guards/admin.guard.ts`     | `adminGuard` calls `decideAdminGuard(...)` with bootstrap + auth state. |
+| 3    | `frontend/src/app/core/guards/admin.guard.decision.ts` | Pure function returning `{kind: 'allow'}` or `{kind: 'redirect', path}`. |
+| 4    | `frontend/src/app/features/home/home.component.ts` | Shell template renders header, conditional nav (`*ngIf="showAdminNav()"`), and `<router-outlet>`. |
+| 5    | `frontend/src/app/features/home/home.shell.ts`     | `shouldShowAdminNav({isAuthenticated, role})` predicate (exported and unit-tested). |
+| 6    | `frontend/src/app/features/admin/admin-users.component.ts` | On init, calls `AdminService.listUsers()` and populates signals (`loading`, `error`, `users`). |
+| 7    | `frontend/src/app/core/services/admin.service.ts` | `GET /api/v1/admin/users` (credentials included); typed as `AdminUser[]`. |
+| 8    | `backend/src/modules/admin/admin.controller.ts`   | `AdminController.list` returns `AdminService.listUsers({limit, cursor, role})`. |
+
+# Notes
+
+* The shell deliberately keeps `HomeComponent` as a thin layout owner —
+  child routes (currently just `/admin`) render into its
+  `<router-outlet>`. New admin sub-pages can be added as additional
+  children without changing the shell.
+* The guard decision function (`decideAdminGuard`) is a pure module so
+  it is straightforward to unit-test without Angular DI. See
+  `tests/frontend/admin-shell.spec.ts` and `tests/frontend/admin-navigation.spec.ts`.
+
+# See also
+
+- [First-Run Bootstrap](/guides/bootstrap.md)
+- [Frontend Structure](/architecture/frontend-structure.md)
+- [REST API Overview](/api/rest-overview.md)
+- [Admin Endpoints](/api/admin.md)