david e5e73a5a13 Refactor documentation for ERP architecture and customer invoices

- Updated general requirements document to clarify its historical context and remove outdated technical details.
- Revised template documentation to serve as a base for writing prompts, emphasizing its auxiliary nature.
- Enhanced architecture documentation with clear distinctions between canonical and complementary documents.
- Added a new document for backend prompt base to centralize common context for backend prompts.
- Created a dedicated README for customer invoices, organizing current contracts, operational support, and historical context.
- Improved clarity and structure in various customer invoice documents, consolidating operational semantics and referencing canonical sources.

2026-08-05 13:18:03 +02:00

2.7 KiB

Raw Blame History

Identity Backend Architecture

Documento complementario de diseño backend.

Para contratos operativos vigentes, prevalecen:

tenant-context.md
identity-auth-api.md
identity-and-companies.md
modules/identity/README.md

Objetivo del módulo `identity`

identity sustituye progresivamente al módulo legacy auth.

Responsabilidades actuales:

cuentas autenticables
login/password
access token
refresh token rotado
logout
sesión actual
memberships
validación de acceso account-company
base para roles/permisos futuros

Dominio actual

Agregados y conceptos relevantes:

Account
RefreshToken
CompanyMembership
Role

Company funcional no pertenece a identity; vive en modules/companies.

Seguridad

Servicios definidos:

IPasswordHasher
IAccessTokenIssuer
IAccessTokenVerifier
IRefreshTokenGenerator
IRefreshTokenHasher

Decisiones vigentes:

password hashing con bcrypt
access token JWT con accountId y email
refresh token aleatorio
refresh token persistido como hash
no incluir companyId, companySlug, roles ni permisos en access token

Builders públicos

identity expone desde @erp/identity/api:

requireIdentityAuthenticated(params: StartParams): RequestHandler[];
requireIdentityTenant(params: StartParams): RequestHandler[];

Uso correcto:

import { requireIdentityTenant } from "@erp/identity/api";

router.use(...requireIdentityTenant(params));

import { requireIdentityAuthenticated } from "@erp/identity/api";

router.use(...requireIdentityAuthenticated(params));

`req.user`

Shape mínimo esperado:

{
  userId: UniqueID;
  email?: EmailAddress;
  companyId?: UniqueID;
  roles?: string[];
}

req.user.companyId solo se debe poblar cuando el middleware tenant valida correctamente la request.

No añadir:

companySlug
company
permissions enriquecidos
companyStatus

Tenant validation

requireIdentityTenant(params) ya no es solo validación sintáctica.

Valida:

token válido
account autenticable
X-Company-Id presente
UUID válido
membership active
company active

Relación con `companies`

identity resuelve membership y accesibilidad
companies resuelve la ficha operativa de empresa
no introducir dependencia identity -> companies

Si un consumidor necesita slug, debe resolverlo desde companies, no desde auth.

Prohibiciones de diseño

No usar en módulos consumidores:

IdentityInternalDeps;
authenticateUserDependencies;
getInternal("identity");

No crear helpers locales de auth por módulo como patrón estable.

No añadir al access token:

companyId
companySlug
roles
permisos

2.7 KiB Raw Blame History