# RF-REPORT-001: Reportes Predefinidos

## Identificacion

| Campo | Valor |
|-------|-------|
| **ID** | RF-REPORT-001 |
| **Modulo** | MGN-009 Reports |
| **Titulo** | Reportes Predefinidos |
| **Prioridad** | P0 - Critica |
| **Estado** | Draft |
| **Fecha** | 2025-12-05 |

---

## Descripcion

El sistema debe proporcionar un conjunto de reportes predefinidos para cada modulo, con parametros configurables, multiples formatos de salida, y capacidad de exportacion.

---

## Requisitos Funcionales

### RF-REPORT-001.1: Estructura de Reporte

```typescript
interface ReportDefinition {
  id: UUID;
  code: string;              // Codigo unico
  name: string;              // Nombre descriptivo
  description: string;       // Descripcion larga
  module: string;            // Modulo al que pertenece
  category: string;          // Categoria
  query: string;             // Query SQL parametrizado
  parameters: ReportParam[]; // Parametros del reporte
  columns: ReportColumn[];   // Columnas de salida
  defaultSort: SortConfig;   // Ordenamiento por defecto
  permissions: string[];     // Permisos requeridos
  isSystem: boolean;         // No editable
  isActive: boolean;
  createdAt: TIMESTAMPTZ;
  updatedAt: TIMESTAMPTZ;
}
```

### RF-REPORT-001.2: Parametros de Reporte

```typescript
interface ReportParam {
  name: string;           // Nombre del parametro
  label: string;          // Etiqueta UI
  type: ParamType;        // Tipo de parametro
  required: boolean;      // Obligatorio
  default?: any;          // Valor por defecto
  options?: any[];        // Para select/multiselect
  validation?: string;    // Regex o reglas
  depends_on?: string;    // Dependencia de otro param
}

enum ParamType {
  STRING = 'string',
  NUMBER = 'number',
  DATE = 'date',
  DATE_RANGE = 'date_range',
  SELECT = 'select',
  MULTISELECT = 'multiselect',
  BOOLEAN = 'boolean',
  ENTITY = 'entity'       // FK a otra tabla
}
```

### RF-REPORT-001.3: Columnas de Reporte

```typescript
interface ReportColumn {
  name: string;           // Nombre del campo
  label: string;          // Etiqueta
  type: ColumnType;       // Tipo de dato
  format?: string;        // Formato (fecha, moneda)
  aggregate?: string;     // SUM, AVG, COUNT
  width?: number;         // Ancho en pixels
  sortable: boolean;
  visible: boolean;       // Visible por defecto
  exportable: boolean;    // Incluir en export
}

enum ColumnType {
  STRING = 'string',
  NUMBER = 'number',
  CURRENCY = 'currency',
  DATE = 'date',
  DATETIME = 'datetime',
  BOOLEAN = 'boolean',
  PERCENTAGE = 'percentage',
  LINK = 'link'
}
```

### RF-REPORT-001.4: Reportes por Modulo

| Modulo | Reportes |
|--------|----------|
| Users | Usuarios activos, Usuarios por rol, Actividad de login |
| Tenants | Tenants activos, Uso por plan, Suscripciones vencidas |
| Catalogs | Productos por categoria, Contactos por tipo |
| Financial | Balance general, Estado de resultados, Movimientos por cuenta |
| Audit | Actividad por usuario, Cambios por entidad |

### RF-REPORT-001.5: Formatos de Salida

| Formato | Extension | Uso |
|---------|-----------|-----|
| Vista web | - | Visualizacion interactiva |
| PDF | .pdf | Impresion, archivo |
| Excel | .xlsx | Analisis, manipulacion |
| CSV | .csv | Integracion, importacion |
| JSON | .json | APIs, integracion |

### RF-REPORT-001.6: Ejecucion de Reportes

```typescript
interface ReportExecution {
  id: UUID;
  reportId: UUID;
  userId: UUID;
  tenantId: UUID;
  parameters: Record<string, any>;
  status: 'pending' | 'running' | 'completed' | 'failed';
  format: ExportFormat;
  rowCount?: number;
  fileUrl?: string;
  fileSize?: number;
  duration?: number;      // ms
  error?: string;
  createdAt: TIMESTAMPTZ;
  completedAt?: TIMESTAMPTZ;
  expiresAt?: TIMESTAMPTZ;
}
```

---

## Operaciones

### Listar Reportes Disponibles

```typescript
GET /api/v1/reports?module=financial

Response:
{
  "data": [
    {
      "id": "uuid",
      "code": "balance_general",
      "name": "Balance General",
      "description": "Estado de situacion financiera",
      "module": "financial",
      "category": "contabilidad",
      "parameters": [
        {
          "name": "fecha_corte",
          "label": "Fecha de corte",
          "type": "date",
          "required": true,
          "default": "today"
        },
        {
          "name": "nivel",
          "label": "Nivel de detalle",
          "type": "select",
          "options": [1, 2, 3, 4],
          "default": 2
        }
      ]
    }
  ]
}
```

### Ejecutar Reporte (Vista)

```typescript
POST /api/v1/reports/:code/execute
{
  "parameters": {
    "fecha_corte": "2025-12-05",
    "nivel": 3
  },
  "page": 1,
  "limit": 50,
  "sort": { "field": "codigo", "order": "asc" }
}

Response:
{
  "columns": [...],
  "data": [...],
  "totals": { "activo": 1000000, "pasivo": 600000 },
  "meta": {
    "total": 250,
    "page": 1,
    "executionTime": 120
  }
}
```

### Exportar Reporte

```typescript
POST /api/v1/reports/:code/export
{
  "parameters": { ... },
  "format": "xlsx"
}

Response:
{
  "executionId": "uuid",
  "status": "pending",
  "estimatedTime": 30
}

// Luego consultar:
GET /api/v1/reports/executions/:executionId

Response:
{
  "status": "completed",
  "downloadUrl": "https://...",
  "expiresAt": "2025-12-05T12:00:00Z",
  "rowCount": 1500,
  "fileSize": 245000
}
```

---

## Reglas de Negocio

| ID | Regla | Severidad |
|----|-------|-----------|
| BR-001 | Reportes grandes (>1000 rows) son asincronos | Performance |
| BR-002 | Archivos expiran en 24 horas | Storage |
| BR-003 | PDF limitado a 500 paginas | Performance |
| BR-004 | Solo usuarios con permiso ven reportes | Security |
| BR-005 | Reportes de sistema no editables | Security |

---

## Criterios de Aceptacion

- [ ] Catalogo de reportes predefinidos
- [ ] Parametros configurables por reporte
- [ ] Vista web interactiva con paginacion
- [ ] Export a PDF, Excel, CSV
- [ ] Ejecucion asincrona para reportes grandes
- [ ] Cache de resultados frecuentes
- [ ] Permisos por reporte

---

## Historial

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