Estado del Proyecto¶

MVP: 100% Completado | API: 100% (22/22 endpoints) | S28: Completado (100%)¶

Metricas¶

Metrica	Valor
Tests	1770 unit + 62 integration = 1832 total
CLI	20 comandos
GUI	9 paginas
API REST	22 endpoints (22/22 funcionales)
Coverage	87.77% (excluyendo GUI, CI gate: 87%)
Calidad	97/100
NER F1	85.3%
DIP violations	0
SECs remediados	16/16 + 4 SEC-API + RBAC + rate limit + security headers
GOBs implementados	16/16 (GOB-12..16 completados en Sprint 23)
ServiceContainer	14 properties lazy-loaded (thread-safe con RLock)
Diagramas	12/12 mermaid + 12 PNG (regenerados S28 con metricas actualizadas)
Gobernanza docs	10 archivos (6 originales + 4 nuevos S23)
Deploy scripts	7 (4 originales + 3 nuevos S23)
Bypasses GUI→Repo	0 (16 eliminados en Fase 1.5)
Deploy API	Entrypoint unificado SHERLOCK_MODE=gui\|api, imagen unica Docker
Produccion API	`https://api.sherlock.sprintjudicial.com` (subdominio, SSL OK)
Manual API	v2.1 con 22/22 endpoints documentados

Sprints (23 + 23.1 + 24 + 25 + 25.1 + 26 + 27 + 27.2 + 28 completados)¶

✅ 01: Setup + Core — 02: Fundamentos — 03: Testing — 04: NER
✅ 05: Hashing + Dedup — 06: GUI v1 — 07: Migracion GUI — 08: MVP Features
✅ 09: GAPS UX + E2E — 10: Fix E2E — 12: NER Optimization (F1 85.3%)
✅ 13: CI/CD Pipeline — 14: Deploy VPS (PRODUCCION LIVE)
✅ 15: SHA-256 Fix — 16: Correcciones + UX — 17: Deuda Tecnica
✅ 18: Pipeline Hibrido — 19: UX + Historial + CLI
✅ 20: Gobernanza Legal IA (CSJ Bello)
✅ 21: Import/Export Excel Fixes — 22: Paginacion + CSV omitidos
✅ 23: Contraauditoria SDD + Fase 0 Pre-API (38/38 SPECs + 4 diferidos)
✅ 23.1: Quick wins deuda tecnica (7/7 SPECs + 5 Fase 1.5 + 4 Fase 1.5b)
✅ 24: API Foundation FastAPI (10/10 SPECs: JWT, 7 endpoints, Swagger)
✅ 25: API Completa (10/10 SPECs: 15 endpoints adicionales, TaskManager async)
✅ 25.1: Security hardening + API quality (15/15 FIXs + 5/5 BUGs produccion)
✅ 26: Auditoria integral API + Deploy (32/32: RBAC, rate limit, security headers, entrypoint unificado, deploy VPS)
✅ 27: Deuda tecnica (9/9 SPECs: mypy 0 errores, Result pattern, VOs)
✅ 27.2: Brechas de calidad (BRECHA-1..3 + BUG-EXCEL: AppError, persistence Result, coverage 83%)
✅ 28: Estabilizacion + coverage 87% (11/11 SPECs + 5 BUGs + NER fix + auditoria CDAID + diagramas)

Sprint 28 — Detalle¶

Estado: COMPLETADO (100%) — 11/11 SPECs + extras Implementado: - SPEC-S28-A1..A4 (logging, type:ignore, f-strings, docs 21→20) - SPEC-S28-B1..B4 (pipeline tests, CLI tests, persistence tests, API tests) + 90 tests extra - SPEC-S28-C1 (gate CI 87%), SPEC-S28-C2 (agent_docs actualizado), SPEC-S28-C3 (auditoria CDAID 8/8 CONFORME) - BUG-1..5 + RISK-7: 5 bugs pre-produccion corregidos (dedup indexing, URLs placeholder, .xls→.xlsx, upload.py, frozen, UTC) - NER fix: 3 defectos acta reparto (regex fallback, doble MUNICIPAL, 62 tests) + umbral ensemble 0.10→0.15 - Diagramas: 12 .mmd + 12 PNG regenerados con metricas actualizadas - Auditoria CDAID: 8/8 CONFORME, 0 defectos

