feat(docs): archive legacy DTO design and naming guidelines, introduce HTTP request flow, module boundaries, and testing guidelines

- Archived historical documents for DTO design and naming conventions.
- Added normative documentation for HTTP request flow and module boundaries.
- Introduced testing guidelines for backend layers.
- Updated onboarding module documentation and clarified onboarding requirements.
- Deprecated backend prompt base and prompt auth documents.
- Adjusted paths in testing documentation for consistency.

docs/README.md

@@ -1,99 +1,48 @@
 # ERP Docs
 
-Este directorio reúne la documentación técnica, operativa y de apoyo del ERP.
+Este es el índice principal de documentación. Las categorías indican autoridad documental.
 
-## Cómo leer esta documentación
+## Normativa arquitectónica
 
-- Empieza por este índice si necesitas orientarte.
+- [Índice de arquitectura](./architecture/README.md)
-- Usa los documentos en subdirectorios temáticos como fuente de verdad operativa.
+- [Arquitectura backend](./architecture/backend-architecture.md)
-- Trata los documentos marcados como históricos o legacy como contexto, no como contrato vigente.
+- [Inyección de dependencias](./architecture/dependency-injection.md)
-- Si hay duda sobre qué documento manda, consulta la [auditoría SSOT](./documentation-ssot-audit.md).
+- [Flujo HTTP y entrada a Application](./architecture/http-request-flow.md)
+- [DTOs y schemas HTTP](./architecture/dto-guidelines.md)
+- [Límites entre módulos](./architecture/module-boundaries.md)
+- [Pruebas backend por capa](./architecture/testing-guidelines.md)
 
-## Estructura documental
+## Testing y operación
 
-### Documentación vigente
-
-#### Arquitectura y runtime
-
-- [Arquitectura general](./architecture/README.md)
-- [Requisitos de `companies`](./companies/company-requirements.md)
-- [Contexto tenant y `X-Company-Id`](./architecture/tenant-context.md)
-- [Tratamiento de errores HTTP en frontend](./architecture/http-error-handling-frontend.md)
-- [API de autenticación de `identity`](./architecture/identity-auth-api.md)
-- [Relación entre `identity` y `companies`](./architecture/identity-and-companies.md)
-- [Estado de migración a `identity`](./architecture/identity-migration-status.md)
-
-#### Frontend
-
-- [Arquitectura frontend](./frontend/frontend-architecture.md)
-- [Sistema UI Rdx](./frontend/ui-system.md)
-- [Patrones de UI](./frontend/ui-patterns.md)
-- [Sistema modular de Settings](./settings/frontend-erp-settings-system-design.md)
-- [Integración de módulos con Settings](./settings/frontend-erp-settings-module-integration-design.md)
-- [README de `apps/web`](../apps/web/README.md)
-
-#### Customer invoices y proformas
-
-- [Índice de `customer-invoices`](./customer-invoices/README.md)
-- [Auditoría SSOT documental](./documentation-ssot-audit.md)
-- [Plazos de pago](./catalogs/payment-terms.md)
-- [Diseño backend del perfil VeriFactu empresarial](./customer-invoices/settings/verifactu-company-profile-backend-design.md)
-  Documento parcialmente superado: sigue siendo canónico para `CompanyVerifactuProfile`, pero no para reintroducir `IssuedInvoice.verifactuPolicy`.
-- [Diseño frontend de Settings para VeriFactu](./customer-invoices/settings/frontend-erp-settings-verifactu-design.md)
-- [Contrato de series de proformas](./customer-invoices/proforma-series-contract.md)
-- [Contrato de create de proformas](./customer-invoices/proforma-create-contract.md)
-- [Configuración fiscal persistida en proformas](./customer-invoices/proforma-tax-config.md)
-- [Reports de proformas](./customer-invoices/proformas-reports.md)
-
-#### Document series
-
-- [README de `document-series`](./document-series/README.md)
-- [Diseño de `document-series`](./document-series/document-series-design.md)
-- [Validación manual de `document-series`](./document-series/manual-validation.md)
-- [Validación manual de concurrencia](./document-series/manual-concurrency-validation.md)
-
-#### Módulos y runtime local
-
-- [README de `modules/identity`](../modules/identity/README.md)
-- [README de `modules/companies`](../modules/companies/README.md)
-- [README de `modules/auth`](../modules/auth/README.md)
-- [API pública de selección y alta rápida de clientes](./customers/customer-selection-and-quick-create.md)
 - [Tests HTTP backend](./testing/backend-http-integration.md)
 - [Harness frontend con `node:test`](./testing/frontend-node-test.md)
+- [Auditoría de fuentes SSOT](./documentation-ssot-audit.md)
 
-#### Guías y estándares
+## Documentación específica de módulo
 
