# TRACEABILITY.yml - MGN-010: Financial
# Matriz de trazabilidad: Documentacion -> Codigo
# Ubicacion: docs/02-fase-core-business/MGN-010-financial/implementacion/

epic_code: MGN-010
epic_name: Financial
phase: 2
phase_name: Core Business
story_points: 45
status: rf_documented

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

documentation:

  requirements:
    - id: RF-FIN-001
      title: Plan de Cuentas
      file: ../requerimientos/RF-FIN-001.md
      priority: P0
      story_points: 13
      status: documented
      traces_to:
        tables: [chart_of_accounts, accounts, account_balances]
        services: [ChartOfAccountsService, AccountsService]
        endpoints: [GET /api/v1/financial/charts, POST /api/v1/financial/charts/:id/accounts]

    - id: RF-FIN-002
      title: Monedas y Tipos de Cambio
      file: ../requerimientos/RF-FIN-002.md
      priority: P0
      story_points: 10
      status: documented
      traces_to:
        tables: [currencies, exchange_rates]
        services: [CurrenciesService, ExchangeRateService]
        endpoints: [GET /api/v1/financial/currencies, POST /api/v1/financial/currencies/convert]

    - id: RF-FIN-003
      title: Periodos Contables
      file: ../requerimientos/RF-FIN-003.md
      priority: P0
      story_points: 10
      status: documented
      traces_to:
        tables: [fiscal_years, fiscal_periods]
        services: [FiscalPeriodService]
        endpoints: [GET /api/v1/financial/fiscal-years, POST /api/v1/financial/periods/:id/close]

    - id: RF-FIN-004
      title: Asientos Contables
      file: ../requerimientos/RF-FIN-004.md
      priority: P0
      story_points: 13
      status: documented
      traces_to:
        tables: [journal_entries, journal_lines, cost_centers]
        services: [JournalService]
        endpoints: [GET /api/v1/financial/journal, POST /api/v1/financial/journal, POST /api/v1/financial/journal/:id/post]

  specifications: []
  # Pendiente de documentacion

  user_stories: []
  # Pendiente de documentacion

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

