# Dynamic Report Builder — Frontend por fases

## Visión

Interfaz tipo Report Builder que consume las APIs del backend. El frontend **no genera** PDF/Excel; solo configura y dispara export.

**Roadmap activo:** refinar editores y preview de **WHREC_DOCUMENT**, **PACKAGE_DOCUMENT**, **GUIA_DOCUMENT**. **No** nuevos templates documento hasta validar los tres en producción. Extensiones reportes **lista** → release futuro (Fase 1 MVP desplegado).

**Dependencia:** Cada segmento frontend requiere el segmento backend equivalente desplegado y estable.

**Stack:** Adaptar al framework de la app web existente (React, Vue o Angular).

**Fuera de scope frontend (futuras fases):** Editor WYSIWYG libre, diseñador pixel-perfect, editor SQL, dashboards BI, scheduling, email, IA generadora.

---

## Estrategia de implementación (IA y PRs)

**No implementar una fase completa en un solo prompt.** Segmentar en bloques pequeños: cada segmento = **1 PR revisable** o **1 sesión de IA**.

| Regla | Detalle |
|-------|---------|
| Un segmento | Una pantalla o flujo completo, probabile en aislamiento |
| Orden | Backend del segmento debe estar listo antes de empezar |
| Validar | Probar contra API real o mock alineado al contrato |
| Prompt IA | Referenciar este doc + segmento (ej. `Front Fase 1 — Segmento 1.3`) |
| Tamaño PR | Ideal: 3–10 archivos por segmento |

### Mapa de segmentos por fase

| Fase | Segmentos | PRs estimados | Depende de backend |
|------|-----------|---------------|-------------------|
| Fase 1 | 8 | 8 | Backend Fase 1 (1.2–1.7) |
| Fase 2 | 6 | 6 | Backend Fase 2 |
| Fase 3 | 5 | 5 | Backend Fase 3 |
| Fase 4 | 4 | 4 | Backend Fase 4 (opcional) |

### Orden global recomendado

```
Backend F1 → Front F1 ✅ → Backend F2 ✅ → Front F2 ✅ → Front F3 → …
```

Fases 1 y 2 completadas. **Próximo paso:** **Fase 3 — refinamiento** (preview ≈ PDF, branding, QA de los 3 documentos). Sin INVOICE/BILL ni nuevos templates en F3.

**Prompt agente F3:** [`FRONTEND_F3_AGENT_PROMPT.md`](./FRONTEND_F3_AGENT_PROMPT.md)

---

## Fase 1 — Report Builder MVP (4–6 semanas)

### Objetivo

Pantallas mínimas para catálogo, edición de configuración, preview y export (templates `PACKAGES`, `WAREHOUSE_RECEIPT`, `GUIA`).

**Backend listo para front:** Fase 1 completa (1.1–1.7). Catálogo, CRUD, preview JSON, export PDF/Excel. `PACKAGES` + `WAREHOUSE_RECEIPT` datos reales; `GUIA` mock.

### Estado de implementación (frontend Fase 1)

| Segmento | Estado | Notas |
| -------- | ------ | ----- |
| F1.1 Capa API y tipos | ✅ Hecho | `reportTemplateApi`, `reportConfigurationApi`, tipos TS |
| F1.2 Lista `/reports` | ✅ Hecho | Catálogo + configs + filtros + cursor |
| F1.3 Crear config | ✅ Hecho | `/reports/new` + POST + redirect |
| F1.4 Editor shell | ✅ Hecho | Layout 3 cols, store, PUT, `isDirty` |
| F1.5 Configurador | ✅ Hecho | Visible, labels, drag&drop |
| F1.6 Preview | ✅ Hecho | `FilterPanel` + `ReportPreviewTable` |
| F1.7 Export | ✅ Hecho | PDF/Excel blob download |
| F1.8 Cierre Fase 1 | ✅ Hecho | `BrandingPanel`, WHREC, i18n, QA |

**Fase 1 frontend:** ✅ MVP completo.

### Pantallas

| Pantalla | Ruta sugerida | Función |
|----------|---------------|---------|
| Lista de reportes | `/reports` | Catálogo + configs guardadas |
| Crear reporte | `/reports/new` | Elegir template base |
| Editor | `/reports/{id}/edit` | Report Builder |
| Vista previa | `/reports/{id}/preview` | Tabla JSON (o panel en editor) |
| Exportar | Modal / acciones en editor | PDF / Excel |

