Skip to content

PLAN.md

Latest commit

 

History

History
53 lines (44 loc) · 3 KB

PLAN.md

File metadata and controls

53 lines (44 loc) · 3 KB
Raw

PLAN — Microservicio de Deuda/Factorización de Contratos

Derivado de SPEC.md + CONTEXT.md + docs/adr/. Trazabilidad: toda tarea/fase apunta al SPEC. Prioridades del SPEC: ambos módulos (Cálculo, Tokens) son P1 (MVP). Las funcionalidades futuras son P2/P3 y quedan fuera de v1 (la arquitectura ya las acoge).

Criterios de "hecho" del conjunto (copiados de S1)

  • SC-1 corrección de la transformación en el 100% de los casos.
  • SC-2 p95 ≤ 400 ms · media ideal < 120 ms (pico ~5.000 simultáneas).
  • SC-3 disponibilidad con la BD de tasa caída (fallback API).
  • SC-4 rechazo del 100% de orígenes no autorizados / exceso de uso.

Fases (todas P1 salvo lo marcado)

Fase 0 — Fundamentos y paridad (P1)

Base común a ambas implementaciones y mecanismo de equivalencia.

  • Scaffold dual: estructura para Python/FastAPI y Laravel/Octane.
  • Config/env unificada (URLs, credenciales BD#1/#2, timeouts, rate-limit, toggle truncate/round, master admin).
  • Utilidades decimales + constantes/enum (4 dec, 6 dec, IGTF 0.03).
  • Suite de conformidad (JSON neutral): casos dorados con casos límite de decimales.
  • ADRs que restringen: ADR-0001 (paridad decimal), ADR-0003 (Redis), ADR-0004 (fail-safe).

Fase 1 — Núcleo: cálculo + API de deuda (P1)

El contrato GET /debt/{contract_id} con la transformación completa.

  • Cliente getcontractdebt (GET con body, parse strings→decimal).
  • Tasa del día: BD exchange_rate_responses + fallback API getexchangerate.
  • Factor: aradial_services por concept_motive_id (regla recurrency).
  • Cálculo por nota + ensamblado {totales, detalles}.
  • Caso "Debt Not Exist" → 200 tiene_deuda:false.
  • Error paths + timeouts + reintentos.
  • Cubre: S3 (Cálculo), S4 (happy + error paths).

Fase 2 — Seguridad: tokens + rate-limit (P1)

Proteger el servicio y validar origen/consumidor.

  • Modelo de token (por consumidor, hasheado, vigencia).
  • Validación de token en GET /debt.
  • Superficie admin /admin/tokens + master credential + red interna.
  • Rate-limit por consumidor (Redis) + validar origen.
  • Cubre: S3 (Gestión de tokens), S2 (auth), S6 (rate-limit). ADRs: ADR-0002.

Fase 3 — Rendimiento y operación (P1/P2)

Sostener la concurrencia y operar en producción.

  • Caché Redis (tasa, aradial, validación de token + blacklist).
  • Observabilidad (logs, trazas, métricas).
  • Despliegue Docker + Kubernetes con escalado horizontal.
  • Cubre: S5 (caché), S6 (observabilidad, hosting, concurrencia). ADRs: ADR-0003.

Futuro (P2/P3 — fuera de v1)

Agregación «deuda total de un cliente» · nuevos impuestos/conversiones · auditoría de consultas · migración a OpenSpec/Spec-Kit.

Reglas del plan

  • Toda tarea traza al SPEC (ver TASKS.md); si no traza, falta en el spec (→ re-spec) o sobra en el plan.
  • Vocabulario del glosario (CONTEXT.md): cero sinónimos de Evitar (p. ej. Cliente ≠ Consumidor).
  • Si una tarea contradice el SPEC o un ADR, señalarlo antes de ejecutarla.