Johann
12 KiB
12 KiB
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.mdcon hallazgosdocs/supuestos.mdconfirmadodocs/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":
- Domiciliación — ya fuera del MVP, no agregar bajo ningún motivo.
- Detección de duplicados/traspasos (tarea 3.11) — push a Fase 2, ahorra ~2 h.
- Reportes programados por email (tarea 4.3) — push a Fase 2, ahorra ~3 h.
- Stripe Webhook automático (tarea 2.8) — fallback: registro manual de pago al confirmar Stripe en su dashboard, ahorra ~4 h.
- IBC Texas (tarea 3.6) — push a Fase 2, los bancos MX cubren 70% del volumen, ahorra ~4 h.
- 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
- Nunca trabajes una hora que no puedas justificar en factura. Si una tarea está fuera de scope acordado, paras y conversas.
- Time-tracking obligatorio (Toggl o Linear). Horas no registradas son horas regaladas.
- Demo cada viernes, sin excepción.
- Loom > reunión. Para updates de status, 3-5 min de Loom en lugar de pedir reunión.
- PRs con descripción larga. Tu evidencia de trabajo y documentación viva.
- CHANGELOG.md — entrada al cerrar cada fase.
- No deployees viernes después de las 4pm. Bug + fin de semana = pesadilla.
- Backup tu propio progreso. Cliente debe poder retomar con otro dev si te enfermas.
- Decir "no" es parte del trabajo. Cada "podríamos también..." que aceptas en MVP es una hora menos para lo crítico.
- 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