### Contrato front ↔ back (Fase 1)

**Auth:** JWT en todas las llamadas. **Rol requerido:** `ROLE_ADMIN`.

| Acción UI | API |
|-----------|-----|
| Cargar catálogo | `GET /api/report-templates` |
| Cargar schema | `GET /api/report-templates/{code}` |
| Listar configs | `GET /api/report-configurations` |
| Abrir editor | `GET /api/report-configurations/{id}` |
| Crear config | `POST /api/report-configurations` |
| Guardar | `PUT /api/report-configurations/{id}` |
| Desactivar | `DELETE /api/report-configurations/{id}` |
| Preview | `POST /api/report-configurations/{id}/preview` ✅ |
| Export PDF | `POST .../export` con `format: "pdf"` ✅ |
| Export Excel | `POST .../export` con `format: "excel"` ✅ |

#### Paginación por cursor (listas)

Ambos listados devuelven:

```json
{
  "data": [ ... ],
  "pagination": {
    "cursor": "eyJmaXJzdCI6...",
    "hasNext": true,
    "hasPrevious": false,
    "itemsPerPage": 20
  }
}
```

| Query param | Default | Uso en UI |
|-------------|---------|-----------|
| `limit` | `20` | Tamaño de página |
| `cursor` | — | Copiar de `pagination.cursor` al pedir siguiente/anterior |
| `direction` | `next` | `next` para avanzar, `prev` para retroceder |

#### Filtros de listado (UI `/reports`)

**Templates** — `GET /api/report-templates`:

| Param | Uso |
|-------|-----|
| `category` | Filtrar cards del catálogo por categoría |

**Configurations** — `GET /api/report-configurations`:

| Param | Uso |
|-------|-----|
| `pattern` | Búsqueda por nombre |
| `templateCode` | Tabs o dropdown: PACKAGES / WAREHOUSE_RECEIPT / GUIA |
| `isDefault` | Toggle "solo default" |
| `includeInactive` | Toggle "mostrar desactivadas" |

#### Bodies CRUD (referencia)

**POST crear:**

```json
{
  "templateCode": "PACKAGES",
  "name": "Mi reporte de paquetes",
  "isDefault": false
}
```

El backend copia `default_config` del template a `config`. No enviar `config` en el POST.

**PUT actualizar** — al menos un campo; `config` reemplaza el JSON completo:

```json
{
  "name": "Reporte actualizado",
  "isDefault": true,
  "config": { "branding": { ... }, "sections": [ ... ] }
}
```

**DELETE:** desactiva la config (`active: false`); no borra el registro.

#### Tipos TypeScript adicionales

```typescript
interface CursorPagination {
  cursor: string | null;
  hasNext: boolean;
  hasPrevious: boolean;
  itemsPerPage: number;
}

interface PaginatedResponse<T> {
  data: T[];
  pagination: CursorPagination;
}

type ReportTemplateCode = 'PACKAGES' | 'WAREHOUSE_RECEIPT' | 'GUIA';

interface ReportConfigurationListParams {
  limit?: number;
  cursor?: string;
  direction?: 'next' | 'prev';
  pattern?: string;
  templateCode?: ReportTemplateCode;
  isDefault?: boolean;
  includeInactive?: boolean;
}

interface ReportTemplateListParams {
  limit?: number;
  cursor?: string;
  direction?: 'next' | 'prev';
  category?: string;
}
```

### Estado frontend (referencia TypeScript)

```typescript
interface ReportBuilderState {
  configurationId: number;
  templateCode: string;
  branding: BrandingConfig;
  sections: SectionConfig[];
  filters: ReportFilters;
  preview: PreviewResponse | null;
  isDirty: boolean;
  isLoading: boolean;
  error: string | null;
}

interface SectionConfig {
  key: string;
  visible: boolean;
  order: number;
  title: string;
  columns?: ColumnConfig[];
}

interface ColumnConfig {
  key: string;
  visible: boolean;
  order: number;
  label: string;
}
```

### Wireframe conceptual

```
┌─────────────────────────────────────────────────────────────┐
│  Reportes  >  Paquetes  >  Mi configuración        [Guardar]│
├──────────┬──────────────────────────────┬───────────────────┤
│ Secciones│         PREVIEW                │ Propiedades       │
│          │  ┌─────────────────────────┐   │                   │
│ ▣ Resumen│  │ Número │ Tracking │ Peso │   │ Título: [____]   │
│ ▣ Detalle│  │ REC-01 │ 1Z999... │ 1.25 │   │ ☑ Visible       │
│          │  └─────────────────────────┘   │ Label: [____]     │
│          │                              │                   │
│ Branding │  Filtros: [Desde] [Hasta]    │ [PDF] [Excel]     │
└──────────┴──────────────────────────────┴───────────────────┘
```

