# TRACEABILITY.yml - MGN-003: Roles y Permisos
# Matriz de trazabilidad: Documentacion -> Codigo
# Ubicacion: docs/01-fase-foundation/MGN-003-roles/implementacion/

epic_code: MGN-003
epic_name: Roles y Permisos
phase: 1
phase_name: Foundation
story_points: 40
status: documented

# =============================================================================
# DOCUMENTACION
# =============================================================================

documentation:

  requirements:
    - id: RF-ROLE-001
      file: ../requerimientos/RF-ROLE-001.md
      title: Gestion de Roles
      priority: P0
      status: migrated
      description: |
        CRUD de roles con nombre, descripcion y estado.
        Roles de sistema vs roles personalizados.

    - id: RF-ROLE-002
      file: ../requerimientos/RF-ROLE-002.md
      title: Gestion de Permisos
      priority: P0
      status: migrated
      description: |
        Definicion de permisos granulares: module:action:resource.
        Asignacion de permisos a roles.

    - id: RF-ROLE-003
      file: ../requerimientos/RF-ROLE-003.md
      title: Asignacion Usuario-Rol
      priority: P0
      status: migrated
      description: |
        Asignar uno o mas roles a usuarios.
        Un usuario hereda todos los permisos de sus roles.

    - id: RF-ROLE-004
      file: ../requerimientos/RF-ROLE-004.md
      title: Verificacion de Permisos
      priority: P0
      status: migrated
      description: |
        Verificar en runtime si usuario tiene permiso especifico.
        Guards y decoradores para proteger endpoints.

  requirements_index:
    file: ../requerimientos/INDICE-RF-ROLE.md
    status: migrated

  specifications:
    - id: ET-RBAC-001
      file: ../especificaciones/ET-rbac-backend.md
      title: Backend RBAC
      rf: [RF-ROLE-001, RF-ROLE-002, RF-ROLE-003, RF-ROLE-004]
      status: migrated

    - id: ET-RBAC-002
      file: ../especificaciones/ET-RBAC-database.md
      title: Database RBAC
      rf: [RF-ROLE-001, RF-ROLE-002, RF-ROLE-003, RF-ROLE-004]
      status: migrated

  user_stories:
    - id: US-MGN003-001
      file: ../historias-usuario/US-MGN003-001.md
      title: Crear Rol
      rf: [RF-ROLE-001]
      story_points: 5
      status: migrated

    - id: US-MGN003-002
      file: ../historias-usuario/US-MGN003-002.md
      title: Asignar Permisos a Rol
      rf: [RF-ROLE-002]
      story_points: 8
      status: migrated

    - id: US-MGN003-003
      file: ../historias-usuario/US-MGN003-003.md
      title: Asignar Rol a Usuario
      rf: [RF-ROLE-003]
      story_points: 5
      status: migrated

    - id: US-MGN003-004
      file: ../historias-usuario/US-MGN003-004.md
      title: Verificar Permiso en Endpoint
      rf: [RF-ROLE-004]
      story_points: 8
      status: migrated

  backlog:
    file: ../historias-usuario/BACKLOG-MGN003.md
    status: migrated

# =============================================================================
# IMPLEMENTACION
# =============================================================================

