# US-MGN009-003: Crear Reportes Personalizados con Builder

## Identificacion

| Campo | Valor |
|-------|-------|
| **ID** | US-MGN009-003 |
| **Modulo** | MGN-009 Reports |
| **Sprint** | Sprint 6 |
| **Prioridad** | P1 - Alta |
| **Story Points** | 8 |
| **Estado** | Ready |
| **RF Relacionado** | RF-REPORT-003 |
| **Fecha** | 2025-12-05 |

---

## Historia de Usuario

**Como** usuario avanzado
**Quiero** crear reportes personalizados sin escribir SQL
**Para** obtener informacion especifica que no esta en reportes predefinidos

---

## Descripcion

El Report Builder permite a usuarios avanzados crear reportes personalizados seleccionando tablas, campos, filtros y agregaciones visualmente. El sistema genera el query automaticamente respetando permisos y RLS.

### Contexto

- Interfaz visual drag & drop
- Modelo de datos expuesto
- Joins automaticos
- Respeta permisos y RLS

---

## Criterios de Aceptacion

### Escenario 1: Ver modelo de datos disponible

```gherkin
Given un usuario con permiso "reports.builder"
When accede a GET /api/v1/reports/builder/model
Then retorna entidades disponibles con sus campos
  And solo muestra entidades permitidas por rol
  And incluye relaciones entre entidades
```

### Escenario 2: Seleccionar entidad principal

```gherkin
Given el report builder abierto
When selecciona entidad "contacts"
Then se agrega al canvas
  And muestra lista de campos disponibles
  And muestra relaciones disponibles
```

### Escenario 3: Agregar campos al reporte

```gherkin
Given entidad "contacts" seleccionada
When arrastra campos "name", "email", "total_sales"
Then los campos se agregan a la seleccion
  And aparecen en la preview
```

### Escenario 4: Agregar entidad relacionada

```gherkin
Given entidad "contacts" en el canvas
When agrega entidad relacionada "orders"
Then el JOIN se configura automaticamente
  And puede seleccionar campos de ambas entidades
```

### Escenario 5: Aplicar agregacion

```gherkin
Given campo "orders.total" seleccionado
When configura aggregate = "sum"
  And groupBy = ["contacts.name"]
Then el reporte agrupa por contacto
  And muestra suma de pedidos
```

### Escenario 6: Agregar filtro

```gherkin
Given campos seleccionados
When agrega filtro:
  | field | "orders.created_at" |
  | operator | "between" |
  | value | ["2025-01-01", "2025-12-31"] |
Then el filtro se aplica a los resultados
```

### Escenario 7: Crear parametro dinamico

```gherkin
Given un filtro agregado
When lo marca como parametro
  | parameterName | "fecha_desde" |
  | label | "Desde" |
Then el filtro se convierte en parametro
  And se pedira al ejecutar el reporte
```

### Escenario 8: Preview de resultados

```gherkin
Given reporte configurado
When hace click en "Preview"
Then muestra primeras 100 filas
  And muestra tiempo de ejecucion
  And muestra advertencias si aplica
```

### Escenario 9: Validar reporte

```gherkin
Given configuracion con errores
  | campos sin entidad |
  | filtro incompleto |
When valida el reporte
Then muestra lista de errores
  And no permite guardar hasta corregir
```

### Escenario 10: Guardar y compartir reporte

```gherkin
Given reporte valido
When guarda con:
  | name | "Ventas por Cliente 2025" |
  | isPublic | true |
Then el reporte se guarda
  And aparece en lista de reportes del tenant
  And puede ejecutarse como reporte normal
```

---

## Mockup / Wireframe

