# TRACEABILITY.yml - MGN-005: Catalogos
# Matriz de trazabilidad: Documentacion -> Codigo
# Ubicacion: docs/02-fase-core-business/MGN-005-catalogs/implementacion/

epic_code: MGN-005
epic_name: Catalogos
phase: 2
phase_name: Core Business
story_points: 30
status: migrated

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

documentation:

  requirements:
    - id: RF-CATALOG-001
      file: ../requerimientos/RF-CATALOG-001.md
      title: CRUD de Catalogos
      priority: P0
      status: migrated
      description: |
        Crear, leer, actualizar y eliminar catalogos maestros.
        Cada catalogo tiene codigo, nombre, descripcion y estado.

    - id: RF-CATALOG-002
      file: ../requerimientos/RF-CATALOG-002.md
      title: Items de Catalogo
      priority: P0
      status: migrated
      description: |
        Gestion de items dentro de cada catalogo.
        Items con codigo, valor, orden y estado.

    - id: RF-CATALOG-003
      file: ../requerimientos/RF-CATALOG-003.md
      title: Catalogos Jerarquicos
      priority: P1
      status: migrated
      description: |
        Soporte para catalogos con estructura de arbol.
        Items padre-hijo, niveles multiples.

    - id: RF-CATALOG-004
      file: ../requerimientos/RF-CATALOG-004.md
      title: Catalogos de Sistema
      priority: P1
      status: migrated
      description: |
        Catalogos predefinidos no eliminables.
        Paises, monedas, unidades basicas.

    - id: RF-CATALOG-005
      file: ../requerimientos/RF-CATALOG-005.md
      title: Busqueda y Filtrado
      priority: P1
      status: migrated
      description: |
        Busqueda eficiente en catalogos grandes.
        Filtros por estado, tipo, texto.

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

  specifications: []
  # Pendiente de creacion

  user_stories: []
  # Pendiente de creacion

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

implementation:

  database:
    schema: core_catalogs
    path: apps/database/ddl/schemas/core_catalogs/
    status: pending

    tables:
      - name: catalogs
        file: apps/database/ddl/schemas/core_catalogs/tables/catalogs.sql
        rf: RF-CATALOG-001
        status: pending
        columns:
          - {name: id, type: UUID, pk: true}
          - {name: tenant_id, type: UUID, fk: tenants}
          - {name: code, type: VARCHAR(50), unique: true}
          - {name: name, type: VARCHAR(100)}
          - {name: description, type: TEXT}
          - {name: is_system, type: BOOLEAN, default: false}
          - {name: is_hierarchical, type: BOOLEAN, default: false}
          - {name: is_active, type: BOOLEAN, default: true}
          - {name: created_at, type: TIMESTAMPTZ}
          - {name: updated_at, type: TIMESTAMPTZ}

      - name: catalog_items
        file: apps/database/ddl/schemas/core_catalogs/tables/catalog_items.sql
        rf: RF-CATALOG-002
        status: pending
        columns:
          - {name: id, type: UUID, pk: true}
          - {name: catalog_id, type: UUID, fk: catalogs}
          - {name: parent_id, type: UUID, fk: catalog_items, nullable: true}
          - {name: code, type: VARCHAR(50)}
          - {name: value, type: VARCHAR(255)}
          - {name: extra_data, type: JSONB}
          - {name: sort_order, type: INTEGER, default: 0}
          - {name: is_active, type: BOOLEAN, default: true}
          - {name: created_at, type: TIMESTAMPTZ}
          - {name: updated_at, type: TIMESTAMPTZ}

  backend:
    module: catalogs
    path: apps/backend/src/modules/catalogs/
    framework: NestJS
    status: pending

    entities:
      - name: Catalog
        file: apps/backend/src/modules/catalogs/entities/catalog.entity.ts
        rf: RF-CATALOG-001
        status: pending

      - name: CatalogItem
        file: apps/backend/src/modules/catalogs/entities/catalog-item.entity.ts
        rf: RF-CATALOG-002
        status: pending

    services:
      - name: CatalogsService
        file: apps/backend/src/modules/catalogs/catalogs.service.ts
        rf: [RF-CATALOG-001, RF-CATALOG-002, RF-CATALOG-005]
        status: pending
        methods:
          - {name: create, rf: RF-CATALOG-001}
          - {name: findAll, rf: RF-CATALOG-005}
          - {name: findOne, rf: RF-CATALOG-001}
          - {name: update, rf: RF-CATALOG-001}
          - {name: remove, rf: RF-CATALOG-001}

    controllers:
      - name: CatalogsController
        file: apps/backend/src/modules/catalogs/catalogs.controller.ts
        status: pending
        endpoints:
          - method: GET
            path: /api/v1/catalogs
            rf: RF-CATALOG-005
            description: Listar catalogos con filtros

          - method: POST
            path: /api/v1/catalogs
            rf: RF-CATALOG-001
            description: Crear catalogo

          - method: GET
            path: /api/v1/catalogs/:id
            rf: RF-CATALOG-001
            description: Obtener catalogo por ID

          - method: PUT
            path: /api/v1/catalogs/:id
            rf: RF-CATALOG-001
            description: Actualizar catalogo

          - method: DELETE
            path: /api/v1/catalogs/:id
            rf: RF-CATALOG-001
            description: Eliminar catalogo

          - method: GET
            path: /api/v1/catalogs/:id/items
            rf: RF-CATALOG-002
            description: Listar items de catalogo

          - method: POST
            path: /api/v1/catalogs/:id/items
            rf: RF-CATALOG-002
            description: Agregar item a catalogo

  frontend:
    feature: catalogs
    path: apps/frontend/src/features/catalogs/
    framework: React
    status: pending

    pages:
      - name: CatalogsPage
        file: apps/frontend/src/features/catalogs/pages/CatalogsPage.tsx
        rf: RF-CATALOG-001
        status: pending
        route: /catalogs

      - name: CatalogDetailPage
        file: apps/frontend/src/features/catalogs/pages/CatalogDetailPage.tsx
        rf: RF-CATALOG-002
        status: pending
        route: /catalogs/:id

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

dependencies:
  depends_on:
    - module: MGN-001
      type: hard
      reason: Autenticacion requerida
    - module: MGN-004
      type: hard
      reason: Aislamiento por tenant

  required_by:
    - module: MGN-010
      type: soft
      reason: Catalogos de monedas, tipos cuenta
    - module: MGN-011
      type: soft
      reason: Catalogos de unidades, categorias

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

metrics:
  story_points:
    estimated: 30
    actual: null

  files:
    database: 3
    backend: 8
    frontend: 6
    total: 17

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

history:
  - date: "2025-12-05"
    action: "Migracion a estructura GAMILIT"
    author: Requirements-Analyst
    changes:
      - "RF migrados de legacy a nueva estructura"
      - "Creacion de TRACEABILITY.yml"
