se agrega modificaciones en retenciones efectuadas

docs/endpoint-filtros.md

+# Endpoint `/api/v1/filtros`
+
+Devuelve catálogos (área, subárea, cargo, local) para poblar los dropdowns de la grilla de
+renta de quinta. Es un único endpoint parametrizado por tipo, no cuatro endpoints separados.
+
+## Contrato
+
+```
+GET /api/v1/filtros?tipo={TIPO}
+```
+
+### Parámetro
+
+| Nombre | Tipo | Obligatorio | Valores válidos |
+|---|---|---|---|
+| `tipo` | string (enum) | Sí | `AREA`, `SUBAREA`, `CARGO`, `LOCAL` |
+
+### Respuesta `200 OK`
+
+Array de objetos `{ id, text }`:
+
+```json
+[
+  { "id": 1, "text": "ADMINISTRACION" },
+  { "id": 2, "text": "ACADEMICO" }
+]
+```
+
+- `id`: `Integer` — el código/id real de la tabla origen (p. ej. `codarea`, `id_subarea`,
+  `codcargo`, `id_local`).
+- `text`: `String` — la descripción a mostrar en el dropdown.
+
+Orden: alfabético por `text`.
+
+### Errores
+
+Si `tipo` viene vacío/ausente → `400` con el shape estándar de error del proyecto:
+
+```json
+{
+  "timestamp": "2026-09-04T12:00:00Z",
+  "status": 400,
+  "message": "Falta el parámetro obligatorio 'tipo'"
+}
+```
+
+Si `tipo` viene con un valor que no es del enum (p. ej. `?tipo=FOO`) → `400`:
+
+```json
+{
+  "timestamp": "2026-09-04T12:00:00Z",
+  "status": 400,
+  "message": "El parámetro 'tipo' debe ser numérico"
+}
+```
+
+> Nota: ese mensaje está pensado originalmente para parámetros numéricos; para un enum
+> inválido el mensaje puede no ser 100% preciso, pero el status 400 y el shape sí aplican.
+
+## Ejemplos de uso
+
+```bash
+curl "http://localhost:8080/api/v1/filtros?tipo=AREA"
+curl "http://localhost:8080/api/v1/filtros?tipo=SUBAREA"
+curl "http://localhost:8080/api/v1/filtros?tipo=CARGO"
+curl "http://localhost:8080/api/v1/filtros?tipo=LOCAL"
+```
+
+Ejemplo con `fetch` en frontend:
+
+```ts
+async function cargarCatalogo(tipo: "AREA" | "SUBAREA" | "CARGO" | "LOCAL") {
+  const res = await fetch(`/api/v1/filtros?tipo=${tipo}`);
+  if (!res.ok) throw new Error("Error cargando catálogo");
+  return res.json() as Promise<{ id: number; text: string }[]>;
+}
+```
+
+## Relación con la grilla de renta de quinta
+
+Los `id` devueltos por este endpoint son los mismos valores que se envían como filtros
+numéricos a `GET /api/v1/renta-quinta` (`areaGeneral`, `subArea`, `cargo`, `sede`/local, etc.).
+El flujo típico es: poblar el dropdown con `/api/v1/filtros?tipo=AREA`, y al elegir una opción
+mandar su `id` como filtro a la grilla.
+
+> Importante (contexto de este proyecto): actualmente las columnas de filtro en
+> `planilla.renta_quinta` guardan **texto** (`sede='BARRANCO'`), no el id numérico del
+> catálogo, así que el filtro numérico no siempre matchea. Si replicás este patrón en otro
+> proyecto, verificá si tu tabla de hechos filtra por id o por texto antes de copiar ese
+> comportamiento.
+
+## Cómo replicarlo en otro proyecto
+
+Piezas mínimas:
+
+1. **Enum de tipos** (`TipoFiltro`): uno por catálogo que quieras exponer.
+2. **DTO de salida** (`FiltroItemDTO`): record simple `{ id, text }` — genérico, sirve para
+   cualquier catálogo tipo lookup.
+3. **Service** con un `switch` que arma el SQL/query según el tipo y devuelve `List<FiltroItemDTO>`.
+   - En este proyecto se usa `JdbcTemplate` con SQL nativo porque las tablas origen son
+     *foreign tables* (FDW) que Hibernate no valida como `@Entity`. Si tus catálogos son
+     tablas normales, podés mapearlos como entities/repositories JPA en vez de SQL nativo.
+4. **Controller** con un único `GET` que recibe `tipo` como `@RequestParam` (enum) y delega al
+   service.
+5. **Manejo de errores**: parámetro ausente → 400 con mensaje claro; valor de enum inválido →
+   400 (Spring lo resuelve solo al bindear el `@RequestParam` a un enum).
+
+Ventaja de este diseño: agregar un catálogo nuevo es solo un `case` más en el `switch` del
+service y un valor más en el enum — no un controller/endpoint nuevo por catálogo.