FactuGES_ERP/docs/documentation-ssot-audit.md

# Auditoría documental SSOT

Fecha de actualización: 2026-08-26

## Objetivo

Fijar una lectura única y consistente de la documentación técnica del ERP para
evitar que documentos históricos, propuestas o secciones parcialmente superadas
se interpreten como contrato vigente.

Estados usados en esta auditoría:

- `CURRENT`: fuente canónica vigente.
- `PARTIALLY SUPERSEDED`: documento útil, pero con secciones ya superadas.
- `SUPERSEDED`: documento conservado por trazabilidad, pero no vigente.
- `PROPOSAL`: diseño o dirección futura aún no implantada.
- `HISTORICAL`: contexto, migración o auditoría de un estado anterior.

## Reglas transversales

- Si un área tiene SSOT explícito, el resto de documentos deben enlazarlo y no duplicar semántica.
- Un objetivo futuro no debe presentarse como comportamiento operativo actual.
- En `customer-invoices`, el estado vigente es:
  - `IssuedInvoice` no tiene `verifactuPolicy` como requisito actual.
  - La cardinalidad vigente es `IssuedInvoice 1 -> 0..1 VerifactuRecord`.
  - La dirección futura deseada es `IssuedInvoice 1 -> 0..N VerifactuRecord`.

## Referencia canónica por bounded context

### `identity`

Estado del contexto: `CURRENT`

Referencias canónicas:

- `docs/architecture/README.md`
- `docs/architecture/tenant-context.md`
- `docs/architecture/identity-auth-api.md`
- `docs/architecture/identity-and-companies.md`
- `docs/architecture/identity-migration-status.md`

Documentos a vigilar:

- `docs/architecture/identity-backend-architecture.md`
  Clasificación: `PARTIALLY SUPERSEDED`
  Acción: mantener como nota complementaria y no como contrato operativo principal.

### `companies`

Estado del contexto: `CURRENT`

Referencias canónicas:

- `docs/companies/company-requirements.md`
- `docs/architecture/identity-and-companies.md`
- `modules/companies/README.md`

Documentos a vigilar:

- Cualquier documento que presente datos de empresa dentro de `identity` como ownership de negocio.
  Acción: enlazar a `identity-and-companies.md`.

### `settings` (shell frontend transversal)

Estado del contexto: `CURRENT`

Referencias canónicas:

- `docs/settings/frontend-erp-settings-system-design.md`
- `docs/settings/frontend-erp-settings-module-integration-design.md`

Documentos a vigilar:

- Cualquier diseño de módulo que describa el shell de Settings con comportamiento distinto al sistema modular actual.
  Acción: resumir y enlazar a estos dos documentos.

### `catalogs`

Estado del contexto: `CURRENT`

Referencias canónicas:

- `docs/catalogs/payment-terms.md`

Documentos a vigilar:

- SQL auxiliares en `docs/catalogs/sql/`
  Clasificación: `CURRENT` como soporte/manual, no como contrato funcional.

### `document-series`

Estado del contexto: `CURRENT`

Referencias canónicas:

- `docs/document-series/README.md`
- `docs/document-series/document-series-design.md`

Documentos a vigilar:

- `docs/document-series/migration-from-customer-invoice-series.md`
  Clasificación: `HISTORICAL`
  Acción: usar solo para trazabilidad de migración.

### `customer-invoices`

Estado del contexto: `CURRENT` con material mezclado de varias fases

Referencias canónicas:

- `docs/customer-invoices/README.md`
- `docs/customer-invoices/proforma-series-contract.md`
- `docs/customer-invoices/proforma-create-contract.md`
- `docs/customer-invoices/proforma-tax-config.md`
- `docs/customer-invoices/document-series-snapshot-contract.md`
- `docs/customer-invoices/settings/frontend-erp-settings-verifactu-design.md`

Referencias canónicas con alcance parcial:

- `docs/customer-invoices/settings/verifactu-company-profile-backend-design.md`
  Clasificación: `PARTIALLY SUPERSEDED`
  Canónico solo para:
  - `CompanyVerifactuProfile`
  - settings/backend de perfil VeriFactu
  - separación entre defaults empresariales y estado operativo
  No canónico para:
  - reintroducir `IssuedInvoice.verifactuPolicy`
  - presentar `IssuedInvoice 1 -> 0..N VerifactuRecord` como runtime vigente

Documentos a corregir o retirar de la lectura operativa:

- `docs/customer-invoices/split-proformas-issued-invoices-migration.md`
  Clasificación: `HISTORICAL`
  Acción: mantener solo como trazabilidad de split y migración.

- `docs/customer-invoices/invoice-series.md`
  Clasificación: `HISTORICAL`
  Acción: enlazar siempre hacia `document-series`.

- `docs/customer-invoices/sql/add-issued-invoice-verifactu-snapshots.sql`
  Clasificación: `SUPERSEDED`
  Acción: no usar en entornos nuevos; conserva una propuesta descartada.

