69 lines
4.3 KiB
Markdown
69 lines
4.3 KiB
Markdown
|
# 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
|