User Management System
**Referenced Files in This Document** - [[user.proto]](file/bi-sys/api/sys/v1/user.proto) - [[user.go]](file/bi-sys/internal/biz/user.go) - [[user.go]](file/bi-sys/internal/data/user.go) - [[user.go]](file/bi-sys/internal/service/user.go) - [[schema.sql]](file/bi-sys/docs/database/schema.sql) - [[model.go]](file/bi-sys/internal/data/model/model.go) - [[user_grpc.pb.go]](file/bi-sys/api/sys/v1/user-grpc.pb.go) - [[user_grpc.pb.go]](file/bi-notify/third-party/bi-sys/sys/v1/user-grpc.pb.go) - [[user.pb.go]](file/bi-tenant/api/tenant/v1/user.pb.go) - [[user_grpc.pb.go]](file/bi-tenant/api/tenant/v1/user-grpc.pb.go) - [[user_pb.validate.go]](file/bi-tenant/api/tenant/v1/user.pb.validate.go) - [[mock-api.ts]](file/ui-web-admin/src/lib/mock-api.ts) - [[mock-data.ts]](file/ui-web-admin/src/lib/mock-data.ts)
Table of Contents
- Introduction
- Project Structure
- Core Components
- Architecture Overview
- Detailed Component Analysis
- Dependency Analysis
- Performance Considerations
- Troubleshooting Guide
- Conclusion
- Appendices
Introduction
This document describes the user management system within the bi-sys service. It covers user CRUD operations, profile management, account status controls, search and filtering, the user data model, API endpoints, request/response schemas, validation rules, error handling, and integration patterns with other services. It also outlines audit logging capabilities and compliance considerations, along with practical examples for user creation workflows, bulk operations, and user import/export functionality.
Project Structure
The user management system spans three layers:
- API layer: Protocol buffer definitions and HTTP/gRPC gateway mappings
- Service layer: Business logic orchestration and request validation
- Data layer: Persistence via GORM models and SQL schema
Diagram sources
Section sources
Core Components
- User data model: Encapsulated in the SysUser entity with GORM tags and mapped to the sys_user table
- Business use case: Handles creation, updates, deletion, listing, status changes, password resets, and role assignments
- Data persistence: Uses GORM with query builder for filtering and pagination
- API surface: gRPC and HTTP endpoints for user management, plus tenant-level export/import support
Key responsibilities:
- Validation and sanitization via protobuf rules and service validators
- Password hashing using bcrypt
- Soft deletion semantics via deleted_at timestamps
- Role assignment through sys_user_role junction table
- Audit logging via dedicated tables (login and operation logs)
Section sources
Architecture Overview
The system follows a layered architecture with clear separation of concerns:
- API layer defines contracts and HTTP/gRPC mappings
- Service layer validates requests, orchestrates use cases, and prepares responses
- Business layer encapsulates domain logic and error handling
- Data layer persists entities and enforces referential integrity
Diagram sources
Detailed Component Analysis
User Data Model
The user entity maps to the sys_user table with the following characteristics:
- Primary key: user_id
- Fields include identity (username, nickname), contact (email, phone, avatar), attributes (gender, status), audit (created_by, updated_by, created_at, updated_at), and soft-deletion marker (deleted_at)
- Password is stored hashed and excluded from JSON serialization
- Indexes on dept_id, status, and deleted_at improve query performance
Diagram sources
Section sources
API Endpoints and Schemas
The UserService exposes the following endpoints:
- ListUser: GET /api/v1/sys/users
- GetUser: GET /api/v1/sys/users/
- CreateUser: POST /api/v1/sys/users
- UpdateUser: PUT /api/v1/sys/users/
- DeleteUser: DELETE /api/v1/sys/users/
- BatchDeleteUser: POST /api/v1/sys/users/batch-delete
- UpdateUserStatus: PUT /api/v1/sys/users/{id}/status
- ResetUserPassword: PUT /api/v1/sys/users/{id}/password/reset
- UpdateUserPassword: PUT /api/v1/sys/users/password
- GetCurrentUser: GET /api/v1/sys/users/current
- UpdateCurrentUser: PUT /api/v1/sys/users/current
- AssignUserRoles: PUT /api/v1/sys/users/{user_id}/roles
- GetUserOptions: GET /api/v1/sys/users/options
Request/response schemas are defined in protobuf with validation rules:
- Username length: 2–64 characters
- Password length: 6–32 characters
- Gender enum: 0 (unknown), 1 (male), 2 (female)
- Status enum: 0 (disabled), 1 (enabled)
- Role IDs: repeated integers for assignment
- Pagination: PageRequest with page_num and page_size validated by service layer
Diagram sources
Section sources
User CRUD Operations
- Create: Validates inputs, checks uniqueness, hashes password, persists user, optionally assigns roles
- Read: Retrieves by ID and enriches with role IDs; lists with pagination and filters
- Update: Updates profile fields; supports role reassignment
- Delete: Soft deletes by setting deleted_at timestamp
- Batch Delete: Deletes multiple users atomically
- Status: Enables/disables accounts
- Password: Resets admin-assigned passwords; updates own password (placeholder in current implementation)
Diagram sources
Section sources
User Profile Management and Account Status Controls
- Profile fields: nickname, email, phone, avatar, gender, remark
- Status control: enable/disable via UpdateUserStatus
- Login info updates: last login IP/time tracked via UpdateLoginInfo
- Current user endpoints: GetCurrentUser and UpdateCurrentUser for self-service profile updates
Section sources
User Search and Filter Capabilities
- Filters: username (like), nickname (like), phone (like), status, dept_id, begin_time, end_time
- Pagination: PageRequest.page_num and page_size validated and applied
- Query building: querybuilder composes conditions and applies ordering and paging
Section sources
Validation Rules
- Username: min 2, max 64
- Password: min 6, max 32
- Email/Phone: max lengths enforced
- Gender: enum in [0,1,2]
- Status: enum in [0,1]
- Role IDs: repeated integers
- Batch delete: 1–100 items
Section sources
Error Handling
- Business errors: structured via apitypes with codes
- NotFound: converted to user-specific not-found error
- Internal errors: logged and returned as generic internal error
- Validation failures: returned as parameter errors
Section sources
Bulk Operations and Import/Export
- Bulk delete: BatchDeleteUser endpoint accepts up to 100 IDs
- Import/export: Tenant-level service includes ExportUserRequest with org_id, username, status and ExportUserReply with file_url
Diagram sources
Section sources
Integration Patterns and Data Synchronization
- Cross-service communication: bi-notify consumes bi-sys user service via generated gRPC stubs
- Tenant isolation: tenant-level user service supports multi-tenant export/import
- Audit trail: sys_login_log and sys_operation_log tables capture login and operation events
Section sources
Frontend Mock Integration (Development)
- Mock API simulates CRUD operations for users, departments, and roles
- Supports toggling status and resetting password placeholders
- Mirrors backend field names for development ergonomics
Section sources
Dependency Analysis
The user management module exhibits clean layering with explicit dependencies:
- API depends on protobuf definitions and OpenAPI annotations
- Service depends on biz use cases and validators
- Biz depends on data repository abstractions
- Data depends on GORM models and SQL schema
Diagram sources
Section sources
Performance Considerations
- Indexes: Bitmap indexes on status and foreign keys (dept_id, user_id) improve filtering and join performance
- Pagination: PageRequest ensures bounded result sets; avoid selecting unnecessary fields
- Soft delete: deleted_at filter prevents scanning inactive records
- Password hashing: bcrypt cost factor balances security and performance
- Query composition: querybuilder centralizes filtering and pagination logic
[No sources needed since this section provides general guidance]
Troubleshooting Guide
Common issues and resolutions:
- Duplicate username: Creation fails; ensure uniqueness before attempting
- Invalid parameters: Validate inputs against protobuf rules; check min/max lengths and enums
- Not found errors: Verify IDs exist and are not soft-deleted
- Internal errors: Review logs for underlying database or hashing failures
- Audit gaps: Confirm login and operation logs are enabled and partitioned appropriately
Section sources
Conclusion
The user management system provides a robust, secure, and scalable foundation for user lifecycle management. It enforces strong validation, maintains audit trails, supports multi-tenancy, and integrates cleanly with cross-service consumers. The layered architecture promotes maintainability and extensibility while ensuring performance through indexing and pagination.
Appendices
API Endpoint Reference
- ListUser: GET /api/v1/sys/users
- GetUser: GET /api/v1/sys/users/
- CreateUser: POST /api/v1/sys/users
- UpdateUser: PUT /api/v1/sys/users/
- DeleteUser: DELETE /api/v1/sys/users/
- BatchDeleteUser: POST /api/v1/sys/users/batch-delete
- UpdateUserStatus: PUT /api/v1/sys/users/{id}/status
- ResetUserPassword: PUT /api/v1/sys/users/{id}/password/reset
- UpdateUserPassword: PUT /api/v1/sys/users/password
- GetCurrentUser: GET /api/v1/sys/users/current
- UpdateCurrentUser: PUT /api/v1/sys/users/current
- AssignUserRoles: PUT /api/v1/sys/users/{user_id}/roles
- GetUserOptions: GET /api/v1/sys/users/options
Section sources
Example Workflows
- User creation: Validate inputs → Check uniqueness → Hash password → Persist → Assign roles → Return ID
- Bulk deletion: Validate IDs (1–100) → Soft delete multiple → Log operation
- User import/export: Prepare tenant export request → Generate file → Return download URL
Section sources