@dsalazardev/ai-hub-cli 0.0.0-stage → 0.1.0

package/presets/angular-express/references/common-imports-catalog.md

@@ -0,0 +1,146 @@
+# Catálogo de imports `common` (desde el patrón `products`)
+
+> Inventario de lo que **products** importa de `common` y para qué sirve. Usar al implementar otros módulos (DRY).
+
+---
+
+## Backend — `backend/src/common/`
+
+### Domain
+
+| Símbolo | Ruta | Uso en products | Cuándo reutilizar |
+|---------|------|-----------------|-------------------|
+| `QueryListDto` | `domain/queryListDto.ts` | Base de `ProductsGetAllDto` | Todo listado paginado |
+| `QueryItemDto` | `domain/queryItemDto.ts` | Base de `ProductsGetByIdDto` | GET por id |
+| `QueryListResult<T>` | `domain/queryListResult.ts` | Retorno GetAll DAL | Listados |
+| `QueryItemResult<T>` | `domain/queryItemResult.ts` | Retorno GetById DAL | Detalle |
+| `SortOrder` | `domain/queryListDto.ts` | Orden ASC/DESC | Listados |
+| `Field`, `FieldType`, `FieldGenere`, `FieldSubType` | `domain/field-meta.ts` | Decoradores en DTOs | Formularios + Zod |
+| `AuthenticatedRequest` | `domain/AuthenticatedRequest.ts` | Router: session | Todos los routers |
+| `IQueryGetListDal` | `domain/IQueryGetListDal.ts` | `ProductsGetAllDal` | List DALs |
+| `IQueryGetItemDal` | `domain/IQueryGetItemDal.ts` | `ProductsGetByIdDal` | GetById DALs |
+| `IServiceDal` | `domain/IServiceDal.ts` | Create/Update/Delete DALs | Mutaciones |
+
+**Legacy (evitar en módulos nuevos)**:
+
+| Símbolo | Notas |
+|---------|-------|
+| `QueryRequest` | Usado en `catalogGetAllUseCase`, `servicesGetAllDal` legacy |
+| `IQueryGetAllPaginatedDal` | Patrón viejo multi-arg |
+
+### Infrastructure
+
+| Símbolo | Ruta | Uso en products |
+|---------|------|-----------------|
+| `DolibarrDal` | `infrastructure/dolibarr/dolibarrDal.ts` | GetAll, Create, Update, Delete |
+| `DolibarrClient` | `infrastructure/dolibarr/dolibarrClient.ts` | GetById (composición directa) |
+| `DolibarrMapper` | `infrastructure/dolibarr/dolibarrMapper.ts` | Base de todos los mappers |
+| `buildZodSchema` | `infrastructure/zodSchemas.ts` | Router POST/PUT/DELETE |
+| `pick` | `utils/rxjs-utils.ts` | Proyección `fields` en GetAll |
+
+**Helpers heredados vía `DolibarrDal`**:
+
+- `mapFiltersFromDomain(value, columns[])`
+- `combineSqlFilters(...filters)`
+- `mapStatusFilterFrom(status, column)`
+
+**`DolibarrClient.query2`** (vía `this.dolibarr`):
+
+- Paginación: `page`, `limit`, `pagination_data`
+- Sort: `sortfield`, `sortorder`
+- Filtros custom en `params`
+
+### Errores (fuera de `common/`, transversal)
+
+`backend/src/errors/domain/` — `ArgumentError`, `ForbiddenError`, etc. Usar en DALs y dejar propagar al middleware.
+
+---
+
+## Frontend — `frontend/src/app/common/`
+
+### Domain (espejo backend)
+
+| Símbolo | Uso en products |
+|---------|-----------------|
+| `QueryListDto` | `ProductsGetAllDto` |
+| `QueryItemDto` | `ProductsGetByIdDto` |
+| `QueryResult<T>` | Tipo retorno listado (`data` + `pagination`) |
+| `QueryItemResult<T>` | Retorno GetById |
+| `field-meta` | `@Field` en DTOs |
+| `SelectorResult` | Pipes `selector()` para enums |
+| `SelectorResponse` | Modal precios (selectores API) |
+| `nullToUndefined` | Normalización en modales |
+
+### Infrastructure — HTTP y bases
+
+| Símbolo | Ruta | Uso en products |
+|---------|------|-----------------|
+| `ApiDalService` | `api.dal.service.ts` | Todos los DALs |
+| `QueryBackendDal` | `dal/backend/queryBackendDal.ts` | GetAll, GetById |
+| `ServiceBackendDal` | `dal/backend/serviceBackendDal.ts` | Create, Update, ChangePrice |
+| `AppQueryBase` | `app-query-base.ts` | `ProductsGetAllComponent` |
+| `AppServiceBase` | `app-service-base.ts` | Create, Update |
+| `formGroupFromDto` | `formField.ts` | Vía bases: FormGroup desde DTO |
+
+**Métodos `ApiDalService` usados por products**:
+
+| Método | Operación |
+|--------|-----------|
+| `queryList(url, QueryListDto)` | GetAll |
+| `queryItem(url, QueryItemDto)` | GetById |
+| `post(url, body)` | Create |
+| `put(url, id, body)` | Update |
+| `delete(url, id)` | Delete |
+
+### Infrastructure — Componentes UI (listados)
+
+| Componente | Uso en products-getall |
+|------------|------------------------|
+| `kpi-card` | Total / Activos / Inactivos |
+| `card-header`, `card-empty` | Cabecera y vacío |
+| `col-icon`, `col-text`, `col-currency`, `col-empty`, `col-button` | Columnas tabla |
+| `form-field-text`, `form-submit` | Filtro búsqueda |
+| `confirm-dialog` | Confirmar borrado |
+
+### Infrastructure — Componentes UI (formularios)
+
+| Componente | Uso en create/update |
+|------------|---------------------|
+| `card-section` | Secciones del formulario |
+| `form-field-text`, `area`, `boolean`, `enum`, `number`, `euro` | Campos |
+| `form-button`, `form-submit`, `form-button-principal` | Acciones |
+
+### Guards
+
+| Guard | Módulo products |
+|-------|-----------------|
+| `canReadProductsGuard` | Listado |
+| `canCreateProductsGuard` | Create, Update |
+
+Definidos en `common/infrastructure/guards/commercial-module.guards.ts`.
+
+---
+
+## Matriz: qué va en `common` vs módulo
+
+| Va en `common` | Va en el módulo |
+|----------------|-----------------|
+| Paginación genérica (`QueryListDto`) | `Product`, `ProductsGetAllDto` |
+| `buildZodSchema`, `formGroupFromDto` | Campos `@Field` del recurso |
+| `DolibarrDal` helpers SQL | `ProductDolibarrDto`, mappers |
+| `ApiDalService` | `ProductsGetAllDal` |
+| `col-*`, `form-field-*`, `kpi-card` | Pipes `{entity}Status*` (ej. `productStatus*`, `userStatus*`) |
+| `AppQueryBase` | `ProductsGetAllComponent` |
+
+**Criterio KISS**: Si solo un módulo lo usa y no es genérico → **no** subir a common. Si 2+ módulos lo repetirían → valorar extraer (ej. parametrizar mensajes de `AppServiceBase`).
+
+---
+
+## Imports preferidos
+
+- Frontend cross-module: `@app/common/...`, `@app/products/...`
+- Backend: rutas relativas `../../common/...` desde `domain/` o `infrastructure/`
+
+---
+
+*Ampliar este catálogo cuando un módulo migrado importe algo nuevo de common que products no usa.*

