# TRACEABILITY.yml - MGN-002: Usuarios
# Matriz de trazabilidad: Documentacion -> Codigo
# Ubicacion: docs/01-fase-foundation/MGN-002-users/implementacion/

epic_code: MGN-002
epic_name: Usuarios
phase: 1
phase_name: Foundation
story_points: 35
status: documented

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

documentation:

  requirements:
    - id: RF-USER-001
      file: ../requerimientos/RF-USER-001.md
      title: CRUD de Usuarios
      priority: P0
      status: migrated
      description: |
        Crear, leer, actualizar y eliminar usuarios del sistema.
        Incluye soft delete para mantener trazabilidad.

    - id: RF-USER-002
      file: ../requerimientos/RF-USER-002.md
      title: Perfil de Usuario
      priority: P0
      status: migrated
      description: |
        Gestion de perfil extendido: bio, empresa, cargo,
        direccion, links sociales.

    - id: RF-USER-003
      file: ../requerimientos/RF-USER-003.md
      title: Cambio de Email
      priority: P1
      status: migrated
      description: |
        Proceso seguro para cambiar email del usuario.
        Requiere verificacion del nuevo email antes del cambio.

    - id: RF-USER-004
      file: ../requerimientos/RF-USER-004.md
      title: Cambio de Password
      priority: P1
      status: migrated
      description: |
        Permitir al usuario cambiar su password.
        Requiere confirmacion del password actual.

    - id: RF-USER-005
      file: ../requerimientos/RF-USER-005.md
      title: Preferencias de Usuario
      priority: P1
      status: migrated
      description: |
        Personalizacion: tema, idioma, formato fecha,
        configuracion de notificaciones.

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

  specifications:
    - id: ET-USERS-001
      file: ../especificaciones/ET-users-backend.md
      title: Backend Users
      rf: [RF-USER-001, RF-USER-002, RF-USER-003, RF-USER-004, RF-USER-005]
      status: migrated

    - id: ET-USERS-002
      file: ../especificaciones/ET-USER-database.md
      title: Database Users
      rf: [RF-USER-001, RF-USER-002, RF-USER-003]
      status: migrated

  user_stories:
    - id: US-MGN002-001
      file: ../historias-usuario/US-MGN002-001.md
      title: Crear Usuario
      rf: [RF-USER-001]
      story_points: 5
      status: migrated

    - id: US-MGN002-002
      file: ../historias-usuario/US-MGN002-002.md
      title: Editar Usuario
      rf: [RF-USER-001]
      story_points: 3
      status: migrated

    - id: US-MGN002-003
      file: ../historias-usuario/US-MGN002-003.md
      title: Gestionar Perfil
      rf: [RF-USER-002]
      story_points: 5
      status: migrated

    - id: US-MGN002-004
      file: ../historias-usuario/US-MGN002-004.md
      title: Configurar Preferencias
      rf: [RF-USER-005]
      story_points: 3
      status: migrated

    - id: US-MGN002-005
      file: ../historias-usuario/US-MGN002-005.md
      title: Cambio de Email
      rf: [RF-USER-003]
      story_points: 6
      status: ready

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

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

