# POS-002 — Implementer notes

## Cambios

### Migraciones

- `project/migrations/043_pos_basics.js`
  - Crea `pos_stores`, `pos_terminals`, `pos_payment_methods`, `pos_quick_products`, `pos_parked_tickets`, `pos_cash_sessions`.
  - Seed idempotente de la tienda por defecto **Natural - Mercado de Vida** (`natural-mercado-de-vida`) y métodos `cash` / `card`.
  - Índice parcial para impedir más de una sesión OPEN por terminal.
- `project/migrations/044_pos_inventory_store.js`
  - Añade `store_id` a `inventory_stock` e `inventory_movements`.
  - Backfill de las 14 filas de stock y 13 movimientos existentes a la tienda por defecto.
  - Sustituye unicidad de `variant_id` por `(variant_id, store_id)`.
- `project/migrations/045_pos_orders_source.js`
  - Añade `source`, `terminal_id`, `cash_session_id` a `orders_orders`.
  - Añade estado `COMPLETED` al CHECK.
  - Permite `user_id NULL` para walk-ins POS, pero añade CHECK `source = 'pos' OR user_id IS NOT NULL`.
- `project/migrations/046_pos_backoffice_roles.js`
  - Añade roles `pos_cashier` y `pos_manager` al CHECK de `backoffice_users.role`.
- `project/migrations/047_orders_user_required_when_not_pos.js`
  - Catch-up para bases que ya habían aplicado la versión inicial de 045 sin el CHECK de `user_id`.

### Dominio/auth

- `src/shared/auth.ts`: `Role` ahora incluye `pos_cashier` y `pos_manager`; nuevo `requireAnyRole()`.
- `src/shared/tests/auth.test.ts`: 8 tests, incluyendo roles POS y lista vacía.
- `src/modules/orders/domain/order.ts`: `OrderState.COMPLETED` y estado terminal sin transiciones.

### Inventario multi-tienda

- `StockItem` ahora expone `storeId`.
- `StockCommand` ahora exige `storeId`.
- `InventoryService.checkAvailability(variantId, storeId, quantity)`.
- Repositorio PostgreSQL filtra y actualiza por `(variant_id, store_id)`; los movimientos también guardan `store_id`.
- El flujo ecommerce/cart usa `DEFAULT_STORE_ID` para mantener compatibilidad con la tienda única actual.
- Endpoints inventory aceptan `storeId` opcional y usan la tienda por defecto si no se envía.
- Bulk-adjust actualizado a la clave compuesta y movimiento con store.
- Tests unitarios e integración actualizados.

### Build admin

- `project/apps/admin/next.config.ts`: `turbopack.root = __dirname` para evitar que Next.js 16 elija el workspace incorrecto por la presencia de múltiples lockfiles (`project/package-lock.json` + `project/frontend/package-lock.json`).
- Se verificó build limpio después de borrar `.next`; `/brands` y `/categories` prerenderizan correctamente.

## Evidencia

```text
Backend build: npm run build                         ✅
Backend tests: 191 passed, 56 skipped                ✅
Backend typecheck: npx tsc --noEmit                  ✅
Admin build limpio: npm run build                    ✅
Admin typecheck: npx tsc --noEmit                    ✅
Admin ESLint relevante                                ✅
Migrations 043..047 aplicadas                        ✅
verify.sh                                             ✅
```

Pruebas de constraint:

```text
ecommerce + user_id NULL  → CHECK violation ✅
pos + user_id NULL        → insert allowed ✅
re-run migrations          → No migrations to run ✅
```

## Nota de build

El error reportado de Next.js (`Export encountered an error on /brands/page`) era un fallo de prerender con el backend inaccesible y raíz de Turbopack ambigua. El problema se reprodujo en el entorno reportado, se limpió `.next`, se fijó `turbopack.root`, y el build limpio pasó sin `ECONNREFUSED`, sin error de prerender y sin warning de lockfiles.

## Archivos modificados

- `project/migrations/043_pos_basics.js`
- `project/migrations/044_pos_inventory_store.js`
- `project/migrations/045_pos_orders_source.js`
- `project/migrations/046_pos_backoffice_roles.js`
- `project/migrations/047_orders_user_required_when_not_pos.js`
- `project/src/shared/auth.ts`
- `project/src/shared/tests/auth.test.ts`
- `project/src/modules/orders/domain/order.ts`
- `project/src/modules/inventory/domain/stock.ts`
- `project/src/modules/inventory/domain/ports.ts`
- `project/src/modules/inventory/application/inventory-service.ts`
- `project/src/modules/inventory/infrastructure/pg-inventory-repository.ts`
- `project/src/modules/inventory/api/inventory.routes.ts`
- `project/src/modules/inventory/index.ts`
- `project/src/modules/inventory/tests/inventory-service.test.ts`
- `project/src/app/tests/inventory.itest.ts`
- `project/src/modules/cart/application/cart-service.ts`
- `project/src/modules/checkout/application/checkout-service.ts`
- `project/src/modules/checkout/tests/checkout-service.test.ts`
- `project/apps/admin/next.config.ts`