---

### Fase 1 — Segmentación (8 segmentos)

#### Segmento F1.1 — Capa API y tipos

**Estado:** ✅ Implementado.

**Objetivo:** Cliente HTTP y tipos alineados al contrato backend.

| Entregable | Detalle |
|------------|---------|
| `reportTemplateApi` | `list(params?)`, `getByCode(code)` — soportar paginación y `category` |
| `reportConfigurationApi` | `list(params?)`, `get(id)`, `create()`, `update()`, `delete()` — filtros + cursor |
| Types | `ReportTemplate`, `ReportConfiguration`, `PaginatedResponse`, `CursorPagination`, `ReportTemplateCode` |
| Error handling | Mapear 400/404 del backend a mensajes UI |

**Prompt IA sugerido:**
> Implementa Front Fase 1 Segmento F1.1: servicios API y tipos TypeScript para report-templates y report-configurations según `docs/report-builder/BACKEND_PHASES.md`. Sin UI aún.

**Criterios de aceptación:**
- [ ] Llamadas API tipadas y con auth JWT existente de la app
- [ ] Tests unitarios de parsing de respuesta preview

**Depende de:** Backend 1.2, 1.3  
**Bloquea:** F1.2+

---

#### Segmento F1.2 — Pantalla lista `/reports`

**Estado:** ✅ Implementado.

**Objetivo:** Vista principal con catálogo y configs guardadas.

| Entregable | Detalle |
|------------|---------|
| `ReportCatalogList` | Cards por template (nombre, descripción, categoría) |
| `SavedConfigurationsList` | Tabla/lista configs con paginación cursor |
| Filtros UI | `pattern`, `templateCode`, `isDefault`, `includeInactive` |
| Ruta `/reports` | Layout con ambas secciones |
| Acciones | Botón "Nueva configuración" → `/reports/new` |
| Empty states | Sin configs, sin templates |
| Paginación | Botones anterior/siguiente usando `pagination.hasNext` / `hasPrevious` y `cursor` |

**Prompt IA sugerido:**
> Implementa Front F1.2: página /reports con catálogo y lista de configuraciones. Usar reportTemplateApi y reportConfigurationApi.

**Criterios de aceptación:**
- [ ] Carga templates y configs al montar (primera página, `limit` configurable)
- [ ] Filtros actualizan la lista sin perder auth
- [ ] Paginación cursor funciona (next/prev)
- [ ] Click en config abre editor
- [ ] Loading y error states

**Depende de:** F1.1  
**Bloquea:** F1.3

---

#### Segmento F1.3 — Flujo crear configuración

**Estado:** ✅ Implementado.

**Objetivo:** Elegir template y crear config.

| Entregable | Detalle |
|------------|---------|
| Ruta `/reports/new` | Grid de templates |
| Modal / form | Nombre de la configuración |
| `POST /api/report-configurations` | Redirect a `/reports/{id}/edit` |
| Validación | Nombre requerido |

**Prompt IA sugerido:**
> Implementa Front F1.3: flujo crear config desde template. POST y redirect al editor.

**Criterios de aceptación:**
- [ ] Usuario elige PACKAGES, WAREHOUSE_RECEIPT o GUIA
- [ ] Tras crear, abre editor con defaults del template

**Depende de:** F1.2  
**Bloquea:** F1.4

---

#### Segmento F1.4 — Editor: layout y estado

**Estado:** ✅ Implementado.

**Objetivo:** Shell del builder con estado global y guardado.

| Entregable | Detalle |
|------------|---------|
| `ReportBuilderLayout` | 3 columnas (secciones | preview | propiedades) |
| Store / Context | `ReportBuilderState`, acciones `setSection`, `setColumn`, `save` |
| Header | Breadcrumb, botón Guardar, indicador `isDirty` |
| `PUT` al guardar | Confirmación éxito / error |
| Unsaved warning | `beforeunload` o modal al salir con cambios |

**Prompt IA sugerido:**
> Implementa Front F1.4: ReportBuilderLayout + estado global + guardar PUT. Sin drag&drop ni preview aún.