-- [Guía de diseño de DTOs](./DTOS - GUÍA DE DISEÑO.md)
+- [Onboarding](./modules/onboarding.md)
-- [Convención de nombres de schemas DTO](./CONVENCION NOMBRADO DE ESQUEMAS DTO.md)
+- [customer-invoices](./customer-invoices/README.md)
+- [companies](./companies/company-requirements.md)
+- [identity y companies](./architecture/identity-and-companies.md)
+- [Contexto tenant](./architecture/tenant-context.md)
+- [document-series](./document-series/README.md)
+- Contratos de catálogos, settings, proformas, recurring-proformas y factuges en sus subdirectorios temáticos.
 
-#### SQL operativos y runbooks
+Los documentos específicos no redefinen DI, DTO, HTTP, mappers, límites de módulo ni testing transversal: enlazan la SSOT correspondiente.
 
-- [SQL de `customer-invoices`](./customer-invoices/sql/README.md)
+## Histórico
-- [Validación de migración a `document-series`](./document-series/sql/validate-document-series-migration.sql)
-- [Seed local de admin](./dev/seed-local-admin.sql)
 
-### Material auxiliar
+- [Diseño backend anterior](./architecture/history/backend-design-consolidated-legacy.md)
+- [Guía DTO anterior](./architecture/history/dto-design-legacy.md)
+- [Naming DTO anterior](./architecture/history/dto-schema-naming-legacy.md)
+- [Prompt customer-invoices anterior](./auxiliary/history/prompt-customer-invoices.md)
+- `API.md`, `REQUISITOS GENERALES.md`, `REQUISITOS CLIENTES.md` y `FACTURAS DE CLIENTE.md` son trazabilidad, no contrato vigente.
+- Las migraciones de `document-series` y `customer-invoices` se consultan solo como historial.
 
-- [Base común para prompts backend](./backend-prompt-base.md)
+## Auxiliar
-- [Prompt de auth](./prompt-auth.md)
-- [Prompt de customer invoices](./prompt-customer-invoices.md)
-- [Plantilla auxiliar](./TEMPLATE.md)
 
-### Histórico, transicional o de descubrimiento
+- [Backend prompt base](./backend-prompt-base.md) — deprecated; no define arquitectura.
+- [Prompt auth](./prompt-auth.md) — histórico/auxiliar; no define arquitectura.
+- [Plantilla](./TEMPLATE.md).
 
-Estos documentos se conservan por trazabilidad, auditoría o contexto de decisiones. No deben usarse como fuente de verdad del runtime actual sin contrastarlos con la documentación vigente.
+Si existe una duda de arquitectura, prevalecen exclusivamente los documentos de la sección normativa.
-
-- [Borrador legacy de API](./API.md)
-- [Requisitos generales históricos](./REQUISITOS GENERALES.md)
-- [Requisitos históricos del módulo de clientes](./REQUISITOS CLIENTES.md)
-- [Notas históricas de facturas de cliente](./FACTURAS DE CLIENTE.md)
-- [Split histórico Proforma / IssuedInvoice](./customer-invoices/split-proformas-issued-invoices-migration.md)
-- [Migración desde `customer_invoice_series`](./document-series/migration-from-customer-invoice-series.md)
-- [InvoiceSeries legacy](./customer-invoices/invoice-series.md)
-
-## Regla práctica de mantenimiento
-
-- Los documentos operativos vigentes deben vivir en subdirectorios temáticos y tener una responsabilidad clara.
-- Los documentos raíz en mayúsculas o con naming heredado deben considerarse legacy o auxiliares salvo que este índice los declare explícitamente vigentes.
-- Si una regla ya tiene fuente canónica, los demás documentos deben resumirla y enlazarla, no copiarla.
-- Para VeriFactu e `IssuedInvoice`, el estado vigente es: sin `verifactuPolicy`, cardinalidad actual `1 -> 0..1`, objetivo futuro `1 -> 0..N`.

docs/REQUISITOS CLIENTES.md

@@ -25,7 +25,7 @@ Este documento recoge requisitos tempranos del módulo de clientes y ya no debe
 
 - Arquitectura del repositorio: [README.md](../README.md)
 - Índice de docs: [README.md](./README.md)
-- Reglas de DTO y schemas: [DTOS - GUÍA DE DISEÑO.md](./DTOS - GUÍA DE DISEÑO.md) y [CONVENCION NOMBRADO DE ESQUEMAS DTO.md](./CONVENCION NOMBRADO DE ESQUEMAS DTO.md)
+- Reglas de DTO y schemas: [DTOs y schemas HTTP](./architecture/dto-guidelines.md)
 
 ## Motivo de conservación
 

docs/architecture/README.md

@@ -1,26 +1,27 @@
-# ERP Architecture Docs
+# Arquitectura del ERP
 
-Índice de arquitectura vigente y documentos transicionales relacionados con autenticación, tenant context y migración a `identity`.
+## Documentación normativa
 
