vitepress-template

Appearance

User Management System ​

**Referenced Files in This Document** - [[user.go]](file/bi-sys/internal/biz/user.go) - [[user.go]](file/bi-sys/internal/service/user.go) - [[user.go]](file/bi-sys/internal/data/user.go) - [[user.proto]](file/bi-sys/api/sys/v1/user.proto) - [[rbac.go]](file/bi-common/auth/rbac.go) - [[rbac.go]](file/bi-sys/internal/middleware/rbac.go) - [[role.go]](file/bi-sys/internal/biz/role.go) - [[dept.go]](file/bi-sys/internal/biz/dept.go) - [[dict.go]](file/bi-sys/internal/biz/dict.go) - [[user.proto]](file/bi-tenant/api/tenant/v1/user.proto) - [[page.tsx]](file/ui-web-admin/src/app/dashboard)/system/users/page.tsx)

Table of Contents ​

  1. Introduction
  2. Project Structure
  3. Core Components
  4. Architecture Overview
  5. Detailed Component Analysis
  6. Dependency Analysis
  7. Performance Considerations
  8. Troubleshooting Guide
  9. Conclusion
  10. Appendices

Introduction ​

This document describes the User Management System within the Admin Panel, focusing on the backend services, RBAC implementation, and the admin UI. It covers user lifecycle operations (create, modify, delete, batch delete), role-based access control, user search and filtering, bulk operations, status management, password reset, and integration points with bi-sys and bi-tenant services. It also outlines audit and compliance considerations and provides examples of common administrative tasks.

Project Structure ​

The User Management System spans three primary areas:

  • Backend services: bi-sys (system management) and bi-tenant (tenant client)
  • Shared RBAC utilities: bi-common
  • Admin UI: ui-web-admin

Diagram sources

Section sources

Core Components ​

  • User service layer: exposes gRPC/HTTP endpoints for user CRUD, status updates, password reset, and role assignment.
  • User business logic: orchestrates validations, hashing, persistence, and logging.
  • User repository: encapsulates data access, soft deletes, pagination, and role assignment.
  • RBAC middleware: enforces permission checks for admin endpoints and integrates with bi-sys for management APIs.
  • Admin UI: renders the user administration interface under the system menu.

Key responsibilities:

  • User creation with unique username validation and password hashing.
  • User update, delete (soft), batch delete, status change, and password reset.
  • Role assignment per user via dedicated endpoint.
  • Search and filtering via list requests with pagination.
  • Integration with bi-tenant for tenant-scoped user operations.

Section sources

Architecture Overview ​

The system follows a layered architecture with clear separation of concerns:

  • Presentation: HTTP/gRPC endpoints defined in protobuf and served by bi-sys.
  • Application: UserService translates requests to business use cases.
  • Domain: UserUsecase performs validations and orchestrates repositories.
  • Data: UserRepo handles database operations and role mapping.
  • Security: RBAC middleware validates permissions centrally.

Diagram sources

Detailed Component Analysis ​

User Service Layer ​

  • Exposes endpoints for listing, retrieving, creating, updating, deleting, batch deleting, updating status, resetting passwords, assigning roles, and fetching user options.
  • Validates pagination and request parameters.
  • Converts domain entities to API DTOs.

Operational highlights:

  • List users supports filters: username, nickname, phone, status, department, and date range.
  • Password reset hashes the new password before persisting.
  • Role assignment replaces existing roles with the provided set.

Section sources

Business Logic (UserUsecase) ​

  • Enforces unique username constraint during creation.
  • Hashes passwords using bcrypt before storage.
  • Supports batch delete with parameter validation.
  • Provides role retrieval and assignment helpers.

Section sources

Data Access (UserRepo) ​

  • Implements soft delete semantics by marking records with a deletion timestamp.
  • Uses a query builder to construct dynamic filters and pagination.
  • Role assignment clears previous entries and inserts new ones.

Section sources

Role-Based Access Control (RBAC) ​

  • Centralized RBAC middleware in bi-common supports:
    • White-listed paths
    • Provider-based permission retrieval
    • Management vs client API distinction
    • Permission caching
    • Wildcard permission support
  • bi-sys middleware provides local enforcement with cache and checker integration.

Diagram sources

Section sources

