feat: agregar flujo de Recomendaciones (Defensoría del Pueblo CABA)

[jansaldo]

Qué hace

Agrega un cuarto flujo — Recomendaciones — para la Defensoría del Pueblo de CABA. El usuario carga una Recomendación, un LLM local extrae los campos estructurados vía POST /llm/data-extraction, los valida contra el documento original con los valores resaltados, y el registro se acumula en una hoja recomendaciones del mismo .xlsx que ya usa el Set de Datos.

Implementa el plan en docs/superpowers/plans/2026-07-31-recomendaciones-defensoria.md (etapas 1–11), con las decisiones de producto ya resueltas en su §9.

Arquitectura

Reutiliza el árbol de rutas /app/$feature/* con el mismo patrón de ramificación que Voz a Texto. Sin cambios en src/main ni src/preload.

• Reutilizado sin cambios: FileProvider, reducer de archivos, useFileParse, fileParser, layout, FileProcessing, FileCheck, services/filesystem/excel.
• Extendido aditivamente: FileAnnotator (extraAnnotations / activeField opcionales), generateSplits (nuevo tipo extracted), DecisionTabs (label / onRemove), DocFile.recomendacion?, una acción nueva en el reducer.
• Nuevo: hook de estado controlado del formulario, localizador exact+fuzzy de valores, pantalla de validación, exportación a Excel, Textarea y RadioGroup en Panda.

Los tres flujos existentes (Set de Datos, Anonimizador, Voz a Texto) quedan verificadamente intactos: ninguno pasa las props nuevas, y la revisión final diffeó el output de generateSplits sobre 9702 entradas generadas de solo tag/search — 0 diferencias.

Highlighting sin offsets

La extracción no viene de NER, así que no hay offsets. utils/recomendaciones/locate-value.ts los deriva: matching exacto sobre todo el documento (todas las ocurrencias), y solo si no hubo ninguno, un pase fuzzy que devuelve el mejor match con umbral 0.9. Se resaltan numero_recomendacion, fecha_recomendacion, y nombre/cargo por destinatario; no se resaltan tema, subtema, sector, datos_personales ni contenido_para_publicar, porque son clasificaciones o síntesis del modelo y resaltarlos apuntaría a texto arbitrario.

Recall medido sobre entradas realistas en español: 99% en nombre y cargo, con precisión 100% sobre 1107 negativos (incluidos cientos construidos en la banda 0.80–0.899).

Backend pendiente

La persistencia no existe todavía. loadRecomendacion devuelve null ante 404/405/501 y errores de red, así que el flujo degrada a re-extraer siempre — es el camino esperado hoy, no un bug. El contrato que necesita el frontend está en docs/superpowers/plans/2026-07-31-recomendaciones-backend-contract.md, copiado del patrón prediction + validation que ya usan datapublic y asr.

Tres requisitos ahí son fáciles de implementar mal, y el segundo es el más importante del contrato:

1. prediction debe guardar el DataExtractionResult completo, con candidatos_nombre y candidatos_cargo — el frontend recupera de ahí los selectores de organigrama al reabrir.
2. El payload de validation debe round-trippear un id estable por destinatario. Hoy el frontend re-empareja por posición, lo que se desalinea si el usuario borró un destinatario antes de guardar.
3. datos_personales es boolean | null, donde null = sin responder. No coercionar a false.

Verificación

• pnpm test — 340 tests, 63 archivos, verde.
• pnpm typecheck — limpio. pnpm knip — exit 0, sin exports duplicados nuestros.
• pnpm lint falla, pre-existente: el script es biome check sin path, procesa 0 archivos y sale con error. Idéntico en el punto de fork. npx biome check src/ está limpio en todo el código nuevo.
• Incluye un cherry-pick de fix: migrate pnpm allowBuilds to v11 and pin packageManager #92, necesario para que la suite corra acá (el symlink de @aymurai/ui producía dos copias de React).

Cada etapa pasó por revisión propia con rondas de corrección. Varios bugs solo aparecieron al probar los módulos empíricamente en vez de leerlos — vale mencionar tres, porque los tests pasaban en verde en los tres casos:

• generateSplits descartaba las anotaciones nuevas una función más abajo de donde se había mirado, dejando la feature en no-op invisible.
• Los key de columna de exceljs no sobreviven la serialización, así que la exportación fallaba en el segundo documento (silenciosamente: el throw se comía en la lista de errores).
• La pantalla de validación guardaba las correcciones solo en estado local, así que el .xlsx recibía la inferencia cruda del LLM y descartaba todo lo que el humano había corregido. Ningún test por etapa podía verlo: el de la etapa 9 verificaba el payload de la mutación y el de la 10 alimentaba toExcelRow directo. Nada cruzaba la costura del reducer.

Pendiente para el reviewer

La pasada manual no se corrió — necesita el backend LLM local y un PDF real de Recomendación. Es la etapa 11 paso 2 del plan, y es el paso que habría detectado el bug de exceljs en segundos. Recomiendo correrla antes de mergear.

Riesgo a decidir

Con validation sin historial (§9.5) y loadRecomendacion fallando a null, cuando la persistencia exista una falla transitoria del GET va a re-extraer en silencio y puede sobrescribir una validación humana con una inferencia nueva, sin dejar rastro. El frontend ahora loguea un console.warn, que es el piso; una mitigación real necesita una señal visible al usuario o historial en el backend.

🤖 Generated with Claude Code

Summary by Sourcery

Add a new Recomendaciones feature flow for Defensoría del Pueblo CABA, integrating LLM-based data extraction, validation UI, and Excel export into the existing app.$feature architecture while keeping existing Dataset, Anonymizer, and VoiceToText flows intact.

New Features:

• Introduce the Recomendaciones flow routed through /app/$feature with onboarding, process, validation, and finish steps.
• Add controlled Recomendaciones validation form with document-side highlighting for extracted values and organigram candidate pickers.
• Export validated recomendaciones to a new recomendaciones worksheet in the existing Excel workbook, keyed by document UUID.

Enhancements:

• Extend FileAnnotator and generateSplits to support non-tag/search extracted annotations without affecting current flows.
• Generalize DecisionTabs with configurable labels and optional per-tab remove control.
• Add Panda-based Textarea and RadioGroup primitives to complement @aymurai/ui components.
• Implement robust data-extraction orchestration hook that handles cached backend data, fresh LLM runs, and abort/retry behaviour under React Query and StrictMode.

Documentation:

• Add detailed implementation and backend-contract plans for the Recomendaciones flow, covering architecture, data model, backend endpoints, and risk considerations.

Tests:

• Add comprehensive unit and integration tests for Recomendaciones form state, value locator, annotations, data-extraction hook, Excel export, and validation screen, including StrictMode and Exceljs edge cases.

[sourcery-ai]

Sorry @jansaldo, your pull request is larger than the review limit of 150000 diff characters

[sourcery-ai]

Reviewer's Guide

Adds a new "Recomendaciones" feature flow for Defensoría del Pueblo CABA, including frontend orchestration of LLM data extraction, controlled validation UI with document highlighting, Excel export into a shared workbook, and the supporting types, hooks, and infrastructure, while keeping existing Dataset/Anonymizer/Voice flows behaviorally intact.

Sequence diagram for the new Recomendaciones flow (extraction, validation, export)

sequenceDiagram
  actor Usuario
  participant RecomendacionesProcess
  participant useDataExtraction
  participant loadRecomendacion
  participant extractRecomendacion
  participant RecomendacionValidation
  participant saveRecomendacion
  participant submitRecomendacion
  participant filesystem_excel

  Usuario->>RecomendacionesProcess: Abre /app/RECOMENDACIONES/process
  RecomendacionesProcess->>useDataExtraction: useDataExtraction(file)
  useDataExtraction->>loadRecomendacion: GET /llm/recomendaciones/validation/document/{documentId}
  alt stored document found
    loadRecomendacion-->>useDataExtraction: RecomendacionDocument (prediction/validation)
    useDataExtraction->>useDataExtraction: normalizeExtraction / validationToValues
    useDataExtraction->>RecomendacionesProcess: dispatch(setRecomendacion)
  else no stored data
    loadRecomendacion-->>useDataExtraction: null
    useDataExtraction->>extractRecomendacion: POST /llm/data-extraction
    extractRecomendacion-->>useDataExtraction: DataExtractionResult
    useDataExtraction->>RecomendacionesProcess: dispatch(setRecomendacion)
  end

  Usuario->>RecomendacionValidation: Abre /app/RECOMENDACIONES/validation
  RecomendacionValidation->>RecomendacionValidation: useRecomendacionForm(recomendacion)
  RecomendacionValidation->>FileAnnotator: FileAnnotator(extraAnnotations, activeField)
  RecomendacionValidation->>RecomendacionValidation: buildExtractedAnnotations(values, paragraphs)

  Usuario->>RecomendacionValidation: Hace clic "validation.validar"
  RecomendacionValidation->>saveRecomendacion: saveRecomendacion(documentId, toValidationPayload(values))
  alt guardado exitoso
    saveRecomendacion-->>RecomendacionValidation: 204
  else error de guardado
    saveRecomendacion-->>RecomendacionValidation: Error
    RecomendacionValidation->>RecomendacionValidation: showToast(validation.saveFailed)
  end
  RecomendacionValidation->>RecomendacionValidation: dispatch(setRecomendacion(origin="validation"))

  Usuario->>submitRecomendacion: Abre RecomendacionFinish
  submitRecomendacion->>filesystem_excel: read() / create()
  submitRecomendacion->>filesystem_excel: ensureRecomendacionesSheet(workbook)
  submitRecomendacion->>submitRecomendacion: toExcelRow(values, documentId, fileName, validatedAt)
  submitRecomendacion->>filesystem_excel: write(workbook)

Loading

File-Level Changes

Change	Details	Files
Introduce the Recomendaciones feature flow into the existing /app/$feature route tree, with dedicated process, validation, and finish screens wired to the file reducer and React Query.	Extend FeatureFlowEnum, featureNamespace, home feature cards, and feature icons to include Recomendaciones Add branching in app.$feature onboarding/preview/process/validation/finish routes to render Recomendaciones-specific components Implement RecomendacionesProcess and RecomendacionValidation/Finish components that reuse FileProvider, layout, and RequireFile while orchestrating parsing, extraction, validation, and Excel export	src/renderer/src/types/features.ts src/renderer/src/constants/config.ts src/renderer/src/routes/home/features.tsx src/renderer/src/routes/app.$feature/route.tsx src/renderer/src/routes/app.$feature/onboarding.tsx src/renderer/src/routes/app.$feature/preview.tsx src/renderer/src/routes/app.$feature/process.tsx src/renderer/src/routes/app.$feature/validation.tsx src/renderer/src/routes/app.$feature/finish.tsx src/renderer/src/components/recomendaciones/process.tsx src/renderer/src/components/recomendaciones/validation.tsx src/renderer/src/components/recomendaciones/finish.tsx
Add domain modeling, schemas, hooks, and HTTP clients for Recomendaciones, including controlled form state and data-extraction orchestration with backend persistence fallback.	Define Recomendaciones types (DataExtractionResult, DestinatarioValue, RecomendacionState) and zod schemas for extraction and validation payloads Implement useRecomendacionForm for controlled form state, normalization of extraction results, and pristine/suggestion tracking Implement useDataExtraction hook that loads stored prediction/validation or triggers LLM extraction, attaching RecomendacionState to DocFile via a new reducer action Add servicios/aymurai/recomendaciones client (extractRecomendacion/loadRecomendacion/saveRecomendacion) and recomendacionValidationMutation in queries.ts Extend DocFile with optional recomendacion and reducer/actions with SET_RECOMENDACION	src/renderer/src/types/recomendaciones.ts src/renderer/src/schema/recomendaciones.ts src/renderer/src/hooks/useRecomendacionForm.ts src/renderer/src/hooks/useDataExtraction.ts src/renderer/src/services/aymurai/recomendaciones.ts src/renderer/src/services/aymurai/queries.ts src/renderer/src/reducers/file/actions.ts src/renderer/src/reducers/file/index.ts src/renderer/src/types/file.ts
Implement frontend value location and annotation building for highlighting extracted fields in the existing FileAnnotator, including support for a new "extracted" annotation type.	Add ExtractedValueAnnotation and extend Annotation union in file-annotator/types.ts Update FileAnnotator to accept extraAnnotations and activeField props, merging extracted annotations into the existing tag/search annotations and rendering them via ExtractedAnnotation Fix generateSplits token merge to preserve non-tag/search tokens (e.g. extracted) and drop them only when overlapping tag/search Implement locateValue (exact+fuzzy matching over paragraphs using fastest-levenshtein) and buildExtractedAnnotations to convert RecomendacionValues into per-paragraph extracted annotations	src/renderer/src/components/file-annotator/types.ts src/renderer/src/components/file-annotator/index.tsx src/renderer/src/components/file-annotator/generateSplits.ts src/renderer/src/components/file/extracted-annotation.tsx src/renderer/src/utils/recomendaciones/locate-value.ts src/renderer/src/utils/recomendaciones/build-annotations.ts
Extend UI primitives and decision tabs to support the Recomendaciones validation UX, including a Panda Textarea, RadioGroup wrapper, and removable, relabelable tabs for destinatarios.	Add Panda-based Textarea component mirroring @aymurai/ui TextField styling for multiline content Add Panda-based RadioGroup wrapper around @aymurai/ui Radio for grouped labelled radios Parameterize DecisionTabs to accept a label prop and optional onRemove handler, adding an accessible remove control per tab when applicable Implement RecomendacionForm, DestinatarioFields, and OrganigramPicker to render the right-hand validation form with suggestions, organigram candidates, and out-of-taxonomy/list warnings	src/renderer/src/components/ui/textarea.tsx src/renderer/src/components/ui/radio-group.tsx src/renderer/src/components/decision-tabs/index.tsx src/renderer/src/components/recomendaciones/recomendacion-form.tsx src/renderer/src/components/recomendaciones/destinatario-fields.tsx src/renderer/src/components/recomendaciones/organigram-picker.tsx
Add Excel export support for Recomendaciones in the shared workbook, using a new recomendaciones worksheet and an upsert writer keyed by DOCUMENT_ID.	Define RECOMENDACIONES_COLUMNS and toExcelRow to flatten RecomendacionValues into a single recomendaciones row with identity and destinatario summary columns Add ensureRecomendacionesSheet to create or re-key a recomendaciones worksheet in the shared workbook, handling exceljs column key aliasing after read/write round-trips Implement submitRecomendacion to read or create the workbook, upsert recomendaciones rows by DOCUMENT_ID, and write back to disk Wire RecomendacionFinish to call submitRecomendacion per file and expose a "Ver recomendaciones" button via filesystem.excel.open; adjust offline dataset writer to target set_de_datos by name	src/renderer/src/utils/recomendaciones/to-excel-rows.ts src/renderer/src/services/filesystem/excel/recomendaciones-sheet.ts src/renderer/src/utils/recomendaciones/submit-recomendacion.ts src/renderer/src/components/recomendaciones/finish.tsx src/renderer/src/utils/file/submitValidations/offline.ts
Add Recomendaciones-specific constants, taxonomy, i18n strings, and planning/contract docs to support the flow and its backend integration.	Introduce TAXONOMY, TEMA_OPTIONS, subtemaOptions, and SECTOR_OPTIONS for tema/subtema/sector selects Add Spanish i18n namespace for recomendaciones covering titles, process/validation/finish text, and validation error messages Add long-form implementation plan and backend contract docs under docs/superpowers/plans for Recomendaciones and its persistence API	src/renderer/src/constants/recomendaciones/taxonomy.ts src/renderer/src/constants/recomendaciones/sectores.ts src/renderer/src/constants/i18n/locales/es/recomendaciones.ts src/renderer/src/constants/i18n/locales/es/index.ts docs/superpowers/plans/2026-07-31-recomendaciones-defensoria.md docs/superpowers/plans/2026-07-31-recomendaciones-backend-contract.md
Adjust infrastructure and config to support the new code, dependencies, and test behavior without breaking existing flows.	Add fastest-levenshtein dependency and bump pnpm packageManager version; remove pnpm.onlyBuiltDependencies block Update pnpm-workspace allowBuilds for @aymurai/ui tarball URL hash Configure tanstack-router codegen to ignore .test.tsx route files and vitest to run with Argentina time zone Fix offline dataset writer to select set_de_datos worksheet by name instead of index so it can coexist with recomendaciones	package.json pnpm-workspace.yaml vite.config.ts vitest.config.ts src/renderer/src/utils/file/submitValidations/offline.ts

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.