-## Documentación canónica vigente
+- [Arquitectura backend](./backend-architecture.md)
+- [Inyección de dependencias](./dependency-injection.md)
+- [Flujo HTTP y entrada a Application](./http-request-flow.md)
+- [DTOs y schemas HTTP](./dto-guidelines.md)
+- [Límites entre módulos](./module-boundaries.md)
+- [Pruebas backend por capa](./testing-guidelines.md)
+
+Solo estos documentos establecen reglas transversales de backend.
+
+## Contratos específicos y complementarios
 
 - [Identity and companies](./identity-and-companies.md)
 - [Tenant context](./tenant-context.md)
 - [Identity auth API](./identity-auth-api.md)
 - [Tratamiento de errores HTTP en frontend](./http-error-handling-frontend.md)
+
+## Histórico y transicional
+
+- [Diseño backend consolidado anterior](./history/backend-design-consolidated-legacy.md)
+- [Identity backend architecture](./identity-backend-architecture.md)
 - [Identity migration status](./identity-migration-status.md)
 - [Identity roadmap](./identity-roadmap.md)
-
-## Documentación complementaria
-
-- [Identity backend architecture](./identity-backend-architecture.md)
-
-`identity-backend-architecture.md` se mantiene como nota complementaria de diseño backend. Para contratos operativos concretos, prevalecen `tenant-context.md`, `identity-auth-api.md` y los README de módulo.
-
-## Resumen actual
-
-- `identity` gestiona autenticación, sesión, refresh y memberships.
-- `companies` gestiona la ficha operativa de empresa.
-- `GET /companies/available` es la vía vigente para companies accesibles.
-- El contexto tenant se resuelve con `X-Company-Id` y `requireIdentityTenant(params)`.
 - El frontend ERP ya usa el runtime nuevo de `identity`.

docs/architecture/backend-architecture.md

@@ -0,0 +1,40 @@
+# Arquitectura backend
+
+> Estado: **NORMATIVO**. Esta es la fuente de verdad de la arquitectura general del backend.
+
+## Stack y principios
+
+El backend usa Node.js, TypeScript, Express, MariaDB, Sequelize v6, Zod v4, PNPM y Turborepo. Las versiones soportadas se consultan en el `package.json` raíz y en los paquetes del workspace.
+
+Se aplica DDD pragmático y Clean Architecture sin convertir cada principio en una capa adicional. Las decisiones favorecen SOLID, KISS, YAGNI, SSOT, fail fast, programación defensiva y claridad semántica antes que abstracciones prematuras.
+
+`Result` representa fallos esperables; `Maybe` representa ausencia semántica. Las excepciones no son el flujo normal de validación.
+
+## Capas y dirección de dependencias
+
+```text
+Infrastructure → Application → Domain
+```
+
+- **Domain** no conoce Application ni Infrastructure. Contiene agregados, entidades, Value Objects e invariantes.
+- **Application** conoce Domain, Core y contratos necesarios. Orquesta casos de uso y servicios, pero no conoce Express, Sequelize ni modelos ORM.
+- **Infrastructure** implementa puertos y contiene HTTP, Sequelize, mappers de persistencia y composition roots.
+- **common** contiene contratos compartibles entre backend y web, especialmente DTOs de API. No es una vía para filtrar infraestructura.
+
+Quedan prohibidas las dependencias en dirección inversa, en especial `Application → Infrastructure`.
+
+## Responsabilidades de aplicación e infraestructura
+
+Los casos de uso orquestan, gestionan transacciones cuando corresponde, delegan en servicios y devuelven `Result`. No contienen lógica HTTP ni acceden a Sequelize directamente.
+
+Los repositorios pertenecen a Infrastructure, gestionan una responsabilidad o agregado concreto y usan mappers de persistencia. Un mapper de persistencia bidireccional expone típicamente `toPersistence()` y `toDomain()`; Infrastructure reconstruye con `rehydrate()`. La creación funcional se realiza con `create()` y valida invariantes.
+
+Los builders de salida materializan contratos definidos por schemas Zod. Son deterministas, no acceden a repositorios y pueden convertir Value Objects a primitivas o `Maybe` a `null`.
+
+## Referencias normativas relacionadas
+
+- [Inyección de dependencias](./dependency-injection.md)
+- [Flujo HTTP y entrada a Application](./http-request-flow.md)
+- [DTOs y schemas](./dto-guidelines.md)
+- [Límites entre módulos](./module-boundaries.md)
+- [Pruebas backend](./testing-guidelines.md)

docs/architecture/dependency-injection.md

