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.