Decision BRECHA-4 (WONTFIX): Document VOs Fase 2 cancelada. Justificacion: 42 archivos / 129 tests afectados, beneficio usuario CERO, VOs como computed properties (Fase 1) ya dan 80% del beneficio DDD. Evaluado por agente senior-architect, aprobado por humano.

Plannings (31)¶

01-Buenas practicas, 02-Gaps IA, 03-SpaCy audit, 04/05-E2E, 06-Roadmap, 07-QA, 08-On-premise, 09-Analisis integral, 10-UX pendiente, 11-Auditoria integral, 12-Prueba manual, 13-Historial accionante, 14-Finalizacion MVP, 15-Security hardening, 16-Cierre MVP, 17-Evolucion CDAID, 18-Gobernanza Legal IA, 19-Auditoria code smells, 20-GOB-05 auth, 21-Import/Export fixes, 22-Paginacion+CSV, 23-Contraauditoria SDD, 23.1-Auditoria deuda tecnica, 24-Analisis API .NET, 24-Fase1 API Foundation, 25-Fase2 API Completa, 25.1-Security hardening API, 26-Auditoria integral API, 27-Auditoria calidad codigo (9.1/10), 28-Estabilizacion + coverage 90%

Produccion¶

URL: https://sherlock.sprintjudicial.com
Deploy: Automatico push a main + manual (workflow_dispatch)
Imagen: ghcr.io/hammerdev99/sherlock-docs:latest
VPS: Hostinger, Ubuntu 24.04, 2 vCPU, 7.8 GB RAM

API REST FastAPI (S24 + S25 + S25.1)¶

22 endpoints: health, auth(4), documents(CRUD+search+stats), process, validate, recurring, duplicates(2), manual, import/export, config(3), tasks
Auth: JWT (HS256, 8h expiry, max 5 refreshes), 20/20 endpoints protegidos
Schemas: Pydantic v2 en schemas/ (common, auth, documents, health, tasks, validation, duplicates, config)
Error handling: result_mapper.py (Result→JSONResponse) + exception handler global en main.py
Async: TaskManager (ThreadPoolExecutor) para OCR processing, polling via /tasks/{id}
Seguridad API: path traversal prevention, temp cleanup, file size validation, XSS sanitization, CORS
Swagger: /docs (auto-generado por FastAPI)
Seguridad S26: RBAC (require_admin), rate limiting login (5/min), security headers, CORS restrictivo, Swagger deshabilitado en prod
OpenAPI S26: response_model en 22 endpoints, error responses documentados (401/403/404/429/500), HTTPBearer auth
Deploy API: Entrypoint unificado SHERLOCK_MODE=gui|api, imagen unica Docker
Postman: Coleccion 22 endpoints en docs/postman/Sherlock_API_v1.postman_collection.json

Security Hardening (Planning 15 + S25.1)¶

16/16 SECs remediados + 4 SEC-API. 3 CRITICOS + 3 ALTOS + 9 MEDIOS. SEC-05 (autenticacion) → implementado como GOB-05 (streamlit-authenticator). SEC-API: path traversal, temp cleanup, refresh limit, file size validation. 19 tests de seguridad base + 33 tests API security.

Gobernanza Legal IA (Planning 18 + Sprint 23)¶

16/16 GOBs implementados. Cumplimiento legal: - PCSJA24-12243: 60% → 95% (avisos IA + audit + auth + manual + incidentes) - Ley 1581: 70% → 95% (politica datos + data governance + retencion + incidentes) - CONPES 3975: 40% → 85% (EIAI + Model Card + audit + ethics + sesgo NER doc) - Guia MinTIC: 40% → 85% (EIAI + Model Card + audit + ethics) - GOB-05: Autenticacion streamlit-authenticator (bcrypt + JWT cookie) - GOB-08/09/10: MANUAL_USUARIO, DATA_GOVERNANCE, AI_ETHICS - GOB-11: CLI sherlock audit-report con filtros + CSV + summary - GOB-12: Analisis sesgo NER documentado (aplazado formal, validacion humana) - GOB-13: SQLCipher decision documentada (aplazado, mitigaciones LUKS+auth) - GOB-14: Politica retencion automatizada + cleanup-uploads.sh - GOB-15: Plan respuesta incidentes operativo (SLA, RACI, plantilla) - GOB-16: Dashboard gobernanza decision (CLI cubre necesidad) - Documentos en docs/governance/: 10 archivos (6 + 3 decisions/ + 1 retention)

