Initial commit: propuesta y documentaci贸n BALAM

02 - PLAN-EJECUCION.md

@@ -0,0 +1,251 @@
+# Plan de Ejecución — Balam MVP (6 semanas · medio tiempo)
+
+Documento interno (tuyo). Mapea las fases de la propuesta a tareas concretas, con desglose de horas y entregables verificables. Sirve para tu seguimiento semanal y para sustentar tus facturas.
+
+---
+
+## Parámetros del proyecto
+
+- **Dedicación:** medio tiempo, ~20 h/semana (flex hasta 25 h en semanas pico)
+- **Calendario:** 6 semanas
+- **Budget total:** 110 – 140 horas
+- **Tarifa:** 600 MXN/h + IVA
+- **Total estimado:** $66,000 – $84,000 MXN
+
+## Cómo usar este documento
+
+- Cada fase tiene **tareas atómicas** con estimación de horas (rango).
+- Al cerrar una tarea, registra horas reales en columna `real`.
+- Si una tarea excede 130% del estimado máximo, **paras y avisas** al cliente antes de continuar.
+- Cada fase termina con un entregable demoable + actualización del Linear/Notion.
+
+## Expectativa de horas con Claude Code
+
+Los rangos están calibrados para **caer cerca del extremo bajo** trabajando con Claude Code como asistente. El rango alto es la holgura para sorpresas en:
+- Formato del export de BIND (puede ser distinto a lo esperado)
+- Parsing de PDFs bancarios (calibración de prompts)
+- IBC Bank Texas (formato menos conocido)
+- Integración Stripe con flujo de webhook
+
+## Disciplina de scope (crítica a medio tiempo)
+
+Como es un MVP de 6 semanas con una sola persona a medio tiempo, **decir que no es la habilidad más importante**. Default respuesta a "podríamos también...":
+
+> "Buena idea. Lo dejo anotado para Fase 2 para no comprometer la entrega del MVP en 6 semanas."
+
+Cualquier cambio de alcance en mitad de fase requiere Change Request escrito y aprobado.
+
+---
+
+## Fase 0 — Discovery + Setup (Semana 1 · 18-22 h)
+
+| # | Tarea | Min | Max | Real |
+|---|---|---|---|---|
+| 0.1 | Kick-off con contacto técnico + gerente administrativo | 2 | 2 | |
+| 0.2 | Inspección formato de export de BIND (clientes, facturas, catálogo) | 2 | 3 | |
+| 0.3 | Recolección y análisis de 2-3 PDFs reales por banco (Banorte/BBVA/IBC) | 2 | 3 | |
+| 0.4 | Validación de viabilidad de Claude API sobre los PDFs reales | 1 | 2 | |
+| 0.5 | Confirmación de cuenta Stripe MX + revisión de fee structure | 1 | 1 | |
+| 0.6 | Setup Azure: App Service + Postgres + Blob Storage + Key Vault | 2 | 3 | |
+| 0.7 | Setup repo monorepo + CI/CD con deploy a Azure | 2 | 3 | |
+| 0.8 | Setup Claude Code: CLAUDE.md, settings.json, gitleaks pre-commit, skills base | 2 | 2 | |
+| 0.9 | docs/conventions.md + domain-glossary.md (vocabulario fiscal CFDI + glosario interno BIND) | 1 | 2 | |
+| 0.10 | Recepción y aplicación de manual de marca a maquetas iniciales | 1 | 1 | |
+| 0.11 | Documento de supuestos validados + plan refinado de Fases 1-4 + ADRs iniciales | 2 | 2 | |
+| **Total Fase 0** |  | **18** | **22** | |
+
+**Entregables Fase 0:**
+- `docs/discovery.md` con hallazgos
+- `docs/supuestos.md` confirmado
+- `docs/adr/0001-0009.md`
+- Repo + CI/CD + staging Azure accesible
+- `CLAUDE.md` + `.claude/` configurado
+- Conventions + glosario de dominio
+- Plan refinado presentado a stakeholders
+
+---
+
+## Fase 1 — Plataforma + Sincronización con BIND (Semanas 2-3 · 30-38 h)
+
+### Semana 2 (15-19 h)
+
+| # | Tarea | Min | Max | Real |
+|---|---|---|---|---|
+| 1.1 | Schema Prisma: tenant, user, role, audit_log, exchange_rate | 2 | 3 | |
+| 1.2 | Auth (Better-auth) con login email + roles (Finanzas/Dirección/Admin) | 3 | 4 | |
+| 1.3 | Layout base frontend (Next.js + shadcn): login, sidebar, branding aplicado | 3 | 4 | |
+| 1.4 | Módulo Catálogo: customer + UI de gestión + bandera auto_reminder_enabled | 3 | 4 | |
+| 1.5 | Audit log universal (middleware Prisma) | 2 | 2 | |
+| 1.6 | Cron diario TC del DOF + cache | 2 | 2 | |
+
+### Semana 3 (15-19 h)
+
+| # | Tarea | Min | Max | Real |
+|---|---|---|---|---|
+| 1.7 | Schema invoice + invoice_line (espejo de BIND) | 2 | 2 | |
+| 1.8 | Importador de archivo BIND: parser + validación + dedupe | 4 | 5 | |
+| 1.9 | UI de importación: upload, preview de deltas (dry-run), confirmación | 3 | 4 | |
+| 1.10 | Listado de facturas con filtros, búsqueda, drill-down a detalle | 3 | 4 | |
+| 1.11 | Snapshot de TC al momento de la factura (display multimoneda MXN/USD) | 1 | 2 | |
+| 1.12 | Outbox pattern + worker base (tabla event + handler skeleton) | 2 | 2 | |
+| **Total Fase 1** |  | **30** | **38** | |
+
+**Entregables Fase 1:**
+- Sistema autenticado con branding aplicado
+- Importación funcional desde BIND con dry-run
+- Listado y consulta de facturas (espejo de BIND) en MXN y USD
+- Audit log activo
+- Outbox pattern listo para handlers
+
+---
+
+## Fase 2 — Cobranza + Dashboard + Pago con link (Semana 4 · 25-32 h)
+
+| # | Tarea | Min | Max | Real |
+|---|---|---|---|---|
+| 2.1 | Schema payment + payment_allocation (M-N a facturas) | 1 | 2 | |
+| 2.2 | UI de registro manual de pago + asociación (totales y parciales) | 3 | 4 | |
+| 2.3 | Template editor para correo de cobranza (markdown + variables) | 2 | 3 | |
+| 2.4 | Motor de envío programado (cron + worker idempotente con Resend) | 3 | 4 | |
+| 2.5 | UI para configurar lista blanca por cliente | 1 | 2 | |
+| 2.6 | Log de comunicaciones enviadas + UI de revisión | 2 | 2 | |
+| 2.7 | Stripe Checkout: cliente + generación de link por factura | 3 | 4 | |
+| 2.8 | Stripe Webhook: recepción + verificación de firma + marca factura pagada | 3 | 4 | |
+| 2.9 | Inclusión del link de pago dentro del email de recordatorio | 1 | 2 | |
+| 2.10 | Dashboard v1: CxC total, por cliente, vencidas, próximas a vencer | 3 | 4 | |
+| 2.11 | Exportación a Excel/CSV | 1 | 2 | |
+| 2.12 | Test E2E: recordatorio respeta lista blanca + link de pago funciona | 2 | 3 | |
+| **Total Fase 2** |  | **25** | **32** | |
+
+**Entregables Fase 2:**
+- Cobranza automatizada con lista blanca
+- Pago con link Stripe (tarjeta + SPEI) funcional end-to-end
+- Dashboard de CxC operativo
+- Exportación a Excel
+
+---
+
+## Fase 3 — Conciliación PDF con Claude API (Semana 5 · 22-28 h)
+
+| # | Tarea | Min | Max | Real |
+|---|---|---|---|---|
+| 3.1 | Schema: bank_account, bank_statement, statement_line | 1 | 2 | |
+| 3.2 | UI de upload de PDF con almacenamiento en Blob | 2 | 3 | |
+| 3.3 | Extracción de texto con pdf-parse + pipeline por banco | 2 | 3 | |
+| 3.4 | Prompt versionado para Banorte + validación de totales | 2 | 3 | |
+| 3.5 | Prompt versionado para BBVA + validación de totales | 2 | 3 | |
+| 3.6 | Prompt versionado para IBC Texas + validación de totales | 3 | 4 | |
+| 3.7 | Dedupe por hash + persistencia de statement_lines | 1 | 2 | |
+| 3.8 | Algoritmo de matching exacto (monto + referencia + ventana fecha) | 3 | 3 | |
+| 3.9 | Tabla customer_alias + matching por alias | 2 | 3 | |
+| 3.10 | UI cola de revisión humana para no conciliados | 2 | 3 | |
+| 3.11 | Detección básica: duplicados + traspasos internos | 2 | 2 | |
+| **Total Fase 3** |  | **22** | **28** | |
+
+**Entregables Fase 3:**
+- Upload + parsing automático de los 3 PDFs bancarios
+- Motor de conciliación con auto-match + cola humana
+- Detección básica de duplicados y traspasos
+
+---
+
+## Fase 4 — Reportes + Cierre (Semana 6 · 15-20 h)
+
+| # | Tarea | Min | Max | Real |
+|---|---|---|---|---|
+| 4.1 | Export de pagos conciliados a Excel en formato BIND | 2 | 3 | |
+| 4.2 | Reporte mensual CxC + CxP exportable | 2 | 2 | |
+| 4.3 | Reportes programados por email (diario / semanal) | 2 | 3 | |
+| 4.4 | Endurecimiento seguridad: helmet, rate limit, RBAC granular, MFA opcional | 2 | 3 | |
+| 4.5 | Backups automáticos Azure + plan de recuperación documentado | 1 | 2 | |
+| 4.6 | Documentación técnica: README, runbook, ADRs finalizados | 2 | 2 | |
+| 4.7 | Sesión de capacitación grabada (1.5 h) con contacto técnico + gerente admin | 2 | 2 | |
+| 4.8 | Handoff + sesión de cierre con stakeholders | 1 | 1 | |
+| 4.9 | Buffer para correcciones finales | 1 | 2 | |
+| **Total Fase 4** |  | **15** | **20** | |
+
+**Entregables Fase 4:**
+- Reportes operativos enviándose automáticamente
+- Export para BIND validado por el contador
+- Seguridad endurecida
+- Documentación y capacitación entregadas
+- Sistema en producción operando
+
+---
+
+## Resumen total
+
+| Fase | Min | Max | MXN Min | MXN Max |
+|---|---|---|---|---|
+| 0 - Discovery + Setup Azure | 18 | 22 | 10,800 | 13,200 |
+| 1 - Plataforma + Sync BIND | 30 | 38 | 18,000 | 22,800 |
+| 2 - Cobranza + Dashboard + Pago link | 25 | 32 | 15,000 | 19,200 |
+| 3 - Conciliación PDF (Claude API) | 22 | 28 | 13,200 | 16,800 |
+| 4 - Reportes + Cierre | 15 | 20 | 9,000 | 12,000 |
+| **TOTAL** | **110** | **140** | **$66,000** | **$84,000** |
+
+**Tiempo calendario:** 6 semanas medio tiempo (~20 h/semana base, hasta 25 h en pico)
+**Tarifa:** 600 MXN/h + IVA
+**Facturación:** semanal viernes, pago a 7 días
+
+---
+
+## Capacidad por semana
+
+| Semana | Horas planeadas (max) | Carga |
+|---|---|---|
+| 1 (Fase 0) | 22 | normal |
+| 2 (Fase 1a) | 19 | normal |
+| 3 (Fase 1b) | 19 | normal |
+| 4 (Fase 2) | 32 | ⚠️ pico (necesita 25-30 h ese semana) |
+| 5 (Fase 3) | 28 | ⚠️ alto (necesita 24-28 h ese semana) |
+| 6 (Fase 4) | 20 | normal |
+
+> **Semanas 4 y 5 son el pico.** Plan: cargar más horas (25-30/sem) y compensar con semanas 1-3 más relajadas. Si en semana 4 no puedes subir el ritmo, alarma temprana y mueves Stripe (8h) a Fase 2 / Fase 2 post-MVP.
+
+---
+
+## Decisiones de descope si vas tarde
+
+Estas son las palancas, en orden de "primero soltar":
+
+1. **Domiciliación** — ya fuera del MVP, no agregar bajo ningún motivo.
+2. **Detección de duplicados/traspasos** (tarea 3.11) — push a Fase 2, ahorra ~2 h.
+3. **Reportes programados por email** (tarea 4.3) — push a Fase 2, ahorra ~3 h.
+4. **Stripe Webhook automático** (tarea 2.8) — fallback: registro manual de pago al confirmar Stripe en su dashboard, ahorra ~4 h.
+5. **IBC Texas** (tarea 3.6) — push a Fase 2, los bancos MX cubren 70% del volumen, ahorra ~4 h.
+6. **Multimoneda display** (tarea 1.11) — push a Fase 2 si solo manejan 5 facturas USD/mes, ahorra ~2 h.
+
+Si activas las palancas 1-3 recuperas ~5 h. Si activas 1-5 recuperas ~13 h. **Más allá de eso ya es replantear contrato.**
+
+---
+
+## Reglas de ejecución
+
+1. **Nunca trabajes una hora que no puedas justificar en factura.** Si una tarea está fuera de scope acordado, paras y conversas.
+2. **Time-tracking obligatorio** (Toggl o Linear). Horas no registradas son horas regaladas.
+3. **Demo cada viernes**, sin excepción.
+4. **Loom > reunión.** Para updates de status, 3-5 min de Loom en lugar de pedir reunión.
+5. **PRs con descripción larga.** Tu evidencia de trabajo y documentación viva.
+6. **CHANGELOG.md** — entrada al cerrar cada fase.
+7. **No deployees viernes después de las 4pm.** Bug + fin de semana = pesadilla.
+8. **Backup tu propio progreso.** Cliente debe poder retomar con otro dev si te enfermas.
+9. **Decir "no" es parte del trabajo.** Cada "podríamos también..." que aceptas en MVP es una hora menos para lo crítico.
+10. **Producción es el único ambiente disponible.** Antes de cualquier export o sync con BIND: dry-run + confirmación explícita + snapshot DB.
+
+---
+
+## Señales tempranas
+
+**Va bien:**
+- Stakeholder responde dudas en <24 hrs
+- Las demos generan ajustes pequeños, no replanteos
+- Las horas reales caen cerca del medio del rango
+- Aparecen requests de Fase 2 (señal de que confían en ti)
+
+**Alerta (paras y conversas):**
+- Stakeholder no contesta más de 3 días → bloqueador serio
+- El export de BIND llega en formato distinto al esperado en Fase 0 → cotizar workaround
+- Claude API no extrae con calidad suficiente algún PDF → reevaluar approach (fallback: parser híbrido para ese banco)
+- Stripe rechaza la cuenta Balam o tarda en validar → bloquea Fase 2.7-2.9
+- Llegas a viernes de semana 3 sin Fase 1 cerrada → renegocia scope **ese viernes**, no la semana siguiente