**Criterios de aceptación:**
- [ ] Carga config por id desde URL
- [ ] Guardar persiste cambios en API
- [ ] Aviso si hay cambios sin guardar

**Depende de:** F1.3  
**Bloquea:** F1.5, F1.6, F1.7

---

#### Segmento F1.5 — Columnas y secciones (configurador)

**Estado:** ✅ Implementado.

**Objetivo:** Editar visibilidad, orden y labels.

| Entregable | Detalle |
|------------|---------|
| `ColumnConfigurator` | Checkbox visible, input label |
| Panel secciones | Lista secciones con toggle visible |
| Drag & drop | Reordenar secciones y columnas (ej. `@dnd-kit` o similar) |
| Panel propiedades | Edita item seleccionado (sección o columna) |

**Prompt IA sugerido:**
> Implementa Front F1.5: ColumnConfigurator + reorder secciones/columnas con drag&drop. Actualizar store local.

**Criterios de aceptación:**
- [ ] Ocultar columna excluye de config guardada
- [ ] Reordenar actualiza `order` en JSON
- [ ] Editar label se refleja en propiedades

**Depende de:** F1.4  
**Bloquea:** F1.6

---

#### Segmento F1.6 — Preview integrado

**Estado:** ✅ Implementado.

**Objetivo:** Tabla de preview en el editor.

| Entregable | Detalle |
|------------|---------|
| `ReportPreviewTable` | Render `headers` + `rows` de preview API |
| Botón "Actualizar preview" | `POST .../preview` |
| `FilterPanel` básico | fromDate, toDate, agencyId |
| Loading skeleton | Mientras carga preview |

**Prompt IA sugerido:**
> Implementa Front F1.6: preview en editor con FilterPanel y ReportPreviewTable. Depende de Backend 1.5+.

**Criterios de aceptación:**
- [ ] Preview respeta columnas visibles del config
- [ ] Filtros se envían en body del preview
- [ ] Error API muestra mensaje en UI

**Depende de:** F1.5, Backend 1.5  
**Bloquea:** F1.7

---

#### Segmento F1.7 — Export PDF y Excel

**Estado:** ✅ Implementado.

**Objetivo:** Descargar archivos desde el editor.

| Entregable | Detalle |
|------------|---------|
| `ExportActions` | Botones PDF y Excel |
| Descarga blob | `URL.createObjectURL` + nombre archivo |
| Loading | Spinner durante export |
| Timeout / error | Mensaje si export falla o tarda |

**Prompt IA sugerido:**
> Implementa Front F1.7: export PDF/Excel con descarga blob. Mismos filtros que preview.

**Criterios de aceptación:**
- [ ] PDF abre/descarga correctamente
- [ ] Excel descarga .xlsx
- [ ] Usa filtros actuales del FilterPanel

**Depende de:** F1.6, Backend 1.6  
**Bloquea:** F1.8

---

#### Segmento F1.8 — Branding panel + cierre Fase 1

**Estado:** ✅ Implementado.

**Objetivo:** Completar MVP con branding y QA.

| Entregable | Detalle |
|------------|---------|
| `BrandingPanel` | showLogo, showCompanyName, headerTitle |
| Soporte WHREC | Editor funciona con template WAREHOUSE_RECEIPT |
| i18n | Labels de UI en archivos de traducción existentes |
| QA manual | Checklist Fase 1 |

**Criterios de aceptación Fase 1 (global):**
- [ ] Listar templates y configuraciones guardadas
- [ ] Crear nueva config desde template
- [ ] Reordenar secciones y columnas (drag & drop)
- [ ] Toggle visibilidad y editar labels
- [ ] Preview sin recargar página completa
- [ ] Descargar PDF y Excel
- [ ] Guardar / cancelar con aviso si hay cambios sin guardar
- [ ] PACKAGES y WAREHOUSE_RECEIPT operativos

**Depende de:** F1.7, Backend 1.7  
**Bloquea:** Fase 2 front

---

## Fase 2 — Editores de documentos (3–4 semanas)

### Objetivo

**Editores para documentos** `layout: document` — foco exclusivo en impresión de un registro (no reportes lista):

- **`WHREC_DOCUMENT`** — warehouse + **PACKAGES** + totales
- **`PACKAGE_DOCUMENT`** — un solo paquete
- **`GUIA_DOCUMENT`** — guía/shipment + Package(s) + **tarifa** + **totales**

Validación inline, duplicate/default y polish UX del builder de documentos.