@@ -0,0 +1,39 @@
+# Inyección de dependencias por módulo
+
+> Estado: **NORMATIVO**. Esta guía define cómo se ensambla un módulo backend.
+
+## Regla base
+
+Cada módulo tiene un único composition root identificable. Usa constructor injection explícita; no usa contenedor DI, Service Locator, decorators, reflection ni registry dinámico interno.
+
+El composition root es el único lugar que puede resolver servicios públicos de otros módulos mediante `getService`. Las DI inferiores reciben todas sus dependencias como argumentos explícitos y nunca llaman a `getService`.
+
+## Responsabilidades del composition root
+
+El root ensambla infraestructura concreta, repositories, transaction managers, servicios de Application, InputMappers y UseCases. También decide qué instancias se crean una vez y se comparten, y devuelve las APIs `services` e `internal` del módulo.
+
+Las DI inferiores pueden separarse por responsabilidad: persistence, application services, mappers, use cases o recurso. No hay obligación de reducir ficheros: la claridad del grafo de dependencias es prioritaria a tener menos ficheros. La duplicación explícita entre composition roots es preferible a una abstracción DI prematura.
+
+No introducir `GenericDI`, `BaseDI`, registry DI, contenedor global ni imports de repositories de otro módulo.
+
+## `services` e `internal`
+
+```text
+services  = API pública intermodular
+internal  = API privada del propio módulo
+```
+
+`services` contiene únicamente contratos con consumidores intermodulares reales. Por YAGNI no se expone nada “por si acaso”. Nunca expone repositories, mappers de persistencia, transaction managers ni use cases HTTP sin consumidor externo.
+
+`internal` puede contener use cases, application services u otras dependencias privadas que necesiten el arranque o las routes. No debe convertirse en una copia indiscriminada del composition root.
+
+Un módulo externo consume `services`; nunca consume `internal` de otro módulo.
+
+## Ejemplo mínimo
+
+El root de onboarding crea persistence, resuelve `companies:general` e `identity:general`, construye use cases y devuelve sus dependencias privadas. Véase `modules/onboarding/src/api/infrastructure/di/onboarding.di.ts`.
+
+## Referencias
+
+- [Límites entre módulos](./module-boundaries.md)
+- [Flujo HTTP](./http-request-flow.md)

docs/architecture/dto-guidelines.md

@@ -0,0 +1,53 @@
+# DTOs y schemas HTTP
+
+> Estado: **NORMATIVO**. Esta guía es la SSOT de contratos HTTP, schemas y naming de DTOs.
+
+## Ubicación y compartición
+
+Los Request DTO se ubican normalmente en:
+
+```text
+modules/<module>/src/common/dto/request
+```
+
+Los DTOs de response y subcontratos compartidos siguen la estructura `common/dto/response` y `common/dto/shared` cuando corresponda. `common` es deliberadamente importable tanto por backend como por web: el cliente puede usar el RequestDTO para tipar el payload que envía.
+
+Un RequestDTO no pertenece a Infrastructure.
+
+## Zod es la SSOT
+
+Cada contrato nace de un schema Zod y el tipo se infiere de él:
+
+```ts
+export const CreateXRequestSchema = z.object({ /* contrato HTTP */ });
+
+export type CreateXRequestDTO = z.infer<typeof CreateXRequestSchema>;
+```
+
+No crear interfaces manuales paralelas. Cada endpoint define sus request y response DTOs, salvo subcontratos que sean realmente idénticos y estables.
+
+## Naming
+
+Para body HTTP, usar `<Action><Resource>RequestSchema` y `<Action><Resource>RequestDTO`:
+
+```text
+CreateCustomerRequestSchema
+CreateProformaRequestSchema
+CompleteInitialOnboardingRequestSchema
+```
+
+Para params y query se mantiene el rol explícito, por ejemplo `GetCustomerByIdParamsRequestSchema` o `CustomerListQueryRequestSchema`, según la convención local ya establecida. `CommandSchema` no es el nombre general de un body HTTP: un Command es una representación de Application cuando realmente exista.
+
+En output usar nombres que expresen el contrato: `SummarySchema`, `ResourceSchema`, `DetailResponseSchema`, `ListResponseSchema`, `CreatedResponseSchema` o `DeletedResponseSchema`.
+
+## Semántica del contrato
+
+`undefined`, `null`, `""` y `[]` tienen significados diferentes y el schema debe expresarlos. Evitar `.default()` y `.transform()` en DTOs de negocio salvo necesidad justificada; la normalización y la decisión de `Maybe` pertenecen a Application.
+
+Usar schemas semánticos para UUID, fechas, timestamps, porcentajes, importes y cantidades. Los decimales exactos no viajan como `number`; Money, Amount, Percentage y Quantity mantienen el contrato de precisión existente.
+
+## Responses y snapshots
+
+El schema Zod es también la SSOT del contrato de salida. Los snapshot builders se tipan contra el DTO inferido, son deterministas, no implementan lógica de negocio ni acceden a Infrastructure. Pueden convertir Value Objects a primitivas, enums internos a valores de contrato y `Maybe` a `null`.
+
+La ejecución de `validateRequest` y la transición hacia InputMapper se documentan en [Flujo HTTP y entrada a Application](./http-request-flow.md).