package/presets/angular-express/references/fichajes-migration-notes.md

@@ -0,0 +1,57 @@
+# Fichajes → workdays + punches — Índice rápido
+
+> **No duplicar este archivo.** La fuente operativa es [`.planning/fichajes-migration-master-plan.md`](../../.planning/fichajes-migration-master-plan.md).
+>
+> **Estado**: planning completado — sin `/speckit.implement` hasta aprobación humana.
+
+---
+
+## Lectura obligatoria del agente
+
+1. [`.planning/fichajes-migration-master-plan.md`](../../.planning/fichajes-migration-master-plan.md) — decisiones, nombres, permisos, 9 changes, riesgos
+2. [`.planning/handoff_fichajes-migration.md`](../../.planning/handoff_fichajes-migration.md) — estado del programa
+3. Guías G2 (track fichajes, autocontenidas): `guia-migracion-monorepo2.md`, `backend/guia-migracion-backend2.md`, `frontend/guia-migracion-frontend2.md`
+4. Plantilla código: [products-module-blueprint.md](./products-module-blueprint.md)
+
+---
+
+## Decisiones cerradas (resumen)
+
+| Tema | Decisión |
+|------|----------|
+| Módulos | `workdays/` + `punches/`; eliminar `fichajes/` al final |
+| BFF | Corte duro `/api/workdays`, `/api/punches` |
+| Config (P5) | `PunchesConfig`, `PunchesConfigParam`, `PunchesConfigFlag` |
+| Permisos (P6) | `RightFichaje` en users; policies en common; **misma lógica que legacy** |
+| users-list (P3) | Facade hasta change 4; refactor KPIs en change 9 |
+| IDs dominio | `id: number` siempre (D21) |
+| `PunchType` | Un solo enum; manual incluido (D22); eliminar `RegistroManualAccionTipo` |
+| Entidad fichaje | `Punch` en inglés (D23) |
+| Auditoría modificados | `workdays/domain/` (D24) |
+| Paginación workdays | Igual que products / `QueryListDto` (D27) |
+| `punch-card` | Permanece en `common/` (D28) |
+| Enriquecimiento pausas | Helper `application/` + batch eventos (D25); no DAL `EnrichBreaks` |
+| Filtro empleados | Criterio employees users (D26); refactor `entityUsersScope` |
+| Export | Motor `common/`; helper `WorkdaysService` (patrón actual) |
+
+---
+
+## Clasificación
+
+| Aspecto | Valor |
+|---------|-------|
+| Perfil | **Híbrido** — workdays listado tipo products; punches acciones + service layer |
+| Referencia listado | `products-getall` + `users-list` (employees) |
+| Primer change | `migrate-workdays-getall` (opcional previo: `fix-app-query-base-products-strings`) |
+
+---
+
+## Enlaces legacy (solo exploración)
+
+| Qué | Dónde |
+|-----|-------|
+| Routes BFF | `backend/routes/fichajes.ts`, `backend/routes/jornadas.ts` |
+| FE monolito | `frontend/src/app/fichajes/` |
+| Permisos dominio | `backend/src/users/domain/rightFichaje.ts` |
+
+Detalle de endpoints, mapa ES→EN, DALs objetivo y complicaciones: **solo en el planning maestro**.