implementation:

  database:
    schema: core_rbac
    path: apps/database/ddl/schemas/core_rbac/

    tables:
      - name: roles
        file: apps/database/ddl/schemas/core_rbac/tables/roles.sql
        rf: RF-RBAC-001
        status: pending
        columns:
          - {name: id, type: UUID, pk: true}
          - {name: tenant_id, type: UUID, fk: tenants}
          - {name: name, type: VARCHAR(100)}
          - {name: slug, type: VARCHAR(100)}
          - {name: description, type: TEXT}
          - {name: is_system, type: BOOLEAN, default: false}
          - {name: is_active, type: BOOLEAN, default: true}
          - {name: created_at, type: TIMESTAMPTZ}
          - {name: updated_at, type: TIMESTAMPTZ}
        indexes:
          - {name: idx_roles_tenant_slug, unique: true}
        rls_policies:
          - tenant_isolation

      - name: permissions
        file: apps/database/ddl/schemas/core_rbac/tables/permissions.sql
        rf: RF-RBAC-002
        status: pending
        columns:
          - {name: id, type: UUID, pk: true}
          - {name: module, type: VARCHAR(50)}
          - {name: action, type: VARCHAR(50)}
          - {name: resource, type: VARCHAR(100)}
          - {name: description, type: TEXT}
          - {name: created_at, type: TIMESTAMPTZ}
        indexes:
          - {name: idx_permissions_unique, columns: [module, action, resource], unique: true}

      - name: role_permissions
        file: apps/database/ddl/schemas/core_rbac/tables/role_permissions.sql
        rf: RF-RBAC-002
        status: pending
        columns:
          - {name: role_id, type: UUID, fk: roles}
          - {name: permission_id, type: UUID, fk: permissions}
          - {name: created_at, type: TIMESTAMPTZ}
        constraints:
          - {type: pk, columns: [role_id, permission_id]}

      - name: user_roles
        file: apps/database/ddl/schemas/core_rbac/tables/user_roles.sql
        rf: RF-RBAC-003
        status: pending
        columns:
          - {name: user_id, type: UUID, fk: users}
          - {name: role_id, type: UUID, fk: roles}
          - {name: assigned_at, type: TIMESTAMPTZ}
          - {name: assigned_by, type: UUID, fk: users}
        constraints:
          - {type: pk, columns: [user_id, role_id]}

    functions:
      - name: user_has_permission
        file: apps/database/ddl/schemas/core_rbac/functions/user_has_permission.sql
        rf: RF-RBAC-004
        status: pending
        params: [p_user_id UUID, p_module VARCHAR, p_action VARCHAR, p_resource VARCHAR]
        returns: BOOLEAN
        description: Verifica si usuario tiene permiso especifico via roles

      - name: get_user_permissions
        file: apps/database/ddl/schemas/core_rbac/functions/get_user_permissions.sql
        rf: RF-RBAC-004
        status: pending
        params: [p_user_id UUID]
        returns: TABLE
        description: Retorna todos los permisos del usuario

      - name: seed_system_roles
        file: apps/database/ddl/schemas/core_rbac/functions/seed_system_roles.sql
        rf: RF-RBAC-005
        status: pending
        params: [p_tenant_id UUID]
        returns: VOID
        description: Crea roles de sistema para nuevo tenant

  backend:
    module: roles
    path: apps/backend/src/modules/roles/
    framework: NestJS

    entities:
      - name: Role
        file: apps/backend/src/modules/roles/entities/role.entity.ts
        rf: RF-RBAC-001
        status: pending

      - name: Permission
        file: apps/backend/src/modules/roles/entities/permission.entity.ts
        rf: RF-RBAC-002
        status: pending

      - name: RolePermission
        file: apps/backend/src/modules/roles/entities/role-permission.entity.ts
        rf: RF-RBAC-002
        status: pending

      - name: UserRole
        file: apps/backend/src/modules/roles/entities/user-role.entity.ts
        rf: RF-RBAC-003
        status: pending

    services:
      - name: RolesService
        file: apps/backend/src/modules/roles/roles.service.ts
        rf: [RF-RBAC-001, RF-RBAC-005]
        status: pending
        methods:
          - {name: create, rf: RF-RBAC-001}
          - {name: findAll, rf: RF-RBAC-001}
          - {name: findOne, rf: RF-RBAC-001}
          - {name: update, rf: RF-RBAC-001}
          - {name: remove, rf: RF-RBAC-001}
          - {name: getSystemRoles, rf: RF-RBAC-005}

      - name: PermissionsService
        file: apps/backend/src/modules/roles/permissions.service.ts
        rf: [RF-RBAC-002, RF-RBAC-004]
        status: pending
        methods:
          - {name: findAll, rf: RF-RBAC-002}
          - {name: findByModule, rf: RF-RBAC-002}
          - {name: assignToRole, rf: RF-RBAC-002}
          - {name: removeFromRole, rf: RF-RBAC-002}
          - {name: getUserPermissions, rf: RF-RBAC-004}
          - {name: hasPermission, rf: RF-RBAC-004}

      - name: UserRolesService
        file: apps/backend/src/modules/roles/user-roles.service.ts
        rf: [RF-RBAC-003]
        status: pending
        methods:
          - {name: assignRole, rf: RF-RBAC-003}
          - {name: removeRole, rf: RF-RBAC-003}
          - {name: getUserRoles, rf: RF-RBAC-003}

    controllers:
      - name: RolesController
        file: apps/backend/src/modules/roles/roles.controller.ts
        status: pending
        endpoints:
          - method: GET
            path: /api/v1/roles
            rf: RF-RBAC-001
            description: Listar roles

          - method: POST
            path: /api/v1/roles
            rf: RF-RBAC-001
            description: Crear rol

          - method: GET
            path: /api/v1/roles/:id
            rf: RF-RBAC-001
            description: Obtener rol

          - method: PATCH
            path: /api/v1/roles/:id
            rf: RF-RBAC-001
            description: Actualizar rol

          - method: DELETE
            path: /api/v1/roles/:id
            rf: RF-RBAC-001
            description: Eliminar rol

          - method: GET
            path: /api/v1/roles/:id/permissions
            rf: RF-RBAC-002
            description: Permisos del rol

          - method: POST
            path: /api/v1/roles/:id/permissions
            rf: RF-RBAC-002
            description: Asignar permiso

          - method: DELETE
            path: /api/v1/roles/:id/permissions/:permissionId
            rf: RF-RBAC-002
            description: Quitar permiso

      - name: PermissionsController
        file: apps/backend/src/modules/roles/permissions.controller.ts
        status: pending
        endpoints:
          - method: GET
            path: /api/v1/permissions
            rf: RF-RBAC-002
            description: Listar permisos disponibles

          - method: GET
            path: /api/v1/permissions/modules
            rf: RF-RBAC-002
            description: Listar modulos

    guards:
      - name: RolesGuard
        file: apps/backend/src/modules/roles/guards/roles.guard.ts
        rf: RF-RBAC-004
        status: pending
        description: Verifica que usuario tenga rol requerido

      - name: PermissionsGuard
        file: apps/backend/src/modules/roles/guards/permissions.guard.ts
        rf: RF-RBAC-004
        status: pending
        description: Verifica que usuario tenga permiso requerido

    decorators:
      - name: Roles
        file: apps/backend/src/modules/roles/decorators/roles.decorator.ts
        rf: RF-RBAC-004
        status: pending
        usage: "@Roles('admin', 'manager')"

      - name: Permissions
        file: apps/backend/src/modules/roles/decorators/permissions.decorator.ts
        rf: RF-RBAC-004
        status: pending
        usage: "@Permissions('users:read:all')"

      - name: RequirePermission
        file: apps/backend/src/modules/roles/decorators/require-permission.decorator.ts
        rf: RF-RBAC-004
        status: pending
        usage: "@RequirePermission('users', 'write', 'all')"

  frontend:
    feature: roles
    path: apps/frontend/src/features/roles/
    framework: React

    pages:
      - name: RolesPage
        file: apps/frontend/src/features/roles/pages/RolesPage.tsx
        rf: RF-RBAC-001
        status: pending
        route: /settings/roles

      - name: RoleDetailPage
        file: apps/frontend/src/features/roles/pages/RoleDetailPage.tsx
        rf: [RF-RBAC-001, RF-RBAC-002]
        status: pending
        route: /settings/roles/:id

      - name: PermissionsPage
        file: apps/frontend/src/features/roles/pages/PermissionsPage.tsx
        rf: RF-RBAC-002
        status: pending
        route: /settings/permissions

    components:
      - name: RoleTable
        file: apps/frontend/src/features/roles/components/RoleTable.tsx
        rf: RF-RBAC-001
        status: pending

      - name: RoleForm
        file: apps/frontend/src/features/roles/components/RoleForm.tsx
        rf: RF-RBAC-001
        status: pending

      - name: PermissionMatrix
        file: apps/frontend/src/features/roles/components/PermissionMatrix.tsx
        rf: RF-RBAC-002
        status: pending
        description: Matriz visual para asignar permisos a rol

      - name: UserRoleAssignment
        file: apps/frontend/src/features/roles/components/UserRoleAssignment.tsx
        rf: RF-RBAC-003
        status: pending

    stores:
      - name: rolesStore
        file: apps/frontend/src/features/roles/stores/rolesStore.ts
        rf: [RF-RBAC-001, RF-RBAC-002]
        status: pending

    hooks:
      - name: usePermission
        file: apps/frontend/src/features/roles/hooks/usePermission.ts
        rf: RF-RBAC-004
        status: pending
        description: Hook para verificar permisos en frontend

      - name: useHasRole
        file: apps/frontend/src/features/roles/hooks/useHasRole.ts
        rf: RF-RBAC-004
        status: pending
        description: Hook para verificar roles en frontend

