# Manual QA — Refactor Presentaciones (Sprints 0-D)

Fecha generación: 2026-04-16
Entorno objetivo: `http://demo.enterfarmaplus.test` (local Laragon)
Credenciales: `admin@gmail.com` / `123456` — RUC `00000000000`
Build Vue: `npm run prod` ejecutado, assets en `/public/js/app.js` (11 MiB)

---

## 0. Datos sembrados para probar

**Item demo creado vía seed**:
- `internal_id`: `QA-AMOX-DEMO-001`
- Descripción: `QA Amoxicilina 500mg (multi-presentación demo)`
- Stock base: 500 unidades en Almacén Oficina Principal
- Stock thresholds: min=50, max=1000, reorder=100

**3 presentaciones**:
| Descripción | Factor | unit_type | P. Público | P. Mayor | P. Convenio | Barcode |
|---|---|---|---|---|---|---|
| Unidad | 1 | NIU | 1.20 | 1.00 | 0.90 | QA-AMOX-UNIT |
| Blister x10 | 10 | BL | 10.00 | 9.00 | 8.50 | QA-AMOX-BL10 |
| Caja x100 | 100 | BX | 90.00 | 80.00 | 75.00 | QA-AMOX-BOX100 |

---

## Resumen automatizado (ya pasó)

- **PHPUnit**: 7/7 (18 assertions) — ItemPresentationServiceTest
- **Jest**: 45/46 (1 fallo pre-existing DocumentInvoice, no relacionado)
- **Playwright e2e**: 17/18 (1 flake pos-tables post-rebuild)
- **PHPStan**: 0 errores en scope modificado
- **`presentation:verify`**: 5/5 invariantes ✓
- **`presentation:health-check`**: ✓ (10 items QA legacy sin presentación, 201 kardex históricos sin FK — esperado)

**Screenshots visuales** (en `test-results/visual-sprint-c/`):
- `01-items-list.png`
- `02-transfers-list.png`
- `03-inventory-list.png`
- `04-promotions-list.png`
- `05-charge-discounts-list.png`
- `06-pos.png`

---

## 1. C.1 — Transferencia con selector presentación

**Ruta**: http://demo.enterfarmaplus.test/transfers → botón Nuevo

**Pasos**:
1. Abrir listado `Transferencias`.
2. Click `Nuevo` → dialog de creación.
3. Buscar/seleccionar item `QA-AMOX-DEMO-001`.
4. Verificar que aparece dropdown **"Presentación"** con opciones:
   - `Unidad base (x1)` (default)
   - `Unidad (x1)`
   - `Blister x10 (x10)`
   - `Caja x100 (x100)`
5. Seleccionar `Caja x100` → verificar que el campo **Factor** muestra `100` (read-only).
6. Cantidad = `2` → completar traslado a otro almacén.
7. Submit.

**Verificación DB (tinker)**:
```php
App\Models\Tenant\Inventory::latest('id')->first()
// Debería tener: quantity = 200 (base = 2*100), presentation_unit_type_id = id de Caja x100
```

**Esperado**:
- ✅ Transfer creado sin error
- ✅ `inventories.presentation_unit_type_id` tiene el ID de "Caja x100"
- ✅ `inventories.quantity = 200` (conversión 2 × 100 aplicada)
- ✅ Stock origen reduce 200 base units, stock destino aumenta 200

---

## 2. C.2 — Ajuste físico con selector presentación

**Ruta**: http://demo.enterfarmaplus.test/inventory → botón Nuevo movimiento

**Pasos**:
1. Click Nuevo → dialog ajuste.
2. Tipo = `Ingreso` (input).
3. Buscar `QA-AMOX-DEMO-001`.
4. Verificar aparece **dropdown Presentación** solo si item tiene multi-presentación (debería aparecer).
5. Seleccionar `Blister x10` → factor se auto-llena en `10`.
6. Cantidad = `5` → comentario libre.
7. Submit.

**Verificación**:
- ✅ Movimiento creado
- ✅ Stock aumentó en 50 base units (5 × 10)
- ✅ `inventories.presentation_unit_type_id` poblado

---

## 3. C.3 — Inputs stock_min/max/reorder por almacén

**Ruta**: http://demo.enterfarmaplus.test/items → Editar `QA-AMOX-DEMO-001`

**Pasos**:
1. Click Editar en `QA-AMOX-DEMO-001`.
2. Ir a pestaña **Almacenes**.
3. Verificar sección **"Parámetros de stock por almacén"** con tabla editable:
   - Columna `Almacén` (read-only)
   - Input `Stock mínimo`
   - Input `Stock máximo`
   - Input `Punto de reorden`
4. Texto de ayuda: "Deja los campos vacíos para usar el mínimo global del producto."
5. Para `Almacén Oficina Principal` los valores precargados son `50 / 1000 / 100` (del seed).
6. Modificar `Stock mínimo` a `75`, dejar `Stock máximo` vacío.
7. Guardar.