```
+------------------------------------------------------------------+
|  REPORT BUILDER                                                   |
+------------------------------------------------------------------+
| [Nuevo] [Abrir v] [Guardar]                          [Preview] [❌] |
+------------------------------------------------------------------+

+------------------------+----------------------------------------+
| ENTIDADES             | CANVAS                                  |
+------------------------+                                         |
| 🔍 Buscar...          | +---------------+    +---------------+  |
|                       | |   CONTACTS    |--->|    ORDERS     |  |
| 📁 Catalogos          | +---------------+    +---------------+  |
|   📋 Contacts         |                                         |
|   📋 Products         |                                         |
|   📋 Categories       |                                         |
|                       |                                         |
| 📁 Ventas             | CAMPOS SELECCIONADOS                    |
|   📋 Orders           | +------------------------------------+  |
|   📋 Order Items      | | contacts.name  | Nombre Cliente    |  |
|                       | | contacts.email | Email             |  |
| 📁 Financiero         | | orders.total   | Total (SUM)       |  |
|   📋 Accounts         | +------------------------------------+  |
|   📋 Journal Entries  |                                         |
+------------------------+-----------------------------------------+

+------------------------------------------------------------------+
| FILTROS                                                           |
+------------------------------------------------------------------+
| orders.created_at | >= | [2025-01-01] | [ ] Parametro            |
| [+ Agregar Filtro]                                                |
+------------------------------------------------------------------+

+------------------------------------------------------------------+
| AGRUPACION Y ORDEN                                                |
+------------------------------------------------------------------+
| Agrupar por: [contacts.name v]                                   |
| Ordenar por: [Total ▼]                                           |
+------------------------------------------------------------------+

+------------------------------------------------------------------+
| PREVIEW                                              100 filas    |
+------------------------------------------------------------------+
| NOMBRE CLIENTE       | EMAIL              | TOTAL                |
+------------------------------------------------------------------+
| Juan Perez           | juan@mail.com      | $45,000              |
| Maria Garcia         | maria@mail.com     | $38,000              |
| Carlos Lopez         | carlos@mail.com    | $22,000              |
+------------------------------------------------------------------+

Validacion:
+------------------------------------------------------------------+
| ⚠️ ADVERTENCIAS                                                   |
+------------------------------------------------------------------+
| - La consulta puede retornar mas de 10,000 filas                 |
| - Considere agregar filtro de fecha                               |
+------------------------------------------------------------------+

Modal: Guardar Reporte
+------------------------------------------------------------------+
| GUARDAR REPORTE                                              [X]  |
+------------------------------------------------------------------+
| Nombre*                                                           |
| [Ventas por Cliente 2025                                    ]    |
|                                                                   |
| Descripcion                                                       |
| [Reporte de ventas agrupado por cliente para el año 2025   ]    |
|                                                                   |
| [✓] Compartir con el equipo                                      |
|                                                                   |
|                              [Cancelar]  [=== Guardar ===]       |
+------------------------------------------------------------------+
```

---

## Notas Tecnicas

### API Endpoints

| Metodo | Path | Descripcion |
|--------|------|-------------|
| GET | /reports/builder/model | Modelo de datos |
| POST | /reports/builder/validate | Validar config |
| POST | /reports/builder/preview | Preview |
| POST | /reports/custom | Guardar reporte |
| GET | /reports/custom | Listar mis reportes |
| PUT | /reports/custom/:id | Actualizar |
| DELETE | /reports/custom/:id | Eliminar |

### Operadores de Filtro

| Operador | SQL | Tipos |
|----------|-----|-------|
| eq | = | todos |
| ne | <> | todos |
| gt, gte | >, >= | number, date |
| lt, lte | <, <= | number, date |
| like | LIKE | string |
| in | IN | todos |
| between | BETWEEN | number, date |
| is_null | IS NULL | todos |

### Generacion de Query

```typescript
// El sistema genera query parametrizado
// Siempre incluye tenant_id filter (RLS)
const query = buildQuery({
  entities: ['contacts', 'orders'],
  fields: [...],
  filters: [...],
  groupBy: [...],
  tenantId: context.tenantId  // Automatico
});
```

---

## Definicion de Done

- [ ] Modelo de datos expuesto
- [ ] UI de entity explorer
- [ ] Drag & drop de campos
- [ ] Constructor de filtros
- [ ] Agregaciones (SUM, AVG, COUNT)
- [ ] JOINs automaticos
- [ ] Preview en tiempo real
- [ ] Guardar y compartir
- [ ] Tests unitarios
- [ ] Documentacion Swagger

---

## Dependencias

### Requiere

| Item | Descripcion |
|------|-------------|
| US-MGN009-001 | Infraestructura de reportes |
| Tabla custom_reports | Storage |
| Tabla report_fields | Campos |

### Bloquea

| Item | Descripcion |
|------|-------------|
| Reportes avanzados | Usuarios crean propios |

---

## Historial

| Version | Fecha | Autor | Cambios |
|---------|-------|-------|---------|
| 1.0 | 2025-12-05 | Requirements-Analyst | Creacion inicial |