package/presets/angular-express/references/module-implementation-flow.md

@@ -0,0 +1,260 @@
+# Flujo de implementación paso a paso (módulos tipo `products`)
+
+> **Objetivo**: Guía ordenada para que un agente implemente un módulo (nuevo o migrado) sin perder contexto ni romper contratos FE↔BE.
+>
+> **Referencia canónica**: [products-module-blueprint.md](./products-module-blueprint.md)
+>
+> **Regla de mantenimiento**: Si este flujo cambia, actualizar este archivo **y** el blueprint. No dejar documentos contradictorios.
+
+---
+
+## Principios del flujo
+
+1. **Contrato primero, código después** — El dominio y los DTOs definen qué se construye; el resto los consume.
+2. **Backend antes que frontend** en cada vertical (salvo que el spec diga lo contrario).
+3. **Una operación = un DAL = un DTO de entrada** (patrón products).
+4. **Verificar tras cada fase** (`tsc`, `ng build`, tests del slice).
+5. **No inventar** — Si falta endpoint, campo Dolibarr o permiso: **preguntar al usuario**.
+6. **KPIs en listados**: patrón `products-getall` (`statusCounts` + `KpiCardComponent` + pipes del módulo).
+7. **Regla de paridad products**: lo general igual que `products`; solo cambian entidad, enums, campos, endpoints y operaciones del dominio ([blueprint §0.1](./products-module-blueprint.md#01-regla-de-paridad-products-general-igual-datos-distintos)).
+
+---
+
+## Perfiles de módulo
+
+| Perfil | Ejemplo | Operaciones típicas |
+|--------|---------|---------------------|
+| **A — CRUD Dolibarr nativo** | `products`, `users/employees` | GetAll, GetById, Create, Update, Delete |
+| **B — API custom + acciones** | `fichajes` | Clock-in/out, breaks, manual entry + CRUD workdays |
+| **C — Transversal** | `users` (auth, rights) | Login, me, policies; no forzar patrón CRUD puro |
+
+Cada módulo puede **extender** el perfil A con operaciones extra (ej. `ProductsChangePriceDal`). Las extensiones se documentan en el spec del módulo.
+
+---
+
+## Fase 0 — Nutrición (solo lectura, sin código)
+
+**Entrada**: nombre del módulo, spec Spec Kit aprobada (o borrador para explorar).
+
+**Leer obligatoriamente**:
+
+| Orden | Qué leer |
+|-------|----------|
+| 1 | [products-module-blueprint.md](./products-module-blueprint.md) |
+| 2 | [common-imports-catalog.md](./common-imports-catalog.md) |
+| 3 | Código canónico de `products` (lista en blueprint §10) |
+| 4 | `backend/doc/swagger.json` — endpoints Dolibarr del recurso |
+| 5 | Anexo del módulo si existe: `fichajes-migration-notes.md`, `users-migration-notes.md` |
+| 6 | Módulo legacy actual (si es migración) — inventario de archivos y rutas |
+
+**Salida escrita** (en `.planning/` o en el change Spec Kit):
+
+- `findings.md` — endpoints reales, campos Dolibarr, permisos, deuda legacy
+- `entity-map.md` — nombres ES→EN si aplica (fichajes)
+- Lista de operaciones → DTOs → DALs (tabla)
+
+**Criterio de salida**: tabla operaciones/DTOs aprobada (usuario o spec).
+
+---
+
+## Fase 1 — Dominio compartido (FE + BE en paralelo conceptual)
+
+> Tu intuición de empezar por `domain` es correcta. Es la **primera fase de código**, pero hay un paso previo (Fase 0) y un orden interno.
+
+### 1.1 Entidad principal
+
+- Crear `domain/{entity}.ts` — `interface` con camelCase.
+- **Solo `id: number` es obligatorio** — **nunca** `id?: number` en `domain/` (FE ni BE). El resto de propiedades con `?`.
+- Verificación: `rg "id\?:" backend/src/{modulo}/domain frontend/src/app/{modulo}/domain` → **0 coincidencias** (salvo comentarios).
+- Si el listado es una proyección (ej. `EmployeeListItem` vs `User` completo), documentar en el spec; el mapper sigue el patrón `{Entity}Mapper`.
+- Enums de negocio en `domain/enums/{name}.ts` (no `Enumerations/` PascalCase).
+- **Backend y frontend: archivos espejo** (mismo contenido, distintos imports relativos).
+
+### 1.2 DTOs por operación
+
+Crear en este orden (dependencias de herencia):
+
+| Orden | Archivo | Extiende |
+|-------|---------|----------|
+| 1 | `{Entity}sUpdateDto` | — (campos con `@Field`) |
+| 2 | `{Entity}sCreateDto` | `UpdateDto` (si aplica mismo formulario) |
+| 3 | `{Entity}sGetAllDto` | `QueryListDto` + filtros `@Field` |
+| 4 | `{Entity}sGetByIdDto` | `QueryItemDto` |
+| 5 | `{Entity}sDeleteDto` | `id` mínimo |
+| 6 | DTOs de **acciones** extra | Según spec (fichajes: `PunchesClockInDto`, `WorkdaysGetAllDto`, etc.) |
+
+**Reglas `@Field`**:
+
+- `label` en español
+- `type`, `required`, `min`, `max`, `enumType` según campo
+- Labels alimentan Zod (BE) y `FormGroup` (FE)
+
+### 1.3 Verificación Fase 1
+
+- [ ] Sin `any`
+- [ ] FE y BE: mismos nombres de propiedades en DTOs y entidad
+- [ ] Enums idénticos en ambos lados
+- [ ] `npx tsc --noEmit` (BE) si ya hay tsconfig que incluye domain
+- [ ] No crear aún DALs ni componentes
+
+**Por qué antes que DAL**: Los DALs y routers **solo importan** tipos de dominio. Cambiar dominio después rompe mappers y formularios.
+
+---
+
+## Fase 2 — Infraestructura backend (por operación)
+
+### 2.1 DTO Dolibarr + mappers
+
+| Orden | Artefacto |
+|-------|-----------|
+| 1 | `infrastructure/dal/dolibarr/{entity}DolibarrDto.ts` — snake_case, shape API |
+| 2 | `mappers/{entity}Mapper.ts` — `toDomain` / `fromDomain` |
+| 3 | Mappers de enum si hace falta | `ProductStatusMapper` pattern |
+
+### 2.2 DALs (uno por operación)
+
+Implementar en este orden recomendado:
+
+| Orden | DAL | Por qué este orden |
+|-------|-----|-------------------|
+| 1 | **GetById** | Valida mapper con un solo registro |
+| 2 | **GetAll** | El más complejo; reutiliza mapper |
+| 3 | **Create** | `fromDomain` → Dolibarr |
+| 4 | **Update** | Igual |
+| 5 | **Delete** | Mínimo |
+| 6 | **Acciones** custom | Fichajes: clock-in, etc. |
+
+Cada DAL: `run(request: XxxDto): Promise<...>` + interfaz `IQueryGetListDal` / `IQueryGetItemDal` / `IServiceDal`.
+
+### 2.3 Router + DI
+
+| Orden | Tarea |
+|-------|-------|
+| 1 | `infrastructure/router/{entity}Router.ts` |
+| 2 | `requireHttpRight` con policy del módulo |
+| 3 | `buildZodSchema` en POST/PUT/DELETE |
+| 4 | Registrar DALs en `container.ts` (`Lifetime.SCOPED`) |
+| 5 | Montar en `server.ts` |
+
+### 2.4 Verificación Fase 2
+
+```bash
+cd backend && npx tsc --noEmit
+cd backend && npm test -- tests/{modulo}   # cuando existan
+```
+
+Probar manualmente o con supertest: GetById → GetAll → Create (si spec lo incluye).
+
+---
+
+## Fase 3 — Infraestructura frontend
+
+### 3.1 DALs (`infrastructure/dal/backend/`)
+
+Mismo orden que backend:
+
+1. `GetByIdDal` → `api.queryItem`
+2. `GetAllDal` → `api.queryList`
+3. `CreateDal` / `UpdateDal` / `DeleteDal` → `ServiceBackendDal`
+
+### 3.2 Pipes de dominio (si hay enums en UI)
+
+- `{entity}StatusLabel`, `Color`, `Icon` + método `selector()` para selects.
+
+### 3.3 Componentes (orden UI)
+
+| Orden | Componente | Base |
+|-------|------------|------|
+| 1 | `{entity}s-getall` | `AppQueryBase` |
+| 2 | `{entity}s-create` | `AppServiceBase` |
+| 3 | `{entity}s-update` | `AppServiceBase` + `loadDal` |
+| 4 | Modales / acciones extra | Según spec |
+
+**Listado (KPIs frontend — patrón products)**:
+
+- `items = signal<Entity[]>([])`
+- `statusCounts = signal<Partial<Record<StatusEnum, number>>>({})`
+- Tras cada `load()`, agrupar `response.data` con RxJS `groupBy` + `reduce` (copiar de `products-getall.ts`)
+- Tarjeta «Total»: `[value]="items().length"` + `[total]="request().total"`
+- UI: `KpiCardComponent` + pipes `{entity}StatusLabel|Color|Icon`
+- Filtro por tarjeta: `setStatus()` → actualiza `request().status` + `load()`
+- **Prohibido**: requests HTTP extra solo para KPIs; **prohibido** leer `stats` del BFF
+
+### 3.4 Rutas
+
+- Añadir en `app.routes.ts`: rutas estáticas (`create`) **antes** de `:id`
+- Guards desde `common/guards/`
+
+### 3.5 Verificación Fase 3
+
+```bash
+cd frontend && ng build
+```
+
+---
+
+## Fase 4 — Integración y cierre
+
+- [ ] Flujo E2E manual documentado en `progress.md`
+- [ ] Tests mínimos (DAL BE, routes BE, DAL FE críticos)
+- [ ] Eliminar o marcar deprecated archivos legacy del módulo
+- [ ] Actualizar anexo de migración del módulo
+- [ ] `/speckit.converge` cuando spec completo
+
+---
+
+## Migración vs módulo nuevo
+
+| Aspecto | Módulo nuevo | Migración (fichajes, users) |
+|---------|--------------|----------------------------|
+| Fase 0 | Swagger + spec | + inventario legacy + mapa renombres |
+| Fase 1 | Crear domain | Renombrar/mover domain; aliases temporales si spec lo pide |
+| Rutas BFF | Solo inglés | Decidir: ¿mantener rutas ES con deprecation? (preguntar) |
+| Código legacy | No existe | Convivencia hasta fase 4; no borrar sin spec |
+
+**Estrategia recomendada para migraciones grandes** (fichajes):
+
+1. **Vertical por feature**: ej. primero `workdays` listado+detalle, luego punch actions, luego config.
+2. **No renombrar todo el módulo en un solo PR** — el spec debe trocear por Spec Kit changes.
+
+---
+
+## Qué NO hacer en medio del flujo
+
+- No crear componentes antes de DTOs
+- No definir tipos en `routes/` o componentes
+- No duplicar lógica de filtros SQL fuera de `DolibarrDal`
+- No usar `application/services` en FE si el patrón products usa `AppQueryBase` / `AppServiceBase`
+- No registrar en Awilix hasta tener el DAL con constructor `(dolikey, entityId)`
+
+---
+
+## Diagrama resumen
+
+```
+Fase 0: Leer products + common + swagger + legacy
+           ↓
+Fase 1: domain/{entity}.ts + enums + DTOs (FE espejo BE)
+           ↓
+Fase 2: BE: DolibarrDto → mappers → DALs → router → container
+           ↓ verify tsc
+Fase 3: FE: DALs → pipes → componentes → rutas
+           ↓ verify ng build
+Fase 4: Tests, limpieza legacy, archive
+```
+
+---
+
+## Documentos relacionados
+
+| Archivo | Contenido |
+|---------|-----------|
+| [products-module-blueprint.md](./products-module-blueprint.md) | Patrón completo products |
+| [common-imports-catalog.md](./common-imports-catalog.md) | Qué importar de common |
+| [replicate-module-checklist.md](./replicate-module-checklist.md) | Checklist corto |
+| [fichajes-migration-notes.md](./fichajes-migration-notes.md) | Fichajes: nombres, subdominios, endpoints |
+| [users-migration-notes.md](./users-migration-notes.md) | Users: auth, employees, transversal |
+
+---
+
+*Actualizar este documento cuando se valide un flujo distinto en un módulo real (fichajes/users).*

package/presets/angular-express/references/products-coding-standard.md

@@ -0,0 +1,143 @@
+# Estándar de código — paridad products / services
+
+> **Audiencia**: todo agente que escriba o revise código en Doligestion.
+> **Fuente de verdad**: el código de `products` y `services` (mismo esqueleto). Si este doc y el código canónico divergen, **manda el código de products/services** y luego actualiza este archivo.
+> **Complementa**: [products-module-blueprint.md](./products-module-blueprint.md) (esqueleto de módulo), [replicate-module-checklist.md](./replicate-module-checklist.md).
+> **Última revisión**: 2026-09-17
+
+---
+
+## 0. Regla de oro
+
+1. **Copiar el patrón general de products/services.** Solo cambian entidad, campos, enums, endpoints y reglas de negocio del módulo.
+2. **Si no sabes el tipo, valor o forma de un dato: pregunta al usuario.** Prohibido inventar uniones (`string | number`), opcionales “por si acaso”, o magic strings.
+3. **Módulos custom** (p. ej. `projectsonna`, fichajes API propia) pueden tener endpoints y DALs distintos, pero **naming, carpetas, `id`, enums, `@Field`, dominio FE≡BE y Zero-Any** siguen este estándar.
+
+---
+
+## 1. `id` — invariante
+
+| Capa | Regla |
+|------|--------|
+| `domain/` (FE y BE) | `id: number` **siempre**. **Sin** `?`. Es el **único** campo obligatorio de la entidad; el resto con `?`. |
+| `*DolibarrDto` (infra) | Igual que products/services: `id: number` **sin** `?`. Dolibarr a veces envía `"1"` como string en JSON: el **mapper** hace `Number(item.id)`. |
+| Prohibido | `id?: …`, `id: number \| string`, `id: string` en dominio limpio, `id: string \| number`. |
+
+```typescript
+// Correcto (domain + DolibarrDto)
+id: number;
+
+// Incorrecto
+id?: number;
+id: number | string;
+id: string; // en domain limpio
+```
+
+---
+
+## 2. Tipos: no adivinar
+
+- **Prohibido** uniones “por incertidumbre” (`string | number`, `A | B` en un campo de dominio) salvo que el contrato de negocio lo exija y esté en el spec.
+- Si la API real no está clara → **preguntar** o mirar respuesta real / swagger; no tipar a ciegas.
+- Zero-Any: usar `unknown` + type guard solo en fronteras externas cuando haga falta.
+- Campos opcionales: solo si el dominio/API realmente los omiten → `campo?: Tipo` (nunca mezclar con uniones inventadas).
+
+---
+
+## 3. Enums y magic strings
+
+- Estados / tipos de negocio **numéricos** (como Dolibarr): `enum` **numérico** en `domain/enums/` (ej. `ProductStatus { Inactive = 0, … }`).
+- **Prohibido** magic strings sueltos en filtros SQL, comparaciones de estado, query params de negocio (`'open'`, `'1'` hardcodeado) → usar el enum.
+- Enum **string** solo cuando el contrato real es código string estable (ej. roles de contacto `BILLING`) y products/el módulo de referencia ya lo hace así; documentarlo en el spec.
+- Constantes nombradas para límites, paths de segmento fijo (`'selector'`), etc., cuando se reutilicen.
+
+---
+
+## 4. Classes con `@Field` vs interfaces
+
+| Artefacto | Forma | Dónde |
+|-----------|--------|--------|
+| Entidad de dominio (`Product`, `Project`) | `interface` | `domain/{entity}.ts` |
+| DTO de query/comando (GetAll, Create, Update…) | `class` + `@Field({…})` | `domain/{resource}{Op}Dto.ts` |
+| Shape cruda Dolibarr | `interface` | `infrastructure/dal/dolibarr/{entity}DolibarrDto.ts` |
+| Shape cruda liviana (selector) | `interface` | `…/{entity}SelectorDolibarrDto.ts` (mismo estilo que `productDolibarrDto`) |
+| Selector de UI BFF | `SelectorDto` (`id` + `description`) | `common/domain/selectorDto` — no inventar otro shape |
+
+- `@Field` lleva `label` en **español** (UI); identificadores en **inglés**.
+- DTOs FE y BE **idénticos** (mismas propiedades y `@Field`); solo cambian imports (`@app/…` vs relativos).
+
+---
+
+## 5. Naming y ubicación de archivos
+
+### Backend (`backend/src/{module}/`)
+
+```
+domain/
+  {entity}.ts                 # interface
+  enums/{Entity}Status.ts
+  {resources}GetAllDto.ts     # class + @Field
+  {resources}CreateDto.ts
+infrastructure/
+  dal/dolibarr/
+    {entity}DolibarrDto.ts
+    {entity}SelectorDolibarrDto.ts   # si hay selector liviano
+    {resources}GetAllDal.ts
+    {resources}SelectorDal.ts        # GET …/selector
+    mappers/{entity}Mapper.ts
+  router/{resources}Router.ts
+```
+
+- Recurso plural en DALs/rutas: `productsGetAllDal`, `projectsSelectorDal`.
+- Entidad singular en DTO Dolibarr: `productDolibarrDto`, `projectSelectorDolibarrDto`.
+- Selectores: ruta estática `GET /selector` **antes** de `/:id`; respuesta `SelectorDto[]`; **sin** N+1 ni stats de listado.
+
+### Frontend (`frontend/src/app/{module}/`)
+
+```
+domain/          # espejo del backend
+infrastructure/
+  dal/backend/{resources}GetAllDal.ts
+  dal/backend/{resources}SelectorDal.ts
+  components/{resources}-getall/
+```
+
+- Dominio FE ≡ BE (paridad de ficheros y tipos).
+- Español solo en labels `@Field` y texto de plantillas.
+
+---
+
+## 6. Capas (Clean Architecture)
+
+- Tipos **solo** en `domain/` (o DTO Dolibarr en `dal/dolibarr/`). Routes/components **importan**, no declaran interfaces de negocio.
+- DALs G2: un caso de uso ≈ un DAL + `run()`.
+- Listado rico (`GetAll` + stats/paginación) **≠** selector (`SelectorDal`). No un boolean “includeX” que mezcle responsabilidades caras.
+- Mapper: frontera snake_case → camelCase; `Number(id)`; sin lógica de UI.
+
+---
+
+## 7. Checklist rápido (antes de marcar hecho)
+
+- [ ] ¿Existe el mismo patrón en `products` o `services`? Si sí, ¿lo copié?
+- [ ] ¿`id: number` sin `?` en domain y DolibarrDto?
+- [ ] ¿Sin `number | string` / uniones inventadas?
+- [ ] ¿Enums numéricos para estados; sin magic strings de negocio?
+- [ ] ¿DTOs = `class` + `@Field`; entidades = `interface`?
+- [ ] ¿Dominio FE alineado byte-a-byte con BE?
+- [ ] ¿Naming/ubicación como la tabla de la §5?
+- [ ] ¿Si dudé de un tipo/campo, pregunté en lugar de inventar?
+
+---
+
+## 8. Referencias canónicas (abrir el código)
+
+| Qué | Dónde |
+|-----|--------|
+| Entidad + id | `backend/src/products/domain/product.ts` |
+| DTO `@Field` | `backend/src/products/domain/productsGetAllDto.ts` ≡ FE |
+| Enum numérico | `backend/src/products/domain/enums/productStatus.ts` |
+| DolibarrDto | `backend/src/products/infrastructure/dal/dolibarr/productDolibarrDto.ts` |
+| DAL listado | `…/productsGetAllDal.ts` |
+| Services (paridad) | `backend/src/services/`, `frontend/src/app/services/` |
+| Selector (terceros/users) | `thirdpartiesSelectorDal`, `usersSelectorDal`, `GET /selector` |
+| Blueprint módulo | [products-module-blueprint.md](./products-module-blueprint.md) |