Uecko_ERP/modules/identity/README.md

# `modules/identity`

`identity` es el runtime nuevo de autenticación, sesión y acceso por memberships del ERP.

## Responsabilidades

Gestiona:

- `Account`
- login
- refresh
- logout
- session
- `RefreshToken`
- `CompanyMembership`
- acceso `account-company`
- roles/permisos futuros

No gestiona:

- la ficha operativa completa de empresa
- `companySlug` en auth
- el tenant dentro del access token

## Endpoints activos

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

El endpoint para companies accesibles es:

```http
GET /companies/available
```

Ese endpoint pertenece al flujo actual, pero no implica que `identity` deba exponer `GET /identity/companies`.

## Access token

El access token contiene solo:

```ts
{
  accountId: string;
  email: string;
}
```

No debe contener:

- `companyId`
- `companySlug`
- roles
- permisos

## Middlewares públicos

Para rutas autenticadas sin tenant:

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

Para rutas tenant-scoped:

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

Código backend nuevo no debe usar:

- `@erp/auth/api`
- `mockUser`
- `requireAuthenticated` legacy
- `requireCompanyContext` legacy

## Servicios públicos

`identity` expone el servicio:

```txt
identity:general
```

Con acceso a `companyAccess` para casos como:

```ts
canAccessCompany(...)
findAccessibleCompanyIds(...)
```

Responsabilidad:

- `identity` decide qué `companyId` puede usar una cuenta según memberships activas.
- no devuelve la ficha completa de empresa.

## Tenant context

`requireIdentityTenant(params)` compone:

- `identity:general.companyAccess`
- `companies:general.finder`

Validación esperada:

1. access token válido
2. cuenta autenticable
3. `X-Company-Id` presente
4. `X-Company-Id` UUID válido
5. membership activa
6. company activa
7. `req.user.companyId` poblado

## Reglas de mantenimiento

- Backend nuevo: usar `@erp/identity/api`.
- No documentar ni crear `GET /identity/companies`.
- No borrar `modules/auth` mientras existan consumidores legacy reales.
- `modules/supplier` sigue pendiente de migración si continúa usando el runtime legacy.