implementation:

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

    tables:
      - name: chart_of_accounts
        file: apps/database/ddl/schemas/core_financial/tables/chart_of_accounts.sql
        status: pending
        requirement: RF-FIN-001
        columns:
          - {name: id, type: UUID, pk: true}
          - {name: tenant_id, type: UUID, fk: tenants}
          - {name: code, type: VARCHAR(50)}
          - {name: name, type: VARCHAR(255)}
          - {name: description, type: TEXT}
          - {name: standard, type: VARCHAR(20)}
          - {name: base_currency_id, type: UUID, fk: currencies}
          - {name: is_active, type: BOOLEAN, default: true}
          - {name: created_at, type: TIMESTAMPTZ}
          - {name: updated_at, type: TIMESTAMPTZ}

      - name: accounts
        file: apps/database/ddl/schemas/core_financial/tables/accounts.sql
        status: pending
        requirement: RF-FIN-001
        columns:
          - {name: id, type: UUID, pk: true}
          - {name: chart_id, type: UUID, fk: chart_of_accounts}
          - {name: parent_id, type: UUID, fk: accounts, nullable: true}
          - {name: code, type: VARCHAR(50)}
          - {name: name, type: VARCHAR(255)}
          - {name: description, type: TEXT}
          - {name: account_type, type: VARCHAR(50)}
          - {name: nature, type: VARCHAR(10)}
          - {name: level, type: INTEGER}
          - {name: is_detail, type: BOOLEAN, default: true}
          - {name: is_active, type: BOOLEAN, default: true}
          - {name: currency_id, type: UUID, fk: currencies, nullable: true}
          - {name: tags, type: JSONB}
          - {name: created_at, type: TIMESTAMPTZ}
          - {name: updated_at, type: TIMESTAMPTZ}

      - name: account_balances
        file: apps/database/ddl/schemas/core_financial/tables/account_balances.sql
        status: pending
        requirement: RF-FIN-001
        columns:
          - {name: id, type: UUID, pk: true}
          - {name: account_id, type: UUID, fk: accounts}
          - {name: period_id, type: UUID, fk: fiscal_periods}
          - {name: opening_debit, type: "DECIMAL(18,4)", default: 0}
          - {name: opening_credit, type: "DECIMAL(18,4)", default: 0}
          - {name: movement_debit, type: "DECIMAL(18,4)", default: 0}
          - {name: movement_credit, type: "DECIMAL(18,4)", default: 0}
          - {name: closing_debit, type: "DECIMAL(18,4)", default: 0}
          - {name: closing_credit, type: "DECIMAL(18,4)", default: 0}
          - {name: balance, type: "DECIMAL(18,4)", default: 0}
          - {name: updated_at, type: TIMESTAMPTZ}

      - name: currencies
        file: apps/database/ddl/schemas/core_financial/tables/currencies.sql
        status: pending
        requirement: RF-FIN-002
        columns:
          - {name: id, type: UUID, pk: true}
          - {name: code, type: VARCHAR(3), unique: true}
          - {name: name, type: VARCHAR(100)}
          - {name: symbol, type: VARCHAR(10)}
          - {name: decimal_places, type: INTEGER, default: 2}
          - {name: decimal_separator, type: VARCHAR(1), default: "."}
          - {name: thousand_separator, type: VARCHAR(1), default: ","}
          - {name: symbol_position, type: VARCHAR(10), default: "before"}
          - {name: is_active, type: BOOLEAN, default: true}

      - name: exchange_rates
        file: apps/database/ddl/schemas/core_financial/tables/exchange_rates.sql
        status: pending
        requirement: RF-FIN-002
        columns:
          - {name: id, type: UUID, pk: true}
          - {name: tenant_id, type: UUID, fk: tenants}
          - {name: from_currency_id, type: UUID, fk: currencies}
          - {name: to_currency_id, type: UUID, fk: currencies}
          - {name: rate, type: "DECIMAL(18,8)"}
          - {name: inverse_rate, type: "DECIMAL(18,8)"}
          - {name: effective_date, type: DATE}
          - {name: source, type: VARCHAR(50)}
          - {name: created_at, type: TIMESTAMPTZ}

      - name: fiscal_years
        file: apps/database/ddl/schemas/core_financial/tables/fiscal_years.sql
        status: pending
        requirement: RF-FIN-003
        columns:
          - {name: id, type: UUID, pk: true}
          - {name: tenant_id, type: UUID, fk: tenants}
          - {name: name, type: VARCHAR(100)}
          - {name: code, type: VARCHAR(20)}
          - {name: start_date, type: DATE}
          - {name: end_date, type: DATE}
          - {name: status, type: VARCHAR(20)}
          - {name: closed_at, type: TIMESTAMPTZ}
          - {name: closed_by, type: UUID, fk: users}
          - {name: created_at, type: TIMESTAMPTZ}

      - name: fiscal_periods
        file: apps/database/ddl/schemas/core_financial/tables/fiscal_periods.sql
        status: pending
        requirement: RF-FIN-003
        columns:
          - {name: id, type: UUID, pk: true}
          - {name: fiscal_year_id, type: UUID, fk: fiscal_years}
          - {name: number, type: INTEGER}
          - {name: name, type: VARCHAR(50)}
          - {name: start_date, type: DATE}
          - {name: end_date, type: DATE}
          - {name: status, type: VARCHAR(20)}
          - {name: is_adjustment, type: BOOLEAN, default: false}
          - {name: closed_at, type: TIMESTAMPTZ}
          - {name: closed_by, type: UUID, fk: users}

      - name: journal_entries
        file: apps/database/ddl/schemas/core_financial/tables/journal_entries.sql
        status: pending
        requirement: RF-FIN-004
        columns:
          - {name: id, type: UUID, pk: true}
          - {name: tenant_id, type: UUID, fk: tenants}
          - {name: period_id, type: UUID, fk: fiscal_periods}
          - {name: entry_number, type: VARCHAR(50)}
          - {name: entry_date, type: DATE}
          - {name: description, type: TEXT}
          - {name: reference, type: VARCHAR(255)}
          - {name: source_type, type: VARCHAR(50)}
          - {name: source_id, type: UUID}
          - {name: status, type: VARCHAR(20)}
          - {name: reversed_entry_id, type: UUID, fk: journal_entries, nullable: true}
          - {name: posted_at, type: TIMESTAMPTZ}
          - {name: posted_by, type: UUID, fk: users}
          - {name: created_by, type: UUID, fk: users}
          - {name: created_at, type: TIMESTAMPTZ}
          - {name: updated_at, type: TIMESTAMPTZ}

      - name: journal_lines
        file: apps/database/ddl/schemas/core_financial/tables/journal_lines.sql
        status: pending
        requirement: RF-FIN-004
        columns:
          - {name: id, type: UUID, pk: true}
          - {name: entry_id, type: UUID, fk: journal_entries}
          - {name: line_number, type: INTEGER}
          - {name: account_id, type: UUID, fk: accounts}
          - {name: cost_center_id, type: UUID, fk: cost_centers, nullable: true}
          - {name: description, type: TEXT}
          - {name: debit, type: "DECIMAL(18,4)", default: 0}
          - {name: credit, type: "DECIMAL(18,4)", default: 0}
          - {name: currency_id, type: UUID, fk: currencies}
          - {name: exchange_rate, type: "DECIMAL(18,8)", default: 1}
          - {name: debit_base, type: "DECIMAL(18,4)", default: 0}
          - {name: credit_base, type: "DECIMAL(18,4)", default: 0}
          - {name: partner_id, type: UUID, nullable: true}
          - {name: tags, type: JSONB}
          - {name: reconciled, type: BOOLEAN, default: false}
          - {name: reconciled_at, type: TIMESTAMPTZ}

      - name: cost_centers
        file: apps/database/ddl/schemas/core_financial/tables/cost_centers.sql
        status: pending
        requirement: RF-FIN-004
        columns:
          - {name: id, type: UUID, pk: true}
          - {name: tenant_id, type: UUID, fk: tenants}
          - {name: parent_id, type: UUID, fk: cost_centers, nullable: true}
          - {name: code, type: VARCHAR(50)}
          - {name: name, type: VARCHAR(255)}
          - {name: level, type: INTEGER}
          - {name: is_active, type: BOOLEAN, default: true}
          - {name: created_at, type: TIMESTAMPTZ}
          - {name: updated_at, type: TIMESTAMPTZ}

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

    entities:
      - name: ChartOfAccounts
        file: apps/backend/src/modules/financial/entities/chart-of-accounts.entity.ts
        status: pending
        requirement: RF-FIN-001

      - name: Account
        file: apps/backend/src/modules/financial/entities/account.entity.ts
        status: pending
        requirement: RF-FIN-001

      - name: AccountBalance
        file: apps/backend/src/modules/financial/entities/account-balance.entity.ts
        status: pending
        requirement: RF-FIN-001

      - name: Currency
        file: apps/backend/src/modules/financial/entities/currency.entity.ts
        status: pending
        requirement: RF-FIN-002

      - name: ExchangeRate
        file: apps/backend/src/modules/financial/entities/exchange-rate.entity.ts
        status: pending
        requirement: RF-FIN-002

      - name: FiscalYear
        file: apps/backend/src/modules/financial/entities/fiscal-year.entity.ts
        status: pending
        requirement: RF-FIN-003

      - name: FiscalPeriod
        file: apps/backend/src/modules/financial/entities/fiscal-period.entity.ts
        status: pending
        requirement: RF-FIN-003

      - name: JournalEntry
        file: apps/backend/src/modules/financial/entities/journal-entry.entity.ts
        status: pending
        requirement: RF-FIN-004

      - name: JournalLine
        file: apps/backend/src/modules/financial/entities/journal-line.entity.ts
        status: pending
        requirement: RF-FIN-004

      - name: CostCenter
        file: apps/backend/src/modules/financial/entities/cost-center.entity.ts
        status: pending
        requirement: RF-FIN-004

    services:
      - name: ChartOfAccountsService
        file: apps/backend/src/modules/financial/chart-of-accounts.service.ts
        status: pending
        requirement: RF-FIN-001
        methods:
          - {name: create, description: Crear plan de cuentas}
          - {name: importTemplate, description: Importar desde template}
          - {name: getTree, description: Obtener arbol de cuentas}

      - name: AccountsService
        file: apps/backend/src/modules/financial/accounts.service.ts
        status: pending
        requirement: RF-FIN-001
        methods:
          - {name: create, description: Crear cuenta}
          - {name: getBalance, description: Obtener saldo de cuenta}
          - {name: validateCode, description: Validar codigo de cuenta}

      - name: CurrenciesService
        file: apps/backend/src/modules/financial/currencies.service.ts
        status: pending
        requirement: RF-FIN-002
        methods:
          - {name: getActive, description: Obtener monedas activas}
          - {name: convert, description: Convertir moneda}
          - {name: format, description: Formatear monto}

      - name: ExchangeRateService
        file: apps/backend/src/modules/financial/exchange-rate.service.ts
        status: pending
        requirement: RF-FIN-002
        methods:
          - {name: getRate, description: Obtener tipo de cambio}
          - {name: setRate, description: Registrar tipo de cambio}
          - {name: getHistory, description: Obtener historial de tasas}

      - name: FiscalPeriodService
        file: apps/backend/src/modules/financial/fiscal-period.service.ts
        status: pending
        requirement: RF-FIN-003
        methods:
          - {name: createYear, description: Crear año fiscal}
          - {name: closePeriod, description: Cerrar periodo}
          - {name: closeYear, description: Cerrar año fiscal}
          - {name: canPostToDate, description: Validar fecha para contabilizar}

      - name: JournalService
        file: apps/backend/src/modules/financial/journal.service.ts
        status: pending
        requirement: RF-FIN-004
        methods:
          - {name: create, description: Crear asiento}
          - {name: validate, description: Validar asiento}
          - {name: post, description: Mayorizar asiento}
          - {name: reverse, description: Reversar asiento}

    controllers:
      - name: ChartOfAccountsController
        file: apps/backend/src/modules/financial/controllers/chart-of-accounts.controller.ts
        status: pending
        endpoints:
          - method: GET
            path: /api/v1/financial/charts
            description: Listar planes de cuentas
            requirement: RF-FIN-001

          - method: POST
            path: /api/v1/financial/charts
            description: Crear plan de cuentas
            requirement: RF-FIN-001

          - method: GET
            path: /api/v1/financial/charts/:id/accounts
            description: Obtener arbol de cuentas
            requirement: RF-FIN-001

          - method: POST
            path: /api/v1/financial/charts/:id/accounts
            description: Crear cuenta
            requirement: RF-FIN-001

          - method: GET
            path: /api/v1/financial/accounts/:id/balance
            description: Obtener saldo de cuenta
            requirement: RF-FIN-001

      - name: CurrenciesController
        file: apps/backend/src/modules/financial/controllers/currencies.controller.ts
        status: pending
        endpoints:
          - method: GET
            path: /api/v1/financial/currencies
            description: Listar monedas
            requirement: RF-FIN-002

          - method: GET
            path: /api/v1/financial/currencies/:code/rates
            description: Obtener historial de tasas
            requirement: RF-FIN-002

          - method: POST
            path: /api/v1/financial/currencies/:code/rates
            description: Registrar tipo de cambio
            requirement: RF-FIN-002

          - method: POST
            path: /api/v1/financial/currencies/convert
            description: Convertir moneda
            requirement: RF-FIN-002

      - name: FiscalPeriodsController
        file: apps/backend/src/modules/financial/controllers/fiscal-periods.controller.ts
        status: pending
        endpoints:
          - method: GET
            path: /api/v1/financial/fiscal-years
            description: Listar años fiscales
            requirement: RF-FIN-003

          - method: POST
            path: /api/v1/financial/fiscal-years
            description: Crear año fiscal
            requirement: RF-FIN-003

          - method: GET
            path: /api/v1/financial/fiscal-years/:id/periods
            description: Obtener periodos del año
            requirement: RF-FIN-003

          - method: POST
            path: /api/v1/financial/periods/:id/close
            description: Cerrar periodo
            requirement: RF-FIN-003

      - name: JournalController
        file: apps/backend/src/modules/financial/controllers/journal.controller.ts
        status: pending
        endpoints:
          - method: GET
            path: /api/v1/financial/journal
            description: Listar asientos
            requirement: RF-FIN-004

          - method: POST
            path: /api/v1/financial/journal
            description: Crear asiento
            requirement: RF-FIN-004

          - method: GET
            path: /api/v1/financial/journal/:id
            description: Obtener asiento
            requirement: RF-FIN-004

          - method: POST
            path: /api/v1/financial/journal/:id/post
            description: Mayorizar asiento
            requirement: RF-FIN-004

          - method: POST
            path: /api/v1/financial/journal/:id/reverse
            description: Reversar asiento
            requirement: RF-FIN-004

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

