# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Comandos

Yarn 4 con workspaces. Desde la raíz:

- `yarn dev` — arranca todos los servicios en watch (tsx).
- `yarn build` — `tsc --build` por workspace + crea `dist/packages/node_modules` con symlinks para que ESM resuelva `sim-shared` y `sim-consumidor-objenious`.
- `yarn start` — arranca los servicios desde `dist/`.
- `yarn typecheck` — `tsc --noEmit` global.
- `yarn lint` / `yarn lint:fix` — ESLint.
- `yarn format` / `yarn format:check` — Prettier.
- `yarn test` — vitest en watch (todos los packages).
- `yarn vitest run packages/<pkg>/path/file.test.ts` — un único test, single-shot.
- `yarn migrate` — aplica migraciones de `deployment/database/migrations` con `@sf-alvar/db-migrate`.

Stack local con Docker (RabbitMQ + Postgres + servicios):

- `./build.local.sh` — build de imágenes.
- `./run.local.sh` — `docker compose up --watch`.
- `./stop.local.sh` — `docker compose down -v` (borra volúmenes).

ESM puro: los imports llevan `.js` aunque el archivo sea `.ts`. Las rutas usan path aliases por servicio (`#config/*`, `#adapters/*`, `#domain/*`, `#ports/*`).

## Arquitectura

Monorepo de microservicios que recibe peticiones HTTP, las publica en RabbitMQ y las consume por compañía proveedora de SIM. La compañía se resuelve en el gateway a partir del ICCID y se inyecta en el routing key.

Packages en `packages/`:

- **`sim-shared/`** — tipos, ports y adapters compartidos (`EventBus`/`RabbitMQEventBus`, `Result<E,D>`, `OrderRepository`, `PgClient`, JWT, `SimEvents`).
- **`sim-entrada-eventos/`** — gateway HTTP (Express, :3000). Valida y publica al exchange.
- **`sim-consumidor-nos/`** — worker NOS (:3001).
- **`sim-consumidor-objenious/`** — worker Objenious (:3002).
- **`sim-objenious-cron/`** — cron de seguimiento de mass-actions de Objenious. **No sigue la arquitectura DDD del resto**, excepción intencional documentada por las particularidades de la API que consume; no auditarlo contra el estilo de la casa salvo petición explícita.
- **`_template/`** — plantilla oficial para servicios nuevos.

Cada servicio (excepto el cron) sigue capas DDD/Hexagonal:

- `domain/` — entidades, eventos, ports (`*.port.ts`).
- `aplication/` — usecases (`X.usecases.ts`), controllers, validators. La carpeta se llama `aplication` (con "p" simple) **intencionalmente**: cambiarla rompe los path aliases de todo el monorepo.
- `infrastructure/` — adapters (repositorios, clientes HTTP, routers Express `*Routes.http.ts`).
- `config/` — composition root + env.

**RabbitMQ**: exchange principal `sim.exchange` (topic). Routing keys `sim.[compañia].[acción]`. Retries con header `x-retry-count`; tras `maxRetry` → DLX en `sim.dlx`. Cada mensaje lleva `correlation_id` (uuidv7) que liga evento ↔ order en Postgres. La topología se declara solo en código de cada consumer; en JSON solo el broker base. Diagrama en `imgs/diagrama-rabbit.png`.

**Errores**: `Result<E, D>` (de `sim-shared/domain/Result.ts`) para fallos esperables (negocio, I/O). `throw` solo para invariantes rotas.

**Inyección de dependencias**: manual, por constructor con objeto `args: { dep1, dep2, ... }` (NO posicional). Cableado en `index.ts` o `config/*.config.ts` — nunca dentro de un usecase, controller o adapter. Los tipos del constructor apuntan al **port**, nunca al adapter concreto.

## Skill experta y referencias

Para cualquier trabajo no trivial de diseño, revisión o auditoría arquitectónica, invoca la skill **`sf-backend-architecture`** (modos: asesor de diseño / auditor de servicios — preguntar al usuario si ambiguo). Su auto-trigger tiene recall bajo, invócala explícitamente. Referencias en `.agents/skills/sf-backend-architecture/references/`:

- `HOUSE-STYLE.md` — carpetas, naming de ficheros, DI, Result, ESM.
- `CODE-STYLE.md` — naming a nivel código, idioma, `interface`/`type`, `any`, async, tests.
- `ANTI-PATTERNS.md` — olores conocidos del repo.
- `AUDIT-CHECKLIST.md` — checklist exhaustivo del modo auditor.
- `EVENTS-RABBITMQ.md` — publish/consume, routing keys, retries, DLX, outbox, idempotencia.

Lee solo la referencia que necesites; no las cargues todas por defecto.

Convenciones de contribución en [`CONTRIBUTING.md`](CONTRIBUTING.md).

@.claude/rules/code-style.md
@.claude/rules/git-conventions.md