docs/architecture/history/backend-design-consolidated-legacy.md

@@ -1,3 +1,13 @@
+# ARCHIVADO — Diseño backend consolidado anterior
+
+> Estado: **HISTÓRICO — NO NORMATIVO**.
+>
+> Las reglas transversales vigentes están distribuidas por responsabilidad en [../backend-architecture.md](../backend-architecture.md), [../dependency-injection.md](../dependency-injection.md), [../http-request-flow.md](../http-request-flow.md), [../dto-guidelines.md](../dto-guidelines.md), [../module-boundaries.md](../module-boundaries.md) y [../testing-guidelines.md](../testing-guidelines.md).
+>
+> En particular, el flujo `RequestDTO → RequestMapper → Command → PropsMapper` que aparece más abajo no es una norma vigente: RequestMapper es opcional y se usa solo cuando existe adaptación HTTP propia.
+
+---
+
 # DOCUMENTO DE DISEÑO — ERP MODULAR BACKEND (ESTADO CONSOLIDADO)
 
 ## 1. Contexto general
@@ -1006,4 +1016,3 @@ Estas no sustituyen a `create()`, sino que complementan su uso.
 > rehydrate() = estado ya válido restaurado
 
 Esta distinción es obligatoria en todo el ERP.
-

docs/architecture/history/dto-design-legacy.md

@@ -1,8 +1,14 @@
+# ARCHIVADO — Guía anterior de diseño de DTOs
+
+> Estado: **HISTÓRICO — NO NORMATIVO**. La fuente vigente es [../dto-guidelines.md](../dto-guidelines.md).
+
+---
+
 # Guía de diseño de DTOs para el ERP
 
 Documento principal para el diseño de DTOs y schemas HTTP del proyecto.
 
-Para reglas de naming más puntuales, consultar también [CONVENCION NOMBRADO DE ESQUEMAS DTO.md](./CONVENCION NOMBRADO DE ESQUEMAS DTO.md).
+Para reglas vigentes de diseño y naming, consultar [../dto-guidelines.md](../dto-guidelines.md).
 
 ## 1. Principios generales
 

docs/architecture/history/dto-schema-naming-legacy.md

@@ -1,6 +1,12 @@
+# ARCHIVADO — Convención anterior de nombres de schemas DTO
+
+> Estado: **HISTÓRICO — NO NORMATIVO**. El naming y diseño vigentes están en [../dto-guidelines.md](../dto-guidelines.md).
+
+---
+
 # Convención de Nombres de Schemas DTO
 
-Guía específica de naming para schemas DTO. Complementa, pero no sustituye, a [DTOS - GUÍA DE DISEÑO.md](./DTOS - GUÍA DE DISEÑO.md), que sigue siendo la referencia principal de diseño.
+Guía específica de naming para schemas DTO. Su referencia vigente es [../dto-guidelines.md](../dto-guidelines.md).
 
 ## Alcance
 

docs/architecture/http-request-flow.md

@@ -0,0 +1,55 @@
+# Flujo HTTP y entrada a Application
+
+> Estado: **NORMATIVO**. Define la frontera Express/Application para código nuevo y refactors futuros.
+
+## Flujo normal
+
+```text
+RequestSchema
+  ↓ validateRequest
+RequestDTO
+  ↓
+Controller
+  ↓
+UseCase({ dto, context })
+  ↓
+I<Input>Mapper
+  ↓
+Value Objects / Application Props
+  ↓
+Application services / Domain
+```
+
+Este es el patrón de `CreateCustomer`, `CreateProforma` y `CompleteInitialOnboarding`.
+
+## Routes y guards
+
+Las routes registran endpoints, guards, `validateRequest`, obtienen el `internal` del propio módulo y pueden construir controllers ligeros. No crean repositories, transaction managers, servicios de Application, Value Objects ni lógica de negocio.
+
+Los guards viven en routes: `requireAuthenticatedGuard()`, `requireCompanyContextGuard()`, `forbidQueryFieldGuard(...)` y `validateRequest(...)`. Algunos controllers históricos de customers y proformas aún registran guards; es deuda de alineación, no una segunda norma para código nuevo.
+
+El schema vive junto al DTO. La route ejecuta `validateRequest(SomeRequestSchema, "body" | "params" | "query")`; el controller no vuelve a ejecutar Zod sobre esa entrada validada.
+
+## Controllers
+
+Un controller lee request validada, obtiene contexto HTTP autenticado, invoca el caso de uso y traduce `Result` a HTTP. No crea Value Objects, no ejecuta InputMappers, no resuelve servicios de otros módulos y no contiene lógica de negocio.
+
+Los identificadores controlados por el servidor (`accountId`, `companyId`, `tenantId`, `actorId`) no forman parte del RequestDTO ni llegan de body, query o path. Por ejemplo, onboarding usa `dto = req.body`, obtiene `accountId = req.user.userId` y ejecuta `useCase.execute({ dto, accountId })`.
+
+## InputMapper de Application
+
+Cuando existe transformación de transporte a Application, el nombre preferido es `I<CreateX>InputMapper` / `CreateXInputMapper`. Recibe DTO y contexto, devuelve `Result<Props | Params>` y puede crear Value Objects, adaptar primitivas, convertir `null`/`undefined` a `Maybe` y acumular `ValidationErrorDetail` en una `ValidationErrorCollection` cuando la operación necesita varios errores de validación.
+
+No conoce Express, repositories ni HTTP, y no construye agregados salvo un diseño explícito distinto. Se inyecta nominalmente en el use case desde DI.
+
+## RequestMapper opcional
+
+Un RequestMapper solo se usa cuando tiene una responsabilidad HTTP propia, por ejemplo combinar body, params, query o contexto para producir un Command. `IssueProformaByIdRequestMapper` es el ejemplo actual.
+
+No se crea un RequestMapper solo para transformar `snake_case` a `camelCase` si Application volverá a transformar los mismos datos.
+
+## Result y Maybe
+
+Los InputMappers, servicios, use cases y repositories usan `Result` para fallos esperables según sus contratos. La frontera DTO conserva `undefined` y `null`; Application decide `Maybe.some()` o `Maybe.none()`. Las responses pueden materializar ausencia como `null` conforme a su DTO.
+
+Para reglas de schema, estructura y naming, véase [DTOs y schemas](./dto-guidelines.md).