Sprint 23 — Completado (38/38 SPECs)¶

Referencia: docs/plannings/planning_23_.../04_SDD_SPEC_SPRINT_23.md + 05_SDD_SPEC_FASE0_USE_CASES.md

Resumen por fase: - Sprint A (Fundamentos): 7/7 — deque, RLock, extract methods, whitelist, atomic txn - Sprint B (App Services): 4/4 — Validation, Search, Statistics, ManualEntry+Dedup - Sprint C (Schema): 2/2 — 4 frozen VOs, tabla duplicate_detections - Sprint D (Cleanup): 3/3 — duplicate_renderer (Facade+Strategy), cli logging, matched_entities - Sprint E (Bugs): 2/2 — negaciones, año MAX_VALID_YEAR - Sprint H (NER DEMANDADO): 5/5 — whitelist sync, tie-breaking, multi-winner, compound splitter, fallback "contra" - Sprint F (Infra): 4/4 — backup offsite, UFW, security headers, Docker digest - Sprint G (Gobernanza): 5/5 — incidentes, retencion, SQLCipher, sesgo NER, dashboard - Sprint I (Fase 0 Pre-API): 6/6 — DTOs+Result en 5 servicios, 5 GUI delegando, ~467 LOC extraidas

Tests: 1005 → 1336 (S23) → 1332 (S23.1: -7 dead code + +3 ActiveLearning) Diferidos: DIF-01..04 (con justificacion tecnica) Auditoria SDD Fase 0: CERTIFICADA — 39 conformes, 7 divergencias justificadas, 2 menores, 0 defectos

Sprint 23.1 — Completado (16/16 SPECs)¶

Referencia: docs/sprints/sprint_23_1_.../01_RESUMEN_SPRINT.md

Quick wins + Fase 1.5 + Fase 1.5b: - 7 quick wins (P0-P4): bug produccion, dead code, config consistency, type hints, diagramas, ActiveLearning - 5 Fase 1.5: Eliminacion de 16 bypasses GUI→Repo - 4 Fase 1.5b: Consolidacion code smells (IA disclaimer, Juzgado widget, prepare_for_validation)

Sprint 24 — API Foundation (10/10 SPECs)¶

Referencia: docs/plannings/planning_24_2026-03-24_.../00_PLANNING_FASE1_API_FOUNDATION.md

FastAPI + JWT auth + 7 endpoints iniciales + Swagger UI (/docs): - App factory con lifespan, CORS, settings via env vars - Auth: JWT encode/decode, credential loading desde YAML - Health, documents CRUD, dashboard stats - 19 tests de integracion

Sprint 25 — API Completa (10/10 SPECs)¶

Referencia: docs/plannings/planning_25_.../00_PLANNING_FASE2_API_COMPLETA.md

15 endpoints adicionales + TaskManager async: - Process (async OCR via ThreadPoolExecutor), validate, manual, search, recurring - Duplicates (detect + verify), import/export Excel, config (dedup, NER, stats) - Task polling, delete document - 18 tests de integracion

Sprint 25.1 — Security Hardening (20/20 items)¶

Referencia: docs/sprints/sprint_25_1_.../01_RESUMEN_SPRINT.md

Fase 1: 15 hallazgos de auditoria API (6 P0, 4 P1, 5 P2) Fase 2: 5 bugs de produccion corregidos (BUG-1..5) Fase 3: 6 hallazgos nuevos documentados (2 media, 4 baja) — pendientes de correccion

Score API: 6.8/10 → 9.2/10. Tests: 1369 → 1402.

Pendientes Fase 3 (6 hallazgos)¶

ID	Sev	Descripcion
HALL-01	Media	9/23 docs fallan en `/documents/{id}/duplicates` (dataclasses.asdict + MappingProxyType)
HALL-02	Media	Validate doc inexistente → 500 FOREIGN KEY (falta check existencia)
HALL-03	Baja	Recurring doc inexistente → 200 en vez de 404
HALL-04	Baja	Export con fecha invalida se ignora
HALL-05	Baja	`javascript:` protocol no sanitizado en XSS
HALL-06	Baja	Import XLSX invalido → 500 en vez de 422

Sprint 26 — Auditoria Integral API — COMPLETADO (32/32)¶

