docs/security/ACCESS_ROLES_README.md

Access Roles CRUD Module

Complete CRUD implementation for access roles management in the SCM microservice.

Overview

The Access Roles module provides comprehensive role-based access control (RBAC) functionality with full CRUD operations, projection support, and base role management.

Features

• ✅ Complete CRUD Operations: Create, Read, Update, Delete access roles
• ✅ Projection List Support: Optimized queries with field selection
• ✅ Base Role Protection: Prevents deletion of system base roles
• ✅ MongoDB Integration: Async MongoDB operations with proper error handling
• ✅ JWT Authentication: Secured endpoints with user authentication
• ✅ Comprehensive Validation: Pydantic models with proper validation
• ✅ Logging & Error Handling: Detailed logging and proper error responses

API Endpoints

Base URL: /access-roles

Method	Endpoint	Description
POST	/create	Create new access role
POST	/get	Get access role by ID
POST	/list	List access roles with filtering
POST	/update?role_id={id}	Update access role
POST	/delete	Delete access role
GET	/base-roles	Get all base system roles

Data Model

AccessRole

{
    "role_id": "role_store_manager",
    "role_name": "Store Manager", 
    "description": "Store level management access",
    "permissions": {
        "inventory": ["view", "create", "update"],
        "orders": ["view", "create", "update"],
        "suppliers": ["view"],
        "catalogues": ["view"],
        "reports": ["view"],
        "settings": ["view"],
        "goods_receipts": ["view", "create", "update"],
        "merchant_setting": ["view"],
        "merchant": ["view"],
        "stock": ["view", "create", "update"],
        "access_control": ["view"],
        "employees": ["view", "create", "update"]
    },
    "is_base_role": false,
    "is_active": true,
    "created_by": "admin_user",
    "created_at": "2025-12-13T10:00:00Z",
    "updated_by": "admin_user",
    "updated_at": "2025-12-13T11:00:00Z"
}

Permission Modules

• inventory: Inventory management
• orders: Order management
• suppliers: Supplier management
• catalogues: Catalogue management
• reports: Reporting and analytics
• settings: System settings
• goods_receipts: Goods receipt notes
• merchant_setting: Merchant settings
• merchant: Merchant management
• stock: Stock management
• access_control: Access control management
• employees: Employee management
• system: System administration
• system_users: System user management

Permission Actions

• view: Read access
• create: Create new records
• update: Modify existing records
• delete: Delete records
• export: Export data
• schedule: Schedule operations
• manage: Full management access
• audit: Audit access
• backup: Backup operations

Base Roles

The system includes three predefined base roles:

1. Super Administrator (role_super_admin)

• Description: Full system access with all permissions
• Permissions: All modules with all actions
• Protected: Cannot be deleted

2. Company Administrator (role_company_admin)

• Description: Company-wide administrative access
• Permissions: Most modules with create/update access (no delete/system)
• Protected: Cannot be deleted

3. cnf Manager (role_cnf_manager)

• Description: cnf operations management
• Permissions: Limited operational access
• Protected: Cannot be deleted

Usage Examples

1. Create Access Role

curl -X POST "http://localhost:8000/access-roles/create" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "role_id": "role_store_manager",
    "role_name": "Store Manager",
    "description": "Store level management access",
    "permissions": {
      "inventory": ["view", "create", "update"],
      "orders": ["view", "create", "update"]
    },
    "is_active": true
  }'

2. List Roles with Projection

curl -X POST "http://localhost:8000/access-roles/list" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "filters": {"is_active": true},
    "skip": 0,
    "limit": 10,
    "projection_list": ["role_id", "role_name", "is_active"]
  }'

3. Update Role

curl -X POST "http://localhost:8000/access-roles/update?role_id=role_store_manager" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "role_name": "Updated Store Manager",
    "permissions": {
      "inventory": ["view", "create", "update", "delete"]
    }
  }'

Setup Instructions

1. Initialize Base Roles

cd cuatrolabs-scm-ms
python initialize_access_roles.py

2. Test CRUD Operations

cd cuatrolabs-scm-ms
python test_access_roles_crud.py

3. Test API Endpoints

cd cuatrolabs-scm-ms
# Update AUTH_TOKEN in the script first
./test_access_roles_api.sh

File Structure

cuatrolabs-scm-ms/app/access_roles/
├── __init__.py
├── controllers/
│   ├── __init__.py
│   └── router.py          # FastAPI router with all endpoints
├── models/
│   ├── __init__.py
│   └── model.py           # Pydantic models
├── schemas/
│   ├── __init__.py
│   └── schema.py          # Request/response schemas
└── services/
    ├── __init__.py
    └── service.py         # Business logic and database operations

Key Features Implementation

1. Projection List Support

Following the API standards, all list/get endpoints support projection lists for optimized queries:

# Service layer implementation
projection_dict = None
if projection_list:
    projection_dict = {field: 1 for field in projection_list}
    projection_dict["_id"] = 0

cursor = collection.find(query, projection_dict)
docs = await cursor.to_list(length=limit)

# Return raw dict if projection, model otherwise
return docs if projection_list else [Model(**d) for d in docs]

2. Base Role Protection

Base roles are protected from deletion:

async def delete_access_role(self, role_id: str) -> bool:
    # Check if it's a base role
    role = await self.collection.find_one({"role_id": role_id})
    if role and role.get("is_base_role", False):
        raise ValueError("Cannot delete base system roles")

3. Comprehensive Error Handling

All operations include proper error handling with detailed logging:

try:
    # Operation logic
    pass
except DuplicateKeyError:
    logger.error(f"Role {role_id} already exists")
    raise HTTPException(status_code=409, detail="Role already exists")
except Exception as e:
    logger.error(f"Error: {str(e)}")
    raise HTTPException(status_code=500, detail="Internal server error")

Database Collection

Collection Name: scm_access_roles

The collection stores access role documents with the following indexes:

• role_id: Unique index for role identification
• is_active: Index for filtering active roles
• is_base_role: Index for base role queries

Integration

The access roles module is fully integrated into the SCM microservice:

1. Router Registration: Added to app/main.py
2. Collection Constant: Defined in app/constants/collections.py
3. Authentication: Uses existing JWT authentication from app/dependencies/auth.py
4. Database: Uses existing MongoDB connection from app/nosql.py

Testing

Unit Tests

• Service layer CRUD operations
• Model validation
• Error handling scenarios

Integration Tests

• API endpoint testing
• Authentication flow
• Database operations

Performance Tests

• Projection list optimization
• Large dataset handling
• Concurrent operations

Security Considerations

1. JWT Authentication: All endpoints require valid JWT tokens
2. Base Role Protection: System roles cannot be deleted
3. Input Validation: Comprehensive Pydantic validation
4. Permission Validation: Role permissions are validated against allowed modules/actions
5. Audit Trail: All operations include created_by/updated_by tracking

Performance Optimizations

1. MongoDB Projection: Reduces data transfer and processing
2. Indexed Queries: Efficient database queries with proper indexes
3. Async Operations: Non-blocking database operations
4. Connection Pooling: Efficient database connection management

Monitoring & Logging

• Comprehensive logging for all operations
• Error tracking with detailed context
• Performance metrics for database operations
• Audit trail for role modifications

This implementation provides a robust, scalable, and secure access roles management system following all established API standards and best practices.