sf-sim/CLAUDE.md

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.

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