**Verificación DB**:
```sql
SELECT * FROM item_warehouse WHERE item_id = <id del item>;
-- stock_min=75, stock_max=NULL, reorder_point=100
```

**Esperado**:
- ✅ `stock_min` actualizado a 75
- ✅ `stock_max` queda NULL (no 0) → fallback a `items.stock_min`
- ✅ `reorder_point` preservado

---

## 4. C.4 — Scope presentación en Promotion

**Ruta**: http://demo.enterfarmaplus.test/promotions → Nuevo

**Pasos**:
1. Click Nuevo promoción.
2. Llenar nombre, descripción.
3. Seleccionar item = `QA-AMOX-DEMO-001`.
4. Verificar que aparece **nuevo dropdown "Presentación"**:
   - `Todas las presentaciones` (default, valor null)
   - `Unidad (x1)`
   - `Blister x10 (x10)`
   - `Caja x100 (x100)`
5. Seleccionar `Caja x100`.
6. Guardar.

**Verificación DB**:
```sql
SELECT id, name, item_id, item_unit_type_id FROM promotions ORDER BY id DESC LIMIT 1;
-- item_unit_type_id = id de Caja x100 (no null)
```

**Estado actual (2026-05-05)**: pendiente por cierre manual final.

**Evidencia pendiente**:
- Falta guardar una promocion real con `item_unit_type_id` de `Caja x100` y adjuntar el resultado SQL.
- Falta validar en venta que la promocion aplica solo al vender `Caja x100`.
- Falta validar que la misma promocion no aplica al vender `Blister x10` o `Unidad`.
- En la revision local del 2026-05-05, el ultimo registro en `tenancy_demo.promotions` tenia `item_unit_type_id = NULL`, por lo que no sirve como cierre de este caso.

**Esperado**:
- ✅ Promoción scoped a presentación Caja x100
- ✅ Si no se selecciona → `item_unit_type_id = NULL` → aplica a todas

**Charge Discounts** (`/charge_discounts`): diferido. No se incluye como pendiente operativo de farmacia en este sprint para no mezclarlo con promociones por presentacion.

---

## 5. C.5 — Audit log de presentaciones

**Ruta**: http://demo.enterfarmaplus.test/items → Editar `QA-AMOX-DEMO-001`

**Pasos**:
1. Editar item demo.
2. Ir a pestaña **"Historial presentaciones"** (solo visible en modo edición, no al crear).
3. Tabla debe estar vacía inicialmente.
4. Guardar cambio de precio en una presentación (ej: cambiar `price1` de Caja x100 de 90 a 95).
5. Recargar o re-abrir la edición.
6. Tab historial ahora debe mostrar 1 fila:
   - Fecha = now
   - Presentación ID = id de Caja x100
   - Campo = `price1`
   - Valor anterior = 90.00
   - Valor nuevo = 95.00
   - Usuario = admin
7. Cambiar factor `quantity_unit` de Blister de 10 a 12, guardar.
8. Volver al tab → 2 filas.

**Verificación DB**:
```sql
SELECT * FROM item_unit_type_changes ORDER BY id DESC LIMIT 5;
```

**Esperado**:
- ✅ Tab aparece solo en edit (not create)
- ✅ Cambios en `quantity_unit`, `price1`, `price2`, `price3` se registran
- ✅ Otros cambios (`description`, `barcode`) NO se registran (intencional — audit sólo campos numéricos críticos)
- ✅ Columna Usuario muestra nombre, no sólo id

**Endpoint directo** (curl):
```bash
curl -b cookies "http://demo.enterfarmaplus.test/items/<id>/presentation-audit"
# → { "data": [{ "id", "item_unit_type_id", "field", "old_value", "new_value", "user_id", "user_name", "reason", "created_at" }, ...] }
```

---

## 6. Observer + UNIQUE barcode (backend invariantes)

**Pasos via UI**:
1. Editar item demo, intentar poner `quantity_unit = 0` en una presentación → debería rechazar con error.
2. Crear item nuevo con barcode `QA-AMOX-UNIT` (duplicado) → debería rechazar (SQLSTATE 23000).
3. Soft delete de presentación "Blister x10" → debería ocultarse del POS pero mantenerse en documentos históricos.

**Vía CLI rápido**:
```bash
php artisan presentation:verify
```
Debe devolver:
```
✓ validator rejected quantity_unit=0
✓ audit trail recorded price change
✓ UNIQUE barcode rejected duplicate (23000)
✓ soft delete column present
✓ ItemPresentationService parses nested JSON correctly
```

---

## 7. Flujo completo compra → venta → NC

**Estado**: validado con Playwright en navegador local (`demo.enterfarmaplus.test`) el 2026-05-05.