Planning: docs/plannings/planning_26_.../00_PLANNING_SPRINT_26.md Verificacion: docs/plannings/planning_26_.../02_AUDITORIA_VERIFICACION_API.md Plan impl: docs/plannings/planning_26_.../03_PLAN_IMPLEMENTACION_SPRINT_26.md Deploy API: docs/plannings/planning_26_.../01_DEPLOY_API_SERVICE_VPS.md Resultado deploy: docs/plannings/planning_26_.../06_RESULTADO_FINAL_DEPLOY_API.md

32/32 items completados: RBAC, rate limit, security headers, entrypoint unificado, deploy VPS. Tests: 1402 → 1442+. Deploy API produccion: https://api.sherlock.sprintjudicial.com

Sprint 27.2 — Brechas de Calidad — COMPLETADO¶

Métricas: 1569 tests, 83% coverage, mypy 0 errores.

Brechas cerradas:

ID	Descripción	Estado
BRECHA-1	`Failure(str)` → `Failure(AppError)` en todos los servicios de application/	✅ Cerrada
BRECHA-2	Persistence Result pattern: `delete`, `update_status`, `update_document_field`, `save_processing_metrics` retornan `Result[T, AppError]`	✅ Cerrada
BRECHA-3	Coverage 78% → 83% (gate CI bloqueante)	✅ Cerrada
BUG-EXCEL	`hora_radicacion` timezone — hora incorrecta en export Excel por falta de timezone-aware	✅ Corregido

Cambios clave: - core/errors.py: AppError (frozen dataclass) + ErrorCode (enum) con mapeo a HTTP status codes - AppError.__str__ retorna message para backward compatibility con str(failure) - Todos los servicios migrados de Result[T, str] a Result[T, AppError] - 53+ tests CLI en tests/unit/interfaces/test_cli.py - 9+ tests integration cross-layer en tests/integration/

Auditoria de Calidad de Codigo (Planning 27)¶

Referencia: docs/plannings/planning_27_.../00_AUDITORIA_CALIDAD_CODIGO_COMPLETA.md

Auditoria exhaustiva por 6 agentes especializados (2026-03-26): - Analisis de ~26,300 LOC, 130+ archivos, 1,442 tests, 27 sprints, 29 plannings - Score global: 9.1/10 (ponderado por capa)

Scores por capa: | Capa | Score | |------|-------| | Core (Domain) | 9.5/10 | | Application | 9.0/10 | | Infrastructure | 9.3/10 | | Persistence | 8.5/10 | | GUI (Streamlit) | 9.0/10 | | CLI | 7.5/10 | | API REST | 9.2/10 | | Testing | 9.2/10 | | Documentacion + Gobernanza | 9.6/10 | | Deploy + CI/CD | 9.2/10 |

Hallazgos clave: 68 frozen dataclasses, 69 usos get_logger (0 violaciones), 18 patrones de diseno, 0 except: pass, 100% type hints, 0 bypasses GUI→Repo.

Roadmap API FastAPI + .NET¶

Referencia: docs/plannings/planning_24_.../00_ANALISIS_ARQUITECTONICO_API_NET_SDD.md

Fase 0: Sprint 23 (extraccion use cases con DTOs+Result) — COMPLETADO (6/6)
Fase 1: Sprint 24 (API Foundation FastAPI) — COMPLETADO (10/10)
Fase 2: Sprint 25 (API Completa 22 endpoints) — COMPLETADO (10/10)
Fase 2.1: Sprint 25.1 (Security hardening + quality) — COMPLETADO (20/20)
Fase 2.2: Sprint 26 (Auditoria integral + docs) — COMPLETADO (32/32)
Fase 2.3: Deploy servicio API en VPS (EasyPanel + Traefik) — COMPLETADO (produccion live: api.sherlock.sprintjudicial.com)
Fase 3: Frontend .NET 8/9 (Blazor/MVC) consumiendo API via OpenAPI — PENDIENTE

Documentacion Detallada¶

docs/sprints/sprint_NN_FECHA_TEMA/ — 28 sprints documentados
docs/plannings/planning_NN_FECHA_TEMA/ — 31 plannings documentados
docs/diagrams/ — 9 diagramas mermaid + PNG renderizados
docs/governance/ — 10 documentos de gobernanza IA
docs/governance/decisions/ — 3 decisiones formales de aplazamiento
docs/plannings/planning_16_.../00_CIERRE_MVP.md — Documento cierre
docs/plannings/planning_27_.../00_AUDITORIA_CALIDAD_CODIGO_COMPLETA.md — Auditoria calidad 9.1/10