- `docs/customer-invoices/sql/drop-issued-invoice-verifactu-snapshot-columns.sql`
  Clasificación: `CURRENT`
  Acción: mantener como runbook correctivo para limpiar drift legacy.

- `docs/customer-invoices/sql/validate-split-proformas-issued-invoices.sql`
  Clasificación: `HISTORICAL`
  Acción: usar solo como validación de un split legacy, no como contrato del runtime actual.

### `reports` / generación documental

Estado del contexto: `PARTIALLY SUPERSEDED`

Referencias canónicas actuales en este árbol:

- `docs/customer-invoices/proformas-reports.md`

Riesgo documental:

- todavía puede confundirse renderer concreto con arquitectura general de reporting.

Acción:

- cuando exista SSOT específico de `reports`, enlazarlo desde `customer-invoices` y evitar que documentos de módulo definan por sí solos la arquitectura transversal.

## Clasificación de documentos clave

| Documento | Estado | Referencia/acción |
|---|---|---|
| `docs/README.md` | `CURRENT` | Índice raíz y regla de navegación |
| `docs/architecture/README.md` | `CURRENT` | Índice canónico de arquitectura |
| `docs/settings/frontend-erp-settings-system-design.md` | `CURRENT` | SSOT del shell de Settings |
| `docs/settings/frontend-erp-settings-module-integration-design.md` | `CURRENT` | SSOT de integración modular en Settings |
| `docs/catalogs/payment-terms.md` | `CURRENT` | SSOT de plazos de pago |
| `docs/document-series/README.md` | `CURRENT` | SSOT operativo de series documentales |
| `docs/document-series/document-series-design.md` | `CURRENT` | Diseño canónico de `document-series` |
| `docs/document-series/migration-from-customer-invoice-series.md` | `HISTORICAL` | Solo migración y trazabilidad |
| `docs/customer-invoices/README.md` | `CURRENT` | Índice canónico del área |
| `docs/customer-invoices/proforma-series-contract.md` | `CURRENT` | SSOT de semántica de series en proformas |
| `docs/customer-invoices/proforma-create-contract.md` | `CURRENT` | SSOT de create de proformas |
| `docs/customer-invoices/proforma-tax-config.md` | `CURRENT` | SSOT de persistencia/configuración fiscal de proformas |
| `docs/customer-invoices/document-series-snapshot-contract.md` | `CURRENT` | SSOT de snapshot documental |
| `docs/customer-invoices/settings/frontend-erp-settings-verifactu-design.md` | `CURRENT` | SSOT frontend de Settings VeriFactu |
| `docs/customer-invoices/settings/verifactu-company-profile-backend-design.md` | `PARTIALLY SUPERSEDED` | Mantener como SSOT del perfil empresarial, no de `IssuedInvoice.verifactuPolicy` |
| `docs/customer-invoices/split-proformas-issued-invoices-migration.md` | `HISTORICAL` | Solo migración/split |
| `docs/customer-invoices/invoice-series.md` | `HISTORICAL` | Legacy |
| `docs/customer-invoices/sql/README.md` | `CURRENT` | Índice canónico de SQL manual |
| `docs/customer-invoices/sql/add-issued-invoice-verifactu-snapshots.sql` | `SUPERSEDED` | No ejecutar como DDL vigente |
| `docs/customer-invoices/sql/drop-issued-invoice-verifactu-snapshot-columns.sql` | `CURRENT` | Runbook correctivo |
| `docs/customer-invoices/sql/validate-split-proformas-issued-invoices.sql` | `HISTORICAL` | Validación de split legacy |
| `docs/API.md` | `HISTORICAL` | Borrador legacy |
| `docs/REQUISITOS GENERALES.md` | `HISTORICAL` | No usar como contrato vigente |
| `docs/REQUISITOS CLIENTES.md` | `HISTORICAL` | No usar como contrato vigente |
| `docs/FACTURAS DE CLIENTE.md` | `HISTORICAL` | Notas heredadas |

## Correcciones prioritarias ya aplicadas

- Eliminado el requisito vigente de `IssuedInvoice.verifactuPolicy` del diseño backend de VeriFactu.
- Explicitada la cardinalidad actual `IssuedInvoice 1 -> 0..1 VerifactuRecord`.
- Explicitada la dirección futura `IssuedInvoice 1 -> 0..N VerifactuRecord`.
- Reclasificado el SQL que añadía columnas VeriFactu legacy en `issued_invoices` como `SUPERSEDED`.
- Reforzada la navegación de índices para que el lector llegue antes al SSOT que al material histórico.

## Siguientes correcciones recomendadas

- Añadir estado documental visible al inicio de cualquier documento nuevo (`CURRENT`, `PARTIALLY SUPERSEDED`, `PROPOSAL`, etc.).
- Cuando aparezca una decisión nueva que invalide una anterior, marcar la sección desplazada dentro del documento antiguo en vez de dejar ambas coexistiendo sin etiqueta.
- Si se crea un SSOT transversal de `reports`, actualizar `docs/README.md` y `docs/customer-invoices/README.md` para enlazarlo como referencia canónica.