docs/architecture/module-boundaries.md

@@ -0,0 +1,11 @@
+# Límites entre módulos
+
+> Estado: **NORMATIVO**. Define las colaboraciones permitidas entre módulos.
+
+Un módulo puede compartir DTOs y contratos de `common`, servicios públicos explícitos y contratos de Core. Un consumidor solo depende de la API pública que el módulo proveedor expone en `services`.
+
+Queda prohibido importar Infrastructure interna de otro módulo, repositories, modelos Sequelize, mappers internos o usar `getInternal` fuera del propio módulo. Tampoco se reconstruyen internals ajenos localmente.
+
+La API pública debe ser pequeña y responder a consumidores reales. La decisión de qué publicar se toma en el composition root del proveedor; para su ensamblaje, véase [Inyección de dependencias](./dependency-injection.md).
+
+`identity-and-companies.md` sigue siendo la referencia específica para la frontera entre esos módulos y ofrece ejemplos de estas reglas.

docs/architecture/testing-guidelines.md

@@ -0,0 +1,23 @@
+# Pruebas backend por capa
+
+> Estado: **NORMATIVO**. Cada capa prueba su responsabilidad; no se repite la misma validación en todas ellas.
+
+## DTO
+
+Probar schemas válidos e inválidos, keys desconocidas cuando aplique, `optional`/`null` y schemas semánticos. Zod se prueba aquí.
+
+## InputMapper
+
+Probar `DTO + context → Value Objects/Props`, fallos de Value Objects, conversión a `Maybe` y `Result`/colecciones de errores. No repetir el parsing Zod de la route.
+
+## Use case
+
+Probar orquestación, transacción, colaboración con servicios, propagación de `Result` e idempotencia cuando aplique.
+
+## Controller y routes
+
+El controller prueba contexto autenticado, input enviado al use case y traducción `Result → HTTP`. Las routes se prueban cuando aporten valor estructural: guards, `validateRequest` y wiring.
+
+## Integración
+
+La integración HTTP real se documenta por separado en [Tests HTTP backend](../testing/backend-http-integration.md): Express, módulos, auth/tenant, MariaDB y Sequelize reales.

docs/auxiliary/history/prompt-customer-invoices.md

@@ -1,3 +1,9 @@
+# ARCHIVADO — Prompt Customer Invoices
+
+> Estado: **HISTÓRICO — NO NORMATIVO**. Describe el agregado híbrido `CustomerInvoice` y servicios retirados. No usar para cambios nuevos; consultar [arquitectura normativa](../../architecture/README.md) y [documentación actual de customer-invoices](../../customer-invoices/README.md).
+
+---
+
 # Prompt Customer Invoices
 
 Base comun reutilizada: [`backend-prompt-base.md`](./backend-prompt-base.md)

docs/backend-prompt-base.md

@@ -1,4 +1,6 @@
-# Backend Prompt Base
+# DEPRECATED — Backend Prompt Base
+
+> Este documento es **AUXILIAR** y no establece arquitectura. Para reglas vigentes, consultar [arquitectura normativa](./architecture/README.md).
 
 ## Objetivo
 

docs/companies/documento-diseno-company-address.md

