# Ontología de Distribuidora Corvana — fuente única de verdad.
# Las definiciones en prosa son para las personas; las reglas, para los sistemas y la IA.
# Viven juntas para que no puedan separarse. El motor (engine/) interpreta las reglas.

meta:
  name: Ontología de Distribuidora Corvana
  version: 1.0.0
  date: 2026-10-30
  status: vigente
  owner: gerenteFinanciera
  fiction: Empresa, personas, sistemas y cifras inventados para esta demostración.

roles:
  - { id: gerenteGeneral, label: Gerente general, person: Martín Bustamante }
  - { id: gerenteFinanciera, label: Gerente financiera, person: Liliana Peñaranda }
  - { id: directorComercial, label: Director comercial, person: Hernán Cuello }
  - { id: contador, label: Contador, person: Ricardo Montes }
  - { id: jefeCartera, label: Jefe de cartera, person: Yolanda Ariza }
  - { id: coordinadorTi, label: Coordinador de TI, person: Andrés Pacheco }

relationTypes:
  - { id: perteneceA, label: pertenece a, inverse: tiene }
  - { id: refiereA, label: se refiere a, inverse: es referido por }
  - { id: generadaPor, label: es generado por, inverse: genera }
  - { id: agrupa, label: agrupa, inverse: está agrupado en }
  - { id: derivaDe, label: se calcula a partir de, inverse: alimenta }
  - { id: resta, label: resta, inverse: se resta de }
  - { id: seRigePor, label: se rige por, inverse: rige }
  - { id: limita, label: fija el objetivo de, inverse: tiene como objetivo }

