feat: FK polimorfica Document -> {partida, cove, edocument} + backfill (T2025-09-004)

Reemplaza el matching fragil por nombre de archivo con FK reales:
- 3 FK nullables (CASCADE) en Document; resolucion central en save() por
  document_type + nombre (core.document_links), cubre toda ruta de creacion
  incluida la ingesta del microservicio; set explicito en create_vu_record.
- Comando backfill_document_links (idempotente, dry-run) para filas existentes.
- Lectura/descarga/borrado SIEMPRE por la FK (id); el nombre solo ESTABLECE la
  FK en save()/backfill. Prefetch con select_related(pedimento, fuente) sin N+1.
- Migraciones: 0004 (campos), 0005 (indices CONCURRENTLY IF NOT EXISTS, idempotente
  via SeparateDatabaseAndState), 0006 (ANALYZE document para estadisticas del planner).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-06-24 08:13:47 -06:00
parent 244bbcb21c
commit 2e7d78fd8b
11 changed files with 592 additions and 196 deletions

37
CHANGELOG.md Normal file
View File

@@ -0,0 +1,37 @@
# Changelog — EFC Backend
Historial de cambios por ticket (más reciente arriba). Cada entrada: fecha, ticket,
tipo, repos afectados, qué se hizo y por qué. Reglas del flujo en `../CLAUDE.md`.
## T2025-09-004 — Pertenencia documento→entidad (matching de partidas + FK polimórfica)
- **Fecha:** 2026-06-24
- **Tipo:** feature
- **Repos:** backend (microservice/frontend: sin cambios — el microservicio ya embebe
el número en el nombre del archivo y el backend resuelve la FK al crear el documento)
- **Branch:** `feature/T2025-09-004` · **PR:** (pendiente de aceptación manual)
- **Qué se hizo:**
- Matching documento→partida con frontera `(_|.|$)` en `core/partida_docs.py` (cubre los
3 formatos de nombre sin confundir la partida 1 con 11/100).
- FK reales `document.partida` / `cove` / `edocument` (nullable, `CASCADE`); los acuses
cuelgan de su cove/edoc padre; los documentos nativos (PC, remesa, subidas generales)
quedan sin FK.
- Resolución central en `Document.save()` vía `core/document_links.py`: liga la FK por
`document_type` + nombre de archivo en toda ruta de creación (incluida la ingesta del
microservicio); set explícito de la FK en `create_vu_record`.
- Comando `backfill_document_links` para poblar la FK en filas existentes (idempotente).
- Lectura, descarga y borrado SIEMPRE por la FK (id), nunca por nombre. El nombre solo
ESTABLECE la FK (en `Document.save()` para altas y en el backfill para filas viejas).
- **Por qué:** retirar el matching frágil por nombre de archivo (`icontains`/prefijo, que
confundía entidades y se rompía con formatos nuevos) y tener la pertenencia
documento→entidad como dato real, consultable e íntegro.
- **Migraciones:** `0004_document_subentidad_fk` (campos, metadata-only),
`0005_document_subentidad_idx` (índices con `CREATE INDEX CONCURRENTLY IF NOT EXISTS`,
`atomic=False`, idempotente vía `SeparateDatabaseAndState`),
`0006_analyze_document` (`ANALYZE document`: refresca estadísticas del planner — sin esto,
el prefetch hacía seq scan sobre ~5M filas y los endpoints tardaban ~9s).
La tabla `document` tiene ~5M filas: cada índice tarda minutos y NO debe interrumpirse.
Recuperación si se corta: índices válidos → `migrate --fake record 0005`; alguno INVALID →
`DROP INDEX IF EXISTS "<nombre>";` y reintentar `migrate record`.
- **Despliegue (orden obligatorio):** aplicar migraciones (0004-0006) → **correr el backfill
completo** → recién entonces la lectura/descarga/borrado por FK es correcta. Como NO hay
fallback por nombre, un documento sin backfillear queda invisible hasta ligar su FK.