**Evidencia registrada**:
- Stock almacén 1: `269.0000 -> 749.0000` (`+500 -30 +10`).
- Compra `id=117`, `QA32-1637820`, item `182`, `Caja x100`, cantidad `5`.
- Venta `document_id=183`, `B001-976247`, item `182`, `Blister x10`, cantidad `3`.
- Nota de crédito `document_id=184`, `BC01-1`, item `182`, `Blister x10`, cantidad `1`.
- Kardex nuevo:
  - `1097`: `+500.0000`, `presentation_unit_type_id=108` (`Caja x100`).
  - `1098`: `-30.0000`, `presentation_unit_type_id=107` (`Blister x10`).
  - `1099`: `+10.0000`, `presentation_unit_type_id=107` (`Blister x10`).
- Resultado JSON: `storage/playwright/presentation-flow/07-flow-rerun-result.json`.

**Setup**: tener el item demo con stock > 0.

### 7.1 Compra con presentación

1. Ir a `/purchases` → Nueva compra.
2. Proveedor (cualquiera registrado).
3. Item: `QA-AMOX-DEMO-001`, cantidad 5, elegir presentación `Caja x100`.
4. Guardar.

**Esperado**: stock aumenta 500 (5 × 100).
**Verificar DB**: `inventory_kardex.presentation_unit_type_id` poblado con ID Caja.

### 7.2 Venta con presentación

1. Ir a `/pos`.
2. Seleccionar cliente (o Clientes varios).
3. Buscar item demo, elegir presentación `Blister x10`, cantidad 3.
4. Procesar venta.

**Esperado**:
- Stock reduce 30 base units
- Ticket muestra "Blister x10" + precio P. Público (1.00 por blister, total S/ 30)
- XML UBL usa `unit_type_id = BL`
- `inventory_kardex.presentation_unit_type_id` poblado con ID Blister

### 7.3 NC parcial

1. Ir a factura recién creada → emitir NC.
2. Devolver 1 blister (parcial).
3. Verificar XML UBL mantiene `unit_type_id = BL`.
4. Stock vuelve a aumentar 10 base units.

**Verificación DB**:
```sql
SELECT document_id, JSON_EXTRACT(item, '$.presentation.id') FROM document_items
WHERE document_id = <id de la NC>;
```
Debe tener el ID de Blister, igual al documento afectado.

---

## 8. Reporte consolidado ventas (D.1)

**Ruta**: Reportes → Ventas consolidadas.

**Pasos**:
1. Ejecutar el reporte.
2. Ver que ahora la columna presentación está poblada con unit_type del UBL.
3. Revisar logs de BD (debug DB): ahora una sola query `SELECT * FROM items WHERE id IN (...)` en vez de N+1.

**Esperado**:
- ✅ Reporte funciona igual que antes
- ✅ Tiempo de ejecución notablemente menor si hay muchas filas (N+1 → batch)

---

## 9. Deploy remoto (cuando esté listo)

```bash
# En servidor demo.sysfarma.pe:
git pull
composer install --no-dev --optimize-autoloader
php artisan tenancy:migrate                   # 8 migraciones
php artisan presentation:backfill-fk --dry-run  # revisar counts
php artisan presentation:backfill-fk
php artisan presentation:health-check         # diagnóstico final
php artisan presentation:verify               # smoke 5 invariantes
php artisan config:clear && php artisan view:clear
npm run prod                                  # rebuild assets

# Restart
sudo systemctl restart php8.3-fpm
# (o equivalente según stack)
```

---

## 10. Rollback plan (si algo sale mal)

**Rollback por migration (reversible)**:
```bash
php artisan tenancy:migrate:rollback --step=8   # deshace las 8 nuevas
```

**Rollback de código**:
```bash
git log --oneline -20
git revert <commit-hash-del-deploy>
git push
```

**Backfill NO se revierte** — datos FK se quedan poblados (inofensivo, son denormalización de JSON).

---

## Checklist de aprobación

Marca con ✓ cada sección tras validarla en la UI:

- [ ] 1. Transfer con presentación — backend + UI
- [ ] 2. Ajuste con presentación — backend + UI
- [ ] 3. Stock min/max/reorder por almacén — UI + DB round-trip
- [ ] 4. Promotion scope por presentación — UI + DB
- [ ] 5. Audit log viewer — tab + endpoint
- [ ] 6. Observer + UNIQUE + soft delete — via `presentation:verify`
- [ ] 7. Flujo completo compra → venta → NC
- [ ] 8. Reporte consolidado (N+1 fix)
- [ ] 9. Deploy staging
- [ ] 10. Deploy prod

---

## Pendientes conocidos (NO son bugs, son decisiones)

- `item_units_per_package` marcada `@deprecated` pero no eliminada (destructivo, requiere OK).
- ChargeDiscount form sin item selector (pre-wired, no expuesto).
- Labels P1/P2/P3 hardcoded ("Público/Mayor/Convenio").
- DIGEMID export ventas no implementado (requiere spec legal).
- Feature tests PHPUnit multi-tenant pendientes (observer + backfill cubiertos vía tinker + `presentation:verify`).