tm_back/internal/user/README.md

# 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
```json
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
```json
POST /api/v1/users/login
{
  "email_or_username": "john.doe@example.com",
  "password": "securepassword123"
}
```

### Update User
```json
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
```go
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