From bcb42072334ea38a5e870fd214db347e178da77b Mon Sep 17 00:00:00 2001 From: Bastian Wagner Date: Fri, 31 Jul 2026 21:58:47 +0200 Subject: [PATCH] docs: add admin user management plan --- docs/plans/admin-user-management.md | 56 +++++++++++++++++++++++++++++ 1 file changed, 56 insertions(+) create mode 100644 docs/plans/admin-user-management.md diff --git a/docs/plans/admin-user-management.md b/docs/plans/admin-user-management.md new file mode 100644 index 0000000..2b593dd --- /dev/null +++ b/docs/plans/admin-user-management.md @@ -0,0 +1,56 @@ +# Admin User Management Implementation Plan + +## Goal + +Add a shared user directory and a secure global-admin management surface spanning the NestJS backend and the modern Angular frontend. The legacy frontend remains untouched. + +## Global Constraints + +- Reuse the existing `User.status`, `User.role`, and `Player.user` relations; do not add a new assignment table. +- Only global `RoleEnum.admin` users may mutate users or player assignments. Team roles are read-only. +- Non-admin directory responses contain only users sharing at least one team with the requester, and only assignments from those shared teams. They never contain email or unrelated-team information. +- Admin directory responses may contain email, global role, status, and all assignments, but never password, hash, social ID, or authentication secrets. +- Admins may edit first name, last name, global role, status, and player assignments. They may not edit email/password, create users, delete users, or edit legacy frontend code. +- Deactivation is immediate for login and already-issued JWTs, preserves assignments, and must not allow self-deactivation or loss of the last active admin. The same last-admin and self-protection applies to role demotion. +- Admin mutation endpoints use narrow DTOs and server-side authorization. The existing generic user PATCH is not used by the modern frontend. +- Follow strict TDD: add focused failing tests first, confirm the expected failure, then add minimal production code and refactor only while green. + +## Task 1: Backend directory contract and query + +- Add explicit directory/admin summary DTOs and pagination/search inputs. +- Implement a user-directory service query that deduplicates users, scopes non-admin results to shared teams, filters their visible assignments to those teams, and returns all users/assignments plus email and role for admins. +- Add focused service tests covering cross-team isolation, email/secret redaction, inactive visibility, admin visibility, deduplication, search, and pagination. +- Keep response mapping explicit rather than serializing entities. + +## Task 2: Backend admin mutations and authentication enforcement + +- Add global-admin-only endpoints for profile changes, role changes, status changes, player search, assignment, reassignment, and unlinking. +- Use transactions/locking for last-admin protection and assignment changes; reject self-deactivation/self-demotion and loss of the last active admin. +- Ensure password/social login rejects inactive users and JWT validation reloads the current user, rejecting inactive/deleted users and returning the current database role. +- Extend audit event types and record admin actor, target, and action without secrets. +- Add a migration/index metadata for the player foreign keys used by directory queries. +- Add focused controller/service/auth tests for authorization, narrow DTO behavior, status/session enforcement, role safeguards, and assignment conflict behavior. + +## Task 3: Modern frontend API, models, routing, and authorization state + +- Add typed directory/admin API clients matching the backend contract and never call the generic user PATCH. +- Add typed view models for safe directory records, admin details, assignments, filters, and mutation requests. +- Add the protected `/users` route and a visible entry in the existing More screen for every authenticated role. +- Expose the current global role through existing auth state and treat it only as a presentation hint; backend authorization remains authoritative. +- Add focused tests for API URLs/payloads, route protection, role derivation, and navigation visibility. + +## Task 4: Modern frontend user directory and admin interactions + +- Implement a responsive user-directory page in the existing modern frontend design system, using its spacing, typography, colors, controls, and list patterns as the accepted visual reference. +- Provide search, pagination, status, and team/player assignment display with loading, empty, and error states. +- Hide email, role, unrelated-team information, and every mutation control from non-admins. +- For admins, add profile/role editing, activation/deactivation confirmation, player search, assignment, unlink confirmation, and explicit reassignment confirmation naming the current and target users. +- Do not optimistically update security-sensitive state; reload affected data after successful mutations and surface `403`/safeguard errors clearly. +- Add component tests for non-admin/admin rendering, confirmations, successful refresh, error behavior, search, and pagination. + +## Task 5: Integration verification and documentation + +- Run all focused backend tests and the backend build; document unrelated pre-existing full-suite failures separately. +- Run the complete modern frontend test suite and a production/container build that does not require external font inlining. +- Run the backend/frontend locally and verify the directory and primary admin workflow at desktop and mobile widths using the available browser tooling or Playwright fallback. +- Confirm the legacy frontend has no changes and review the complete branch diff for data leakage, authorization bypasses, concurrency errors, and visual regressions.