Admin UI Integration ​

  • The admin UI renders the user management page under the system menu.
  • It consumes bi-sys endpoints for listing, creating, updating, deleting, and managing user roles and statuses.

Section sources

Tenant User Operations ​

  • bi-tenant provides tenant-scoped user endpoints for listing, creating, updating, deleting, role assignment, store delegation, password reset, status changes, and exports.
  • These endpoints operate independently from bi-sys and target tenant-specific data.

Section sources

Supporting Modules ​

  • Roles: role creation, updates, deletion, listing, status management, menu assignment, data scope assignment, and permission retrieval.
  • Departments: hierarchical department management with ancestry computation and constraints.
  • Dictionary: dictionary types and values for controlled vocabularies.

Section sources

Dependency Analysis ​

The user management stack exhibits clean layering with explicit dependencies:

  • UI depends on bi-sys and bi-tenant services.
  • bi-sys depends on bi-common for RBAC utilities.
  • bi-sys business logic depends on data access layer.
  • Data access layer depends on shared utilities and database.

Diagram sources

Section sources

Performance Considerations ​

  • Pagination defaults are enforced in the service layer to prevent unbounded queries.
  • Soft deletes avoid costly cascading operations; ensure appropriate indexing on deletion markers and timestamps.
  • Password hashing is performed in-process; consider async hashing for high-throughput scenarios.
  • RBAC permission caching reduces repeated provider calls; configure cache TTL appropriately.
  • Role assignment replaces all existing roles; for large role sets, consider incremental updates if needed.

Troubleshooting Guide ​

Common issues and resolutions:

  • Duplicate username on create: Verify uniqueness before insertion; the usecase returns a specific error when duplicates are detected.
  • Invalid parameters for batch delete: Ensure non-empty ID lists; the service validates input and returns an error otherwise.
  • Permission denied: Confirm the user’s tenant context and role permissions; management endpoints require TenantID zero and proper permissions resolved via bi-sys.
  • Password reset failures: Ensure the new password meets length constraints; hashing errors are handled gracefully with internal error responses.
  • Role assignment not taking effect: Role assignment replaces prior roles; confirm the request payload includes intended role IDs.

Section sources

Conclusion ​

The User Management System provides a robust, layered implementation for user administration with strong RBAC enforcement, comprehensive CRUD operations, and tenant-aware integrations. The admin UI seamlessly connects to bi-sys endpoints, while bi-tenant offers tenant-scoped user management. The design supports scalability, maintainability, and compliance through standardized workflows and centralized security controls.

Appendices ​

API Definitions: User Management Endpoints ​

  • List users: GET /api/v1/sys/users
  • Get user: GET /api/v1/sys/users/
  • Create user: POST /api/v1/sys/users
  • Update user: PUT /api/v1/sys/users/
  • Delete user: DELETE /api/v1/sys/users/
  • Batch delete users: POST /api/v1/sys/users/batch-delete
  • Update user status: PUT /api/v1/sys/users/{id}/status
  • Reset user password: PUT /api/v1/sys/users/{id}/password/reset
  • Update current user: PUT /api/v1/sys/users/current
  • Get current user: GET /api/v1/sys/users/current
  • Assign user roles: PUT /api/v1/sys/users/{user_id}/roles
  • Get user options: GET /api/v1/sys/users/options

Section sources

RBAC Permission Mapping Examples ​

  • GET /api/v1/sys/users → sys:user:list
  • GET /api/v1/sys/users/{id} → sys:user:get
  • POST /api/v1/sys/users → sys:user:create
  • PUT /api/v1/sys/users/{id} → sys:user:update
  • DELETE /api/v1/sys/users/{id} → sys:user:delete

Section sources

Common Administrative Tasks ​

  • Provision a new user:
    • Call CreateUser with username, password, personal info, and initial role IDs.
    • Confirm unique username and successful hash.
  • Assign roles to an existing user:
    • Call AssignUserRoles with the user ID and desired role IDs.
    • Roles are replaced atomically.
  • Deactivate a user:
    • Call UpdateUserStatus with status=0.
  • Bulk user operations:
    • Use BatchDeleteUser with a list of user IDs.
  • Password reset:
    • Use ResetUserPassword with a new secure password.
  • Search and filter:
    • Use ListUser with pagination and filters (username, nickname, phone, status, dept_id, begin_time, end_time).

Section sources