David dac22372b9 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.

2026-09-08 23:40:49 +02:00

2.7 KiB

Raw Blame History

Tests HTTP backend

Esta guía pone en marcha un entorno real de integración HTTP para el backend del ERP usando:

Express real
módulos reales
middleware real de auth y tenant
MariaDB real
Sequelize real

Estado actual

La suite vive en:

apps/server/src/testing/http

Script disponible:

cd /home/david/dev/uecko-erp
pnpm --filter @erp/factuges-server test:http

Entorno requerido

El runtime carga:

apps/server/.env.test

Contrato mínimo:

NODE_ENV=test
DB_NAME debe contener test
la base se recrea en cada arranque de runtime
el usuario configurado debe poder hacer CREATE DATABASE y DROP DATABASE

Para evitar colisiones entre suites o casos concurrentes:

el runtime genera un nombre de base efímero a partir de DB_NAME
cada test trabaja sobre una base distinta

Runtime reutilizable

Pieza principal:

apps/server/src/testing/http/http-test-runtime.ts

Responsabilidades:

cargar .env.test
resetear registries globales del server
validar configuración segura de test
recrear la base de datos
arrancar la app real en un puerto efímero
exponer request() y stop()

Fixtures actuales

Helpers disponibles:

apps/server/src/testing/http/http-test-fixtures.ts

Cobertura inicial:

cuentas de identity
companies
memberships account-company
payment terms
login real por API
consulta directa a la fila persistida de companies

Suite piloto actual

Archivo:

apps/server/src/testing/http/companies-current.http.test.ts

Cobertura inicial confirmada:

GET /api/v1/companies/current
PATCH /api/v1/companies/current
401 sin auth
403 sin X-Company-Id
403 con membership inactiva
update parcial
limpieza explícita con null
asignación y desasignación de default_payment_term_id
default_payment_term_id cross-company => 422
default_payment_term_id inactivo => 422
rollback transaccional cuando falla la asignación de default_payment_term_id
422 por payload inválido

Convenciones prácticas

usar login real en vez de fabricar JWTs
sembrar solo los datos mínimos del caso
cerrar siempre el runtime con stop()
no compartir base de datos entre tests
validar tanto respuesta HTTP como persistencia cuando la mutación lo requiera

Contrato de `default_payment_term_id`

Semántica actual:

omitido -> conservar
null -> desvincular
UUID activo de la misma company -> asignar
UUID no asignable -> 422

Se considera no asignable:

un PaymentTerm de otra company
un PaymentTerm inactivo

Además, el PATCH /companies/current es transaccional:

si falla default_payment_term_id
no se persisten otros cambios del mismo request

2.7 KiB Raw Blame History