**Fuera de alcance Fase 2 front:** galería multi-categoría con CONSOL/MANIFEST, filtros dinámicos lista, editor multi-template lista — **release futuro**.

Ver anatomía en `BACKEND_PHASES.md` (Fase 2).

### Estado de implementación (frontend Fase 2)

| Segmento | Estado | Notas |
| -------- | ------ | ----- |
| F2.1 Selector documentos | ✅ Hecho | `/reports/new` — templates `layout: document` |
| F2.2 Duplicate / default | ✅ Hecho | Duplicar + marcar default + badge |
| F2.3 Validación inline | ✅ Hecho | `ValidationBanner`, validación cliente al guardar |
| F2.7 Editor WHREC_DOCUMENT | ✅ Hecho | PACKAGES + totales, preview/export `whrecId` |
| F2.8 Editor PACKAGE_DOCUMENT | ✅ Hecho | `items_table`, preview/export `receiptId` |
| F2.9 Editor GUIA_DOCUMENT | ✅ Hecho | Tarifa + totales, preview/export `guideId` |
| F2.6 Cierre Fase 2 | ✅ Hecho | QA documentos; editor listas F1 sin regresión |

**Fase 2 frontend:** ✅ Completa (2026-06).

**Trabajo inmediato Fase 3:** paridad `DocumentPreview` con PDF (F3.2) y branding (F3.1).

### Orden recomendado Fase 2 (front)

```
F2.3 Validación inline (tras Backend 2.1)
  ├── F2.7 Editor WHREC — tras Backend 2.7
  ├── F2.8 Editor PACKAGE — tras Backend 2.8
  └── F2.9 Editor GUIA — tras Backend 2.9
F2.2 Duplicate (tras Backend 2.2)
F2.1 Selector documentos (WHREC / PACKAGE / GUIA)
  └── F2.6 Cierre
```

**Próximo segmento front sugerido:** **F3.2** (paridad preview/PDF) en paralelo o tras **F3.1** (branding).

---

### Fase 2 — Segmentación (6 segmentos)

#### Segmento F2.1 — Selector de templates documento

**Estado:** ✅ Implementado.

| Entregable | Detalle |
|------------|---------|
| `DocumentTemplatePicker` | Cards solo para `WHREC_DOCUMENT`, `PACKAGE_DOCUMENT`, `GUIA_DOCUMENT` |
| `/reports/new` v2 | Filtra catálogo por `layout: document` (o categoría Documentos) |
| Templates lista F1 | Opcional: ocultar de "crear nuevo" o sección separada "Reportes tabla" |

**Depende de:** F1.8, Backend 2.7+ (seeds documento)  
**Bloquea:** F2.6

---

#### Segmento F2.2 — Duplicate y config por defecto

**Estado:** ✅ Implementado.

| Entregable | Detalle |
|------------|---------|
| Acción "Duplicar" | En lista de configs → `POST .../duplicate` |
| Acción "Marcar como default" | `PATCH .../set-default` |
| Badge "Default" | En SavedConfigurationsList |
| Modal renombrar | Al duplicar |

**Depende de:** Backend 2.2, F1.8

---

#### Segmento F2.3 — Validación inline

**Estado:** ✅ Implementado.

| Entregable | Detalle |
|------------|---------|
| `ValidationBanner` | Errores del backend al guardar (400) |
| Validación cliente | Al menos 1 columna visible por tabla |
| Deshabilitar Guardar | Si validación falla |
| `ConfigurationVersionBadge` | Opcional: fecha última modificación |

**Depende de:** Backend 2.1

---

#### Segmento F2.7 — Editor WHREC_DOCUMENT (warehouse + PACKAGES)

**Estado:** ✅ Implementado.

**Objetivo:** UI para warehouse completo — incluye sección **PACKAGES** (tabla multi-fila de paquetes hijos + fila totales), términos y doble firma.

| Entregable | Detalle |
|------------|---------|
| `WhrecDocumentEditor` | Extiende `DocumentEditorLayout` |
| `PackagesTableConfigurator` | Columnas de `packages_section` (number, description, dims, tracking, weight, volume, …) |
| `DocumentPreview` | Header WH + party + **PACKAGES** con totales |
| `DocumentFilterPanel` | Input **`whrecId`** + preview/export |
| Entrada opcional | Desde detalle WHRec → "Imprimir con plantilla…" |

**Prompt IA sugerido:**