# ── 16 conceptos ──────────────────────────────────────────────────────────────
concepts:
  # Transacción
  - id: pedido
    label: Pedido
    group: transaccion
    kind: entity
    data: pedido
    owner: directorComercial
    definition: >-
      Solicitud de compra que el vendedor de preventa toma en el punto de venta. Su valor
      incluye IVA y se ubica en el periodo por la fecha en que se toma.
    relations:
      - { type: perteneceA, concept: puntoVenta }
      - { type: refiereA, concept: vendedor }
    notes:
      - Un pedido puede quedar tomado, anulado o rechazado por cupo. El estado lo decide el ERP; la app de preventa no se entera.

  - id: lineaPedido
    label: Línea de pedido
    group: transaccion
    kind: entity
    data: lineaPedido
    owner: directorComercial
    definition: >-
      Un producto dentro de un pedido, con la cantidad pedida y la cantidad despachada.
      La diferencia entre las dos es el faltante por agotado.
    relations:
      - { type: perteneceA, concept: pedido }
      - { type: seRigePor, concept: tratamientoIva }

  - id: factura
    label: Factura electrónica
    group: transaccion
    kind: entity
    data: factura
    owner: contador
    definition: >-
      Documento validado por la DIAN que se emite al despachar un pedido, a nombre de un
      tercero y con la fecha del despacho. Registra el valor despachado sin IVA y el IVA aparte.
    relations:
      - { type: generadaPor, concept: pedido }
      - { type: refiereA, concept: tercero }
      - { type: seRigePor, concept: periodoYCorte }
    notes:
      - Una factura electrónica no se anula; se corrige con una nota crédito.

  - id: notaCredito
    label: Nota crédito
    group: transaccion
    kind: entity
    data: notaCredito
    owner: contador
    definition: >-
      Documento que reduce el valor de una factura ya emitida, por devolución, avería o
      descuento comercial. Cuenta en el periodo de su propia fecha.
    relations:
      - { type: refiereA, concept: factura }
      - { type: generadaPor, concept: devolucion }
    decisions: [D-002]

  - id: devolucion
    label: Devolución
    group: transaccion
    kind: entity
    data: devolucion
    owner: contador
    definition: >-
      Mercancía que el cliente regresa, total o parcialmente, al recibirla o después, por
      rechazo, avería o vencimiento. Origina una nota crédito, que puede emitirse días más tarde.
    relations:
      - { type: refiereA, concept: factura }

  # Medida
  - id: ventaFacturada
    label: Venta facturada
    group: medida
    kind: measure
    owner: contador
    unit: COP
    definition: >-
      Suma de las facturas electrónicas emitidas en el mes, antes de notas crédito. Se expresa {importe}.
    rule:
      op: sum
      terms:
        - source: factura
          value: $importe
          date: fechaFactura
          period: { month: 0 }
    params:
      importe: &importe
        label: Tratamiento de IVA
        default: subtotal
        options:
          - { value: subtotal, texto: sin IVA }
          - { value: total, texto: con IVA }
    relations:
      - { type: derivaDe, concept: factura }
      - { type: seRigePor, concept: tratamientoIva }
      - { type: seRigePor, concept: periodoYCorte }

  - id: ventaNeta
    label: Venta neta
    group: medida
    kind: measure
    owner: gerenteFinanciera
    unit: COP
    definition: >-
      Venta facturada del mes menos las notas crédito {fechaNotas}. Se expresa {importe}. Es la
      «venta» sin calificativo.
    rule:
      op: sum
      terms:
        - ref: ventaFacturada
        - sign: -1
          source: notaCredito
          value: $importe
          date: $fechaNotas
          period: { month: 0 }
    params:
      importe: *importe
      fechaNotas:
        label: Periodo de las notas crédito
        default: fechaNota
        options:
          - { value: fechaNota, texto: "emitidas en ese mismo mes, aunque se refieran a facturas de meses anteriores" }
          - { value: factura.fechaFactura, texto: "de las facturas emitidas en ese mes, sin importar cuándo se emitió la nota" }
    relations:
      - { type: derivaDe, concept: ventaFacturada }
      - { type: resta, concept: notaCredito }
    decisions: [D-001, D-002]

  - id: recaudo
    label: Recaudo
    group: medida
    kind: measure
    owner: jefeCartera
    unit: COP
    definition: >-
      Dinero recibido de los clientes en el mes, con IVA, aplicado a facturas de cualquier
      mes. Mide caja, no venta.
    rule:
      op: sum
      terms:
        - source: recaudo
          value: valor
          date: fechaPago
          period: { month: 0 }
    relations:
      - { type: refiereA, concept: factura }
      - { type: refiereA, concept: tercero }
    decisions: [D-004]

  - id: metaComercial
    label: Meta comercial
    group: medida
    kind: measure
    owner: gerenteGeneral
    unit: COP
    definition: >-
      Venta neta sin IVA que la junta directiva aprueba para cada mes en el presupuesto. Las
      cuotas de pedidos de los vendedores se derivan de ella con una regla escrita.
    rule:
      op: sum
      terms:
        - source: meta
          value: valor
          date: mes
          period: { month: 0 }
    relations:
      - { type: limita, concept: ventaNeta }
      - { type: refiereA, concept: vendedor }
    decisions: [D-003, D-004]

  # Reglas transversales
  - id: periodoYCorte
    label: Periodo y corte
    group: reglasTransversales
    kind: rule
    owner: gerenteFinanciera
    definition: >-
      Un periodo es un mes calendario en hora de Colombia. Cada medida declara qué fecha la
      ubica en el periodo; el corte es la frontera entre dos meses.
    policy:
      zonaHoraria: America/Bogota
      granularidad: mes
      ventanasInclusivas: true
    notes:
      - Un pedido del 30 de septiembre que se despacha el 1 de octubre es pedido de septiembre y factura de octubre. Las dos cosas son ciertas.

  - id: tratamientoIva
    label: Tratamiento de IVA
    group: reglasTransversales
    kind: rule
    owner: contador
    definition: >-
      La venta se expresa sin IVA: el IVA se recauda para la DIAN y no es ingreso de la
      empresa. Toda cifra con IVA debe decirlo en su nombre.
    policy:
      tarifas: 0 %, 5 % y 19 %
      redondeo: por línea, al peso, mitad hacia arriba
    notes:
      - Las tarifas por producto son ilustrativas; no reemplazan el estatuto tributario.

  # Identidad
  - id: tercero
    label: Tercero
    group: identidad
    kind: identity
    data: tercero
    owner: contador
    definition: >-
      Persona natural o jurídica identificada ante la DIAN por cédula o NIT. Es a quien se
      factura y a quien se otorga crédito.
    policy:
      deduplicacion: raíz del NIT (sin dígito de verificación)
    relations:
      - { type: agrupa, concept: puntoVenta }
    decisions: [D-006]
    notes:
      - El NIT de una persona natural es su cédula más el dígito de verificación; por eso cédula y NIT de la misma persona tienen la misma raíz.

  - id: puntoVenta
    label: Punto de venta
    group: identidad
    kind: identity
    data: puntoVenta
    owner: directorComercial
    definition: >-
      Lugar físico que el vendedor visita y al que se despacha. Pertenece a un tercero; una
      cadena es un tercero con muchos puntos de venta.
    relations:
      - { type: perteneceA, concept: tercero }
      - { type: refiereA, concept: vendedor }
    decisions: [D-005]

  - id: clienteActivo
    label: Cliente activo
    group: identidad
    kind: identity
    owner: gerenteFinanciera
    unit: conteo
    definition: >-
      Tercero, {deduplicar}, con al menos una factura en los últimos {ventanaDias} días. Un punto
      de venta no es un cliente.
    rule:
      op: count
      entity: tercero
      key: $deduplicar
      where:
        - exists:
            source: factura
            via: tercero
            date: fechaFactura
            period: { window: $ventanaDias }
    params:
      deduplicar:
        label: Unificar terceros por NIT
        default: nitRaiz
        options:
          - { value: nitRaiz, texto: unificado por la raíz de su NIT }
          - { value: id, texto: "contado tal como está registrado, sin unificar" }
      ventanaDias: { label: Ventana en días, min: 30, max: 120, step: 15, default: 90 }
    relations:
      - { type: derivaDe, concept: tercero }
      - { type: derivaDe, concept: factura }
    decisions: [D-005, D-006]

  - id: cupo
    label: Cupo de crédito
    group: identidad
    kind: identity
    data: cupo
    owner: jefeCartera
    definition: >-
      Monto máximo y plazo de pago que la empresa otorga a un tercero. Plazo cero es contado;
      un cupo activo tiene plazo de 30 o 60 días.
    relations:
      - { type: perteneceA, concept: tercero }

  - id: vendedor
    label: Vendedor
    group: identidad
    kind: identity
    data: vendedor
    owner: directorComercial
    definition: >-
      Persona de la fuerza de preventa que visita puntos de venta y toma pedidos en una sede.
    notes:
      - Las comisiones se pagan sobre pedidos. La regla se menciona; la nómina no se modela.

