# 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