balam/plans/etapa1-plan.md

Plan: Documento "Plan-Etapa1.md" — plan fiel y completo de la Etapa 1

Contexto

Johann necesita el plan de trabajo de la Etapa 1 — "Plataforma base y sincronización con BIND" (32–39 h contractuales, semanas 2–3, ventana 13–24 jul). Hoy 16-jul solo 1 de los 8 entregables contractuales está terminado (el cliente API de BIND, portado a C# con 13 pruebas) y hay 8 h registradas de la etapa; quedan ~24–31 h y la demo semanal del viernes 18-jul es el compromiso más cercano. El usuario pidió un plan "lo más fiel posible" a toda la documentación (propuesta comercial v1.2, ADRs de Etapa 0, VALIDACION-API.md, bitácora, seguimiento de horas) — se revisó todo con 2 agentes de exploración y 1 de diseño.

Decisión del usuario: generar SOLO el documento (no arrancar implementación todavía), guardado en el repo privado de gestión ../balam (nunca en el repo del cliente balam-plataforma — regla del CLAUDE.md de ese repo).

Qué se hará

1. Crear planeacion/Plan-Etapa1.md en c:\Users\JohannVelazquez\Desktop\Personal\balam con el contenido detallado abajo.
2. Agregar 1 línea de referencia en planeacion/Plan-actividades.md (sección Etapa 1) apuntando al nuevo documento: > Plan detallado de ejecución: [Plan-Etapa1.md](Plan-Etapa1.md).
3. Nada más: sin commits al repo del cliente, sin código. (El repo bitácora tiene cambios sin commitear del usuario; NO commitear nada ahí tampoco, solo dejar los archivos.)

Contenido del documento Plan-Etapa1.md

Estructura y contenido esencial (redactado en español MX, estilo de los docs existentes de planeacion/):

§1 Resumen y estado (al 16-jul)

• Entregable contractual de la etapa (propuesta L142–157): plataforma que ingiere clientes/facturas de BIND, los normaliza, mantiene trazabilidad y habilita capa de escritura controlada. 32–39 h · $19,200–$23,400.
• Horas: 8.00 h registradas (reconstruidas) → quedan ~24–31 h. Tabla de los 8 entregables contractuales con estado real (solo cliente BIND ✅; scaffold/DbContext/entidades semilla ✅ como avance parcial; resto ❌).
• Hechos del repo de código: solución .NET 10 compilando, 13 pruebas verdes, API con /health y /api/bind/status, Angular 21 con tema de marca.

§2 Calendario e hitos externos

Fecha	Hito
jue 17-jul	Fin de ventana planeada de backend base + multi-tenant
vie 18-jul	Demo semanal (30 min, Pedro + gerencia) — meta: login+roles, sync real de BIND en Postgres, endpoint de cartera
sem 21-jul	Acceso Azure (Pedro+Noé) — no bloquea trabajo local
mié 22-jul	Sesión de definiciones Etapa 1 (Arturo + CEO): alta cliente, fee, envío, alcance Jira→BIND
jue 23-jul 7pm	Validación del prototipo Etapa 0
vie 24-jul	CI/CD + secretos · demo/cierre de etapa

§3 Plan de construcción por bloques (B0–B9, fases F1–F6)

Incluir el plan técnico completo producido en el diseño (resumido aquí; el documento lo lleva íntegro):

• F1 (16-jul) — B0 Preparación (0.5–1 h) + B1 Modelo de datos (3.5–4.5 h): docker-compose Postgres 17 local; entidades Tenant, Client, Invoice (modelo central con estados), Quote, QuoteInvoiceLink (ADR-003), InvoiceStatusChange (ADR-004), WriteOperation; extender SyncCheckpoint/AuditLogEntry con TenantId; BalamDbContext → IdentityDbContext<BalamUser,…>; convenciones de fechas Npgsql (BIND sin zona → timestamp without time zone) y decimales; migración Inicial + DbSeeder idempotente (tenant Balam, 4 roles, 5 usuarios ficticios).
• F2 (17-jul) — B2 Auth+roles+bitácora (4–5 h) + B3 Sync clientes (2.5–3.5 h): ASP.NET Core Identity + JWT propio (sin MapIdentityApi, sin refresh tokens en E1); roles Finanzas/Direccion/Operaciones/Administracion (sin acentos como identificador); policies nombradas + matriz de acceso por endpoint; AuditMiddleware (mutantes + 401/403) + IAuditLogger explícito (login, ciclos de sync, escritura) — NO interceptor EF (inundaría con upserts del sync); sync de clientes: full-scan barato de lista (sin campo fecha filtrable) + SourceHash + detalle solo nuevos/cambiados + normalización RFC/nombre + dedup por RFC exacto excluyendo genéricos (DuplicateOfClientId).
• F3 (18-jul am) — B4 Sync facturas/cotizaciones + cartera (4.5–5.5 h) → DEMO: delta Date ge desde checkpoint + re-barrido de ventana de facturas abiertas (los pagos caen en facturas viejas) + detalle solo nuevas/cambiadas con tope por ciclo; mapeo de estados plataforma (Emitida=prefactura, Vigente, Vencida=derivada con fecha MX, Pagada, Cancelada) como función pura con pruebas (frontera Emitida/Vigente a confirmar el 22-jul); detección de pagos por transición → InvoiceStatusChange con fecha de DETECCIÓN (ADR-004); endpoints GET /api/cartera (agregados POR MONEDA, nunca mezclarlas), /api/invoices, /api/clients, /api/quotes, POST /api/sync/run; sync inicial del histórico (>1,000 facturas) se corre el jueves en la noche, nunca en vivo.
• F4 (21-jul) — B5 Scheduler (2–3 h) + B6 RLS (1.5–2.5 h): BackgroundService + PeriodicTimer 15 min (NO Quartz/Hangfire — un solo job, estado en checkpoints), SemaphoreSlim anti-solape, guarda de cuota vía BindQuotaTracker (reserva configurable), backfill gradual de detalle histórico; RLS REAL de Postgres (contractual): políticas tenant_isolation por tabla con current_setting('app.tenant_id') + FORCE + WITH CHECK, TenantConnectionInterceptor con set_config, más filtro global EF (ITenantOwned) como segunda capa; fuera: CRUD tenants, resolución por request.
• F5 (22-jul, post-sesión) — B7 Capa de escritura controlada (3–4 h): pipeline Draft → DryRun → Confirm persistido en WriteOperations, todo auditado; BindWriteClient : BindClient (reusa RequestAsync protected y sus salvaguardas); feature flags BindWrite:Enabled=false default; PPD default, PUE solo con confirmación explícita (salvaguarda 4); CERO llamadas reales a BIND — shapes provisionales marcados TODO hasta doc del portal con Pedro; conversión mock registra QuoteInvoiceLink.
• F6 (23–24 jul) — B8 Suite de pruebas (2.5–3.5 h) + B9 datos de prueba + runbook (1–2 h): nuevo proyecto tests/Balam.Api.Tests con WebApplicationFactory + SQLite in-memory (no EF InMemory — no valida FKs/únicos; no Testcontainers — exige red/Docker en tests); cobertura contractual: matriz de roles, sync (delta/checkpoint/detección de pago), multimoneda, salvaguardas de escritura; DevDataSeeder ficticio multimoneda/multi-estado (respaldo de demo); runbook de demo.

§4 Presupuesto de horas

Tabla B0–B9 (nominal ~27.5 h, rango 25–31) + recortes identificados (≈ −5 h): audit endpoint y quotes-sync pueden moverse post-demo; dedup solo RFC; backfill mínimo. B6 (RLS) NO recortable a cero por ser contractual.

§5 Decisiones de arquitectura (con porqués, citables)

Scheduler BackgroundService vs Quartz; RLS real en dos capas; Identity+JWT sin refresh tokens (diferidos a Etapa 2 con la UI); bitácora middleware+servicio vs interceptor EF; SQLite en pruebas con costo aceptado (RLS/timestamptz se verifican manual en runbook); trampas Npgsql (fechas), "hoy" con zona México, partial class Program.

§6 Bloqueado hasta el 22-jul y fuera de alcance

• Bloqueado: escritura real a BIND (ADR-001), reglas de alta de cliente/fee/envío, alcance Jira→BIND, semántica exacta Emitida/Vigente, mapeo CFDIUse→SAT.
• Fuera de Etapa 1: UI (E2), refresh tokens (E2), recordatorios a clientes (Anexo B), multiempresa (ADR-005), fecha valor de pagos/REP (ADR-004), aging/tablero (E3), conciliación, CI/CD+Azure (actividades propias 21–24 jul), envío de PDF.

§7 Riesgos y gestión (no técnico, en el mismo doc)

• Riesgos: primera corrida de sync en vivo (mitigado: jueves noche); filtro CreationDate de Quotes no validado (fallback full-scan); repo visible al cliente (solo datos ficticios, sin co-autoría en commits).
• Pendientes de gestión que tocan la etapa: correo formal a Noé (salvaguardas — borrador listo), 5 preguntas técnicas a Pedro (REP/pagos, CFDIUse, /xml, webhooks, token Power BI), borrar bind_token_api.txt del disco, registrar horas diario en Seguimiento-horas.csv, preparar sesión 22-jul (ya existe Sesion-Etapa1-2026-07-22.md — referenciarla).

Archivos a crear/modificar

Archivo	Acción
c:\Users\JohannVelazquez\Desktop\Personal\balam\planeacion\Plan-Etapa1.md	Crear (documento completo)
c:\Users\JohannVelazquez\Desktop\Personal\balam\planeacion\Plan-actividades.md	Agregar 1 línea de referencia en la sección Etapa 1

Verificación

1. El documento existe, abre bien en Markdown y sus tablas renderizan (revisión visual).
2. Cifras contractuales cuadran con la propuesta: 32–39 h, entregables L148–155, roles y stack (verificar contra propuesta/00 - PROPUESTA-COMERCIAL.md).
3. Cifras de horas cuadran con Seguimiento-horas.md (8.00 h E1, 30 h totales).
4. Fechas cuadran con bitacora/REGISTRO.md #42–#43 (22-jul, 23-jul, Azure sem 21, CI/CD 24).
5. El enlace desde Plan-actividades.md navega al nuevo documento.
6. Confirmar que NADA se escribió en el repo del cliente (balam-plataforma limpio: git -C ...balam-plataforma status).