# ── Sistemas: qué campo de cada sistema corresponde a qué concepto ───────────
systems:
  - id: preventa
    label: App de preventa
    owner: directorComercial
    description: >-
      App móvil donde los vendedores registran visitas y toman pedidos. Es la única fuente con
      API lista, y por eso la que alimenta al asistente de IA.
    fields:
      - { field: COD_PUNTO, concept: puntoVenta, path: puntoVenta.codigo, unit: texto }
      - { field: COD_VENDEDOR, concept: vendedor, path: vendedor.codigo, unit: texto }
      - { field: FEC_VISITA, concept: puntoVenta, path: visita.fechaVisita, unit: fecha, note: "La visita no es concepto de la ontología; solo cuenta qué puntos se visitaron." }
      - { field: FEC_PEDIDO, concept: pedido, path: pedido.fechaPedido, unit: fecha }
      - { field: CANT_PEDIDA, concept: lineaPedido, path: lineaPedido.cantidadPedida, unit: conteo }
      - { field: VLR_PEDIDO, concept: pedido, path: pedido.valorConIva, unit: COP, iva: incluido, note: "Valor pedido con IVA, cualquiera que sea el estado final." }

  - id: erp
    label: ERP (facturación electrónica)
    owner: contador
    description: >-
      Sistema contable y de facturación electrónica. Registra terceros por NIT o cédula,
      decide el estado de los pedidos y emite facturas y notas crédito.
    fields:
      - { field: NIT_TERCERO, concept: tercero, path: tercero.documento, unit: texto, note: "Con o sin dígito de verificación, según quién lo digitó." }
      - { field: EST_PEDIDO, concept: pedido, path: pedido.estado, unit: texto, note: "tomado, anulado o rechazado por cupo." }
      - { field: CANT_DESPACHADA, concept: lineaPedido, path: lineaPedido.cantidadDespachada, unit: conteo }
      - { field: NUM_FACTURA, concept: factura, path: factura.numero, unit: texto }
      - { field: FEC_FACTURA, concept: factura, path: factura.fechaFactura, unit: fecha }
      - { field: VLR_BRUTO, concept: ventaFacturada, path: factura.subtotal, unit: COP, iva: excluido }
      - { field: VLR_IVA, concept: tratamientoIva, path: factura.iva, unit: COP }
      - { field: VLR_TOTAL, concept: factura, path: factura.total, unit: COP, iva: incluido }
      - { field: FEC_VENCE, concept: cupo, path: factura.fechaVencimiento, unit: fecha, note: "Fecha de factura más el plazo del cupo." }
      - { field: NUM_NOTA, concept: notaCredito, path: notaCredito.numero, unit: texto }
      - { field: FEC_NOTA, concept: notaCredito, path: notaCredito.fechaNota, unit: fecha }
      - { field: MOTIVO_NOTA, concept: notaCredito, path: notaCredito.motivo, unit: texto }
      - { field: VLR_TOTAL_NOTA, concept: notaCredito, path: notaCredito.total, unit: COP, iva: incluido }
      - { field: VLR_NOTA, concept: ventaNeta, path: notaCredito.subtotal, unit: COP, iva: excluido, note: "Se resta en el mes de la nota (D-002)." }
      - { field: FEC_DEVOLUCION, concept: devolucion, path: devolucion.fechaDevolucion, unit: fecha }

  - id: cartera
    label: Cartera (Excel)
    owner: jefeCartera
    description: >-
      Libro de Excel donde cartera registra cupos, pagos y mora por cliente. Cada fila es un
      tercero tal como se digitó.
    fields:
      - { field: NIT, concept: tercero, path: cupo.documentoCartera, unit: texto, note: "Texto libre, con puntos, guiones o espacios." }
      - { field: CUPO, concept: cupo, path: cupo.monto, unit: COP }
      - { field: PLAZO, concept: cupo, path: cupo.plazo, unit: dias }
      - { field: ESTADO CUPO, concept: cupo, path: cupo.estado, unit: texto }
      - { field: DIAS MORA, concept: cupo, path: tercero.diasMoraMax, unit: dias }
      - { field: FACTURA, concept: factura, path: recaudo.factura.numero, unit: texto, note: "Número de la factura que paga, tal como lo anota cartera." }
      - { field: FECHA PAGO, concept: recaudo, path: recaudo.fechaPago, unit: fecha }
      - { field: VALOR PAGADO, concept: recaudo, path: recaudo.valor, unit: COP, iva: incluido }

  - id: powerbi
    label: Power BI
    owner: coordinadorTi
    description: >-
      Dos tableros con una medida llamada «Ventas» en cada uno: el comercial lee la app de
      preventa; el financiero lee el ERP.
    reads: [preventa, erp]
    fields:
      - { field: Comercial · Ventas, concept: pedido, path: pedido.valorConIva, unit: COP, iva: incluido, note: "Lee VLR_PEDIDO de preventa." }
      - { field: Financiero · Ventas, concept: ventaFacturada, path: factura.subtotal, unit: COP, iva: excluido, note: "Lee VLR_BRUTO del ERP. Mismo nombre, otro concepto." }

  - id: asistente
    label: Asistente de IA (Teams)
    owner: coordinadorTi
    description: >-
      Responde preguntas de la gerencia. Conectado solo a la app de preventa, la única fuente
      con API lista en agosto.
    reads: [preventa]
    fields:
      - { field: ventas_mes, concept: pedido, path: pedido.valorConIva, unit: COP, iva: incluido }
      - { field: clientes_activos, concept: puntoVenta, unit: conteo, note: "Cuenta puntos visitados." }

