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

package/presets/angular-express/skills/onna-architecture-angular/SKILL.md

@@ -0,0 +1,229 @@
+---
+name: onna-architecture-angular
+description: Define la arquitectura específica del frontend Angular en Onna/Doligestion. Activa este skill al crear o modificar componentes, servicios, DALs, guards, interceptors o cualquier fichero TypeScript del frontend. Complementa los skills angular-developer, angular-new-app y onna-architecture-common con las decisiones propias del cliente Angular.
+license: MIT
+---
+
+# Onna Angular Architecture Guidelines
+
+Decisiones arquitectónicas propias del frontend Angular de Onna/Doligestion.
+
+- Para buenas prácticas generales de Angular (signals, forms, routing, DI, testing, CLI): ver skill `angular-developer`.
+- Para el contrato compartido con el BFF (dominio, errores, comunicación): ver skill `onna-architecture-common`.
+- Para convenciones visuales de ventanas, formularios y listados: ver skill `onna-design-system`.
+
+## Estructura de Carpetas
+
+```
+src/app/
+  <dominio>/               → Una carpeta por entidad (products, invoices, fichajes...)
+    domain/                → Interfaces, tipos, enumeraciones (idénticos al backend)
+    application/           → Application services (lógica de caso de uso)
+    infrastructure/
+      dal/                 → Clases DAL: acceso al BFF, una por caso de uso
+        <resources>.dal.ts
+      components/          → Componentes Angular, uno por subcarpeta
+        <resources>-create/
+        <resources>-update/
+        <resources>-retrieve/
+      <resources>.service.ts  → Service que orquesta los DALs
+```
+
+Las carpetas de dominio son solo agrupadores. Ningún `.ts`, `.html` o `.css` de componente se coloca en la raíz — cada componente vive en su propia subcarpeta.
+
+Dentro de `infrastructure/` la separación es estricta:
+- `dal/` — solo clases DAL que se comunican con el BFF. Ningún componente ni lógica de UI aquí.
+- `components/` — solo componentes Angular. Ninguna llamada directa a la API aquí.
+
+## Capa DAL (Data Access Layer)
+
+El componente nunca llama directamente a la API — siempre a través de `DAL → Service`.
+
+- Los DALs viven en `infrastructure/dal/`
+- Naming: `<resources>.dal.ts` (ej. `products.dal.ts`)
+- Para casos de uso separados: `products-create.dal.ts` / `products-update.dal.ts`
+- Los DALs se inyectan en los application services, no en los componentes directamente.
+
+## Reglas de Tipado
+
+- **Zero-Any Policy**: prohibido `any`. TypeScript estricto en todos los ficheros.
+- Las interfaces de dominio viven en `<entidad>/domain/` y deben ser idénticas a las del backend (ver `onna-architecture-common`).
+- Los tipos auxiliares de UI (`*Pagination`, `*ListResponse`, `*Stats`, payloads de formulario) pueden vivir en `domain/` pero en ficheros separados de la entidad principal.
+
+## Diseño responsive — Mobile First
+
+Toda la interfaz debe ser responsive. El diseño se construye primero para móvil y se adapta al escritorio con media queries o directivas de breakpoint de Angular Material.
+
+- **Móvil**: los listados se muestran como **cards independientes**, una por elemento.
+- **Escritorio**: los listados se muestran como **tabla** (`mat-table`).
+- Usar `@if` con un breakpoint observer para alternar entre ambas vistas dentro del mismo componente.
+
+## Convenciones de listados
+
+### Paginación
+
+- El tamaño de página por defecto es **50 elementos**.
+- Las opciones de página disponibles son siempre: `[10, 25, 50, 100, 250, 500, 1000]`.
+
+```typescript
+readonly pageSizeOptions = [10, 25, 50, 100, 250, 500, 1000];
+readonly defaultPageSize = 50;
+```
+
+### Columna de estado (primera columna)
+
+La primera columna de toda tabla no tiene cabecera y representa el **estado y tipo** del objeto listado mediante un icono con color.
+
+- El color se obtiene de un **pipe** que recibe el objeto y devuelve un string de color.
+- El icono se obtiene de otro **pipe** independiente que recibe el objeto y devuelve el nombre del icono Material.
+- El icono debe llevar un `matTooltip` que explique su significado al usuario.
+
+```typescript
+// Ejemplo de pipes
+@Pipe({ name: 'productStatusColor', standalone: true })
+export class ProductStatusColorPipe implements PipeTransform {
+  transform(product: Product): string { ... }
+}
+
+@Pipe({ name: 'productStatusIcon', standalone: true })
+export class ProductStatusIconPipe implements PipeTransform {
+  transform(product: Product): string { ... }
+}
+```
+
+```html
+<!-- Primera columna sin cabecera -->
+<ng-container matColumnDef="status">
+  <th mat-header-cell *matHeaderCellDef></th>
+  <td mat-cell *matCellDef="let row">
+    <mat-icon
+      [style.color]="row | productStatusColor"
+      [matTooltip]="row | productStatusIcon | productStatusTooltip">
+      {{ row | productStatusIcon }}
+    </mat-icon>
+  </td>
+</ng-container>
+```
+
+### Columna de acciones (última columna)
+
+La última columna contiene los **iconos de acción** que redirigen a las operaciones disponibles sobre el elemento.
+
+- Cada icono debe llevar un `matTooltip` que describa la acción.
+- Usar los iconos estándar definidos en `onna-design-system` (`visibility`, `edit`, `add`, `delete` con `action-btn-delete`).
+- No mostrar texto, solo iconos.
+
+```html
+<ng-container matColumnDef="actions">
+  <th mat-header-cell *matHeaderCellDef></th>
+  <td mat-cell *matCellDef="let row">
+    <button mat-icon-button [routerLink]="['/products', row.id]" matTooltip="Ver detalle">
+      <mat-icon>visibility</mat-icon>
+    </button>
+    <button mat-icon-button [routerLink]="['/products', row.id]" matTooltip="Editar">
+      <mat-icon>edit</mat-icon>
+    </button>
+    <button mat-icon-button (click)="onDelete(row)" matTooltip="Eliminar" class="action-btn-delete">
+      <mat-icon>delete</mat-icon>
+    </button>
+  </td>
+</ng-container>
+```
+
+## Estructura interna de componentes create/update
+
+Aplica **solo** a componentes `*-create`/`*-update` (formulario de un único registro, Signal Forms, extendiendo `AppServiceSignalBase`). No aplica a listados (`*-getall`), vistas de detalle de solo lectura, diálogos, ni ningún otro tipo de componente — esos no siguen esta estructura de secciones.
+
+Todo componente `*-create`/`*-update` organiza sus miembros de clase en el siguiente orden, cada bloque precedido por su comentario de sección. El objetivo es que cualquier componente de este tipo se lea igual, independientemente del dominio.
+
+```typescript
+export class ProductsUpdateComponent extends AppServiceSignalBase<...> {
+  // #region DALs
+  private productsUpdateDal = inject(ProductsUpdateDal);
+  private categoriesGetAllDal = inject(CategoriesGetAllDal);
+  // #endregion
+
+  // #region Services
+  private companyService = inject(CompanyService);
+  // #endregion
+
+  // #region Other members
+  private dialog = inject(MatDialog);
+  protected globalInfo = inject(GlobalInfoService);
+  private emailDal = inject(EmailDal);
+  // (router, route, snackBar ya vienen heredados de AppBase/AppServiceSignalBase — no
+  // se redeclaran aquí salvo que el comportamiento por defecto no sirva, ver más abajo)
+  // #endregion
+
+  // #region Model
+  isLoading = signal<boolean>(false);
+  // #endregion
+
+  // #region Forms
+  protected override configureSchema(p: SchemaPathTree<ProductFormModel>): void {
+    required(p.name, { message: 'El nombre es obligatorio' });
+    ...
+  }
+  // #endregion
+
+  // #region Related categories
+  categories = signal<Category[]>([]);
+  categoryOptions = computed<SelectorResult[]>(() =>
+    this.categories().map((c) => ({ value: c.id, label: c.name })),
+  );
+  private loadCategories(): void {
+    this.categoriesGetAllDal.getAll().subscribe({
+      next: (data) => this.categories.set(data),
+      error: () => this.showSnackBar('Error al cargar categorías', 'Cerrar'),
+    });
+  }
+  // #endregion
+
+  // #region Constructor / onInit / onDestroy
+  constructor() {
+    super(new ProductFormModel());
+  }
+
+  override ngOnInit(): void {
+    super.ngOnInit();
+    this.loadCategories();
+  }
+  // #endregion
+
+  // #region Actions
+  protected override onSave(): void { ... }
+  protected override onCancel(): void { ... }
+  onDeleteClick(): void { ... }
+  // #endregion
+}
+```
+
+Cada sección va envuelta en `// #region <Nombre>` / `// #endregion` (folding region nativo de VS Code, sin extensión ni equivalencia a JSDoc) para poder colapsarla en el editor — mismo comentario que hace de cabecera de sección, solo que ahora abre y cierra el bloque plegable.
+
+Reglas del orden:
+
+0. **Herencia obligatoria de `AppServiceSignalBase`** — todo componente `*-create`/`*-update` que use Signal Forms extiende `AppServiceSignalBase<TModel, T, TPayload>` (`frontend/src/app/common/infrastructure/app-service-signal-base.ts`), nunca reimplementa `model`/`fieldTree`/`onSave`/`load` desde cero. Si el flujo del componente no encaja 1:1 con el contrato genérico de la base (múltiples DAL de transición de estado, modo lectura/edición conmutable, `onSave` con lógica propia), se hereda igualmente solo para lo que sí encaja — como mínimo `model`/`fieldTree` vía `configureSchema()` — y el resto de métodos (`onSave`, `load`, etc.) se sobreescriben con `override` en vez de duplicarse fuera de la jerarquía. Ver `proposal-update.ts` como referencia de una herencia parcial bien resuelta (`model`/`fieldTree` heredados; `proposal`, `isLoading`, `isEditing`, `loadProposal()`, `onSave()` propios).
+1. **DALs** — todas las inyecciones de clases `*Dal`, agrupadas primero.
+2. **Services** — application services u otros servicios de dominio inyectados (`CompanyService`, `GlobalInfoService` si el componente lo trata como servicio de negocio, no como utilidad transversal).
+3. **Other members** — el resto de inyecciones que no encajan arriba: `MatDialog` y cualquier referencia a diálogos, `GlobalInfoService` como utilidad transversal, `EmailDal`, `Injector`, etc. `router`, `route`, `snackBar`, `isMobile`, `onCancel` ya existen en `AppBase`/`AppServiceSignalBase`: no se re-inyectan ni redeclaran con el mismo nombre — se usan tal cual (`this.router`, `this.getId()`, `this.showSnackBar(...)`). Si el comportamiento heredado no encaja (breakpoint distinto, snackbar con opciones no soportadas), se resuelve extendiendo la base compartida, nunca duplicando el campo con otro nombre ad-hoc por componente.
+4. **Model** — signals de estado propio del componente que no son el modelo de formulario ni un catálogo relacionado (`model`/`fieldTree` ya los aporta la base): flags (`isLoading`, `isEditing`), estado de UI propio de la pantalla.
+5. **Forms** — `configureSchema()` (validadores del `SchemaPathTree`) y cualquier lógica de formulario adicional.
+6. **Related `<nombre>`** — una subsección `#region`/`#endregion` por catálogo relacionado (`// #region Related clients`, `// #region Related products`, `// #region Related projects`...), cada una con TODO lo de ese catálogo junto: el signal fuente (`clients = signal<...>([])`), su(s) `computed` derivado(s) (`clientsList`, `clientOptions`, `productsOptions`/`servicesOptions` cuando derivan de un mismo signal, etc.) y su `load*()` privado — en ese orden, sin repartir el signal en «Model» y el resto en otra sección. Tantas subsecciones «Related» como catálogos tenga el componente.
+7. **Constructor / onInit / onDestroy** — `super(...)` y suscripciones/`effect()` que deban existir desde la construcción, junto con el ciclo de vida Angular (`ngOnInit`/`ngOnDestroy`). Una única región: ambos bloques son inicialización del componente, solo que en momentos distintos del ciclo de vida.
+8. **Actions** — `onSave`, `onCancel`, y cualquier acción disparada por botón del template (`onDeleteClick`, `onValidateClick`, etc.). `load()` (si se sobreescribe) y los helpers transversales sin acción propia asociada (`formatCurrency`, `formatDate`, `onBackToList`, `canManageProposal`) van sueltos, sin subregión. Cuando el componente tiene varias acciones de botón independientes (típico en `*-update` con workflow de estados: validar, aceptar, rechazar, convertir...), cada una se envuelve en su propia subsección `// #region Action <nombre>` que agrupa TODO lo de esa acción junto — el `xxxClick()` que abre el diálogo de confirmación, el `onXxx()` que hace la llamada al DAL, y cualquier `canXxx` que solo esa acción consulta — en vez de repartir click/handler/condición en puntos distintos del archivo. Si un `can*` condiciona más de una acción a la vez (p. ej. `canConvertProposal()` usado tanto por `createOrderClick` como por `createInvoiceClick`), vive en su propia subsección compartida (`// #region Action convertProposal`) en vez de duplicarse o adjuntarse arbitrariamente a una sola. Ver `proposal-update.ts` como referencia. En componentes sin ese patrón de múltiples acciones de workflow (p. ej. `*-create`, con un único flujo de guardado), no se fuerzan subregiones — la lista plana ya es clara.
+
+## Nomenclatura
+
+Regla general: **inglés y plural** en todo el código, salvo el dominio que es **inglés y singular**.
+
+| Artefacto | Forma | Ejemplo |
+|---|---|---|
+| Carpeta de entidad | plural | `products/`, `invoices/` |
+| Rutas URL | plural | `/products`, `/products/create` |
+| Componentes | plural | `products-retrieve`, `products-create` |
+| DALs | plural | `products.dal.ts` |
+| Services | plural | `products.service.ts` |
+| Application services | plural | `products-create.service.ts` |
+| Interfaces de dominio | singular | `Product`, `Invoice` |
+| Clases de dominio | singular | `Product`, `BomLine` |
+| Enumeraciones | singular | `ProductStatus`, `InvoiceType` |

