tm_back/internal/user

User Management Service

This service provides comprehensive user management functionality for the Tender Management system, following Clean Architecture principles and Domain-Driven Design patterns.

Features

User Authentication

• Login: Authenticate users with email/username and password
• Refresh Token: Refresh access tokens
• Logout: Securely log out users
• Password Management: Change password and reset password functionality

User Management

• Create User: Create new users with roles and permissions
• Update User: Update user information and profile
• Delete User: Soft delete users (set status to inactive)
• Get User: Retrieve user information by ID
• List Users: Search and filter users with pagination

Role-Based Access Control

• User Roles: admin, manager, operator, viewer
• Role Management: Update user roles
• Status Management: Activate, deactivate, or suspend users

Company Management

• Company Users: Get users by company ID
• User Count: Count users per company

API Endpoints

Public Endpoints

Authentication

POST /api/v1/users/login
POST /api/v1/users/refresh-token
POST /api/v1/users/reset-password

Protected Endpoints (Require Authentication)

User Profile

GET  /api/v1/users/profile
PUT  /api/v1/users/profile
PUT  /api/v1/users/change-password
POST /api/v1/users/logout

Admin Endpoints (Require Admin Role)

User Management

POST   /api/v1/users/admin/
GET    /api/v1/users/admin/
GET    /api/v1/users/admin/:id
PUT    /api/v1/users/admin/:id
DELETE /api/v1/users/admin/:id

User Status & Role Management

PUT /api/v1/users/admin/:id/status
PUT /api/v1/users/admin/:id/role

Company & Role Queries

GET /api/v1/users/admin/company/:company_id
GET /api/v1/users/admin/role/:role

Request/Response Examples

Create User

POST /api/v1/users/admin/
{
  "full_name": "John Doe",
  "username": "johndoe",
  "email": "john.doe@example.com",
  "password": "securepassword123",
  "role": "manager",
  "company_id": "550e8400-e29b-41d4-a716-446655440000",
  "department": "Engineering",
  "position": "Senior Manager",
  "phone": "+1234567890",
  "profile_image": "https://example.com/avatar.jpg"
}

Login

POST /api/v1/users/login
{
  "email_or_username": "john.doe@example.com",
  "password": "securepassword123"
}

Update User

PUT /api/v1/users/admin/:id
{
  "full_name": "John Smith",
  "department": "Product Management",
  "status": "active"
}

List Users with Filters

GET /api/v1/users/admin/?search=john&role=manager&status=active&limit=20&offset=0&sort_by=created_at&sort_order=desc

Data Models

User Entity

type User struct {
    ID           uuid.UUID  `bson:"_id"`
    FullName     string     `bson:"full_name"`
    Username     string     `bson:"username"`
    Email        string     `bson:"email"`
    Password     string     `bson:"password"`
    Role         UserRole   `bson:"role"`
    Status       UserStatus `bson:"status"`
    CompanyID    *uuid.UUID `bson:"company_id,omitempty"`
    Department   *string    `bson:"department,omitempty"`
    Position     *string    `bson:"position,omitempty"`
    Phone        *string    `bson:"phone,omitempty"`
    ProfileImage *string    `bson:"profile_image,omitempty"`
    IsVerified   bool       `bson:"is_verified"`
    LastLoginAt  *int64     `bson:"last_login_at,omitempty"`
    CreatedAt    int64      `bson:"created_at"`
    UpdatedAt    int64      `bson:"updated_at"`
    CreatedBy    *uuid.UUID `bson:"created_by,omitempty"`
    UpdatedBy    *uuid.UUID `bson:"updated_by,omitempty"`
}

User Roles

• admin: Full system access
• manager: Company and team management
• operator: Operational tasks
• viewer: Read-only access

User Status

• active: User can access the system
• inactive: User account is disabled
• suspended: User account is temporarily suspended

Security Features

Password Security

• Passwords are hashed using bcrypt
• Minimum password length: 8 characters
• Maximum password length: 128 characters

Authentication

• JWT-based authentication (to be implemented)
• Token refresh mechanism
• Secure logout with token invalidation

Authorization

• Role-based access control
• Admin-only endpoints for user management
• Company-scoped access for multi-tenant support

Database Indexes

The service creates the following MongoDB indexes for optimal performance:

• Email Index: Unique index on email field
• Username Index: Unique index on username field
• Company ID Index: For company-based queries
• Role Index: For role-based filtering
• Status Index: For status-based filtering
• Created At Index: For sorting by creation date
• Text Search Index: For full-text search across name, email, username, department, and position

Error Handling

The service provides comprehensive error handling with:

• Validation Errors: Detailed validation messages using govalidator
• Business Logic Errors: Clear error messages for business rule violations
• Database Errors: Proper handling of database constraints and connection issues
• Security Errors: Secure error messages that don't leak sensitive information

Logging

All operations are logged with structured logging including:

• Operation Context: User ID, company ID, operation type
• Error Details: Full error context for debugging
• Security Events: Login attempts, password changes, role updates
• Performance Metrics: Operation timing and resource usage

Future Enhancements

Planned Features

• JWT Token Management: Complete JWT implementation with refresh tokens
• Email Verification: Email verification for new user accounts
• Password Reset: Complete password reset flow with email
• Audit Trail: Comprehensive audit logging for all user operations
• Bulk Operations: Bulk user import/export functionality
• Advanced Search: Elasticsearch integration for advanced search capabilities

Integration Points

• Email Service: For password reset and verification emails
• Notification Service: For user activity notifications
• Audit Service: For comprehensive audit logging
• Permission Service: For fine-grained permission management