# ── Lentes: la definición implícita de cada sistema, en el mismo lenguaje ────
lenses:
  - id: ventaSegunPreventa
    system: preventa
    defendedBy: directorComercial
    usedBy: [asistente, powerbi]
    word: venta
    label: Pedidos tomados (con IVA)
    measures: pedido
    definition: Valor de los pedidos tomados en el mes, con IVA, en cualquier estado.
    rule:
      op: sum
      terms:
        - source: pedido
          value: valorConIva
          date: fechaPedido
          period: { month: 0 }
    notes:
      - Sin filtro de estado, porque la app no se entera de anulaciones ni rechazos; esos viven en el ERP.
      - Es la cifra correcta para comisiones, que se pagan sobre pedidos.

  - id: ventaSegunErp
    system: erp
    defendedBy: contador
    usedBy: [powerbi]
    word: venta
    label: Venta facturada ({importe})
    measures: ventaFacturada
    definition: Facturas electrónicas emitidas en el mes, {importe}, antes de notas crédito.
    rule:
      op: sum
      terms:
        - ref: ventaFacturada
    notes:
      - Es la cifra que se reporta a la DIAN por facturación del mes.

  - id: ventaSegunCierre
    system: erp
    defendedBy: gerenteFinanciera
    word: venta
    label: Venta neta ({importe})
    measures: ventaNeta
    definition: Venta facturada menos las notas crédito {fechaNotas}, {importe}.
    rule:
      op: sum
      terms:
        - ref: ventaNeta
    notes:
      - La gerencia financiera la arma con el ERP y ajustes en Excel; las definiciones acordadas la adoptaron como «venta» sin calificativo (D-001).

  - id: ventaSegunCartera
    system: cartera
    defendedBy: jefeCartera
    word: venta
    label: Recaudo (con IVA)
    measures: recaudo
    definition: Dinero recibido en el mes, con IVA, de facturas de cualquier mes.
    rule:
      op: sum
      terms:
        - ref: recaudo
    notes:
      - Es la cifra correcta para caja; la mayor parte viene de facturas de meses anteriores.

  - id: clienteActivoSegunPreventa
    system: preventa
    defendedBy: directorComercial
    usedBy: [asistente]
    word: clienteActivo
    label: Puntos visitados en 90 días
    measures: puntoVenta
    definition: Puntos de venta visitados al menos una vez en los últimos 90 días, compraran o no.
    rule:
      op: count
      entity: puntoVenta
      where:
        - exists:
            source: visita
            via: puntoVenta
            date: fechaVisita
            period: { window: 90 }
    notes:
      - Una cadena de doce tiendas cuenta doce.

  - id: clienteActivoSegunErp
    system: erp
    defendedBy: contador
    word: clienteActivo
    label: Terceros facturados en 90 días
    measures: tercero
    definition: Registros de tercero (NIT o cédula, tal como están en el ERP) con al menos una factura en los últimos 90 días.
    rule:
      op: count
      entity: tercero
      key: id
      where:
        - exists:
            source: factura
            via: tercero
            date: fechaFactura
            period: { window: 90 }
    notes:
      - Un mismo cliente registrado dos veces (con y sin dígito de verificación, o con cédula y con NIT) cuenta dos.

  - id: clienteActivoSegunCartera
    system: cartera
    defendedBy: jefeCartera
    word: clienteActivo
    label: Terceros con cupo activo y sin mora mayor a 60 días
    measures: cupo
    definition: Filas de cartera con cupo activo a crédito y sin facturas vencidas hace más de 60 días.
    rule:
      op: count
      entity: tercero
      where:
        - { field: cupo.estado, in: [activo] }
        - { field: cupo.plazo, gte: 1 }
        - { field: diasMoraMax, lte: 60 }
    notes:
      - No mira si el cliente compró; mira si se le puede vender a crédito. Los clientes de contado no aparecen.