implementation:

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

    tables:
      - name: users
        file: apps/database/ddl/schemas/core_users/tables/users.sql
        rf: RF-USERS-001
        status: pending
        columns:
          - {name: id, type: UUID, pk: true}
          - {name: tenant_id, type: UUID, fk: tenants}
          - {name: first_name, type: VARCHAR(100)}
          - {name: last_name, type: VARCHAR(100)}
          - {name: display_name, type: VARCHAR(200)}
          - {name: avatar_url, type: TEXT}
          - {name: phone, type: VARCHAR(20)}
          - {name: timezone, type: VARCHAR(50)}
          - {name: locale, type: VARCHAR(10)}
          - {name: is_active, type: BOOLEAN}
          - {name: created_at, type: TIMESTAMPTZ}
          - {name: updated_at, type: TIMESTAMPTZ}
          - {name: deleted_at, type: TIMESTAMPTZ}
        indexes:
          - idx_users_tenant
          - idx_users_name_search
        rls_policies:
          - tenant_isolation

      - name: user_profiles
        file: apps/database/ddl/schemas/core_users/tables/user_profiles.sql
        rf: RF-USERS-002
        status: pending
        columns:
          - {name: id, type: UUID, pk: true}
          - {name: user_id, type: UUID, fk: users, unique: true}
          - {name: bio, type: TEXT}
          - {name: company, type: VARCHAR(200)}
          - {name: job_title, type: VARCHAR(100)}
          - {name: address, type: JSONB}
          - {name: social_links, type: JSONB}
          - {name: created_at, type: TIMESTAMPTZ}
          - {name: updated_at, type: TIMESTAMPTZ}

      - name: user_preferences
        file: apps/database/ddl/schemas/core_users/tables/user_preferences.sql
        rf: RF-USERS-003
        status: pending
        columns:
          - {name: id, type: UUID, pk: true}
          - {name: user_id, type: UUID, fk: users, unique: true}
          - {name: theme, type: VARCHAR(20)}
          - {name: notifications_email, type: BOOLEAN}
          - {name: notifications_push, type: BOOLEAN}
          - {name: language, type: VARCHAR(10)}
          - {name: date_format, type: VARCHAR(20)}
          - {name: created_at, type: TIMESTAMPTZ}
          - {name: updated_at, type: TIMESTAMPTZ}

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

    entities:
      - name: User
        file: apps/backend/src/modules/users/entities/user.entity.ts
        rf: RF-USERS-001
        status: pending
        table: users

      - name: UserProfile
        file: apps/backend/src/modules/users/entities/user-profile.entity.ts
        rf: RF-USERS-002
        status: pending
        table: user_profiles

      - name: UserPreferences
        file: apps/backend/src/modules/users/entities/user-preferences.entity.ts
        rf: RF-USERS-003
        status: pending
        table: user_preferences

    services:
      - name: UsersService
        file: apps/backend/src/modules/users/users.service.ts
        rf: [RF-USERS-001, RF-USERS-004, RF-USERS-005]
        status: pending
        methods:
          - {name: create, rf: RF-USERS-001}
          - {name: findAll, rf: RF-USERS-001}
          - {name: findOne, rf: RF-USERS-001}
          - {name: update, rf: RF-USERS-001}
          - {name: remove, rf: RF-USERS-001}
          - {name: activate, rf: RF-USERS-004}
          - {name: deactivate, rf: RF-USERS-004}
          - {name: search, rf: RF-USERS-005}

      - name: ProfileService
        file: apps/backend/src/modules/users/profile.service.ts
        rf: [RF-USERS-002]
        status: pending
        methods:
          - {name: getProfile, rf: RF-USERS-002}
          - {name: updateProfile, rf: RF-USERS-002}
          - {name: uploadAvatar, rf: RF-USERS-002}

      - name: PreferencesService
        file: apps/backend/src/modules/users/preferences.service.ts
        rf: [RF-USERS-003]
        status: pending
        methods:
          - {name: getPreferences, rf: RF-USERS-003}
          - {name: updatePreferences, rf: RF-USERS-003}

    controllers:
      - name: UsersController
        file: apps/backend/src/modules/users/users.controller.ts
        status: pending
        endpoints:
          - method: GET
            path: /api/v1/users
            rf: RF-USERS-001
            description: Listar usuarios con paginacion

          - method: GET
            path: /api/v1/users/:id
            rf: RF-USERS-001
            description: Obtener usuario por ID

          - method: POST
            path: /api/v1/users
            rf: RF-USERS-001
            description: Crear nuevo usuario

          - method: PATCH
            path: /api/v1/users/:id
            rf: RF-USERS-001
            description: Actualizar usuario

          - method: DELETE
            path: /api/v1/users/:id
            rf: RF-USERS-001
            description: Soft delete usuario

          - method: GET
            path: /api/v1/users/:id/profile
            rf: RF-USERS-002
            description: Obtener perfil

          - method: PATCH
            path: /api/v1/users/:id/profile
            rf: RF-USERS-002
            description: Actualizar perfil

          - method: POST
            path: /api/v1/users/:id/avatar
            rf: RF-USERS-002
            description: Subir avatar

          - method: GET
            path: /api/v1/users/:id/preferences
            rf: RF-USERS-003
            description: Obtener preferencias

          - method: PATCH
            path: /api/v1/users/:id/preferences
            rf: RF-USERS-003
            description: Actualizar preferencias

          - method: POST
            path: /api/v1/users/:id/activate
            rf: RF-USERS-004
            description: Activar usuario

          - method: POST
            path: /api/v1/users/:id/deactivate
            rf: RF-USERS-004
            description: Desactivar usuario

          - method: GET
            path: /api/v1/users/search
            rf: RF-USERS-005
            description: Buscar usuarios

    dtos:
      - name: CreateUserDto
        file: apps/backend/src/modules/users/dto/create-user.dto.ts
        rf: RF-USERS-001
        status: pending

      - name: UpdateUserDto
        file: apps/backend/src/modules/users/dto/update-user.dto.ts
        rf: RF-USERS-001
        status: pending

      - name: UserFilterDto
        file: apps/backend/src/modules/users/dto/user-filter.dto.ts
        rf: RF-USERS-005
        status: pending

      - name: UpdateProfileDto
        file: apps/backend/src/modules/users/dto/update-profile.dto.ts
        rf: RF-USERS-002
        status: pending

      - name: UpdatePreferencesDto
        file: apps/backend/src/modules/users/dto/update-preferences.dto.ts
        rf: RF-USERS-003
        status: pending

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

    pages:
      - name: UsersPage
        file: apps/frontend/src/features/users/pages/UsersPage.tsx
        rf: RF-USERS-001
        status: pending
        route: /users

      - name: UserDetailPage
        file: apps/frontend/src/features/users/pages/UserDetailPage.tsx
        rf: RF-USERS-001
        status: pending
        route: /users/:id

      - name: ProfilePage
        file: apps/frontend/src/features/users/pages/ProfilePage.tsx
        rf: RF-USERS-002
        status: pending
        route: /profile

      - name: PreferencesPage
        file: apps/frontend/src/features/users/pages/PreferencesPage.tsx
        rf: RF-USERS-003
        status: pending
        route: /settings/preferences

    components:
      - name: UserTable
        file: apps/frontend/src/features/users/components/UserTable.tsx
        rf: RF-USERS-001
        status: pending

      - name: UserForm
        file: apps/frontend/src/features/users/components/UserForm.tsx
        rf: RF-USERS-001
        status: pending

      - name: ProfileForm
        file: apps/frontend/src/features/users/components/ProfileForm.tsx
        rf: RF-USERS-002
        status: pending

      - name: AvatarUpload
        file: apps/frontend/src/features/users/components/AvatarUpload.tsx
        rf: RF-USERS-002
        status: pending

      - name: PreferencesForm
        file: apps/frontend/src/features/users/components/PreferencesForm.tsx
        rf: RF-USERS-003
        status: pending

      - name: UserSearchInput
        file: apps/frontend/src/features/users/components/UserSearchInput.tsx
        rf: RF-USERS-005
        status: pending

    stores:
      - name: usersStore
        file: apps/frontend/src/features/users/stores/usersStore.ts
        rf: [RF-USERS-001, RF-USERS-005]
        status: pending
        state:
          - {name: users, type: "User[]"}
          - {name: selectedUser, type: "User | null"}
          - {name: isLoading, type: boolean}
          - {name: pagination, type: PaginationState}
        actions:
          - fetchUsers
          - createUser
          - updateUser
          - deleteUser
          - searchUsers

    api:
      - name: usersApi
        file: apps/frontend/src/features/users/api/usersApi.ts
        status: pending
        methods:
          - {name: getUsers, endpoint: "GET /users"}
          - {name: getUser, endpoint: "GET /users/:id"}
          - {name: createUser, endpoint: "POST /users"}
          - {name: updateUser, endpoint: "PATCH /users/:id"}
          - {name: deleteUser, endpoint: "DELETE /users/:id"}
          - {name: getProfile, endpoint: "GET /users/:id/profile"}
          - {name: updateProfile, endpoint: "PATCH /users/:id/profile"}
          - {name: getPreferences, endpoint: "GET /users/:id/preferences"}
          - {name: updatePreferences, endpoint: "PATCH /users/:id/preferences"}
          - {name: searchUsers, endpoint: "GET /users/search"}

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

