# 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.