152 lines
6.5 KiB
Markdown
152 lines
6.5 KiB
Markdown
# Functional Design Plan — Unit 5: User Management
|
|
|
|
**Status**: 🚧 In Progress
|
|
|
|
## Unit Context
|
|
|
|
**Unit**: Unit 5 — User Management
|
|
**Type**: Frontend (React/TypeScript) + minor backend addition
|
|
**Depends on**: Unit 3 (AppLayout, RoleGuard), Unit 4 (TanStack Query patterns established)
|
|
**Stories Covered**: US-10 (View list of users), US-11 (Invite a new user), US-12 (Share invite link)
|
|
|
|
**Key Deliverables** (from unit-of-work.md):
|
|
- `frontend/src/api/useUsers.ts` — `useUsers` hook (user list), `useInviteUser` mutation
|
|
- Update `frontend/src/api/useInvitation.ts` — align with established patterns
|
|
- `frontend/src/components/users/InviteUserDialog.tsx` — two-step: invite form → share link
|
|
- `frontend/src/pages/UsersPage.tsx` — replace placeholder with user table + invite dialog
|
|
- MSW mocks for user endpoints
|
|
- i18n keys for user management (en + nl)
|
|
- Unit tests
|
|
|
|
**API Endpoints** (backend):
|
|
- `GET /api/v1/Users` — list all users (**NOT YET IMPLEMENTED in backend — see Q1**)
|
|
- `POST /api/v1/Users/invite` — invite a user (requires AdminOnly policy; returns `{ inviteLink: string }`)
|
|
- `GET /api/v1/Invitation/validate?token=...` — validate token (anonymous, existing)
|
|
- `POST /api/v1/Invitation/complete` — complete invitation (anonymous, existing)
|
|
|
|
**Key Observations**:
|
|
- `UsersPage.tsx` is currently a placeholder ("Coming soon.") — full implementation needed
|
|
- `useInvitation.ts` uses raw `useState`/`useEffect` with local interfaces diverging from `types.ts`; Unit 4 established TanStack Query as the standard
|
|
- `userHandlers.ts` has a placeholder `GET /Users` MSW mock — needs full implementation
|
|
- Backend has no `GET /Users` endpoint yet — decision needed (Q1)
|
|
|
|
---
|
|
|
|
## Functional Design Steps
|
|
|
|
- [x] Step 1: Analyze unit context and existing code patterns
|
|
- [x] Step 2: Generate questions, collect answers
|
|
- [x] Step 3: Create `domain-entities.md`
|
|
- [x] Step 4: Create `business-rules.md`
|
|
- [x] Step 5: Create `business-logic-model.md`
|
|
- [x] Step 6: Create `frontend-components.md`
|
|
- [x] Step 7: Present completion message and await approval
|
|
|
|
---
|
|
|
|
## Questions
|
|
|
|
Please fill in the letter after each `[Answer]:` tag.
|
|
|
|
---
|
|
|
|
### Question 1: Backend GET /Users endpoint
|
|
|
|
The frontend needs a list of all users for UsersPage, but `UsersController` currently has no `GET /Users` endpoint. How should this be handled?
|
|
|
|
A) Add `GET /api/v1/Users` to the backend (`UsersController`) in this unit — returning `id`, `email`, `displayName`, `role`, `isActive` per user (recommended — required for the feature to function end-to-end)
|
|
B) Use only the data already available in AuthContext (current logged-in user only) — no user list shown
|
|
C) Other
|
|
|
|
[Answer]: A
|
|
|
|
---
|
|
|
|
### Question 2: Who can access User Management?
|
|
|
|
The backend `POST /Users/invite` has `[Authorize(Policy = "AdminOnly")]`. Which roles should be able to view the UsersPage and invite users?
|
|
|
|
A) Owner and Administrator can view the user list and invite users; User role has no access to UsersPage (recommended — consistent with backend AdminOnly policy)
|
|
B) Owner and Administrator can view the user list; only Owner can invite users
|
|
C) All authenticated users can view the user list; only Owner and Administrator can invite
|
|
D) Other
|
|
|
|
[Answer]: A
|
|
|
|
---
|
|
|
|
### Question 3: Invitable roles
|
|
|
|
When inviting a user via the dialog, which roles can be assigned to the invitee?
|
|
|
|
A) Administrator and User only — Owner role is excluded (Owner is created via initial setup; there can only be one) (recommended — consistent with system design)
|
|
B) All three roles: Owner, Administrator, User
|
|
C) User only — no role selection; role is always User
|
|
D) Other
|
|
|
|
[Answer]: D, Administrator and User only, but it is false that there can only be 1 Owner. Another owner can make another Admin an owner. Users cannot become an owner directly. There always has to be at least 1 owner
|
|
|
|
---
|
|
|
|
### Question 4: User table columns
|
|
|
|
Which columns should the user table on UsersPage show?
|
|
|
|
A) Name, Email, Role, Status (Active/Inactive) — four columns, clean and informative (recommended)
|
|
B) Name, Email, Role, Status, Created At — five columns including timestamp
|
|
C) Email, Role, Status only — minimal
|
|
D) Other
|
|
|
|
[Answer]: B
|
|
|
|
---
|
|
|
|
### Question 5: TanStack Query migration for useInvitation.ts
|
|
|
|
The existing `useInvitation.ts` (from Unit 2) uses raw `useState`/`useEffect` and has local interfaces that diverge from `types.ts`. Unit 4 established TanStack Query as the standard for data fetching. Should `useInvitation.ts` be migrated to TanStack Query in this unit?
|
|
|
|
A) Yes — migrate `useValidateInvitation` (useQuery) and `useCompleteInvitation` (useMutation) to TanStack Query and align with types.ts (recommended — keeps all data-fetching uniform and removes the divergence)
|
|
B) No — leave `useInvitation.ts` as-is; only new hooks (`useUsers`, `useInviteUser`) use TanStack Query
|
|
C) Other
|
|
|
|
[Answer]: A
|
|
|
|
---
|
|
|
|
### Question 6: InviteUserDialog — Step 1 form fields
|
|
|
|
Step 1 of the invite dialog collects the information to send an invitation. What should the form contain?
|
|
|
|
A) Email address + Role selector (Administrator / User) — two fields, minimal and sufficient (recommended — the backend `InviteUserRequest` only needs email and role)
|
|
B) Email address, Role selector, and a display name field so the invitation is personalized
|
|
C) Email address only — role defaults to User
|
|
D) Other
|
|
|
|
[Answer]: A
|
|
|
|
---
|
|
|
|
### Question 7: InviteUserDialog — Step 2 share link
|
|
|
|
After submitting the invite form successfully, the backend returns an `inviteLink`. How should Step 2 present the link to the inviting user?
|
|
|
|
A) Show the full invite link in a read-only text input with a "Copy to clipboard" button + close button (recommended — usable, transparent, and standard pattern)
|
|
B) Show only a "Copy link" button — no visible URL in the UI
|
|
C) Show a success message only with instructions to share the link manually (no copy button)
|
|
D) Other
|
|
|
|
[Answer]: A, also make it possible to copy the link at a later point and also to refresh an invite token, for example when it is expired or you just require a new one for security reasons. The invite link should also be visible on the user details page for invited users that haven't completed their invitation yet.
|
|
|
|
---
|
|
|
|
### Question 8: Unit test scope
|
|
|
|
Which parts of Unit 5 should have unit tests?
|
|
|
|
A) `useUsers` hook + `useInviteUser` mutation + `InviteUserDialog` (step 1 → step 2 flow) + `UsersPage` render with table data (recommended — covers all logic and UI paths)
|
|
B) `UsersPage` integration test only — renders table + dialog flow end-to-end via MSW
|
|
C) `useUsers` and `useInviteUser` hooks only — skip component tests
|
|
D) Other
|
|
|
|
[Answer]: A
|