package/presets/angular-express/skills/onna-architecture-bff/SKILL.md

@@ -0,0 +1,446 @@
+---
+name: onna-architecture-bff
+description: Define la arquitectura específica del BFF (Node.js + Express) de Onna/Doligestion. Activa este skill al crear o modificar rutas, middleware, DALs o cualquier fichero TypeScript del backend. Complementa onna-architecture-common con las decisiones propias del BFF.
+license: MIT
+---
+
+# Onna BFF Architecture Guidelines
+
+Decisiones arquitectónicas propias del BFF (Node.js + Express). Para el contrato compartido con el frontend (dominio, DTOs, errores): ver `onna-architecture-common`.
+
+## Rol del BFF
+
+Orquestador entre Angular y Dolibarr/Kubernetes. Es el único punto de entrada desde el frontend:
+- Inyecta el `dolikey` (API key de Dolibarr) en todas las peticiones salientes — nunca expuesto al frontend.
+- Gestiona autenticación mediante cookies `httpOnly`, `secure`, `SameSite: Strict`.
+- Tiene dos funciones muy imporntes:
+  - Recibe la llamada con el router de Nodejs + Express desde el frontend
+  - Transforma respuestas crudas de Dolibarr (PHP snake_case) en interfaces de dominio tipadas y envia las llamadas a los métodos de dolibarr a través de sus DTOs.
+
+## Estructura de carpetas
+
+```
+src/
+  <dominio>/
+    domain/                        → Interfaces, enums, DTOs (= frontend, ver onna-architecture-common)
+    infrastructure/
+      dal/dolibarr/
+        <entidad>DolibarrDto.ts    → Shape crudo de la respuesta de Dolibarr
+        <Entidad>GetAllDal.ts      → extends DolibarrDal, implements IQueryGetListDal
+        <Entidad>GetByIdDal.ts     → instancia DolibarrClient directamente, implements IQueryGetItemDal
+        <Entidad>CreateDal.ts      → extends DolibarrDal, implements IServiceDal
+        <Entidad>UpdateDal.ts      → extends DolibarrDal, implements IServiceDal
+        <Entidad>DeleteDal.ts      → extends DolibarrDal, implements IServiceDal
+        enums/                     → Enums exclusivos de la capa DAL (ej. ProductMode para filtros)
+        mappers/
+          <entidad>Mapper.ts       → toDomain() + fromDomain()
+          <entidad>StatusMapper.ts → fromDomain/toDomain para cada enum
+      router/
+        <entidad>Router.ts         → Endpoints Express para este dominio
+  common/
+    infrastructure/dolibarr/
+      dolibarrClient.ts            → Cliente HTTP a Dolibarr (create/read/update/delete/query2)
+      dolibarrDal.ts               → Clase base abstracta con helpers de filtros SQL
+      dolibarrMapper.ts            → Clase base vacía para mappers
+  container.ts                     → Registro Awilix (IoC) + createRequestScope
+```
+
+## Patrón DAL — Clases base
+
+El patrón DAL (Data Access Layer) es una capa de adaptador para transformar las entidades de dominio en las del dominio subyacente (en nuestro caso principalmente Dolibrr) o realizar las llamadas a los métodos del sistema donde están los datos (principalmente Dolibarr).
+
+### DolibarrDal (abstract)
+
+Clase base para DALs que necesitan filtros SQL o acceso múltiple a Dolibarr:
+
+```typescript
+export abstract class DolibarrDal {
+  protected dolibarr: DolibarrClient;
+
+  constructor(dolikey: string, entityId: number = 1) {
+    this.dolibarr = new DolibarrClient(dolikey, entityId);
+  }
+
+  // Construye filtro SQL: strings → LIKE '%valor%', números → :=:valor
+  protected mapFiltersFromDomain(value: string | number | undefined | null, columns: string[]): string
+
+  // Combina múltiples filtros con AND (ignora los vacíos)
+  protected combineSqlFilters(...filters: string[]): string
+}
+```
+
+### Cuándo extender DolibarrDal vs instanciar DolibarrClient directamente
+
+- **Extender `DolibarrDal`**: GetAll, Create, Update, Delete — necesitan `combineSqlFilters` o varias llamadas.
+- **Instanciar `DolibarrClient` directamente**: GetById — operación puntual sin filtros SQL.
+
+## Patrón DAL — GetAll
+
+Obtiene una colección paginada. Construye los filtros SQL a partir del DTO, llama a `query2` en Dolibarr, y transforma cada elemento crudo a dominio con el mapper. La proyección de campos (`fields`) se aplica en memoria mediante el operador `pick` de RxJS antes de devolver la lista.
+
+```typescript
+export class ProductsGetAllDal extends DolibarrDal implements IQueryGetListDal<ProductsGetAllDto, Product> {
+  private endpoint = 'products';
+  private productMapper = new ProductMapper();
+  private productModeMapper = new ProductModeMapper();
+  private productStatusMapper = new ProductStatusMapper();
+
+  constructor(dolikey: string, entityId: number = 1) {
+    super(dolikey, entityId);
+  }
+
+  async run(request: ProductsGetAllDto): Promise<QueryListResult<Product>> {
+    request.sortfield = `t.${request.sortfield || 'rowid'}`;
+
+    const paramsSql = {
+      sqlfilters: this.combineSqlFilters(
+        this.mapFiltersFromDomain(request.filterBy.trim(), ['t.label', 't.ref']),
+        this.mapFiltersFromDomain(request.status, ['t.tosell'])
+      ),
+      mode: this.productModeMapper.fromDomain(ProductMode.Products),
+      status: this.productStatusMapper.fromDomain(request.status),
+    };
+
+    const responseRaw = await this.dolibarr.query2<ProductDolibarrDto>(this.endpoint, paramsSql, request);
+    const response = await lastValueFrom(
+      from(responseRaw.data).pipe(
+        map(item => this.productMapper.toDomain(item)),
+        pick(request.fields?.split(',') ?? []),
+        toArray()
+      )
+    );
+
+    return { data: response, pagination: responseRaw.pagination };
+  }
+}
+```
+
+## Patrón DAL — GetById
+
+Obtiene un único registro por su `id`. No extiende `DolibarrDal` porque no necesita filtros SQL — instancia `DolibarrClient` directamente. Llama a `read` y transforma el resultado con el mapper.
+
+```typescript
+export class ProductsGetByIdDal implements IQueryGetItemDal<ProductsGetByIdDto, Product> {
+  private dolibarr: DolibarrClient;
+  private productMapper = new ProductMapper();
+
+  constructor(dolikey: string, entityId: number = 1) {
+    this.dolibarr = new DolibarrClient(dolikey, entityId);
+  }
+
+  async run(request: ProductsGetByIdDto): Promise<QueryItemResult<Product>> {
+    const item = await this.dolibarr.read<ProductDolibarrDto>('products', request.id);
+    return { item: this.productMapper.toDomain(item) };
+  }
+}
+```
+
+## Patrón DAL — Create / Update / Delete
+
+Las tres operaciones siguen el mismo flujo: reciben el DTO de dominio, lo transforman al shape de Dolibarr con `fromDomain`, llaman al método correspondiente del cliente, y devuelven el request original (no la respuesta de Dolibarr, que en estos casos no aporta más información que la ya conocida). Delete es la excepción: no necesita mapper porque solo requiere el `id`.
+
+```typescript
+// Create: mapea dominio → DTO Dolibarr y devuelve el request original
+export class ProductsCreateDal extends DolibarrDal implements IServiceDal<ProductsCreateDto, Product> {
+  private productMapper = new ProductMapper();
+
+  constructor(dolikey: string, entityId: number = 1) {
+    super(dolikey, entityId);
+  }
+
+  async run(request: ProductsCreateDto): Promise<Product> {
+    const dto = this.productMapper.fromDomain(request);
+    await this.dolibarr.create<unknown>('products', dto);
+    return request;
+  }
+}
+
+// Update: el id llega inyectado desde req.params junto al DTO — no forma parte del UpdateDto
+export class ProductsUpdateDal extends DolibarrDal implements IServiceDal<{ id: number; dto: ProductsUpdateDto }, Product> {
+  private productMapper = new ProductMapper();
+
+  constructor(dolikey: string, entityId: number = 1) {
+    super(dolikey, entityId);
+  }
+
+  async run({ id, dto }: { id: number; dto: ProductsUpdateDto }): Promise<Product> {
+    const dolibarrDto = this.productMapper.fromDomain(dto);
+    await this.dolibarr.update<unknown>('products', id, dolibarrDto);
+    return { id, ...dto };
+  }
+}
+
+// Delete: solo necesita el id — no requiere mapper
+export class ProductsDeleteDal extends DolibarrDal implements IServiceDal<ProductsDeleteDto, Product> {
+  constructor(dolikey: string, entityId: number = 1) {
+    super(dolikey, entityId);
+  }
+
+  async run(request: ProductsDeleteDto): Promise<ProductsDeleteDto> {
+    await this.dolibarr.delete('products', request.id);
+    return request;
+  }
+}
+```
+
+## Patrón Mapper
+
+El mapper es la frontera entre la capa subyacente (Dolibarr) y el dominio de la aplicación. Contiene dos métodos:
+- **`toDomain`**: transforma el DTO crudo de Dolibarr (`<Entidad>DolibarrDto`) en la entidad de dominio (`Product`, `Invoice`...). Convierte snake_case a camelCase, números a booleanos o enums, y garantiza que los strings nunca sean `undefined` (`?? ''`).
+- **`fromDomain`**: transforma la entidad de dominio (o un DTO de Update/Create) en el shape que espera Dolibarr. El proceso inverso.
+
+El `<Entidad>DolibarrDto` es el shape crudo tal como llega de Dolibarr: snake_case, tipos PHP mezclados (números donde el dominio usa booleanos, strings donde usa enums, etc.).
+
+```typescript
+// Shape crudo de Dolibarr
+export interface ProductDolibarrDto {
+  id: number;
+  ref?: string;
+  label?: string;
+  status?: number;          // tosell: 1 = activo, 0 = inactivo
+  status_buy?: number;      // tobuy
+  price?: number;
+  tva_tx?: number;          // ivaRate
+  price_base_type?: string; // 'HT' | 'TTC'
+  cost_price?: number;
+}
+
+export class ProductMapper extends DolibarrMapper {
+  private productStatusMapper = new ProductStatusMapper();
+  private priceBaseTypeMapper = new ProductPriceBaseTypeMapper();
+
+  toDomain(item: ProductDolibarrDto): Product {
+    return {
+      id: Number(item.id),
+      ref: item.ref ?? '',                                              // string → siempre ''
+      label: item.label ?? '',                                          // string → siempre ''
+      status: this.productStatusMapper.toDomain(item.status),
+      toSell: item.status !== undefined ? Boolean(item.status) : undefined,
+      price: item.price !== undefined ? Number(item.price) : undefined,
+      ivaRate: item.tva_tx !== undefined ? Number(item.tva_tx) : undefined,
+      priceBaseType: this.priceBaseTypeMapper.toDomain(item.price_base_type),
+      toBuy: item.status_buy !== undefined ? Boolean(item.status_buy) : undefined,
+      costPrice: item.cost_price !== undefined ? Number(item.cost_price) : undefined,
+    };
+  }
+
+  fromDomain(item: Partial<Product>): ProductDolibarrDto {
+    return {
+      id: item.id ?? 0,
+      ref: item.ref ?? '',                                              // string → siempre ''
+      label: item.label ?? '',                                          // string → siempre ''
+      status: item.toSell !== undefined ? Number(item.toSell) : undefined,
+      price: item.price ?? undefined,
+      tva_tx: item.ivaRate ?? undefined,
+      price_base_type: this.priceBaseTypeMapper.fromDomain(item.priceBaseType),
+      status_buy: item.toBuy !== undefined ? Number(item.toBuy) : undefined,
+      cost_price: item.costPrice ?? undefined,
+    };
+  }
+}
+
+// Mapper de enum
+export class ProductStatusMapper {
+  toDomain(value?: number): ProductStatus | undefined {
+    if (value === undefined) return undefined;
+    return value === 1 ? ProductStatus.Active : ProductStatus.Inactive;
+  }
+
+  fromDomain(status?: ProductStatus): number | undefined {
+    if (status === undefined) return undefined;
+    return status === ProductStatus.Active ? 1 : 0;
+  }
+}
+```
+
+### Reglas del Mapper
+
+- `toDomain`: strings siempre con `?? ''` — nunca `undefined` para campos string en dominio.
+- `toDomain`: números y booleanos con `!== undefined ? Number/Boolean(...) : undefined` — nunca colapsar el `0` o `false` con un `if (valor)`.
+- `fromDomain`: recibe `Partial<Product>` para admitir tanto Create como Update sin duplicar el mapper.
+- Los mappers de enum son clases separadas (`ProductStatusMapper`, `ProductPriceBaseTypeMapper`, etc.), instanciadas como atributos privados del mapper principal.
+
+## Patrón Router (Express)
+
+Un fichero por dominio. Incluye todos los endpoints CRUD del dominio.
+
+```typescript
+import { Router, Request, Response, NextFunction } from 'express';
+import { z } from 'zod';
+import { buildZodSchema } from '../../common/infrastructure/buildZodSchema';
+import { requireHttpRight } from '../../common/infrastructure/requireHttpRight';
+import { AuthenticatedRequest, createRequestScope } from '../../container';
+import { InjectionTokens } from '../../container';
+import { productHttpRightPolicy } from './productHttpRightPolicy';
+import { ProductsGetAllDto } from '../domain/productsGetAllDto';
+import { ProductsGetByIdDto } from '../domain/productsGetByIdDto';
+import { ProductsCreateDto } from '../domain/productsCreateDto';
+import { ProductsUpdateDto } from '../domain/productsUpdateDto';
+import { ProductsDeleteDto } from '../domain/productsDeleteDto';
+
+const router = Router();
+
+router.use(requireHttpRight(productHttpRightPolicy, 'No tienes permiso para gestionar productos'));
+
+// GET /products — listado paginado
+router.get('/', async (req: Request, res: Response, next: NextFunction) => {
+  try {
+    const { session, query } = req as AuthenticatedRequest;
+    const request = new ProductsGetAllDto(query);
+
+    const scope = createRequestScope(session.dolikey, session.entity);
+    const dal = scope.resolve(InjectionTokens.productsGetAllDal);
+    res.json(await dal.run(request));
+  } catch (error) {
+    next(error);
+  }
+});
+
+// GET /products/:id — detalle por id
+router.get('/:id', async (req: Request, res: Response, next: NextFunction) => {
+  try {
+    const { session } = req as AuthenticatedRequest;
+    const request = new ProductsGetByIdDto({ id: Number(req.params.id) });
+
+    const scope = createRequestScope(session.dolikey, session.entity);
+    const dal = scope.resolve(InjectionTokens.productsGetByIdDal);
+    res.json(await dal.run(request));
+  } catch (error) {
+    next(error);
+  }
+});
+
+// POST /products — crear
+router.post('/', async (req: Request, res: Response, next: NextFunction) => {
+  try {
+    const parsed = buildZodSchema(ProductsCreateDto).safeParse(req.body);
+    if (!parsed.success) {
+      return res.status(400).json({ error: 'Payload inválido', statusCode: 400, details: z.flattenError(parsed.error) });
+    }
+
+    const { session } = req as AuthenticatedRequest;
+    const scope = createRequestScope(session.dolikey, session.entity);
+    const dal = scope.resolve(InjectionTokens.productsCreateDal);
+    res.json(await dal.run(parsed.data));
+  } catch (error) {
+    next(error);
+  }
+});
+
+// PUT /products/:id — actualizar
+router.put('/:id', async (req: Request, res: Response, next: NextFunction) => {
+  try {
+    const parsed = buildZodSchema(ProductsUpdateDto).safeParse({ ...req.body, id: Number(req.params.id) });
+    if (!parsed.success) {
+      return res.status(400).json({ error: 'Payload inválido', statusCode: 400, details: z.flattenError(parsed.error) });
+    }
+
+    const { session } = req as AuthenticatedRequest;
+    const scope = createRequestScope(session.dolikey, session.entity);
+    const dal = scope.resolve(InjectionTokens.productsUpdateDal);
+    res.json(await dal.run(parsed.data));
+  } catch (error) {
+    next(error);
+  }
+});
+
+// DELETE /products/:id — eliminar
+router.delete('/:id', async (req: Request, res: Response, next: NextFunction) => {
+  try {
+    const { session } = req as AuthenticatedRequest;
+    const request = new ProductsDeleteDto({ id: Number(req.params.id) });  // sin validación Zod — solo id
+
+    const scope = createRequestScope(session.dolikey, session.entity);
+    const dal = scope.resolve(InjectionTokens.productsDeleteDal);
+    res.json(await dal.run(request));
+  } catch (error) {
+    next(error);
+  }
+});
+
+export default router;
+```
+
+### Reglas del Router
+
+- `GET /` — construye el DTO desde `req.query` directamente con `new ProductsGetAllDto(query)`. Sin validación Zod (los parámetros de listado son opcionales).
+- `GET /:id` — construye el DTO con `new ProductsGetByIdDto({ id: Number(req.params.id) })`. Sin validación Zod.
+- `POST /` y `PUT /:id` — validan el body con `buildZodSchema(Dto).safeParse(...)`. El `id` en PUT se inyecta desde `req.params.id`.
+- `DELETE /:id` — construye el DTO con `new ProductsDeleteDto({ id: Number(req.params.id) })`. Sin validación Zod.
+- Siempre `next(error)` en el catch — el middleware global de Express formatea el error como `ErrorResult`.
+
+## Sistema de validación con @Field + buildZodSchema
+
+Los decoradores `@Field` de los DTOs generan automáticamente el esquema Zod. No escribir esquemas Zod a mano.
+
+```typescript
+// En el router:
+const parsed = buildZodSchema(ProductsUpdateDto).safeParse(req.body);
+if (!parsed.success) {
+  return res.status(400).json({
+    error: 'Payload inválido',
+    statusCode: 400,
+    details: z.flattenError(parsed.error)
+  });
+}
+```
+
+Los DTOs de dominio definen los `@Field` — ver `onna-architecture-common` para el contrato completo.
+
+## IoC Container (Awilix)
+
+Todos los DALs se registran en `src/container.ts` y se resuelven por petición mediante `createRequestScope`:
+
+```typescript
+// container.ts — registro
+const registrations = {
+  productsGetAllDal:    asClass(ProductsGetAllDal,    { lifetime: Lifetime.SCOPED }),
+  productsGetByIdDal:   asClass(ProductsGetByIdDal,   { lifetime: Lifetime.SCOPED }),
+  productsCreateDal:    asClass(ProductsCreateDal,    { lifetime: Lifetime.SCOPED }),
+  productsUpdateDal:    asClass(ProductsUpdateDal,    { lifetime: Lifetime.SCOPED }),
+  productsDeleteDal:    asClass(ProductsDeleteDal,    { lifetime: Lifetime.SCOPED }),
+};
+
+export const InjectionTokens = Object.fromEntries(
+  Object.keys(registrations).map(k => [k, k])
+) as { [K in keyof typeof registrations]: K };
+
+export function createRequestScope(dolikey: string, entityId: number) {
+  const scope = container.createScope<RequestCradle>();
+  scope.register({ dolikey: asValue(dolikey), entityId: asValue(entityId), ...registrations });
+  return scope;
+}
+
+// En el router:
+const scope = createRequestScope(session.dolikey, session.entity);
+const dal = scope.resolve(InjectionTokens.productsGetAllDal);
+```
+
+Al añadir un nuevo DAL: (1) importarlo en `container.ts`, (2) añadirlo a `registrations`, (3) `InjectionTokens` se genera automáticamente.
+
+## Jerarquía de errores
+
+| Clase | statusCode | Uso |
+|-------|------------|-----|
+| `ArgumentError` | 400 | Parámetro inválido |
+| `NotAuthenticatedError` | 401 | Sin sesión |
+| `ForbiddenError` | 403 | Sin permisos |
+| `NotFoundError` | 404 | No encontrado |
+| `IllegalOperationError` | 422 | Operación no permitida |
+| `InternalError` | 500 | Error no controlado |
+
+Los errores no controlados deben llegar a `next(error)` — el middleware global de Express los formatea como `ErrorResult`.
+
+## Reglas de estilo
+
+- **Zero-Any**: prohibido `any`. Usar el tipo de dominio o `unknown`.
+- **Async/Await**: exclusivo. Prohibido `.then()/.catch()` encadenados.
+- DALs son clases, no funciones. Un fichero por DAL.
+- Los mappers son clases instanciadas como atributos privados del DAL que las usa (no singleton, no inyectados).
+- Los enums exclusivos de la capa DAL (como `ProductMode` para el parámetro `mode` de Dolibarr) viven en `infrastructure/dal/dolibarr/enums/`, no en `domain/`.
+
+## Verificación obligatoria tras cambios
+
+```bash
+cd backend && npx tsc --noEmit
+```