dependencies:
  depends_on:
    - module: MGN-001
      type: hard
      reason: Usuarios requieren autenticacion

  required_by:
    - module: MGN-003
      type: hard
      reason: Roles se asignan a usuarios
    - module: MGN-004
      type: hard
      reason: Usuarios pertenecen a tenants
    - module: MGN-011
      type: soft
      reason: HR extiende usuarios como empleados
    - module: MGN-019
      type: soft
      reason: Audit registra acciones de usuarios

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

tests:
  unit:
    - name: UsersService.spec.ts
      file: apps/backend/src/modules/users/__tests__/users.service.spec.ts
      status: pending
      cases: 15
      rf: [RF-USERS-001, RF-USERS-004, RF-USERS-005]

    - name: ProfileService.spec.ts
      file: apps/backend/src/modules/users/__tests__/profile.service.spec.ts
      status: pending
      cases: 6
      rf: [RF-USERS-002]

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

  frontend:
    - name: UserForm.test.tsx
      file: apps/frontend/src/features/users/__tests__/UserForm.test.tsx
      status: pending
      cases: 6

  coverage:
    target: 80%
    current: 0%

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

metrics:
  story_points:
    estimated: 35
    actual: null

  files:
    database: 4
    backend: 15
    frontend: 12
    tests: 6
    total: 37

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

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