> Implementa Front F2.7: editor WHREC_DOCUMENT con packages_table, preview/export whrecId.

**Criterios de aceptación:**

- [ ] Preview muestra N paquetes (WR3010XP1, WR3010XP2, …) + fila totales
- [ ] Ocultar columna PACKAGES → no en PDF
- [ ] Editor listas Fase 1 sin regresión (si siguen en catálogo)

**Depende de:** Backend 2.7, F1.8, F2.3 (recomendado)  
**Bloquea:** F2.8, F2.6

---

#### Segmento F2.8 — Editor PACKAGE_DOCUMENT (paquete individual)

**Estado:** ✅ Implementado.

**Objetivo:** UI para **un solo paquete** — mismo motor que F2.7 pero **sin** sección PACKAGES; tabla `items_table` con medidas del receipt.

| Entregable | Detalle |
|------------|---------|
| `PackageDocumentEditor` | Reutiliza componentes F2.7 |
| `ItemsTableConfigurator` | Columnas items (description, weight, dimensions, volume, …) |
| `DocumentFilterPanel` | Input **`receiptId`** + preview/export |
| Entrada opcional | Desde detalle Receipt → "Imprimir con plantilla…" |

**Prompt IA sugerido:**

> Implementa Front F2.8: PACKAGE_DOCUMENT reutilizando F2.7, filtro receiptId, sin packages_table.

**Criterios de aceptación:**

- [ ] Preview/export con `receiptId` — documento tipo WR3010XP1
- [ ] No muestra sección PACKAGES
- [ ] WHREC editor (F2.7) sigue funcionando

**Depende de:** Backend 2.8, F2.7  
**Bloquea:** F2.9, F2.6

---

#### Segmento F2.9 — Editor GUIA_DOCUMENT (guía + tarifa + totales)

**Estado:** ✅ Implementado.

**Objetivo:** UI para **guía/shipment** — Package(s) como WHRec, más secciones **Shipment Rate Details** (tarifa) y **Shipment's Basic Details** (totales: insured, declared, COD, tax, total shipment, discount).

| Entregable | Detalle |
|------------|---------|
| `GuiaDocumentEditor` | Reutiliza `DocumentEditorLayout` |
| `PackagesTableConfigurator` | Columnas Package(s) (unit, id, dims, weight, volume, pvol) |
| `RateDetailsConfigurator` | Columnas tarifa + subtotales (total services, total shipment) |
| `ChargesSummaryConfigurator` | Toggle/label por campo financiero (insuredValue, taxPaid, …) |
| `DocumentFilterPanel` | Input **`guideId`** + preview/export |
| Entrada opcional | Desde detalle Guía → "Imprimir con plantilla…" |

**Prompt IA sugerido:**

> Implementa Front F2.9: GUIA_DOCUMENT con preview de packages + rate_details + charges_summary, filtro guideId.

**Criterios de aceptación:**

- [ ] Preview muestra tarifa asociada (nombre, qty, price, total)
- [ ] Sección totales muestra declared value, insurance, tax, total shipment
- [ ] WHREC y PACKAGE editors sin regresión

**Depende de:** Backend 2.9, F2.7  
**Bloquea:** F2.6

---

#### Segmento F2.6 — UX polish + cierre Fase 2

**Estado:** ✅ Implementado.

| Entregable | Detalle |
|------------|---------|
| Búsqueda | En catálogo y configs guardadas |
| Undo/redo | Stack local de cambios en editor (opcional) |
| Keyboard shortcuts | Guardar Ctrl+S |
| QA | Todos los templates Backend F2 |

**Criterios Fase 2 (global):**
- [ ] Crear config solo desde templates documento (F2.1)
- [ ] Duplicar y renombrar configs
- [ ] Errores de validación visibles antes de guardar
- [ ] WHRec (`WHREC_DOCUMENT`) con PACKAGES + totales
- [ ] Paquete (`PACKAGE_DOCUMENT`) preview + export PDF
- [ ] Guía (`GUIA_DOCUMENT`) con Package(s) + tarifa + totales

**Depende de:** F2.1–F2.3, F2.7, F2.8, F2.9

---

## Release futuro — Extensiones de reportes lista (deferido)

| Segmento (referencia) | Contenido deferido |
| --------------------- | ------------------ |
| F2.4 | `FilterSchemaForm` — filtros dinámicos por template lista |
| F2.5 | Editor multi-template lista (CONSOL, SHIPMENT, MANIFEST, …) |
| Gallery ampliada | Categorías Operacional / Manifiestos con 5+ templates lista |

