Organization Detail User Management Tab - Design Spec

Overview

Add a new Quản lý người dùng tab to the organization detail screen so user management can happen directly inside the selected organization context instead of forcing navigation to the global users page.

This feature is organization-scoped in the UI and policy-scoped in the backend:

  • The page context fixes organizationId
  • The tab never allows switching organization context
  • Frontend hides actions the actor cannot perform
  • Backend enforces the real permission and role-hierarchy rules

The tab supports:

  • List organization users
  • Search by full name or email
  • View user details
  • Create users when allowed
  • Edit profile, role, status, and password when allowed
  • Suspend or activate users when allowed
  • Delete users when allowed

Scope

In Scope

  • Extend the frontend organization detail page with a user-management tab
  • Reuse the existing users services, hooks, table, slide-over, and delete modal where practical
  • Add organization-scoped permission handling for Super Admin, Admin, and Owner
  • Enforce actor and target constraints in backend user operations

Out of Scope

  • New standalone user-management routes
  • Bulk actions
  • Cross-organization reassignment from this tab
  • Changes to the core RBAC model beyond the policy checks needed for this feature

Route and Navigation

  • Existing route remains: /admin/organizations/:id
  • The page is extended with tabs:
    • Thông tin tổ chức
    • Quản lý người dùng
  • Back navigation remains unchanged and returns to /admin/organizations
  • The user-management tab is a container inside the page shell, not a redirect to the global users screen

Access Model

Actor Rules

Super Admin

  • Can access the tab on any organization detail page
  • Has full CRUD and status management across all organizations

Admin

  • Can access the tab only for the organization they belong to
  • Has full CRUD and status management for users inside that organization
  • Cannot operate on users outside their organization

Owner

  • Can access the tab only for the organization they belong to
  • Can list, search, view, edit, change roles within allowed bounds, and suspend or activate users in that organization
  • Cannot create users
  • Cannot delete users
  • Cannot operate on Admin
  • Cannot assign a role higher than Owner

Staff and Technical

  • Cannot access the tab
  • Cannot perform organization user-management actions through API calls

Enforcement Rules

  • Frontend uses capability-based visibility for tabs, buttons, and row actions
  • Backend remains the source of truth and must reject forbidden operations even if the UI is bypassed
  • Permission checks must consider:
    • actor role
    • actor organization
    • selected organization in the route
    • target user organization
    • target user role
    • role assignment target in update flows

UX Design

Tab Layout

The Quản lý người dùng tab contains:

  • A compact header with title, subtitle, and optional Tạo người dùng button
  • Search input for full name or email
  • A user table
  • Pagination aligned to the bottom right when more than one page exists

The organization filter from the global users page is removed because the organization context is fixed by the parent page.

States

  • Loading: reuse the existing loading skeleton or table-loading pattern
  • Error: show retryable error state inside the tab only
  • Empty: show no-user message and optional create action

If the organization detail query succeeds but the users query fails, the information tab still works and only the user-management tab shows an error state.

User Table

The table shows only users belonging to the selected organization.

Recommended columns:

  • Họ tên
  • Email
  • Vai trò
  • Trạng thái
  • Ngày tạo
  • Thao tác

Notes:

  • The Tổ chức column from the global users page is hidden in this tab because it is redundant
  • Action visibility is filtered per row based on actor capability and target user role

Available actions, when permitted:

  • Xem
  • Sửa
  • Khóa or Kích hoạt
  • Xóa

Create User Flow

Create is launched from the tab header button and reuses the existing slide-over pattern.

Only Super Admin and Admin can access this flow.

Fields:

  • Full name
  • Email
  • Phone number if supported by the current model
  • Password
  • Confirm password
  • Role

Organization behavior:

  • Organization is not selectable in this tab
  • The current organization is either hidden from the form payload UI or shown as read-only context
  • Submitted payload must always use the organization id from the current detail page

Role behavior:

  • Role options are filtered according to actor permissions
  • Owner has no create flow
  • Admin cannot create users outside their own organization

View and Edit Flow

The existing user detail and edit slide-over should be reused or lightly refactored for organization-scoped use.

Edit supports:

  • Profile field updates already supported by the current API
  • Role change within allowed bounds
  • Status-related actions through existing suspend or activate actions
  • Password change

Password behavior in edit mode:

  • Password update is optional
  • If left empty, password is unchanged
  • If one password field is filled, full password validation must run

