# ERP Backend · Identity/Auth Migration Notes

## Propósito

Este documento consolida las decisiones de arquitectura y el estado de migración del backend ERP desde el módulo legacy `auth` hacia el nuevo módulo `identity`.

Debe usarse como referencia para futuros incrementos relacionados con:

- autenticación
- sesión
- contexto tenant/company
- registro de usuarios
- roles y permisos
- autorización
- login frontend
- retirada progresiva de `modules/auth`

## Estado actual resumido

El backend ya dispone de un módulo `identity` registrado en servidor y con endpoints de autenticación funcionales:

```http
POST /identity/auth/login
POST /identity/auth/refresh
POST /identity/auth/logout
GET  /identity/auth/session
```

El módulo `identity` expone builders genéricos desde `@erp/identity/api`:

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

Uso esperado en routers tenant-scoped:

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

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

Uso esperado en routers que solo requieren usuario autenticado:

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

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

## Módulos backend migrados a `identity`

Ya no usan `@erp/auth/api` ni `mockUser`:

- `modules/catalogs`
- `modules/customers`
- `modules/customer-invoices`
- `modules/factuges`

## Consumidores legacy pendientes

Backend pendiente explícitamente:

- `modules/supplier/src/api/infrastructure/express/suppliers.routes.ts`

Frontend todavía usa cliente legacy:

- `apps/web/src/register-modules.tsx`
- `apps/web/src/app.tsx`

Por tanto, `modules/auth` no puede retirarse todavía.

## Regla de arquitectura vigente

Los módulos funcionales no deben importar ni recomponer internals de `identity`.

No usar en módulos consumidores:

```ts
IdentityInternalDeps;
authenticateUserDependencies;
getInternal("identity");
```

No crear helpers de auth por módulo como patrón final:

```txt
catalogs-auth-middlewares.ts
customers-auth-middlewares.ts
...
```

El middleware genérico pertenece a `identity`.

## Separación de responsabilidades

### Authentication

Responde a:

- quién es el usuario
- si el token es válido
- si la cuenta puede autenticarse

### Tenant context

Responde a:

- qué empresa activa se está usando en la request
- actualmente se resuelve por header `X-Company-Id`

### Authorization

Responderá a:

- qué permisos efectivos tiene el usuario dentro de la empresa

Todavía no está implementado en modo completo.

### Document context

Datos como `companySlug`, templates, certificados o metadatos de generación documental no pertenecen al middleware de autenticación.

No añadir a `identity` auth:

- `companySlug`
- `X-Company-Slug`
- `companySlug` en access token

Si un flujo documental necesita `companySlug`, debe resolverse mediante un servicio específico de empresa/documentos.

## Roadmap corto recomendado

1. Crear pantalla de login en Frontend ERP contra `/identity/auth/login`.
2. Mantener `supplier` temporalmente en legacy si así se decide.
3. Implementar refresh automático en frontend.
4. Implementar selección de empresa y uso de `X-Company-Id`.
5. Implementar persistencia y validación real de `CompanyMembership`.
6. Implementar resolución de permisos efectivos.
7. Migrar `supplier` cuando se decida.
8. Retirar backend legacy de `@erp/auth/api`.
9. Migrar o retirar `@erp/auth/client`.

## Documentos relacionados

- [`identity-auth-api.md`](./identity-auth-api.md)
- [`identity-backend-architecture.md`](./identity-backend-architecture.md)
- [`identity-migration-status.md`](./identity-migration-status.md)
- [`identity-roadmap.md`](./identity-roadmap.md)