# ── Conciliaciones: pasos calculados desde los registros, con puntos de control ─
reconciliations:
  - id: puenteVenta
    label: De pedidos tomados a venta neta
    owner: gerenteFinanciera
    description: >-
      Cada paso se calcula desde los registros, no por diferencia. Los puntos de control se
      calculan aparte con la regla del concepto y deben coincidir al peso.
    steps:
      - id: pedidosTomados
        label: Pedidos tomados en el mes, con IVA (todos los estados)
        explanation: "Lo que los vendedores anotaron en la app: el pedido completo, con IVA, se haya entregado o no."
        source: pedido
        value: valorConIva
        date: fechaPedido
        period: { month: 0 }
      - id: ivaPedidos
        label: IVA incluido en esos pedidos
        explanation: "El IVA no es venta: es un impuesto que la empresa recauda para la DIAN."
        sign: -1
        source: pedido
        value: iva
        date: fechaPedido
        period: { month: 0 }
      - id: anuladosRechazados
        label: Pedidos anulados o rechazados por cupo (sin IVA)
        explanation: "Pedidos que nunca salieron: el cliente los canceló o el ERP los frenó porque el cliente no tenía cupo de crédito."
        sign: -1
        source: pedido
        value: valorSinIva
        date: fechaPedido
        period: { month: 0 }
        where: [{ field: estado, in: [anulado, rechazadoCupo] }]
      - id: agotados
        label: Faltantes por agotado (sin IVA)
        explanation: "Lo que se pidió pero no había en bodega el día del despacho."
        sign: -1
        source: pedido
        value: valorAgotadoSinIva
        date: fechaPedido
        period: { month: 0 }
        where: [{ field: estado, in: [tomado] }]
      - id: corteSalida
        label: Pedidos del mes facturados el mes siguiente (sin IVA)
        explanation: "Pedidos del 29 y 30 de septiembre que se despacharon, y por tanto se facturaron, ya en octubre."
        sign: -1
        source: pedido
        value: valorDespachadoSinIva
        date: fechaPedido
        period: { month: 0 }
        where: [{ field: factura.fechaFactura, period: { month: { gte: 1 } } }]
      - id: corteEntrada
        label: Pedidos del mes anterior facturados en este mes (sin IVA)
        explanation: "Al revés: pedidos de los últimos días de agosto que se facturaron en septiembre."
        source: pedido
        value: valorDespachadoSinIva
        date: fechaPedido
        period: { month: { lte: -1 } }
        where: [{ field: factura.fechaFactura, period: { month: 0 } }]
      - checkpoint: ventaFacturada
        label: Venta facturada
        explanation: "Lo que facturó la empresa en septiembre: la cifra del contador."
      - id: devolucionesAverias
        label: Notas crédito del mes por devolución y avería
        explanation: "Mercancía que los clientes devolvieron o reportaron dañada: la factura se corrige con una nota crédito."
        sign: -1
        source: notaCredito
        value: subtotal
        date: fechaNota
        period: { month: 0 }
        where: [{ field: motivo, in: [devolucion, averia] }]
      - id: descuentosComerciales
        label: Notas crédito del mes por descuentos comerciales posteriores
        explanation: "Descuentos por volumen y ajustes de precio que se dan después de facturar, también con nota crédito."
        sign: -1
        source: notaCredito
        value: subtotal
        date: fechaNota
        period: { month: 0 }
        where: [{ field: motivo, in: [descuentoComercial] }]
      - checkpoint: ventaNeta
        label: Venta neta
        explanation: "Lo que de verdad se vendió en septiembre: la cifra del cierre de la gerencia financiera."

  - id: composicionRecaudo
    label: Recaudo del mes según el mes de la factura
    owner: jefeCartera
    description: >-
      El dinero que entra en un mes paga, sobre todo, facturas de meses anteriores.
    steps:
      - id: recaudoFacturasDelMes
        label: De facturas del mismo mes (sobre todo contado)
        source: recaudo
        value: valor
        date: fechaPago
        period: { month: 0 }
        where: [{ field: factura.fechaFactura, period: { month: 0 } }]
      - id: recaudoMesAnterior
        label: De facturas del mes anterior
        source: recaudo
        value: valor
        date: fechaPago
        period: { month: 0 }
        where: [{ field: factura.fechaFactura, period: { month: -1 } }]
      - id: recaudoMesesPrevios
        label: De facturas de dos o más meses atrás
        source: recaudo
        value: valor
        date: fechaPago
        period: { month: 0 }
        where: [{ field: factura.fechaFactura, period: { month: { lte: -2 } } }]
      - checkpoint: recaudo
        label: Recaudo del mes