# =============================================================================
# DEPENDENCIAS
# =============================================================================

dependencies:
  depends_on:
    - module: MGN-001
      type: hard
      reason: RBAC usa tokens JWT
    - module: MGN-002
      type: hard
      reason: Roles se asignan a usuarios

  required_by:
    - module: MGN-004
      type: soft
      reason: Tenants tienen roles por defecto
    - module: ALL_BUSINESS
      type: hard
      reason: Todos los modulos usan permisos

# =============================================================================
# TESTS
# =============================================================================

tests:
  unit:
    - name: RolesService.spec.ts
      file: apps/backend/src/modules/roles/__tests__/roles.service.spec.ts
      status: pending
      cases: 10

    - name: PermissionsService.spec.ts
      file: apps/backend/src/modules/roles/__tests__/permissions.service.spec.ts
      status: pending
      cases: 12

    - name: RolesGuard.spec.ts
      file: apps/backend/src/modules/roles/__tests__/roles.guard.spec.ts
      status: pending
      cases: 8

  integration:
    - name: roles.controller.e2e.spec.ts
      file: apps/backend/test/roles/roles.controller.e2e.spec.ts
      status: pending
      cases: 12

  coverage:
    target: 80%
    current: 0%

# =============================================================================
# METRICAS
# =============================================================================

metrics:
  story_points:
    estimated: 40
    actual: null

  files:
    database: 7
    backend: 18
    frontend: 10
    tests: 6
    total: 41

# =============================================================================
# HISTORIAL
# =============================================================================

history:
  - date: "2025-12-05"
    action: "Creacion de TRACEABILITY.yml"
    author: Requirements-Analyst