Retomar tras cerrar editores de documento (F2.6) y backend lista deferido (2.3–2.5).

---

## Fase 3 — Refinamiento preview y branding (2–3 semanas)

**Prompt para agente IA:** [`FRONTEND_F3_AGENT_PROMPT.md`](./FRONTEND_F3_AGENT_PROMPT.md)

### Objetivo

Perfeccionar la experiencia de los **tres documentos Fase 2**: preview estructuralmente alineada al PDF, branding en editor y PDF, polish UX de editores F2.7–F2.9, QA contra referencias.

**En alcance:** solo `WHREC_DOCUMENT`, `PACKAGE_DOCUMENT`, `GUIA_DOCUMENT`.

**Fuera de alcance Fase 3:** nuevos editores documento (INVOICE, BILL, etc.) → **Release futuro — Nuevos documentos** (abajo).

### Referencias PDF

| Template | Referencia |
| -------- | ---------- |
| `WHREC_DOCUMENT` | Warehouse WR3010 |
| `PACKAGE_DOCUMENT` | WR3010XP1 |
| `GUIA_DOCUMENT` | SHIPMENT GUI1320132124 |

---

### Fase 3 — Segmentación (5 segmentos)

#### Segmento F3.1 — Branding extendido en UI

| Entregable | Detalle |
|------------|---------|
| `BrandingPanel` v2 | primaryColor, footerText, locale, showPageNumbers |
| Color picker | Para primaryColor |
| Preview header mock | Logo + título en panel preview |

**Depende de:** Backend 3.1, F2.6

---

#### Segmento F3.2 — DocumentPreview — paridad con PDF

**Prioridad alta.** Objetivo: dejar de mostrar keys internas / JSON crudo; render por `section.type` como el Twig backend.

| Entregable | Detalle |
|------------|---------|
| `DocumentPreviewSection` | switch por type: grid, party, text, tables, charges_summary, signatures |
| `ReportPreviewHeader` | Logo, company name, título configurado |
| Estilos preview | Tablas con borde, party 2 cols **1fr 1fr stretch** (mismo ancho/alto), `partyLines` multilínea — ver `FRONTEND_F3_PARTY_SECTION_PROMPT.md` |
| Ocultar vacías | Secciones sin contenido útil no se renderizan |

**Depende de:** F2.7–F2.9 (editores base); Backend 3.2 recomendado para datos alineados

---

#### Segmento F3.3 — Editor polish (los 3 documentos)

| Entregable | Detalle |
|------------|---------|
| Secciones colapsables | Panel izquierdo del editor |
| Totales en preview | Fila summary si backend envía `totalsRow` |
| UI `visibleWhen` | Solo si Backend 3.3 lo expone |
| Labels / i18n | Revisión copy en WHREC, PACKAGE, GUIA |

**Depende de:** F3.2, Backend 3.3

---

#### Segmento F3.4 — QA vs referencias PDF

| Entregable | Detalle |
|------------|---------|
| Checklist 3 templates | Preview + export PDF vs referencias |
| WHREC | PACKAGES + totales + parties |
| PACKAGE | items_table, sin multi-paquete |
| GUIA | rate_details + charges_summary |
| Regresión F1 | Editores lista sin cambios |

**Depende de:** F3.1–F3.3, Backend 3.2–3.5

---

#### Segmento F3.5 — Cierre Fase 3

| Entregable | Detalle |
|------------|---------|
| Selector idioma labels | Si `branding.locale` disponible |
| QA branding | PDF descargado vs preview |
| Tooltips | Branding y filtros documento |
| Ctrl+S | Guardar (opcional) |

**Criterios Fase 3 (global):**
- [ ] Preview legible y estructuralmente igual al PDF (los 3 documentos)
- [ ] Branding configurado visible en preview y PDF
- [ ] WHREC / PACKAGE / GUIA pasan checklist vs referencias
- [ ] **No** se agregan templates documento nuevos en UI

**Depende de:** F3.1–F3.4

---

### Release futuro — Nuevos documentos (deferido)

| Contenido deferido | Notas |
| ------------------ | ----- |
| F3.x (plan anterior) | `InvoiceDocumentEditor`, `BillDocumentEditor` |
| Filtros `invoiceId`, `billId` | Tras sign-off WHREC / PACKAGE / GUIA |
| Entrada "Imprimir con plantilla" | Desde detalle WHRec/Receipt/Guía (opcional, no bloqueante) |