# ── Decisiones de gobierno ───────────────────────────────────────────────────
decisions:
  - id: D-001
    date: 2026-10-30
    decided_by: gerenteGeneral
    concerns: [ventaNeta, ventaFacturada, pedido, recaudo]
    decision: «Venta» sin calificativo significa venta neta, sin IVA, por fecha de factura.
    rationale: >-
      Es la cifra del cierre contable y la base en que la junta aprobó la meta. Las otras tres
      cifras siguen siendo correctas, pero con su propio nombre: pedidos tomados, venta
      facturada y recaudo.

  - id: D-002
    date: 2026-10-30
    decided_by: gerenteFinanciera
    concerns: [notaCredito, ventaNeta]
    decision: Las notas crédito cuentan en el periodo de la fecha de la nota, aunque se refieran a una factura de un mes anterior.
    rationale: >-
      Un mes cerrado no se reabre: imputar la nota al mes de la factura cambiaría cifras ya
      reportadas a la junta y a la DIAN. La alternativa queda disponible como parámetro de
      análisis, no para el reporte.

  - id: D-003
    date: 2026-10-30
    decided_by: gerenteGeneral
    concerns: [metaComercial, pedido, vendedor]
    decision: >-
      La meta se fija en venta neta sin IVA. Las cuotas de pedidos de los vendedores se
      derivan de ella: cuota con IVA = meta × (1 + IVA efectivo) ÷ (1 − pérdida histórica
      entre pedido y venta neta), con tasas que publica finanzas cada trimestre.
    rationale: >-
      Antes, la junta aprobaba la meta en venta neta y comercial la repartía como cuota de
      pedidos con IVA, sin regla escrita. Las dos cifras se comparaban como si fueran la misma.

  - id: D-004
    date: 2026-10-30
    decided_by: gerenteFinanciera
    concerns: [recaudo, metaComercial]
    decision: El recaudo nunca se compara contra la meta comercial.
    rationale: >-
      El recaudo de un mes paga sobre todo facturas de meses anteriores; compararlo con la
      meta del mes mezcla caja con venta.

  - id: D-005
    date: 2026-10-30
    decided_by: gerenteGeneral
    concerns: [clienteActivo, tercero, puntoVenta]
    decision: >-
      Cliente activo es un tercero, unificado por la raíz del NIT, con al menos una factura en
      los últimos 90 días. Los puntos de venta son un concepto aparte, no clientes.
    rationale: >-
      A quien se le factura y se le da crédito es al tercero. Contar puntos sirve para planear
      rutas, no para saber cuántos clientes hay.

  - id: D-006
    date: 2026-10-30
    decided_by: contador
    concerns: [tercero, clienteActivo, cupo]
    decision: >-
      La cédula y el NIT de una misma persona natural son el mismo tercero. La S.A.S. que
      constituye un tendero es un tercero distinto: se marca como posible duplicado, no se unifica.
    rationale: >-
      La S.A.S. es otra persona jurídica, con otro riesgo de crédito y otras obligaciones
      tributarias. Unificarla por parecido sería una decisión comercial disfrazada de limpieza
      de datos.

out_of_scope:
  - { item: Inventario y compras a fabricantes, reason: "Los agotados se simulan como faltantes en el despacho; no se modela de dónde vienen." }
  - { item: Margen por producto, reason: "La pregunta es cuánto se vendió, no cuánto se ganó." }
  - { item: Logística de rutas, reason: "Las rutas solo fijan el día de visita y el rezago de despacho." }
  - { item: Nómina y comisiones, reason: "La regla de comisión sobre pedidos se menciona; no se calcula." }
  - { item: Presupuesto completo, reason: "Solo se usa la meta mensual de venta neta." }
  - { item: Retenciones en la fuente, reason: "Algunos clientes retienen parte del pago; aquí el recaudo es el valor aplicado completo." }
  - { item: Impuesto a bebidas azucaradas y ultraprocesados, reason: "Solo se modela el IVA." }
  - { item: Consignaciones sin identificar, reason: "Todo pago se aplica a una factura el día en que llega." }

changelog:
  - version: 1.0.0
    date: 2026-10-30
    summary: Primera versión vigente. 16 conceptos, cinco sistemas mapeados, siete lentes y seis decisiones.
