User Module

The User Module (/users) is the core of the identity system. It handles the lifecycle of user accounts, their profile management, and relationships with other system entities.

Data Model

The User entity is the central node in the RBAC graph.

• Relations:
  • roles: Many-to-Many relation with the Role entity.
  • department: Many-to-One relation with the Department entity.
  • sessions: One-to-Many relation with active UserSession records.
• Security Fields:
  • password: Stored as a bcrypt hash. Never returned in API responses.
  • totpSecret: Encrypted secret for MFA.
  • recoveryCodes: Encrypted backup codes.

User Management (/users)

These endpoints are primarily used by the Admin UI for user administration.

• List Users (GET /users)

  • Supports pagination (page, pageSize).
  • Filters: username, realName, deptId (recursive), status, roleId.
  • Returns a list of users with their associated Department and Role names.

• Create User (POST /users)

  • Logic:
    • Checks for duplicate usernames.
    • Hashes the default password (if not provided).
    • Connects relations (Roles, Dept).

• Update User (PUT /users/:id)

  • Updates profile fields.
  • Note: Password updates are handled via a separate endpoint for security.
  • Status Change: If a user is disabled (status: 0), their active sessions are immediately revoked.

• Delete User (DELETE /users/:id)

  • Hard Delete: Currently implements a hard delete (removes the record).
  • Constraint: Cannot delete the currently logged-in user (Self-protection).

Profile Management (/users/me)

These endpoints are for the currently authenticated user to manage their own account.

• Get Profile (GET /users/me)

  • Returns the full profile of the current user.
  • Includes permissions list (merged from all roles) for frontend access control.

• Update Profile (PUT /users/me)

  • Allows updating: realName, avatar, homePath.
  • Restricted: Users cannot change their own username, roles, or department via this endpoint.

• Change Password (PUT /auth/password)

  • Requires oldPassword and newPassword.
  • Upon success, all other sessions for this user are revoked.