Organization behavior in edit mode:

  • User organization cannot be changed from this tab

Role constraints in edit mode:

  • Super Admin can assign roles allowed by the current backend model
  • Admin can manage roles only inside their own organization
  • Owner cannot assign any role above Owner and cannot modify Admin

Suspend and Activate Flow

  • Reuse the current row action pattern
  • Refresh the organization-scoped list after mutation
  • Owner can suspend or activate only users lower than Owner in the same organization
  • Admin and Super Admin follow their broader allowed scopes

Delete Flow

  • Reuse the existing delete confirmation modal
  • Only Super Admin and Admin can delete users
  • Admin can delete only within their own organization
  • Owner, Staff, and Technical cannot delete
  • After successful deletion, refresh the organization-scoped list and close any open panel for the deleted user

Data and API Integration

The feature should prefer the current API surface.

Expected backend usage:

  • GET /api/v1/users with orgId=<organizationId> support for organization-scoped listing
  • POST /api/v1/users
  • PUT /api/v1/users/:id
  • DELETE /api/v1/users/:id
  • POST /api/v1/users/:id/suspend
  • POST /api/v1/users/:id/activate
  • POST /api/v1/users/:id/change-password if password updates remain a dedicated backend flow

Frontend data rules:

  • Every list query in the tab includes the current organization id
  • Create submissions include the current organization id
  • Edit submissions must not allow changing organization id even if the shared form supports it elsewhere
  • The global users page remains unchanged in behavior

Backend integration rules:

  • Super Admin must be able to query or mutate across organizations without being incorrectly forced to their own organizationId
  • Admin and Owner must be constrained to their own organization
  • Owner-specific hierarchy checks must be enforced server-side, not inferred from UI alone

Component Strategy

Preferred approach:

Implementation direction:

  • Build a small organization-specific container instead of embedding the full global users page
  • Refactor shared components only as needed to support:
    • hidden or read-only organization field
    • optional password updates in edit mode
    • role-option filtering
    • row-level action visibility
    • hiding the redundant organization column in organization context

Backend direction:

  • Add a dedicated policy helper or service-level guard logic for actor-target validation
  • Avoid duplicating hierarchy checks across multiple service methods

Validation Rules

  • Email must be valid
  • Password is required in create mode
  • Confirm password must match password when password fields are present
  • In edit mode, password fields are optional, but if either password field is filled, full password validation must run
  • Role selection is required for create and role-changing edit flows
  • Organization id in this tab always comes from the route context, never from free user input

Error Handling

  • Mutation failures keep the slide-over open and show the existing error feedback pattern
  • List failures do not break the organization detail page shell
  • Forbidden actions must return explicit authorization errors from the backend
  • UI should recover cleanly after failed mutations without losing list filters or page context

Testing Strategy

Frontend

  • Add or update tests for organization detail tab rendering
  • Add tests for organization-scoped list queries
  • Add tests that create flow always submits the parent organization id
  • Add tests that the organization selector is hidden or read-only in organization context
  • Add tests for role-option filtering by actor
  • Add tests for action visibility by actor and target user role
  • Add tests for suspend or activate and delete actions refreshing the list

Backend

  • Add tests for Super Admin cross-organization access
  • Add tests for Admin being limited to their own organization
  • Add tests for Owner being blocked from create and delete
  • Add tests for Owner being blocked from operating on Admin
  • Add tests for Staff and Technical being denied access
  • Add tests for role-assignment rejection when target role exceeds actor capability

Regression Focus

  • Global user page must continue to work unchanged
  • Organization detail info tab must remain unchanged
  • Shared user slide-over must still support existing global usage
  • Existing admin user-management flows must not regress while adding organization-context behavior

Acceptance Criteria

  1. Organization detail page shows a new Quản lý người dùng tab.
  2. The tab lists only users of the selected organization.
  3. The tab does not expose an organization filter or allow switching organization context.
  4. Super Admin can fully manage users from any organization detail page.
  5. Admin can fully manage users only in their own organization.
  6. Owner can list, view, edit, change allowed roles, and suspend or activate users only in their own organization.
  7. Owner cannot create users, delete users, operate on Admin, or assign roles above Owner.
  8. Staff and Technical cannot access the tab or its API actions.
  9. Create flow always assigns the selected organization automatically.
  10. Edit flow supports optional password change without allowing organization reassignment.
  11. The global user-management page continues to function after the refactor.