dependencies:
  depends_on:
    - module: MGN-001
      type: hard
      reason: Autenticacion requerida
    - module: MGN-004
      type: hard
      reason: Aislamiento por tenant
    - module: MGN-005
      type: soft
      reason: Catalogos de monedas, tipos cuenta

  required_by:
    - module: FINANCIAL_VERTICALS
      type: hard
      reason: Base para facturacion, CxC, CxP, tesoreria

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

metrics:
  story_points:
    estimated: 45
    actual: null

  documentation:
    requirements: 4
    specifications: 0
    user_stories: 0

  files:
    database: 10
    backend: 20
    frontend: 10
    total: 40

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

history:
  - date: "2025-12-05"
    action: "Creacion de estructura GAMILIT"
    author: Requirements-Analyst
    changes:
      - "Creacion de TRACEABILITY.yml"
      - "Definicion de estructura base"

  - date: "2025-12-05"
    action: "Documentacion de RF"
    author: Requirements-Analyst
    changes:
      - "RF-FIN-001: Plan de Cuentas"
      - "RF-FIN-002: Monedas y Tipos de Cambio"
      - "RF-FIN-003: Periodos Contables"
      - "RF-FIN-004: Asientos Contables"
      - "Actualizacion de trazabilidad RF -> implementacion"