@@ -346,7 +346,7 @@ No se permiten direcciones parcialmente válidas dentro de `Company`.
 
 La dirección no es obligatoria como invariante universal de `Company`.
 
-Sin embargo, el futuro onboarding sí debe exigirla.
+El onboarding exige una dirección completa al crear inicialmente la empresa.
 
 Regla:
 
@@ -591,7 +591,7 @@ objeto
 
 Esto evita romper consumidores actuales de `POST /companies`.
 
-El futuro onboarding utilizará un contrato más estricto donde la dirección sí será obligatoria.
+El onboarding utiliza un contrato más estricto donde la dirección es obligatoria.
 
 ---
 
@@ -989,7 +989,7 @@ Los assets actuales de Handlebars pertenecen a las plantillas y no constituyen a
 
 ---
 
-## 31. Slug y futura creación desde onboarding
+## 31. Slug y creación desde onboarding
 
 El onboarding no debe pedir:
 
@@ -1036,7 +1036,7 @@ La política exacta de desambiguación se cerrará al diseñar esa capability.
 
 ---
 
-## 32. Campos del futuro onboarding
+## 32. Campos del onboarding
 
 La evolución de `Company` permite fijar el bloque empresarial del onboarding.
 
@@ -1269,10 +1269,9 @@ Queda como limitación conocida.
 
 ## 37. Fuera de alcance
 
-No implementar en esta evolución:
+Fuera del alcance de esta evolución original:
 
 ```txt
-onboarding
 snapshot issuer de IssuedInvoice
 defaultLanguage
 defaultCurrency
@@ -1307,13 +1306,13 @@ P5
 Conectar Company.address al reporting de proformas
 
 P6
-Crear capability pública de creación inicial de Company para onboarding
+Crear capability pública de creación inicial de Company para onboarding — completado
 
 P7
 Diseñar por separado issuer snapshot de IssuedInvoice
 
 P8
-Cerrar e implementar onboarding
+Cerrar e implementar onboarding — completado
 ```
 
 Esta secuencia mantiene cambios incrementales y evita mezclar `Company`, reporting histórico y onboarding en una única modificación.

docs/documentation-ssot-audit.md

@@ -1,210 +1,42 @@
 # Auditoría documental SSOT
 
-Fecha de actualización: 2026-08-26
+Fecha de actualización: 2026-09-08
 
-## Objetivo
+## Autoridad documental
 
-Fijar una lectura única y consistente de la documentación técnica del ERP para
+- **NORMATIVO**: establece reglas transversales; vive en `docs/architecture/` y aparece en su índice.
-evitar que documentos históricos, propuestas o secciones parcialmente superadas
+- **ESPECÍFICO DE MÓDULO**: define contrato o negocio de un contexto; no redefine arquitectura transversal.
-se interpreten como contrato vigente.
+- **HISTÓRICO**: conserva trazabilidad y no debe guiar código nuevo.
+- **AUXILIAR**: apoyo operativo o prompts; no establece reglas.
 
-Estados usados en esta auditoría:
+## SSOT normativas
 
-- `CURRENT`: fuente canónica vigente.
+| Materia | Documento |
-- `PARTIALLY SUPERSEDED`: documento útil, pero con secciones ya superadas.
+| --- | --- |
-- `SUPERSEDED`: documento conservado por trazabilidad, pero no vigente.
+| Arquitectura backend | `docs/architecture/backend-architecture.md` |
-- `PROPOSAL`: diseño o dirección futura aún no implantada.
+| DI y composition root | `docs/architecture/dependency-injection.md` |
-- `HISTORICAL`: contexto, migración o auditoría de un estado anterior.
+| HTTP, guards, validation e InputMapper | `docs/architecture/http-request-flow.md` |
+| DTO, Zod, naming y snapshots | `docs/architecture/dto-guidelines.md` |
+| Fronteras intermodulares | `docs/architecture/module-boundaries.md` |
+| Testing por capa | `docs/architecture/testing-guidelines.md` |
 
-## Reglas transversales
+`docs/testing/backend-http-integration.md` es la guía específica de integración real; no sustituye la guía transversal de pruebas.
 
-- Si un área tiene SSOT explícito, el resto de documentos deben enlazarlo y no duplicar semántica.
+## Documentación específica vigente
-- 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
+- `docs/modules/onboarding.md`: contrato funcional y composición observable de onboarding.
+- `docs/customer-invoices/README.md` y sus contratos: negocio de proformas/facturas.
+- `docs/architecture/identity-and-companies.md` y `tenant-context.md`: contratos concretos de identity/companies y tenant.
+- Documentos de companies, catalogs, document-series, settings, factuges y recurring-proformas: reglas de sus respectivos contextos.
 
-### `identity`
+## Histórico y auxiliar
 