**Cuándo retomar:** Tras cerrar Fase 3 refinamiento y validación en producción.

---

## Fase 4 — Pulido y adopción (2–3 semanas)

### Objetivo

Producción, onboarding y observabilidad.

---

### Fase 4 — Segmentación (4 segmentos)

#### Segmento F4.1 — Onboarding y empty states

| Entregable | Detalle |
|------------|---------|
| Tour guiado | Primer visita a `/reports` (ej. intro.js, driver.js) |
| Empty states | Ilustración + CTA "Crear primer reporte" |
| Tooltips | En secciones del editor |

**Depende de:** F3.5

---

#### Segmento F4.2 — Loading, errores y accesibilidad

| Entregable | Detalle |
|------------|---------|
| Skeletons | Preview, lista, export |
| Error boundaries | En editor |
| Keyboard reorder | Alternativa a drag & drop |
| ARIA | Listas reordenables accesibles |

**Depende de:** F4.1

---

#### Segmento F4.3 — Telemetría y métricas UI

| Entregable | Detalle |
|------------|---------|
| Events | `report_preview`, `report_export`, `report_save`, `report_error` |
| Timing | Duración preview/export en cliente |
| Integración | Analytics existente del proyecto |

**Depende de:** F4.2

---

#### Segmento F4.4 — Documentación in-app y cierre

| Entregable | Detalle |
|------------|---------|
| Ayuda contextual | Panel "?" en editor |
| Indicador engine | Si backend F4: badge "Jasper" vs "Nativo" (informativo) |
| QA release | Checklist producción |

**Criterios Fase 4 (global):**
- [ ] Tour para primer uso
- [ ] Manejo de errores de red y timeout en export
- [ ] Métricas básicas de uso
- [ ] Accesibilidad básica en reorder

**Depende de:** F4.1–F4.3

---

## Riesgos frontend

| Riesgo | Mitigación |
|--------|------------|
| Editor demasiado complejo | Segmentos F1.4–F1.5 incrementales |
| Preview ≠ PDF | Documentar en F3; no prometer pixel-perfect |
| Estado inconsistente | F1.4: `isDirty` + unsaved warning |
| API inestable | No empezar front hasta backend del segmento listo |
| Exports lentos | F1.7 + F4.2: spinner, timeout, mensaje claro |

---

## Alineación front ↔ back por segmento

| Front | Backend requerido |
|-------|-------------------|
| F1.1 | 1.2, 1.3 |
| F1.2–F1.3 | 1.2, 1.3 |
| F1.4–F1.5 | 1.3 |
| F1.6 | 1.5 |
| F1.7 | 1.6 |
| F1.8 | 1.7 |
| F2.1–F2.3 | 2.1–2.2 |
| F2.7 | 2.7 |
| F2.8 | 2.8 |
| F2.9 | 2.9 |
| F2.6 | 2.6 |
| F3.x | 3.x |
| F4.x | 4.x (F4.4 engine badge opcional) |

---

## Cronograma sugerido (con IA segmentada)

| Fase | Segmentos | Duración estimada |
|------|-----------|-------------------|
| Fase 1 | F1.1 – F1.8 | ✅ Completa |
| Fase 2 | F2.1 – F2.9 (F2.6 cierre; sin F2.4/F2.5 lista) | ✅ Completa |
| Fase 3 | F3.1 – F3.5 (refinamiento WHREC / PACKAGE / GUIA) | 2–3 semanas |
| Fase 4 | F4.1 – F4.4 | 1–2 semanas |

Cada segmento: implementar → probar contra API → PR → merge → siguiente segmento.

---

## Retomar trabajo (checkpoint 2026-06-12)

| Área | Estado | Siguiente paso |
| ---- | ------ | -------------- |
| Front Fase 1 | ✅ MVP completo (F1.1–F1.8) | — |
| Backend Fase 2 | ✅ Completa | — |
| Front Fase 2 | ✅ Completa (F2.1–F2.3, F2.7–F2.9, F2.6) | **F3.2** preview ≈ PDF — ver [`FRONTEND_F3_AGENT_PROMPT.md`](./FRONTEND_F3_AGENT_PROMPT.md) |

**Nota:** Fase 3 = **refinamiento** de los 3 documentos; no nuevos templates. INVOICE/BILL → release futuro. Extensiones lista (CONSOL, MANIFEST) → release futuro.