-Estado del contexto: `CURRENT`
+- `docs/architecture/history/backend-design-consolidated-legacy.md`: diseño backend anterior, archivado.
+- `docs/architecture/history/dto-design-legacy.md`: guía DTO anterior, archivada.
+- `docs/architecture/history/dto-schema-naming-legacy.md`: naming DTO anterior, archivado.
+- `docs/auxiliary/history/prompt-customer-invoices.md`: prompt retirado, archivado.
+- `docs/backend-prompt-base.md`: deprecated; auxiliar.
+- `docs/prompt-auth.md`: histórico/auxiliar.
+- Los documentos API, requisitos y migraciones marcados como históricos en `docs/README.md` se conservan solo por trazabilidad.
 
-Referencias canónicas:
+Los documentos que no pertenezcan al conjunto normativo no pueden establecer reglas de DI, DTO, HTTP, mappers, límites de módulo o testing transversal.
-
-- `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.

docs/modules/onboarding.md

@@ -0,0 +1,28 @@
+# Onboarding
+
+> Estado: **ESPECÍFICO DE MÓDULO**. Las reglas transversales se consultan en [arquitectura](../architecture/README.md).
+
+## Propósito y endpoints
+
+El módulo mantiene el estado del onboarding inicial y permite completar la creación inicial de una empresa para una cuenta autenticada.
+
+```text
+GET  /api/v1/onboarding/initial
+POST /api/v1/onboarding/initial/complete
+```
+
+La ruta de completado valida `CompleteInitialOnboardingRequestSchema`. El `accountId` no pertenece al payload: procede de `req.user.userId`.
+
+## Dependencias y composición
+
+El módulo consume los servicios públicos `companies:general.initialCompanyCreator` e `identity:general.initialCompanyAdminAssigner`. Su composition root está en `modules/onboarding/src/api/infrastructure/di/onboarding.di.ts` y el módulo declara esas dependencias en `modules/onboarding/src/api/module.ts`.
+
+Actualmente `services.general` no expone servicios públicos porque no hay consumidores intermodulares reales. `internal` contiene los use cases y servicios privados necesarios por routes y arranque.
+
+## Flujo de completado
+
+`CompleteInitialOnboardingController` toma el DTO validado y el contexto autenticado. `CompleteInitialOnboardingUseCase` usa `CompleteInitialOnboardingInputMapper` para crear parámetros de Application y Value Objects, completa la transacción, crea la empresa, asigna el administrador y persiste el onboarding completado.
+
+La operación es idempotente: si el onboarding ya está completado y es consistente, devuelve la misma `companyId`.
+
+Para DI, DTOs, HTTP y tests, véanse las SSOT de arquitectura; este documento no las redefine.

docs/prompt-auth.md

@@ -1,4 +1,6 @@
-# Prompt Auth
+# HISTÓRICO/AUXILIAR — Prompt Auth
+
+> Este prompt no establece reglas transversales. Para arquitectura vigente, consultar [arquitectura normativa](./architecture/README.md).
 
 Base comun reutilizada: [`backend-prompt-base.md`](./backend-prompt-base.md)
 

docs/testing/backend-http-integration.md

@@ -19,7 +19,7 @@ apps/server/src/testing/http
 Script disponible:
 
 ```bash
-cd /home/rodax/Documentos/uecko-erp
+cd /home/david/dev/uecko-erp
 pnpm --filter @erp/factuges-server test:http
 ```
 

docs/testing/frontend-node-test.md

@@ -14,7 +14,7 @@ No existe infraestructura activa de `vitest`, `jest`, `jsdom` ni `happy-dom` en
 Ejecuta los tests en Ubuntu desde la raíz del repo:
 
 ```bash
-cd /home/rodax/Documentos/uecko-erp
+cd /home/david/dev/uecko-erp
 node --version
 pnpm --version
 ```
@@ -26,28 +26,28 @@ El runtime esperado del repo es Node `>= 24`.
 ### Test React individual
 
 ```bash
-cd /home/rodax/Documentos/uecko-erp
+cd /home/david/dev/uecko-erp
 pnpm test:frontend -- modules/customer-invoices/src/web/proformas/update/ui/components/proforma-update-help-popover.test.tsx
 ```
 
 ### Tests frontend de un módulo
 
 ```bash
-cd /home/rodax/Documentos/uecko-erp
+cd /home/david/dev/uecko-erp
 pnpm test:frontend -- modules/customer-invoices/src/web/**/*.test.tsx
 ```
 
 ### Tests frontend de `apps/web`
 
 ```bash
-cd /home/rodax/Documentos/uecko-erp
+cd /home/david/dev/uecko-erp
 pnpm test:frontend -- apps/web/src/**/*.test.tsx
 ```
 
 ### Test TypeScript puro
 
 ```bash
-cd /home/rodax/Documentos/uecko-erp
+cd /home/david/dev/uecko-erp
 pnpm test:unit -- packages/rdx-utils/src/helpers/__tests__/maybe.test.ts
 ```