Initial commit: propuesta y documentación BALAM
This commit is contained in:
Johann
@@ -0,0 +1,5 @@
|
||||
.DS_Store
|
||||
Thumbs.db
|
||||
*.swp
|
||||
.vscode/
|
||||
.idea/
|
||||
@@ -0,0 +1,472 @@
|
||||
# Propuesta Comercial — Plataforma de Automatización Financiera (Balam)
|
||||
|
||||
**Para:** Balam
|
||||
**De:** [Tu nombre]
|
||||
**Fecha:** Mayo 2026
|
||||
**Vigencia:** 30 días
|
||||
|
||||
---
|
||||
|
||||
## 1. Entendimiento del proyecto
|
||||
|
||||
### El problema, en palabras del equipo directivo
|
||||
|
||||
> *"El proceso está tan desvinculado… pasa por varias manos… cada parte humana se está equivocando."*
|
||||
|
||||
Esto es lo que escuché en la llamada con CEO, CFO y CTO: el dolor no es técnico, es operativo y costoso. Cada handoff manual entre nómina, facturación, cobranza, conciliación y contabilidad introduce error humano que se paga en dinero perdido, retrabajo y deterioro de relación con clientes estratégicos.
|
||||
|
||||
### Lo que existe hoy
|
||||
|
||||
- **BIND ERP** (facturación + contabilidad con PAC integrado)
|
||||
- **BUK** (HR, contratos, nómina, vacaciones — core de gestión de talento)
|
||||
- **Jira** (gestión de proyectos y servicios con clientes)
|
||||
- **3 bancos** en PDF (2 MX + IBC Bank Texas)
|
||||
|
||||
Estos sistemas funcionan individualmente, pero no conversan entre sí. La **operación financiera vive en el espacio entre ellos** — y hoy ese espacio se llena con trabajo manual y propenso a error.
|
||||
|
||||
### Lo que propongo construir
|
||||
|
||||
Una **capa de operaciones financieras encima de los sistemas existentes**, no un reemplazo. BIND sigue siendo fuente de verdad para facturación y contabilidad; BUK sigue siendo el core de HR; Jira sigue gestionando proyectos. La plataforma orquesta el flujo financiero que hoy nadie tiene:
|
||||
|
||||
**MVP (6 semanas):**
|
||||
- Cobranza automatizada con reglas de negocio (lista blanca ACUNTIA + top 3)
|
||||
- Conciliación bancaria sobre PDFs (3 bancos, incluyendo IBC Texas) usando IA para parsing
|
||||
- Dashboard consolidado de CxC y vencimientos
|
||||
- Pago con link Stripe — nuevo requerimiento confirmado
|
||||
- Alertas y reportes programados
|
||||
|
||||
**Visión end-to-end (Fase 2-3):**
|
||||
La arquitectura del MVP queda preparada para cerrar el ciclo completo que el equipo directivo describió en la llamada:
|
||||
|
||||
```
|
||||
Jira (horas) → BUK (nómina) → Plataforma → Factura → Cobranza → Conciliación → Asiento
|
||||
```
|
||||
|
||||
Cuando BIND y BUK habiliten APIs (o decidan invertir en Belvo / Plaid / conectores), la plataforma absorbe esos nuevos disparadores sin reescribir lo construido. Hoy importamos archivos; mañana escuchamos webhooks. El motor de orquestación es el mismo.
|
||||
|
||||
### El éxito del proyecto se mide en
|
||||
|
||||
- **Reducción ≥ 70%** de errores manuales contables
|
||||
- **Reducción ≥ 60%** del tiempo de conciliación bancaria
|
||||
- **Visibilidad en tiempo real** del estado financiero para dirección
|
||||
- **MVP funcional** con flujo end-to-end de cobranza + conciliación + pago en 6 semanas
|
||||
- **Cero riesgo** sobre la relación con clientes estratégicos (lista blanca dura)
|
||||
|
||||
### Escala operativa (referencia)
|
||||
- 45 colaboradores en nómina + 5 freelancers
|
||||
- ~50 facturas emitidas al mes
|
||||
- 3 bancos (2 MX + IBC Bank Texas)
|
||||
- 2 jurisdicciones fiscales (México + Texas, tax estándar en MVP)
|
||||
- Stakeholders operativos: contacto técnico + gerente administrativo (con visibilidad ejecutiva de CEO/CFO/CTO)
|
||||
|
||||
---
|
||||
|
||||
## 2. Modelo de colaboración
|
||||
|
||||
### 2.1 Modalidad: Time & Materials con presupuesto por fase
|
||||
|
||||
Trabajo bajo modelo de **horas reales con tarifa transparente**, no precio cerrado. Razón: el alcance real de las integraciones (BIND, bancos, SAT) sólo se conoce al inspeccionar APIs y datos en vivo; un precio fijo obligaría a inflar el presupuesto para cubrir incertidumbre, encareciendo el proyecto innecesariamente.
|
||||
|
||||
A cambio, ofrezco:
|
||||
|
||||
- **Rango estimado por fase** (mín-máx en horas) acordado por escrito antes de iniciar cada fase
|
||||
- **Soft cap por fase**: si proyecto rebasar el rango máximo, paro y conversamos antes de continuar — nunca hay "sorpresas" en factura
|
||||
- **Reporte semanal** de horas trabajadas con desglose por tarea (vía Notion / Linear / sheet compartido)
|
||||
- **Demo semanal** del avance entregado
|
||||
|
||||
### 2.2 Toolchain moderno (Claude Code + revisión humana)
|
||||
|
||||
Trabajo con un toolchain de desarrollo asistido por IA (Claude Code de Anthropic) como acelerador. **Esto es información que Balam debe saber por transparencia y por compliance**:
|
||||
|
||||
- **Beneficio para Balam:** ranges de horas estimados arriba son conservadores; con esta metodología tienden al **extremo bajo del rango** sin pérdida de calidad. Mayor cobertura de tests, mejor documentación y refactor más frecuente quedan dentro del mismo presupuesto.
|
||||
- **Responsabilidad humana:** todo código entregado es revisado y validado por mí. La IA es asistente, no es quien firma el código. Yo soy responsable de cada línea que se mergea a `main`.
|
||||
- **Datos de Balam quedan fuera:** ningún dato real de Balam (clientes, montos, credenciales, XMLs reales, estados de cuenta) se envía a modelos externos. Se trabaja con datos sintéticos generados a partir de la estructura, no del contenido. Las credenciales viven en gestores de secretos cifrados; nunca se pegan en prompts.
|
||||
- **Compliance:** la metodología cumple con la política habitual de proveedores que manejan datos financieros (no entrenamiento sobre datos del cliente, no telemetría de datos del cliente, código en repositorio del cliente desde día 1).
|
||||
- **Auditabilidad:** las decisiones de arquitectura quedan registradas en ADRs versionados (`docs/adr/`), exactamente como si fueran de un humano.
|
||||
|
||||
### 2.3 Dedicación: medio tiempo
|
||||
|
||||
Trabajaré **medio tiempo (~20 h/semana)** sobre el proyecto. El calendario de 6 semanas asume esa dedicación; con eso el budget total es de **110–140 horas**.
|
||||
|
||||
### 2.4 Tarifa
|
||||
|
||||
**600 MXN / hora trabajada** + IVA (facturación CFDI 4.0).
|
||||
|
||||
### 2.5 Facturación
|
||||
|
||||
- **Semanal**, los viernes, por las horas trabajadas la semana anterior
|
||||
- Pago a 7 días naturales vía transferencia
|
||||
- Cada factura incluye anexo con detalle de horas por tarea/fase
|
||||
|
||||
### 2.6 Comunicación
|
||||
|
||||
- **Standup async 2-3 veces por semana** (texto + Loom corto en Slack/WhatsApp) — qué hice, qué sigue, bloqueadores
|
||||
- **Demo semanal** (30 min, viernes) con el contacto técnico y el gerente administrativo
|
||||
- **Sesión técnica quincenal** (1 h) — decisiones de arquitectura, validación de reglas de negocio
|
||||
- Disponibilidad para llamadas urgentes con 24 h de aviso en horario laboral (9-18 hrs CST)
|
||||
|
||||
---
|
||||
|
||||
## 3. Alcance — MVP en 6 semanas (medio tiempo)
|
||||
|
||||
> **Filosofía:** Un MVP entrega valor real lo antes posible con el alcance **mínimo viable**, no con todo lo deseable. Lo que no entre en estas 6 semanas vive en el roadmap de Fase 2 (§4) y se cotiza al cerrar el MVP, con datos reales de uso que justifiquen las prioridades.
|
||||
|
||||
> **Posicionamiento:** la plataforma es una **capa de operaciones financieras encima de BIND**, no un reemplazo. BIND sigue siendo la fuente de verdad para facturación, timbrado CFDI y contabilidad. La plataforma orquesta cobranza, conciliación, dashboard, pagos con link y alertas.
|
||||
|
||||
### Fase 0 — Discovery + Setup *(Semana 1 · 18 – 22 h)*
|
||||
|
||||
**Objetivo:** Validar supuestos técnicos críticos (BIND, PDFs bancarios, Stripe), preparar la infraestructura Azure y dejar el repositorio listo.
|
||||
|
||||
**Entregables:**
|
||||
|
||||
- Inspección del formato de export de BIND (estructura del archivo, frecuencia, contenido — facturas, clientes, catálogo)
|
||||
- Recolección de muestras reales (anonimizadas) de PDFs de los 3 bancos
|
||||
- Validación de viabilidad de parsing con Claude API sobre 2-3 PDFs reales por banco
|
||||
- Cuenta Azure creada con recursos base (App Service + Postgres + Storage) y staging vacío
|
||||
- Repositorio monorepo + CI/CD + workflow Claude Code configurado con guardrails de seguridad
|
||||
- Cuenta Stripe MX creada y validada
|
||||
- Documento de supuestos validados + plan refinado de Fases 1-4
|
||||
- Manual de marca recibido y aplicado a maquetas iniciales
|
||||
|
||||
---
|
||||
|
||||
### Fase 1 — Plataforma base + Sincronización BIND *(Semanas 2-3 · 30 – 38 h)*
|
||||
|
||||
**Objetivo:** Plataforma funcional que ingiere facturas de BIND, mantiene catálogo de clientes y rastrea estatus.
|
||||
|
||||
**Entregables:**
|
||||
|
||||
- Backend con autenticación, roles (Finanzas / Dirección / Operaciones / Admin), audit log universal
|
||||
- Multi-tenancy en schema (`tenant_id` + RLS) — preparado sin onboarding self-service
|
||||
- Importador de archivo de BIND (clientes, facturas, productos) con dedupe y validación
|
||||
- Modelo central de facturas con estados (Emitida / Pagada / Vencida / Cancelada)
|
||||
- Visualización multimoneda **MXN y USD** con TC diario del DOF (snapshot al momento de la factura)
|
||||
- UI: listado de facturas con filtros, búsqueda, drill-down a detalle
|
||||
- Gestión de catálogo de clientes con bandera `auto_reminder_enabled` para lista blanca
|
||||
- Branding aplicado (logo + colores del manual de marca)
|
||||
- Manual de usuario v1
|
||||
|
||||
> **Importante:** la plataforma **no emite CFDI**; eso lo sigue haciendo BIND con su PAC integrado. Si en el futuro Balam quiere emitir desde la plataforma, se evalúa en Fase 2 (requiere contratar PAC adicional o desarrollar conector contra BIND).
|
||||
|
||||
> **Fuera de MVP:** EUR, integración BUK, sincronización en vivo con BIND (mientras BIND no exponga API, se trabaja con export programado).
|
||||
|
||||
---
|
||||
|
||||
### Fase 2 — Cobranza + Dashboard + Pago con link *(Semana 4 · 25 – 32 h)*
|
||||
|
||||
**Objetivo:** Cobranza semi-automatizada con visibilidad real y un canal moderno de cobro.
|
||||
|
||||
**Entregables:**
|
||||
|
||||
- Registro manual de pagos + asociación a facturas (totales y parciales)
|
||||
- Editor de template para correos de cobranza (markdown + variables)
|
||||
- Motor de recordatorios automáticos por email (cron + worker idempotente)
|
||||
- **Lista blanca dura:** ACUNTIA + Top 3 jamás reciben recordatorio automático (configurable)
|
||||
- Recordatorio 5 días antes del vencimiento (configurable)
|
||||
- Log de comunicaciones enviadas con UI de revisión
|
||||
- **Pago con link (Stripe Checkout):**
|
||||
- Generación de link de pago por factura
|
||||
- Envío del link junto con el recordatorio de cobranza
|
||||
- Webhook que marca factura como pagada al recibir confirmación de Stripe
|
||||
- Soporte para tarjeta y SPEI vía Stripe
|
||||
- Dashboard v1: CxC totales y por cliente, vencidas, próximas a vencer, exportación a Excel
|
||||
|
||||
> **Fuera de MVP:** domiciliación / pagos recurrentes (Stripe Subscriptions o equivalente, requiere onboarding del cliente y manejo de mandatos — se cotiza en Fase 2). Cash-flow proyectado 30/60/90.
|
||||
|
||||
---
|
||||
|
||||
### Fase 3 — Conciliación bancaria por PDF *(Semana 5 · 22 – 28 h)*
|
||||
|
||||
**Objetivo:** Eliminar conciliación manual sobre los 3 PDFs bancarios.
|
||||
|
||||
**Entregables:**
|
||||
|
||||
- Importación de estados de cuenta en PDF (upload manual por el equipo)
|
||||
- **Extracción estructurada vía Claude API** (movimientos: fecha, monto, concepto, referencia)
|
||||
- Una pipeline por banco con prompts validados sobre muestras reales (incluyendo IBC Bank Texas)
|
||||
- Validación de totales (suma de movimientos vs. resumen del PDF) para detectar extracciones incorrectas
|
||||
- Dedupe por hash del registro extraído
|
||||
- Motor de conciliación:
|
||||
- Match exacto (monto + referencia + ventana de fecha) → automático
|
||||
- Match por alias de cliente → automático con flag de revisión
|
||||
- Sin match → cola de revisión humana
|
||||
- Detección básica de duplicados y traspasos internos entre cuentas propias
|
||||
- Dashboard de movimientos no conciliados
|
||||
|
||||
> **Por qué Claude API para parsing:** los formatos de PDF varían por banco y dentro del mismo banco a lo largo del tiempo; un parser hardcodeado por banco rompe con cada cambio. Con Claude se genera salida estructurada robusta a variaciones, con costo ~$0.01-0.05 USD por página y validación automática contra totales. Anthropic API por default no entrena con los datos enviados; los PDFs se procesan con datos reales bajo este compromiso contractual.
|
||||
|
||||
> **Fuera de MVP:** integración en vivo con bancos (Belvo / Plaid), detección de anomalías avanzada (z-score, vendor nuevo, horarios atípicos), scraping automatizado del portal de IBC.
|
||||
|
||||
---
|
||||
|
||||
### Fase 4 — Asientos contables + Cierre del MVP *(Semana 6 · 15 – 20 h)*
|
||||
|
||||
**Objetivo:** Cerrar el flujo de operaciones con export para BIND y entrega formal.
|
||||
|
||||
**Entregables:**
|
||||
|
||||
- Reporte de pagos conciliados exportable a Excel/CSV en formato compatible con BIND (para carga manual por el contador)
|
||||
- Reporte mensual de CxC y CxP
|
||||
- Backups automáticos + plan de recuperación documentado
|
||||
- Endurecimiento de seguridad final (helmet, rate limiting, RBAC granular, modo dry-run para operaciones contra BIND)
|
||||
- Documentación técnica: README, runbook operativo, ADRs
|
||||
- Sesión de capacitación grabada (1.5-2 h) con contacto técnico y gerente administrativo
|
||||
- Handoff + soporte post-lanzamiento de 2 semanas (corrección de bugs)
|
||||
|
||||
> **Importante:** los asientos contables completos los **sigue generando BIND**. La plataforma exporta pagos conciliados y movimientos clasificados que el contador sube a BIND. Generación de asientos automáticos contra BIND vía API queda para Fase 2 (depende de que BIND habilite API).
|
||||
|
||||
---
|
||||
|
||||
### Resumen de estimaciones
|
||||
|
||||
| Fase | Entregable principal | Rango (horas) | Rango (MXN) |
|
||||
|---|---|---|---|
|
||||
| 0 | Discovery + Setup Azure | 18 – 22 | $10,800 – $13,200 |
|
||||
| 1 | Plataforma + Sync con 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 MVP** | | **110 – 140 horas** | **$66,000 – $84,000** |
|
||||
|
||||
> Cifras antes de IVA. Tiempo calendario: **6 semanas** con dedicación medio tiempo (~20 h/semana, con flex hasta 25 h en semanas pico).
|
||||
> Por el uso de toolchain asistido por IA (ver §2.2), la expectativa real es caer cerca del **extremo bajo** de cada rango, salvo sorpresas en parsing de PDFs bancarios o exports de BIND.
|
||||
|
||||
---
|
||||
|
||||
## 4. Fase 2 (post-MVP) — Roadmap propuesto
|
||||
|
||||
No incluido en esta propuesta; se cotiza al cerrar MVP, priorizando con base en lo que se observe en uso real.
|
||||
|
||||
**Cerrar el flujo end-to-end (la visión original del equipo directivo)**
|
||||
- **Jira → horas por colaborador-cliente** ingestadas a la plataforma
|
||||
- **BUK → nómina aprobada** como trigger automático de factura al cliente
|
||||
- **Plataforma → BIND**: generación automática de factura tras evento de nómina (caso de uso #1 del PRD inicial)
|
||||
- **Plataforma → BIND**: asientos contables automáticos tras conciliación
|
||||
- Ciclo completo: `Jira → BUK → Factura → Cobranza → Conciliación → Asiento`
|
||||
|
||||
**Integraciones bancarias y ERP**
|
||||
- Integración en vivo con bancos vía Belvo (MX) — elimina la carga manual de PDFs
|
||||
- Plaid u OCR automatizado para IBC Bank si se valida que el cliente puede compartir credenciales
|
||||
- Conector contra BIND cuando habilite API (eliminar export/import manual)
|
||||
- Integración con BUK (nómina, contratos, freelancers) cuando exponga API
|
||||
- Integración con Jira para horas trabajadas → input de facturación
|
||||
|
||||
**Funcionalidad financiera**
|
||||
- Soporte de EUR (clientes europeos)
|
||||
- Cash-flow proyectado a 30/60/90 días
|
||||
- Manejo automático de pérdidas/ganancias cambiarias
|
||||
- **Domiciliación y pagos recurrentes** vía Stripe Subscriptions (pólizas, mensualidades)
|
||||
- Detección avanzada de anomalías (z-score, vendor nuevo, horarios atípicos, frecuencia)
|
||||
- Compliance avanzado para operación en Texas (más allá de tax estándar)
|
||||
|
||||
**Plataforma y producto**
|
||||
- Agentes IA / LLM para clasificación de transacciones y sugerencias de match
|
||||
- Portal de cliente self-service (consulta de facturas, descargas, historial de pagos)
|
||||
- App móvil para captura de tickets físicos
|
||||
- Multi-tenancy comercial (onboarding self-service, billing) para comercializar como producto
|
||||
- Compliance avanzado: NOM-151, evidencia digital, auditoría fiscal Texas
|
||||
|
||||
---
|
||||
|
||||
## 5. Costos operativos (a cargo de Balam)
|
||||
|
||||
Estos no son honorarios míos; son servicios de terceros que la plataforma requiere:
|
||||
|
||||
| Servicio | Concepto | Costo estimado |
|
||||
|---|---|---|
|
||||
| Azure App Service (Linux, B1/B2) | App + worker | $13 – $55 USD/mes |
|
||||
| Azure Database for PostgreSQL | Base de datos productiva | $25 – $80 USD/mes |
|
||||
| Azure Blob Storage | PDFs bancarios, exports | $1 – $5 USD/mes |
|
||||
| Sentry + uptime monitoring | Observabilidad | $0 – $26 USD/mes |
|
||||
| Email transaccional (Resend) | Recordatorios + links de pago | $0 – $20 USD/mes |
|
||||
| **Claude API** (parsing de PDFs bancarios) | ~3 PDFs/mes × ~20 págs c/u | $5 – $20 USD/mes |
|
||||
| **Stripe** (pago con link) | Comisión por transacción | 3.6% + $3 MXN por pago tarjeta · ~$3 MXN por SPEI |
|
||||
| **PAC para CFDI** | Ya incluido en BIND | $0 — no costo adicional |
|
||||
| **Total mensual MVP** | | **$45 – $210 USD/mes + comisiones Stripe** |
|
||||
|
||||
> En Fase 2, al activar integración bancaria en vivo se suma Belvo ($200 – $500 USD/mes) y/o Plaid ($0.30 – $1 USD por cuenta/mes).
|
||||
> Costos de Azure pueden optimizarse evaluando reserved instances después de validar consumo real.
|
||||
|
||||
---
|
||||
|
||||
## 6. Supuestos críticos
|
||||
|
||||
Si alguno no se cumple, replanteamos esa fase:
|
||||
|
||||
1. **Export programable o periódico de BIND** disponible (facturas + clientes) en Fase 0; formato documentable.
|
||||
2. **PDFs reales (anonimizados)** de los 3 bancos compartidos al inicio de Fase 0 para validar parsing.
|
||||
3. **Acceso al portal de IBC Bank Texas** para que el equipo descargue PDFs manualmente y los suba a la plataforma.
|
||||
4. **PAC de BIND maneja los volúmenes** actuales y futuros sin costo adicional; la plataforma no timbra facturas en MVP.
|
||||
5. **Cuenta Azure de Balam** (o autorización para crearla a nombre de Balam) disponible al inicio de Fase 0.
|
||||
6. **Cuenta Stripe MX** verificada (RFC + datos bancarios) antes de iniciar Fase 2.
|
||||
7. **Manual de marca** compartido al inicio de Fase 0.
|
||||
8. **Reglas de negocio finales** validadas en Fase 0 — especialmente lista blanca de clientes, ciclos de cobranza, frecuencia de export de BIND.
|
||||
9. **Dos stakeholders disponibles** (contacto técnico + gerente administrativo) con capacidad de resolver bloqueadores en <48 hrs.
|
||||
10. **Producción es el único ambiente disponible** (sin sandbox de BIND ni BUK). La plataforma operará con modo *dry-run* cuando exista riesgo de afectar BIND, con confirmación explícita del usuario antes de cualquier escritura.
|
||||
11. **Acuerdo de uso de Claude API para parsing de PDFs bancarios** firmado (compromiso de no entrenamiento sobre datos del cliente, ya estándar en Anthropic API).
|
||||
|
||||
---
|
||||
|
||||
## 7. Lo que entrego más allá de código
|
||||
|
||||
- **Código en repositorio del cliente** (GitHub) desde el día 1 — Balam es dueño del IP
|
||||
- **Documentación técnica viva** en `/docs` del repo
|
||||
- **Pruebas automatizadas** para flujos críticos (facturación, conciliación)
|
||||
- **Pipeline CI/CD** funcionando, despliegues con un clic
|
||||
- **Backups automatizados** y plan de recuperación documentado
|
||||
- **Sesión de transferencia de conocimiento** grabada
|
||||
- **Soporte post-lanzamiento** de 2 semanas incluido (correcciones de bugs, no nuevo alcance)
|
||||
|
||||
---
|
||||
|
||||
## 8. Lo que no incluye esta propuesta
|
||||
|
||||
- Diseño visual / branding (puedo usar shadcn/ui + diseño funcional; si quieren branding pleno, sumar diseñador)
|
||||
- Compra de licencias de software de terceros (PAC, agregadores, hosting)
|
||||
- Cambios de proceso interno o capacitación de cambio organizacional más allá de la sesión técnica
|
||||
- Integraciones no listadas (Jira, CRM, etc.) — cotizables por separado
|
||||
- Garantía contra cambios fiscales del SAT que requieran rework mayor (cotizables como mantenimiento)
|
||||
|
||||
---
|
||||
|
||||
## 9. Garantía y retención
|
||||
|
||||
- **Bugs en funcionalidad entregada:** cobertura sin costo por 30 días después de entrega de cada fase.
|
||||
- **Cambios de alcance:** se documentan como Change Request, se estiman, y se aprueban antes de ejecutar.
|
||||
- **IP y código:** propiedad de Balam desde el primer commit. Retengo derecho de mencionar el proyecto en mi portafolio sin revelar información confidencial.
|
||||
- **Calidad del código generado con asistencia de IA:** cualquier defecto cae bajo la misma garantía. La responsabilidad final del código es mía, sin importar la herramienta usada para escribirlo.
|
||||
|
||||
---
|
||||
|
||||
## 10. Próximos pasos
|
||||
|
||||
1. Reunión de kickoff (1 h) para revisar esta propuesta y resolver dudas
|
||||
2. Firma de acuerdo (contrato de prestación de servicios + NDA si aplica)
|
||||
3. Anticipo de 30 horas de Fase 0 para arrancar Discovery
|
||||
4. Inicio inmediato — entrega del MVP en 6 semanas
|
||||
|
||||
---
|
||||
|
||||
**Contacto**
|
||||
[Tu nombre]
|
||||
[Tu email] · [Tu WhatsApp]
|
||||
Monterrey, NL
|
||||
|
||||
---
|
||||
|
||||
## Anexo A — Trazabilidad PRD ↔ MVP (6 semanas)
|
||||
|
||||
Este anexo mapea cada funcionalidad y requerimiento del **PRD oficial de Balam** contra el alcance comprometido en las 6 semanas del MVP. Sirve como referencia rápida para alinear expectativas y para discutir explícitamente lo que entra, lo que entra parcial y lo que se difiere a Fase 2.
|
||||
|
||||
Leyenda: ✅ Cubierto · ⚠️ Parcial · ❌ Diferido a Fase 2
|
||||
|
||||
### A.1 Funcionalidades del MVP (PRD §3.1)
|
||||
|
||||
#### Facturación
|
||||
|
||||
| Funcionalidad PRD | Cobertura | Detalle |
|
||||
|---|---|---|
|
||||
| Generación automatizada de facturas | ❌ | La emisión sigue en BIND con su PAC. La generación desde eventos de negocio (Jira→BUK→Factura) depende de APIs que esos sistemas no exponen hoy — Fase 2. |
|
||||
| Integración multimoneda para clientes internacionales (USD sin IVA) | ⚠️ | MXN y USD con TC del DOF y snapshot al momento de la factura (Fase 1). **EUR queda fuera del MVP**. |
|
||||
| Descarga automática de facturas / reporte | ✅ | Listado con filtros, búsqueda y export Excel (Fase 1 + Fase 4). |
|
||||
|
||||
#### Cobranza
|
||||
|
||||
| Funcionalidad PRD | Cobertura | Detalle |
|
||||
|---|---|---|
|
||||
| Registro automático de pagos | ⚠️ | Automático **vía webhook de Stripe** para pagos con link. Pagos a cuenta bancaria se concilian desde el PDF en Fase 3, no en vivo. |
|
||||
| Identificación de pagos por cliente | ✅ | Asociación a facturas, soporte de pagos parciales y completos (Fase 2). |
|
||||
| Seguimiento de CxC con template de correo + lista blanca ACUNTIA y Top 3 (gestión humana) | ✅ | Lista blanca **dura** configurable, editor de template con variables, log de comunicaciones, recordatorio configurable (default 5 días antes de vencer) (Fase 2). |
|
||||
|
||||
#### Conciliación bancaria
|
||||
|
||||
| Funcionalidad PRD | Cobertura | Detalle |
|
||||
|---|---|---|
|
||||
| Conciliación automática pagos vs. facturas | ✅ | Match exacto, match por alias de cliente, cola de revisión humana para no-match (Fase 3). |
|
||||
| Integración con estados de cuenta (3 bancos, incluye IBC Texas) | ⚠️ | **PDF upload manual + extracción estructurada vía Claude API** con validación contra totales del PDF. Integración bancaria en vivo (Belvo/Plaid/OCR portal IBC) → Fase 2. |
|
||||
| Identificación de discrepancias | ✅ | Dedupe por hash, detección básica de duplicados y traspasos internos entre cuentas propias (Fase 3). |
|
||||
|
||||
#### Contabilidad
|
||||
|
||||
| Funcionalidad PRD | Cobertura | Detalle |
|
||||
|---|---|---|
|
||||
| Generación automática de asientos contables (ERP BIND) | ❌ | Depende de que BIND habilite API. En MVP se entrega **export en formato BIND** que el contador sube manualmente — Fase 2 para conector en vivo. |
|
||||
| Integración básica con sistema contable existente | ⚠️ | Vía export/import programado, no API en vivo. |
|
||||
|
||||
#### Reportes y alertas
|
||||
|
||||
| Funcionalidad PRD | Cobertura | Detalle |
|
||||
|---|---|---|
|
||||
| Dashboard de estado financiero | ✅ | CxC totales y por cliente, vencidas, próximas a vencer, exportable (Fase 2). |
|
||||
| Alerta — pagos pendientes | ✅ | Fase 2 |
|
||||
| Alerta — errores en conciliación | ✅ | Fase 3 |
|
||||
| Alerta — facturas no cobradas | ✅ | Fase 2 |
|
||||
|
||||
### A.2 Requerimientos funcionales (PRD §6)
|
||||
|
||||
| ID | Descripción | Cobertura | Notas |
|
||||
|---|---|---|---|
|
||||
| RF-01 | Generar facturas automáticamente desde eventos de negocio | ❌ | Fase 2 — requiere Jira/BUK como triggers |
|
||||
| RF-02 | Soporte multimoneda USD/EUR/MXN | ⚠️ | MXN + USD en MVP, EUR en Fase 2 |
|
||||
| RF-03 | Integración con sistemas existentes (BUK / nómina) | ❌ | BUK no expone API; Fase 2 |
|
||||
| RF-04 | Registrar pagos automáticamente desde fuentes bancarias | ⚠️ | Automático vía Stripe; bancos vía PDF + conciliación |
|
||||
| RF-05 | Asociar pagos a facturas | ✅ | Fase 2 |
|
||||
| RF-06 | Identificar pagos parciales y completos | ✅ | Fase 2 |
|
||||
| RF-07 | Conciliar automáticamente transacciones bancarias | ✅ | Fase 3 |
|
||||
| RF-08 | Detectar discrepancias | ✅ | Fase 3 |
|
||||
| RF-09 | Generar reportes de conciliación | ✅ | Fase 3 + 4 |
|
||||
| RF-10 | Generar asientos contables automáticos | ❌ | Fase 2 (depende API BIND) |
|
||||
| RF-11 | Integración con sistema contable | ⚠️ | Vía export en MVP |
|
||||
| RF-12 | Dashboard financiero en tiempo real | ✅ | Fase 2 |
|
||||
| RF-13 | Alertas automáticas configurables | ✅ | Fases 2-3 |
|
||||
| RF-14 | Reportes exportables | ✅ | Fase 4 |
|
||||
|
||||
### A.3 Requerimientos no funcionales (PRD §7)
|
||||
|
||||
| ID | Descripción | Cobertura | Notas |
|
||||
|---|---|---|---|
|
||||
| RNF-01 | Arquitectura modular y escalable | ✅ | Multi-tenancy en schema (`tenant_id` + RLS) desde día 1 |
|
||||
| RNF-02 | Alta disponibilidad | ⚠️ | MVP single-region en Azure; HA real (multi-region, failover) → Fase 2 |
|
||||
| RNF-03 | Seguridad de datos financieros | ✅ | Secretos cifrados, RBAC, audit log universal, hardening final en Fase 4 |
|
||||
| RNF-04 | Cumplimiento fiscal (México y Texas) | ⚠️ | Tax estándar en MVP; compliance avanzado Texas → Fase 2 |
|
||||
| RNF-05 | Integración con APIs externas | ✅ | Stripe, Claude API, DOF para TC |
|
||||
| RNF-06 | Trazabilidad completa de operaciones | ✅ | Audit log universal desde Fase 1 |
|
||||
|
||||
### A.4 Adicionales fuera del PRD oficial, **incluidos** en el MVP
|
||||
|
||||
Estas funcionalidades surgieron durante la llamada con el equipo directivo y se sumaron al alcance:
|
||||
|
||||
| Funcionalidad | Justificación | Fase |
|
||||
|---|---|---|
|
||||
| Pago con link Stripe (Checkout, tarjeta + SPEI) | Canal moderno de cobro sin depender del banco del cliente; webhook marca factura pagada automáticamente | Fase 2 |
|
||||
| Parsing de PDFs bancarios con Claude API | Decisión técnica frente a parser hardcodeado por banco: los formatos cambian con frecuencia; salida estructurada robusta + validación contra totales | Fase 3 |
|
||||
|
||||
### A.5 Diferidos a Fase 2 — resumen ejecutivo
|
||||
|
||||
Lo que **no entra en las 6 semanas**, agrupado por causa raíz:
|
||||
|
||||
**Bloqueado por terceros (APIs no disponibles hoy):**
|
||||
- Generación automática de facturas desde eventos (Jira → BUK → Factura)
|
||||
- Asientos contables automáticos contra BIND
|
||||
- Integración bancaria en vivo (Belvo MX / Plaid / OCR IBC)
|
||||
- Integración con BUK (nómina, contratos, freelancers)
|
||||
- Integración con Jira (horas trabajadas → input facturación)
|
||||
|
||||
**Decisión de alcance (priorizado fuera del MVP):**
|
||||
- EUR (no hay clientes europeos activos hoy)
|
||||
- Cash-flow proyectado 30/60/90
|
||||
- Detección avanzada de anomalías (z-score, vendor nuevo, horarios atípicos)
|
||||
- Domiciliación / pagos recurrentes vía Stripe Subscriptions
|
||||
- Portal de cliente self-service
|
||||
- App móvil para tickets físicos
|
||||
- Multi-tenancy comercial con onboarding self-service
|
||||
- Compliance avanzado Texas (más allá de tax estándar)
|
||||
|
||||
### A.6 Criterios de éxito del PRD (§13) y cómo se miden en MVP
|
||||
|
||||
| Criterio PRD | Cubierto | Cómo se mide en el MVP |
|
||||
|---|---|---|
|
||||
| Reducción de errores manuales ≥ 70% | ✅ | Línea base levantada en Fase 0; comparación al cierre del MVP sobre conciliación + cobranza |
|
||||
| Disminución del tiempo de conciliación ≥ 60% | ✅ | Tiempo de conciliación pre-MVP (manual) vs. post-MVP (PDF + Claude API + cola humana) |
|
||||
| Visibilidad en tiempo real | ✅ | Dashboard v1 entregado en Fase 2 |
|
||||
| MVP funcional en ≤ 6 semanas | ✅ | Alcance comprometido y soft cap por fase
|
||||
@@ -0,0 +1,722 @@
|
||||
# Arquitectura Técnica — Plataforma Balam
|
||||
|
||||
Este documento es la decisión técnica que sostendrá el proyecto. Está pensada para:
|
||||
1. Permitir entregar el MVP en **6 semanas (medio tiempo, ~120 h)**.
|
||||
2. **Escalar sin re-escribir** cuando se agreguen nuevos módulos, clientes o cuando se decida comercializar como producto SaaS.
|
||||
3. Ser comprensible por otro desarrollador si hay que sumar gente.
|
||||
|
||||
## Posicionamiento
|
||||
|
||||
La plataforma es una **capa de operaciones financieras encima de BIND ERP**, no un reemplazo. El sistema de verdad para emisión de CFDI y contabilidad sigue siendo BIND (que ya tiene PAC integrado). Lo que falta y aporta valor:
|
||||
|
||||
- Cobranza con reglas (lista blanca, recordatorios automáticos, templates)
|
||||
- Conciliación bancaria sobre PDFs (Banorte/BBVA/IBC Texas)
|
||||
- Dashboard consolidado de CxC
|
||||
- Pagos con link (Stripe)
|
||||
- Alertas y reportes programados
|
||||
|
||||
## Visión end-to-end (el horizonte que persigue la arquitectura)
|
||||
|
||||
El equipo directivo (CEO/CFO/CTO) describió un ciclo financiero completamente desconectado: nómina, facturación, cobranza, conciliación y contabilidad pasan por manos distintas y cada handoff cuesta dinero. El MVP **no resuelve todo el ciclo**, pero la arquitectura se diseña para llegar a él sin reescribir:
|
||||
|
||||
```
|
||||
Fase 2-3 (futuro) MVP (lo que construimos en 6 semanas)
|
||||
────────────────── ────────────────────────────────────
|
||||
Jira (horas) ┌─ Cobranza
|
||||
│ │
|
||||
▼ │
|
||||
BUK (nómina) ┌─ BIND (facturación) ─────┼─ Conciliación
|
||||
│ │ │ (PDF + IA)
|
||||
▼ │ │
|
||||
Plataforma ───trigger──>│ ├─ Dashboard
|
||||
(auto-factura) │ │
|
||||
└─ BIND (asientos) <────────┴─ Pago con link
|
||||
(Stripe)
|
||||
```
|
||||
|
||||
**Cómo el MVP prepara la visión completa:**
|
||||
|
||||
| Capacidad futura | Qué construye el MVP que la habilita |
|
||||
|---|---|
|
||||
| Trigger de factura desde nómina (BUK) | Outbox pattern + worker — basta agregar un handler `nomina.approved` |
|
||||
| Ingesta de horas desde Jira | Schema multi-fuente para facturas (origen ya tipificado) |
|
||||
| Generación automática de asiento contable contra BIND | Motor de reportería con mapeo evento → asiento ya existe; falta solo conector BIND |
|
||||
| Banco en vivo (Belvo / Plaid) | Schema `statement_line` agnóstico a fuente; pipeline de Claude API es reemplazable sin tocar conciliación |
|
||||
| Anomalía con IA / agentes | Stream de eventos del outbox alimenta cualquier consumidor IA en Fase 2 |
|
||||
| Multi-tenant comercial | `tenant_id` + RLS desde día 1 — solo falta onboarding self-service |
|
||||
|
||||
**Por eso el MVP, aunque acotado, es estratégico:** entrega valor operativo en 6 semanas y abre el camino al ciclo completo sin deuda técnica.
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────┐
|
||||
│ Plataforma Balam (nueva) │
|
||||
│ Cobranza · Dashboard · Conciliación · Pago │
|
||||
└──────┬───────────────┬───────────────┬──────┘
|
||||
│ import │ export │ webhook
|
||||
│ (archivo) │ (archivo) │
|
||||
▼ ▼ ▼
|
||||
┌──────────┐ ┌──────────┐ ┌──────────┐
|
||||
│ BIND │ │ BIND │ │ Stripe │
|
||||
│ (facturas│ │ (asientos│ │ (pago) │
|
||||
│ + PAC) │ │ + ERP) │ └──────────┘
|
||||
└──────────┘ └──────────┘
|
||||
┌──────────┐
|
||||
│ Claude │
|
||||
│ API │
|
||||
│ (parsing │
|
||||
│ PDFs) │
|
||||
└────▲─────┘
|
||||
│
|
||||
┌────┴─────┐
|
||||
│ PDFs de │
|
||||
│ 3 bancos │
|
||||
└──────────┘
|
||||
```
|
||||
|
||||
## MVP vs diseño completo
|
||||
|
||||
El diseño descrito en este documento es la **arquitectura objetivo**, calibrada para soportar todo el roadmap (incluyendo Fase 2). El MVP de 6 semanas a medio tiempo construye los cimientos completos pero **no implementa todos los módulos**:
|
||||
|
||||
| Componente | MVP (6 sem · medio tiempo) | Fase 2 |
|
||||
|---|---|---|
|
||||
| Auth, RBAC, audit log | ✅ | — |
|
||||
| Multi-tenancy en schema (`tenant_id` + RLS) | ✅ | onboarding self-service |
|
||||
| Import de catálogo + facturas desde BIND (archivo) | ✅ | API en vivo |
|
||||
| **Emisión de CFDI desde la plataforma** | ❌ (BIND lo hace) | sólo si se valida necesidad |
|
||||
| Multimoneda visualización | ✅ MXN + USD | EUR |
|
||||
| Cobranza + recordatorios + lista blanca configurable | ✅ | — |
|
||||
| **Pago con link (Stripe Checkout + webhook)** | ✅ | domiciliación / recurrentes |
|
||||
| Dashboard CxC | ✅ básico | cash-flow 30/60/90 |
|
||||
| **Banca: import de PDFs + parsing con Claude API** | ✅ | Belvo / Plaid en vivo |
|
||||
| Conciliación: match exacto + por alias | ✅ | scoring difuso completo |
|
||||
| Detección de anomalías | ⚠️ solo duplicados + traspasos | z-score, vendor nuevo, horarios |
|
||||
| Reporte para asientos contables (Excel para BIND) | ✅ | API en vivo |
|
||||
| Outbox pattern + eventos | ✅ | — |
|
||||
| Agentes IA / LLM operativos | ❌ | ✅ |
|
||||
| Portal cliente / móvil | ❌ | ✅ |
|
||||
| Integración BUK | ❌ | ✅ cuando exponga API |
|
||||
|
||||
**Por qué este recorte:** la arquitectura modular y event-driven permite agregar Fase 2 sin tocar lo entregado. El MVP demuestra valor con el mínimo viable; las decisiones de qué invertir en Fase 2 se toman con datos de uso real, no a priori.
|
||||
|
||||
## Constraint operativo: sin sandboxes
|
||||
|
||||
BIND y BUK solo cuentan con producción. Esto se mitiga así:
|
||||
|
||||
1. **La plataforma no escribe a BIND en MVP.** El flujo es estrictamente: BIND exporta → plataforma importa → plataforma exporta para que el contador suba manualmente. Ninguna operación tuya puede corromper BIND.
|
||||
2. **Modo dry-run** disponible en cualquier acción con efecto externo (envío de correos, generación de links Stripe), con preview obligatorio antes de confirmar.
|
||||
3. **Snapshots automáticos** de la base de datos antes de cualquier import masivo desde BIND.
|
||||
4. **Audit log** registra el actor (humano o sistema), la acción, y el delta. Reversible en <5 min para operaciones internas.
|
||||
|
||||
---
|
||||
|
||||
## 1. Principios rectores
|
||||
|
||||
| Principio | Implicación |
|
||||
|---|---|
|
||||
| **Modular monolito > microservicios** | Empezamos con un solo despliegue, módulos con fronteras claras. Microservicios sólo si el volumen lo justifica. |
|
||||
| **Boring tech** | PostgreSQL, TypeScript, Node, React. Nada exótico. |
|
||||
| **Eventos internos desde día 1** | El core publica eventos (`invoice.issued`, `payment.received`); los módulos reaccionan. Eso permite agregar módulos nuevos sin tocar los existentes. |
|
||||
| **Multi-tenancy desde el esquema** | `tenant_id` en todas las tablas (aunque por ahora exista un solo tenant). Cuando llegue el momento de vender el producto, no hay que rehacer la DB. |
|
||||
| **Audit log universal** | Todo cambio en entidades financieras se registra (quién, qué, cuándo, antes/después). Cumple RNF-06 y es vital para fiscal. |
|
||||
| **Idempotencia en integraciones** | Webhooks, jobs y endpoints externos siempre con `idempotency_key`. Evita facturas duplicadas o pagos repetidos. |
|
||||
| **Failure isolation** | Un error en conciliación nunca tira la facturación. Workers separados, colas independientes. |
|
||||
|
||||
---
|
||||
|
||||
## 2. Stack recomendado
|
||||
|
||||
### Backend
|
||||
- **Lenguaje:** TypeScript (Node.js 22 LTS)
|
||||
- **Framework:** NestJS *o* Fastify + tRPC
|
||||
- NestJS si esperamos sumar devs (estructura opinionada, fácil onboarding)
|
||||
- Fastify + tRPC si seguiré solo (más ligero, mejor DX con frontend)
|
||||
- **Recomendación: NestJS** — pensando en futura comercialización + onboarding
|
||||
- **ORM:** Prisma (migraciones, tipos, ergonomía)
|
||||
- **Validación:** Zod (compartida entre front y back)
|
||||
- **Auth:** Better-auth o Auth.js (autohospedado, sin lock-in)
|
||||
|
||||
### Frontend
|
||||
- **Framework:** Next.js 15 (App Router)
|
||||
- **UI:** shadcn/ui + Tailwind v4
|
||||
- **Data fetching:** TanStack Query
|
||||
- **Tablas / data grids:** TanStack Table
|
||||
- **Charts:** Recharts o Tremor (Tremor está pensado para dashboards financieros)
|
||||
- **Forms:** React Hook Form + Zod
|
||||
|
||||
### Datos
|
||||
- **Primaria:** PostgreSQL 16
|
||||
- **Cache / Queue:** Redis 7 (BullMQ para jobs)
|
||||
- **Object storage:** S3 / R2 (XML/PDF de facturas, estados de cuenta)
|
||||
|
||||
### Infra (Azure por preferencia del cliente)
|
||||
- **App + Worker:** Azure App Service (Linux, plan B2 inicial)
|
||||
- **Base de datos:** Azure Database for PostgreSQL Flexible Server
|
||||
- **Storage:** Azure Blob Storage (PDFs bancarios cifrados en reposo)
|
||||
- **Cache / Queue:** Azure Cache for Redis (Basic) o Upstash Redis serverless si el costo de Azure Redis no se justifica
|
||||
- **Observabilidad:** Sentry (errores) + Application Insights (logs/métricas integrado a Azure) + uptime monitoring externo
|
||||
- **CI/CD:** GitHub Actions con deploy a Azure App Service
|
||||
- **Secretos:** Azure Key Vault
|
||||
|
||||
### Calidad
|
||||
- **Tests:** Vitest (unit) + Playwright (E2E críticos)
|
||||
- **Lint/Format:** Biome (rápido, reemplaza ESLint + Prettier)
|
||||
- **Types:** TypeScript strict en todo
|
||||
- **Pre-commit:** Lefthook
|
||||
|
||||
### Integraciones obligatorias en MVP
|
||||
- **Import de archivos BIND** (formato CSV/Excel a confirmar en Fase 0)
|
||||
- **Parsing de PDFs bancarios:** Claude API (Anthropic) — un pipeline por banco
|
||||
- **Pago con link:** Stripe Checkout + Webhook
|
||||
- **Tipo de cambio:** API del DOF (Banxico) + cache diario
|
||||
- **Email transaccional:** Resend (DX excelente) o Postmark
|
||||
|
||||
### Integraciones diferidas a Fase 2
|
||||
- PAC propio (solo si Balam decide emitir CFDI desde la plataforma — hoy lo hace BIND)
|
||||
- Agregador bancario MX: Belvo o Finerio Connect (reemplaza upload manual de PDFs)
|
||||
- Banco US: Plaid o scraping autorizado del portal IBC
|
||||
- BUK API (cuando exista)
|
||||
- Conector contra BIND vía API (cuando exista)
|
||||
|
||||
---
|
||||
|
||||
## 3. Estructura del repositorio (monorepo)
|
||||
|
||||
```
|
||||
balam/
|
||||
├── apps/
|
||||
│ ├── web/ # Next.js (frontend)
|
||||
│ ├── api/ # NestJS (backend HTTP)
|
||||
│ └── worker/ # Procesos en background (BullMQ)
|
||||
├── packages/
|
||||
│ ├── db/ # Prisma schema + migraciones + tipos
|
||||
│ ├── core/ # Lógica de dominio compartida
|
||||
│ ├── contracts/ # Schemas Zod compartidos front/back
|
||||
│ ├── integrations/ # Clientes para PAC, bancos, etc.
|
||||
│ └── ui/ # Componentes shadcn customizados
|
||||
├── docs/ # ADRs, runbooks, manuales
|
||||
└── infra/ # IaC mínimo, scripts de deploy
|
||||
```
|
||||
|
||||
Gestor: **pnpm workspaces** + **Turborepo** para caché de builds.
|
||||
|
||||
---
|
||||
|
||||
## 4. Modelo de datos (núcleo)
|
||||
|
||||
Diagrama lógico simplificado:
|
||||
|
||||
```
|
||||
tenant ─┬─ user ──── role
|
||||
├─ customer ─┬─ invoice ──┬─ invoice_line
|
||||
│ │ └─ cfdi_xml
|
||||
│ └─ contact
|
||||
├─ bank_account ─┬─ bank_statement ── statement_line
|
||||
│ └─ reconciliation_match
|
||||
├─ payment ─── payment_allocation (M-N con invoice)
|
||||
├─ exchange_rate (DOF diario)
|
||||
├─ accounting_entry ─── entry_line
|
||||
├─ event (event sourcing ligero / outbox)
|
||||
├─ audit_log
|
||||
└─ notification (recordatorios enviados, blacklist)
|
||||
```
|
||||
|
||||
**Reglas duras del modelo:**
|
||||
|
||||
- Toda tabla financiera tiene: `id`, `tenant_id`, `created_at`, `updated_at`, `created_by`, `updated_by`.
|
||||
- Montos siempre en **decimal(18,4)** + columna `currency` ISO 4217. **Nunca** `float`.
|
||||
- Fechas en UTC en DB, presentación en CST/MX.
|
||||
- Soft delete con `deleted_at` en entidades editables; **hard delete prohibido** en facturas/pagos (cancelación lógica).
|
||||
- `idempotency_key` único por tenant en endpoints de creación masiva.
|
||||
|
||||
---
|
||||
|
||||
## 5. Arquitectura de capas
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────┐
|
||||
│ Frontend Next.js (Dashboard, Forms) │
|
||||
└──────────────────┬──────────────────────────┘
|
||||
│ HTTPS + JWT/Session
|
||||
┌──────────────────▼──────────────────────────┐
|
||||
│ API NestJS (REST + tRPC opcional) │
|
||||
│ ├── Auth & RBAC │
|
||||
│ ├── Controllers / Resolvers │
|
||||
│ └── Application Services │
|
||||
└──────┬─────────────────────┬────────────────┘
|
||||
│ │
|
||||
│ publish events │ enqueue jobs
|
||||
▼ ▼
|
||||
┌──────────────┐ ┌─────────────────────────┐
|
||||
│ Event Bus │ │ Worker (BullMQ) │
|
||||
│ (outbox tbl) │ │ ├── invoice timbrado │
|
||||
└──────┬───────┘ │ ├── bank sync (cron) │
|
||||
│ │ ├── reconciliation │
|
||||
▼ │ ├── reminders (cron) │
|
||||
┌──────────────┐ │ └── reports │
|
||||
│ Modules │ └────────┬────────────────┘
|
||||
│ reaccionan │ │
|
||||
└──────┬───────┘ │
|
||||
│ │
|
||||
▼ ▼
|
||||
┌─────────────────────────────────────────────┐
|
||||
│ Domain Services + Repositories (Prisma) │
|
||||
└──────────────────┬──────────────────────────┘
|
||||
▼
|
||||
┌─────────────────────────────────────────────┐
|
||||
│ PostgreSQL + Redis + S3 │
|
||||
└─────────────────────────────────────────────┘
|
||||
▲ ▲ ▲
|
||||
│ │ │
|
||||
┌──────┴──────────────┴──────────────┴────────┐
|
||||
│ Integraciones externas (clientes) │
|
||||
│ BIND (archivo) · Claude API · Stripe · DOF · Email │
|
||||
└─────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Patrón Event-Driven (clave para escalar)
|
||||
|
||||
Tabla `event` (outbox pattern):
|
||||
|
||||
```sql
|
||||
CREATE TABLE event (
|
||||
id uuid PRIMARY KEY,
|
||||
tenant_id uuid NOT NULL,
|
||||
type text NOT NULL, -- 'invoice.issued', 'payment.received'
|
||||
payload jsonb NOT NULL,
|
||||
aggregate_id uuid NOT NULL, -- id de la entidad afectada
|
||||
occurred_at timestamptz NOT NULL,
|
||||
processed_at timestamptz,
|
||||
attempts int DEFAULT 0
|
||||
);
|
||||
```
|
||||
|
||||
**Flujo:** Cuando se emite una factura, en la misma transacción se inserta un evento `invoice.issued`. Un worker lee la tabla y dispara handlers: enviar email al cliente, generar asiento contable, programar recordatorio de cobro.
|
||||
|
||||
**Por qué importa:** mañana cuando agreguen "notificar a Slack al timbrar", se agrega un handler sin tocar el código de facturación. Ese es el diseño que les va a encantar — no porque lo digan, sino porque verán que pedir cambios es barato.
|
||||
|
||||
---
|
||||
|
||||
## 7. Módulos del sistema (bounded contexts)
|
||||
|
||||
### 7.1 Identity & Access (`identity`)
|
||||
- Users, tenants, roles, permissions
|
||||
- Sesiones, MFA opcional (recomendado para finanzas)
|
||||
- Audit log
|
||||
|
||||
### 7.2 Catálogo (`catalog`)
|
||||
- Customers (con flag `is_strategic`, `auto_reminder_enabled`)
|
||||
- Products/Services
|
||||
- Tax regimes, payment methods (catálogos SAT)
|
||||
|
||||
### 7.3 Sincronización con BIND (`bind-sync`)
|
||||
- Importador de archivo de BIND (clientes, facturas, productos, catálogo de cuentas)
|
||||
- Dedupe por id externo (UUID del CFDI o id de BIND)
|
||||
- Visualización multimoneda con snapshot de TC al momento de la factura
|
||||
- Modo dry-run para previsualizar deltas antes de aplicar
|
||||
- Sincronización programada o manual
|
||||
|
||||
### 7.4 Cobranza (`collections`)
|
||||
- Estados de factura derivados de BIND + pagos locales
|
||||
- Motor de recordatorios (cron + templates editables)
|
||||
- Lista blanca: clientes con `auto_reminder_enabled=false` jamás reciben (ACUNTIA + Top 3 — configurable)
|
||||
- Tracking de comunicaciones enviadas
|
||||
|
||||
### 7.5 Pagos (`payments`)
|
||||
- Stripe Checkout: generación de link por factura
|
||||
- Webhook receiver: marca factura como pagada al confirmar
|
||||
- Soporte tarjeta + SPEI
|
||||
- Conciliación lista para pagos directos por banco (no via Stripe) en módulo banking
|
||||
|
||||
### 7.6 Banca (`banking`)
|
||||
- Upload de PDFs (Banorte/BBVA/IBC) por usuario
|
||||
- Pipeline de extracción con Claude API + validación de totales
|
||||
- Almacenamiento de statement_lines con dedupe por hash
|
||||
- (Fase 2: conexiones a Belvo / Plaid)
|
||||
|
||||
### 7.7 Conciliación (`reconciliation`)
|
||||
- Motor de matching con scoring (exacto → alias → cola humana)
|
||||
- Detección de duplicados y traspasos internos
|
||||
- (Fase 2: detección avanzada de anomalías, z-score, etc.)
|
||||
|
||||
### 7.8 Reportería (`reporting`)
|
||||
- Dashboard tiempo real (CxC, vencidas, próximas a vencer)
|
||||
- Reportes programables (diario/semanal por email)
|
||||
- Export para BIND: pagos conciliados + movimientos clasificados en Excel/CSV
|
||||
|
||||
### 7.9 Alertas (`notifications`)
|
||||
- Email, en-app
|
||||
- Configurables por usuario y por evento
|
||||
|
||||
---
|
||||
|
||||
## 8. Seguridad y compliance
|
||||
|
||||
### Obligatorio desde día 1
|
||||
- TLS everywhere (Let's Encrypt vía proxy)
|
||||
- Secrets en variables de entorno cifradas, nunca en el repo
|
||||
- Cifrado en reposo de PostgreSQL (Railway/Fly lo proveen)
|
||||
- Cifrado a nivel campo para datos sensibles (credenciales bancarias, tokens de agregadores) usando `pgcrypto`
|
||||
- Bcrypt para passwords (Argon2 si Better-auth lo permite)
|
||||
- Rate limiting en endpoints públicos
|
||||
- CORS estricto
|
||||
- Headers de seguridad (helmet)
|
||||
- Validación Zod en cada entrada
|
||||
- RBAC granular por módulo y acción
|
||||
|
||||
### Mexicano-específico
|
||||
- Emisión y sello digital del CFDI: **lo maneja BIND con su PAC integrado**; la plataforma no toca el SAT en MVP
|
||||
- Almacenamiento de XML/PDF de facturas en Blob Storage (referenciado por id de BIND) — por **5 años** según SAT
|
||||
- Bitácora de cancelaciones espejo (motivo + UUID sustituto) sincronizada desde el export de BIND
|
||||
- Tipos de cambio del DOF para reportería interna
|
||||
|
||||
### Texas (banco US)
|
||||
- Si hay operación contable real en Texas, revisar requerimientos con contador (no asumir).
|
||||
- Para el MVP, tratamos las cuentas US como cuentas bancarias normales en USD.
|
||||
|
||||
---
|
||||
|
||||
## 9. Estrategia de tipo de cambio
|
||||
|
||||
- Cache diario en tabla `exchange_rate` desde API de Banxico (DOF FIX)
|
||||
- Al emitir factura USD, se "fija" el TC del día en la factura
|
||||
- Para conciliación de pagos USD a facturas MXN: regla configurable (TC del día del pago o del día de la factura)
|
||||
- Pérdidas/ganancias cambiarias se registran como asientos automáticos
|
||||
|
||||
---
|
||||
|
||||
## 10. Pipeline de extracción de PDFs bancarios
|
||||
|
||||
Los 3 bancos entregan estados de cuenta como PDF (Banorte, BBVA, IBC Bank Texas). No hay CSV/API disponibles. La estrategia:
|
||||
|
||||
```
|
||||
Upload PDF ──> Almacenar en Blob ──> Job en cola ──> Pipeline por banco
|
||||
│
|
||||
┌───────────────┼───────────────┐
|
||||
▼ ▼ ▼
|
||||
pdfplumber/ Claude API Validación
|
||||
pdftotext extracción (totales,
|
||||
(texto) estructurada duplicados,
|
||||
→ JSON formato)
|
||||
│
|
||||
▼
|
||||
statement_line[]
|
||||
│
|
||||
▼
|
||||
hash + dedupe + persist
|
||||
```
|
||||
|
||||
**Decisiones clave:**
|
||||
|
||||
1. **Texto primero, modelo después.** Se extrae texto con `pdfplumber` (Python) o `pdf-parse` (Node) y se pasa el texto plano a Claude. Más barato y rápido que mandar el PDF binario.
|
||||
2. **Un prompt por banco**, versionado. Cada prompt incluye: ejemplos few-shot, schema JSON esperado, instrucciones de manejo de saltos de página y casos borde.
|
||||
3. **Validación automática post-extracción:**
|
||||
- Suma de movimientos == saldo final - saldo inicial (con tolerancia mínima)
|
||||
- Cantidad de movimientos == lo que el resumen del PDF indica
|
||||
- Si validación falla → flag manual review, no se inserta
|
||||
4. **Schema único** para `statement_line` (independiente de banco):
|
||||
```
|
||||
{ fecha, monto, tipo: 'cargo'|'abono', concepto, referencia, saldo_post, hash }
|
||||
```
|
||||
5. **Hash de dedupe:** `sha256(banco_id + fecha + monto + concepto)`. Re-upload del mismo PDF es idempotente.
|
||||
6. **Costo aproximado:** 50 facturas/mes → ~3 PDFs/mes × ~20 páginas × ~1500 tokens/pág × $3/MTok input + $15/MTok output. **~$2-8 USD/mes** total. Despreciable.
|
||||
7. **Privacidad:** Anthropic API por default no entrena con datos del cliente (Zero Data Retention disponible bajo enterprise agreement si se requiere). Documentado en supuesto §11 de la propuesta.
|
||||
8. **Migration path:** cuando en Fase 2 se conecte Belvo, el `statement_line` schema no cambia. Solo cambia la fuente. Mismo motor de conciliación reutilizable.
|
||||
|
||||
**Por qué Claude API y no parsers hardcoded:**
|
||||
- Los bancos cambian formato sin avisar. Un parser regex se rompe; Claude tolera variaciones.
|
||||
- IBC Texas tiene formato muy diferente a los bancos MX. Reutilizar prompts es trivial; reutilizar regex no.
|
||||
- Tiempo de implementación: ~3-4 h por banco con Claude vs. 8-12 h por banco con parser custom + tests.
|
||||
|
||||
## 11. Estrategia de conciliación (corazón del proyecto)
|
||||
|
||||
Algoritmo en cascada (mayor a menor confianza):
|
||||
|
||||
1. **Match exacto:** monto idéntico + referencia/UUID en concepto + ±3 días → auto-match
|
||||
2. **Match alto:** monto idéntico + cliente identificable por patrón en concepto + ±7 días → auto-match con flag de revisión
|
||||
3. **Match medio:** monto en ventana ±2% + cliente identificable → cola de revisión humana
|
||||
4. **Sin match:** se guarda en `unmatched_statement_line`, dashboard de pendientes
|
||||
|
||||
**Cliente identificable por patrón:** usar regex / fuzzy match contra alias del cliente (`Banorte` puede llegar el pago como "BANORTE SA", "BNTE", etc. — armar tabla `customer_alias`).
|
||||
|
||||
**Anomalías detectables sin IA:**
|
||||
- Gasto que excede 2σ del promedio mensual de esa categoría
|
||||
- Cargo duplicado (mismo monto + mismo concepto + ventana 5 días)
|
||||
- Cargos en horarios atípicos (madrugada, fines de semana si la empresa no opera)
|
||||
- Vendor nuevo (no aparece en los últimos 6 meses)
|
||||
|
||||
Esto es robusto, explicable y gratis. **La IA se agrega en v2** sobre estos cimientos, no como reemplazo.
|
||||
|
||||
---
|
||||
|
||||
## 12. Multi-tenancy: ahora vs después
|
||||
|
||||
**Ahora (MVP):**
|
||||
- `tenant_id` en todas las tablas
|
||||
- Row-level security en PostgreSQL (RLS) con policies por tenant
|
||||
- Un solo tenant en producción (Balam)
|
||||
|
||||
**Después (comercialización):**
|
||||
- Onboarding self-service
|
||||
- Plan/billing del SaaS
|
||||
- Aislamiento de archivos por tenant en S3
|
||||
|
||||
Costo de incluir `tenant_id` ahora: <5% del esfuerzo. Costo de agregarlo después: rewrite parcial. **Por eso se hace desde día 1.**
|
||||
|
||||
---
|
||||
|
||||
## 13. Testing strategy
|
||||
|
||||
| Tipo | Cobertura objetivo | Herramienta |
|
||||
|---|---|---|
|
||||
| Unit (lógica de dominio: cálculos, reglas) | >90% | Vitest |
|
||||
| Integration (servicios + DB) | rutas críticas | Vitest + Testcontainers |
|
||||
| E2E (flujos críticos UI) | 5-8 flujos | Playwright |
|
||||
| Contract (mocks de PAC, Belvo) | endpoints integrados | MSW |
|
||||
|
||||
**Flujos E2E obligatorios:**
|
||||
1. Crear cliente → emitir factura MXN → timbrar → descargar PDF
|
||||
2. Emitir factura USD a cliente extranjero (sin IVA)
|
||||
3. Importar movimiento bancario → conciliar manualmente → ver pago aplicado
|
||||
4. Conciliación automática end-to-end con datos sintéticos
|
||||
5. Enviar recordatorio que respeta lista blanca (cliente Top 3 no recibe)
|
||||
|
||||
---
|
||||
|
||||
## 14. Plan de despliegue
|
||||
|
||||
- `main` → producción (deploy automático tras CI verde + aprobación manual)
|
||||
- `develop` → staging (deploy automático)
|
||||
- Feature branches → preview environments (Railway lo soporta)
|
||||
- Rollback en <2 min vía Railway dashboard
|
||||
|
||||
**Migraciones:**
|
||||
- Siempre backward-compatible (expand → migrate → contract)
|
||||
- Backup automático antes de cada migración productiva
|
||||
- Migraciones revisadas manualmente, nunca destructivas en hot-path
|
||||
|
||||
---
|
||||
|
||||
## 15. Observabilidad mínima
|
||||
|
||||
- **Sentry:** errores no manejados, performance de queries lentas
|
||||
- **Better Stack / Axiom:** logs estructurados (cada request, cada job)
|
||||
- **Métricas:** dashboard interno con (a) facturas/día, (b) pagos conciliados auto vs manual, (c) jobs fallidos, (d) latencia p95
|
||||
- **Alertas a tu correo/Slack:**
|
||||
- Job de timbrado falla
|
||||
- Sync bancario sin éxito por >4 hrs
|
||||
- >10 errores en 5 min
|
||||
- Disco/memoria al 80%
|
||||
|
||||
---
|
||||
|
||||
## 16. ADRs (Architecture Decision Records)
|
||||
|
||||
Llevar `docs/adr/NNNN-titulo.md` con decisiones grandes:
|
||||
|
||||
- ADR-0001: Monorepo con pnpm + Turborepo
|
||||
- ADR-0002: NestJS como framework backend
|
||||
- ADR-0003: PostgreSQL como única base de datos primaria
|
||||
- ADR-0004: Multi-tenancy por `tenant_id` desde día 1
|
||||
- ADR-0005: BIND como fuente de verdad de facturación; plataforma como capa de operaciones
|
||||
- ADR-0006: Claude API para extracción estructurada de PDFs bancarios (vs parsers hardcoded)
|
||||
- ADR-0007: Stripe Checkout para pago con link (vs Conekta / MercadoPago)
|
||||
- ADR-0008: Azure App Service + PostgreSQL Flexible para hosting (vs Railway/Fly)
|
||||
- ADR-0009: Outbox pattern para eventos internos
|
||||
|
||||
Cada ADR: contexto, decisión, alternativas consideradas, consecuencias. Esto vale oro cuando entra el próximo dev (o tú dentro de 6 meses).
|
||||
|
||||
---
|
||||
|
||||
## 17. Roadmap de evolución (post-MVP)
|
||||
|
||||
Priorizado por **acercarse al ciclo end-to-end** que el equipo directivo describió en la llamada original (Jira → BUK → Factura → Cobranza → Conciliación → Asiento):
|
||||
|
||||
| Cuándo | Qué | Por qué |
|
||||
|---|---|---|
|
||||
| Mes 3-4 | Belvo (MX) en vivo + asientos contables auto contra BIND | Elimina dos cuellos de botella manuales que sobrevivieron al MVP |
|
||||
| Mes 4-5 | Ingesta de horas Jira → input de facturación + EUR | Habilita el caso de uso #1 del PRD inicial (factura auto desde horas) |
|
||||
| Mes 5-7 | Integración profunda con BUK (cuando exponga API) — trigger nómina → factura | Cierra el extremo izquierdo del ciclo |
|
||||
| Mes 7-9 | Domiciliación Stripe, anomalía con IA, portal cliente | Capa de valor agregado sobre el ciclo ya cerrado |
|
||||
| Mes 9-12 | Multi-tenancy comercial, onboarding self-service, billing del SaaS | Pivote a producto comercializable |
|
||||
| Año 2 | Marketplace de integraciones (otros PACs, bancos, ERPs) | Crecimiento del producto |
|
||||
|
||||
---
|
||||
|
||||
## 18. Workflow de desarrollo con Claude Code
|
||||
|
||||
El proyecto se desarrolla con **Claude Code** como acelerador. La arquitectura, convenciones y herramientas elegidas en este documento están deliberadamente alineadas con prácticas que **maximizan la calidad del output asistido por IA**: tipos estrictos, módulos con fronteras claras, ADRs versionados, tests como contrato.
|
||||
|
||||
### 17.1 Estructura de soporte a la IA (en el repo)
|
||||
|
||||
```
|
||||
.claude/
|
||||
├── settings.json # permisos de herramientas, hooks
|
||||
├── skills/ # workflows reutilizables (slash commands)
|
||||
│ ├── new-module/ # scaffolding de un módulo nuevo
|
||||
│ ├── new-integration/ # cliente de API externa con tests + retries
|
||||
│ ├── new-event-handler/ # handler con outbox + tests + idempotencia
|
||||
│ ├── new-cfdi-test/ # E2E de facturación
|
||||
│ └── review-pr/ # checklist de revisión antes de merge
|
||||
├── agents/ # sub-agentes especializados (opcional)
|
||||
└── memory/ # contexto persistente (decisiones, gotchas)
|
||||
|
||||
CLAUDE.md # contexto raíz del proyecto (siempre cargado)
|
||||
docs/
|
||||
├── adr/ # decisiones arquitectónicas
|
||||
├── conventions.md # cómo se nombran cosas, patrones obligatorios
|
||||
├── domain-glossary.md # vocabulario fiscal/financiero (CFDI, asiento, etc.)
|
||||
└── integrations/ # docs por integración (Belvo, PAC, BIND)
|
||||
```
|
||||
|
||||
### 17.2 CLAUDE.md raíz (esqueleto)
|
||||
|
||||
Este archivo se carga automáticamente en cada sesión. Tiene que ser **corto y duro**:
|
||||
|
||||
```markdown
|
||||
# Balam — Plataforma de Automatización Financiera
|
||||
|
||||
## Contexto crítico
|
||||
|
||||
Sistema financiero productivo de empresa real. Errores cuestan dinero,
|
||||
relaciones con clientes y compliance fiscal. Cuidado extremo con:
|
||||
|
||||
- Cálculos de impuestos (decimal(18,4), nunca float)
|
||||
- Idempotencia en endpoints de creación
|
||||
- Lista blanca de cobranza (ACUNTIA + Top 3 jamás reciben recordatorio auto)
|
||||
- Cancelación de facturas: lógica, nunca hard delete
|
||||
- Multi-tenancy: tenant_id en cada query (RLS activo)
|
||||
|
||||
## Reglas duras
|
||||
|
||||
- TypeScript strict siempre. Nada de `any`.
|
||||
- Toda mutación financiera escribe a audit_log en la misma transacción.
|
||||
- Toda integración externa con retry + idempotency_key.
|
||||
- Tests obligatorios para: cálculo de impuestos, matching de conciliación,
|
||||
reglas de cobranza, generación de asientos.
|
||||
- Nunca commitees secretos. Nunca pegues datos reales de Balam en prompts.
|
||||
|
||||
## Stack
|
||||
|
||||
NestJS + Prisma + PostgreSQL + Redis (BullMQ) + Next.js + shadcn/ui.
|
||||
Monorepo pnpm + Turborepo. Tests con Vitest + Playwright. Lint con Biome.
|
||||
|
||||
## Comandos comunes
|
||||
|
||||
- `pnpm dev` — levanta web + api + worker
|
||||
- `pnpm test` — corre toda la suite
|
||||
- `pnpm db:migrate` — aplica migración (siempre backward-compatible)
|
||||
- `pnpm db:seed` — datos sintéticos para desarrollo
|
||||
- `pnpm typecheck` — valida tipos sin compilar
|
||||
|
||||
## Antes de cerrar una tarea
|
||||
|
||||
1. `pnpm typecheck && pnpm test && pnpm lint` debe pasar
|
||||
2. Si tocaste schema, hay migración + rollback verificado
|
||||
3. Si tocaste lógica financiera, hay test que la cubre
|
||||
4. Si tocaste integración externa, hay mock + test contra mock
|
||||
5. PR description explica el "por qué", no solo el "qué"
|
||||
|
||||
## Documentos vivos
|
||||
|
||||
- Convenciones: docs/conventions.md
|
||||
- Glosario fiscal: docs/domain-glossary.md
|
||||
- ADRs: docs/adr/
|
||||
- Integraciones: docs/integrations/<nombre>.md
|
||||
```
|
||||
|
||||
### 17.3 Slash commands / skills críticos
|
||||
|
||||
Cada uno automatiza un workflow repetitivo y enforce las convenciones del proyecto:
|
||||
|
||||
| Skill | Qué hace |
|
||||
|---|---|
|
||||
| `/new-module <nombre>` | Crea estructura del bounded context (controller, service, repository, schema Prisma, tests, evento outbox) siguiendo el template del proyecto |
|
||||
| `/new-integration <api>` | Genera cliente con reintentos exponenciales, idempotency, error mapping, mock para tests, y registro en `docs/integrations/` |
|
||||
| `/new-event-handler <evento>` | Crea handler que lee outbox, es idempotente, registra en audit, y tiene test de retry |
|
||||
| `/new-cfdi-scenario` | Genera test E2E de Playwright para flujo de facturación específico |
|
||||
| `/pre-merge-review` | Corre checklist: types + tests + lint + ADR si aplica + migration safety + no secretos |
|
||||
| `/add-adr <titulo>` | Crea nuevo ADR con template estándar y lo lista en MEMORY |
|
||||
|
||||
### 17.4 Sub-agentes (uso disciplinado)
|
||||
|
||||
Útiles para tareas paralelizables o que ensucian el contexto principal:
|
||||
|
||||
- **`explore`** — buscar dónde se usa una entidad antes de refactorizar
|
||||
- **`reviewer`** — segunda lectura sobre cambios sensibles (lógica fiscal, seguridad, queries con tenant_id)
|
||||
- **`integration-debugger`** — investigar fallos contra mocks de APIs externas sin saturar contexto principal
|
||||
|
||||
No abuses. Cada subagente cuesta tokens y tiempo de orquestación.
|
||||
|
||||
### 17.5 Convenciones que multiplican la productividad de la IA
|
||||
|
||||
Todas viven en `docs/conventions.md`:
|
||||
|
||||
1. **Nombres explícitos**: `calculateInvoiceTaxesMXN()` mejor que `calc()`. La IA infiere intención del nombre.
|
||||
2. **Schemas Zod compartidos** en `packages/contracts/`: una fuente de verdad para tipos front/back.
|
||||
3. **Tests como spec**: cada función pública con test de happy path + edge cases. La IA usa los tests como contrato vivo.
|
||||
4. **Comentarios solo para "por qué"**, nunca para "qué". Los nombres dicen el qué.
|
||||
5. **Archivos cortos**: máximo ~300 líneas. Si un archivo crece más, se divide. Mejor para IA, mejor para humanos.
|
||||
6. **Errores tipados** (`Result<T, DomainError>` o excepciones tipadas), nunca `throw new Error('algo')` genérico.
|
||||
7. **Una responsabilidad por archivo.** Un servicio, un controller, un schema por archivo.
|
||||
8. **README por package** con: propósito, entrypoints, ejemplos de uso.
|
||||
|
||||
### 17.6 Seguridad operativa con IA
|
||||
|
||||
Reglas no negociables:
|
||||
|
||||
- **Datos reales de Balam jamás entran a prompts.** Para pruebas se usan datos sintéticos generados con scripts (faker + patrones reales).
|
||||
- **Credenciales (PAC, Belvo, Plaid, DB) viven en gestor de secretos.** Nunca pegadas en chat ni en `.env` versionado.
|
||||
- **XMLs de CFDI reales, estados de cuenta, listas de clientes:** no van a IA. Para debugging se trabaja sobre versiones anonimizadas.
|
||||
- **Hooks de pre-commit** que bloquean: secretos detectados (gitleaks), archivos con extensión `.cfdi` o `.statement`, datos en formato BIND real.
|
||||
- **Permisos de Claude Code restrictivos** (`.claude/settings.json`): allowlist explícito para Bash; deny en comandos destructivos sin confirmación; no acceso a `/Users/johann/Desktop/Proyectos personales/BALAM/datos-reales/` si esa carpeta llega a existir.
|
||||
- **Code review pre-merge obligatorio** (humano, mío): la IA propone, yo apruebo. Documentado en commit trail.
|
||||
|
||||
### 17.7 Ventaja en velocidad (qué pasa con el presupuesto)
|
||||
|
||||
Tareas que **se aceleran 40-60%** con Claude Code:
|
||||
|
||||
- Boilerplate de módulos, controllers, schemas
|
||||
- Generación de tests (sobre todo edge cases que un humano olvidaría)
|
||||
- Refactor mecánico (renombrar, mover, extraer)
|
||||
- Migraciones de schema con rollback
|
||||
- Documentación (ADRs, READMEs, manuales de usuario)
|
||||
- Mappers y transformaciones de DTOs
|
||||
- Mocks de APIs externas
|
||||
|
||||
Tareas que **NO se aceleran significativamente** (sigue siendo trabajo humano):
|
||||
|
||||
- Decisiones de arquitectura
|
||||
- Discovery y conversaciones con stakeholders
|
||||
- Debugging de integraciones reales (BIND, bancos)
|
||||
- Validación con datos reales
|
||||
- Diseño de UX
|
||||
- Negociación de cambios de scope
|
||||
|
||||
Por eso los rangos de horas siguen incluyendo holgura: Fase 0 y debugging de integraciones no se aceleran; lo que se acelera es el 60% restante del trabajo. Espera caer cerca del **extremo bajo** de cada rango.
|
||||
|
||||
### 17.8 Memoria persistente del proyecto (en `.claude/memory/`)
|
||||
|
||||
Llevar memorias semánticas pequeñas con `[[links]]` entre ellas. Ejemplos útiles para este proyecto:
|
||||
|
||||
- `gotcha-belvo-paginacion.md` — Belvo pagina por cursor, no por offset (descubierto durante Fase 3)
|
||||
- `gotcha-cfdi-cancelacion.md` — cancelación requiere UUID sustituto si motivo=01 (no para motivos 02-04)
|
||||
- `gotcha-fxrate-dof.md` — el DOF publica TC del día siguiente a las 18:00 hrs; usar T-1 para facturas mañaneras
|
||||
- `convention-tenant-id.md` — toda query nueva debe filtrar por tenant_id explícitamente o usar RLS, jamás confiar en aplicación
|
||||
- `decision-bind-as-source-of-truth.md` — BIND queda como fuente de verdad para facturación y contabilidad; plataforma es capa de operaciones (ver ADR-0005)
|
||||
|
||||
Estas memorias hacen que la IA no repita errores y que recuerdes tú mismo las decisiones meses después.
|
||||
|
||||
---
|
||||
|
||||
## 19. Por qué este diseño les va a gustar (sin que lo digan)
|
||||
|
||||
1. **Pedir cambios será barato** — al ser event-driven, sumar comportamiento es un handler, no una cirugía.
|
||||
2. **Auditable** — cuando finanzas pregunte "¿quién canceló esa factura?", hay respuesta exacta en 5 segundos.
|
||||
3. **Sin lock-in** — el código es suyo, el hosting es portable, sin SDKs propietarios.
|
||||
4. **Multi-tenant ready** — el día que decidan vender el producto, no hay rewrite.
|
||||
5. **Explicable** — cualquier dev puede leer el monorepo y entender qué hace cada módulo en una tarde.
|
||||
6. **Robusto** — el motor de conciliación funciona sin IA; la IA es mejora, no dependencia.
|
||||
7. **Respeta lo que ya funciona** — BIND queda como sistema de verdad para facturación y contabilidad. La plataforma orquesta, no reemplaza. Esto reduce riesgo, costo y resistencia al cambio.
|
||||
8. **Construido con toolchain moderno** — desarrollo asistido por IA con revisión humana, tests exhaustivos y documentación al día. Mismo resultado, menos horas facturadas, mejor mantenibilidad.
|
||||
@@ -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
|
||||
@@ -0,0 +1,359 @@
|
||||
# Guía operativa — Stakeholders, llamadas y decisiones por fase
|
||||
|
||||
Documento de referencia personal para el proyecto **Balam · Plataforma de Automatización Financiera (MVP 6 semanas)**.
|
||||
|
||||
Sirve para:
|
||||
1. **Antes de arrancar** — preparar la llamada con el CTO para validar supuestos críticos.
|
||||
2. **Durante el proyecto** — saber a quién acercarte en cada fase y para qué decisión exacta.
|
||||
3. **Detectar bloqueadores temprano** — si la persona indicada no responde, sabes qué riesgo se materializa.
|
||||
|
||||
> Compañeros de este documento:
|
||||
> - `00 - PROPUESTA-COMERCIAL.md` — alcance comprometido y supuestos firmados
|
||||
> - `01 - ARQUITECTURA-TECNICA.md` — módulos y decisiones técnicas
|
||||
> - `02 - PLAN-EJECUCION.md` — tareas atómicas y horas por fase
|
||||
|
||||
---
|
||||
|
||||
## Cómo usar este documento
|
||||
|
||||
- **Sección 1**: lectura inicial. El mapa de stakeholders + diagrama es el modelo mental que cargas en la cabeza durante todo el proyecto.
|
||||
- **Sección 2**: consulta semanal. Cada lunes de una nueva fase, revisa las tablas para confirmar que ya tienes las respuestas que vas a necesitar esa semana.
|
||||
- **Sección 3**: consulta pre-llamada CTO. Antes de la llamada de pre-arranque (todavía no estás en Fase 0).
|
||||
- **Sección 4**: chequeo mensual de salud — si ves anti-patrones, paras y conversas con el contacto técnico.
|
||||
|
||||
---
|
||||
|
||||
# Sección 1 · Mapa de stakeholders por fase
|
||||
|
||||
## 1.1 Quién decide qué
|
||||
|
||||
| Stakeholder | Decide / valida | Pregúntale **antes** de tocar |
|
||||
|---|---|---|
|
||||
| **CEO** | Visión, qué clientes son intocables, scope cuando hay conflicto entre áreas | Cualquier decisión que toque relación con cliente estratégico (lista blanca, tono de cobranza) |
|
||||
| **CFO** | Reglas fiscales y contables, ciclos de cobranza, política de pagos, métricas financieras, validación de reportes | Templates de cobranza, dashboard, tolerancias de conciliación, export para contabilidad |
|
||||
| **CTO** | Sistemas, APIs, infra, secretos, integraciones técnicas, seguridad | Acceso a BIND/bancos, Azure, política de datos, decisiones técnicas no triviales |
|
||||
| **Gerente Administrativo** | Operación día a día: quién descarga PDFs, cómo se identifican pagos, cómo se manejan parciales | Reglas operativas: aliases de clientes, ventanas de match, comportamiento UI |
|
||||
| **Contador (interno o externo)** | Formato del export para BIND, catálogo de cuentas, cierre contable | Estructura del export, mapeo de eventos a asientos contables |
|
||||
|
||||
> **Regla práctica:** si la decisión afecta dinero o relación con cliente → CFO/CEO. Si es técnica → CTO. Si es operativa día a día → gerente admin. Cuando dudes, escala al CFO porque típicamente es quien orquesta este tipo de proyectos en una PyME.
|
||||
|
||||
## 1.2 Diagrama — Stakeholders × Fases
|
||||
|
||||
```mermaid
|
||||
flowchart TB
|
||||
classDef ceo fill:#FFD93D,stroke:#666,color:#000,stroke-width:1px
|
||||
classDef cfo fill:#6BCB77,stroke:#666,color:#000,stroke-width:1px
|
||||
classDef cto fill:#4D96FF,stroke:#666,color:#FFF,stroke-width:1px
|
||||
classDef ga fill:#FF6B6B,stroke:#666,color:#FFF,stroke-width:1px
|
||||
classDef cont fill:#9D4EDD,stroke:#666,color:#FFF,stroke-width:1px
|
||||
|
||||
subgraph F0["FASE 0 · Semana 1 · Discovery + Setup"]
|
||||
direction LR
|
||||
CEO0["CEO<br/><br/>Kickoff<br/>Lista blanca definitiva"]:::ceo
|
||||
CFO0["CFO<br/><br/>Reglas operativas<br/>Línea base errores y tiempo"]:::cfo
|
||||
CTO0["CTO<br/><br/>Azure + Stripe MX<br/>Política de datos / Claude API"]:::cto
|
||||
GA0["GERENTE ADMIN<br/><br/>PDFs reales 3 bancos<br/>Lista de usuarios"]:::ga
|
||||
CONT0["CONTADOR<br/><br/>Formato export BIND"]:::cont
|
||||
end
|
||||
|
||||
subgraph F1["FASE 1 · Semanas 2-3 · Plataforma + Sync BIND"]
|
||||
direction LR
|
||||
CFO1["CFO<br/><br/>Roles RBAC<br/>Política de cancelación"]:::cfo
|
||||
CTO1["CTO<br/><br/>Auth y MFA<br/>Acceso para inspeccionar BIND"]:::cto
|
||||
GA1["GERENTE ADMIN<br/><br/>Validación demo S2<br/>Clientes duplicados / aliases"]:::ga
|
||||
CONT1["CONTADOR<br/><br/>Campos obligatorios de invoice<br/>Fuente del TC"]:::cont
|
||||
end
|
||||
|
||||
subgraph F2["FASE 2 · Semana 4 · Cobranza + Dashboard + Pago link"]
|
||||
direction LR
|
||||
CEO2["CEO<br/><br/>Tono del template<br/>Clientes en zona gris"]:::ceo
|
||||
CFO2["CFO<br/><br/>TEMPLATE FINAL aprobado<br/>Métricas del dashboard"]:::cfo
|
||||
CTO2["CTO<br/><br/>Stripe webhook secret<br/>Email transaccional"]:::cto
|
||||
GA2["GERENTE ADMIN<br/><br/>Ciclo de recordatorios<br/>UX de pagos Stripe"]:::ga
|
||||
CONT2["CONTADOR<br/><br/>Asiento de pagos Stripe<br/>Manejo de duplicados"]:::cont
|
||||
end
|
||||
|
||||
subgraph F3["FASE 3 · Semana 5 · Conciliación PDF"]
|
||||
direction LR
|
||||
CFO3["CFO<br/><br/>Tolerancia de match<br/>Retención PDFs 5 años"]:::cfo
|
||||
CTO3["CTO<br/><br/>Cifrado Blob Storage<br/>Confirmación Claude API ok"]:::cto
|
||||
GA3["GERENTE ADMIN<br/><br/>ALIASES de clientes<br/>Validación de match rate"]:::ga
|
||||
CONT3["CONTADOR<br/><br/>Catálogo de cuentas<br/>Traspasos internos"]:::cont
|
||||
end
|
||||
|
||||
subgraph F4["FASE 4 · Semana 6 · Reportes + Cierre"]
|
||||
direction LR
|
||||
CEO4["CEO<br/><br/>Sign-off del MVP"]:::ceo
|
||||
CFO4["CFO<br/><br/>Criterios de éxito<br/>Aprobación de reportes"]:::cfo
|
||||
CTO4["CTO<br/><br/>Backups<br/>Handoff técnico"]:::cto
|
||||
GA4["GERENTE ADMIN<br/><br/>Capacitación grabada"]:::ga
|
||||
CONT4["CONTADOR<br/><br/>VALIDACIÓN del export BIND"]:::cont
|
||||
end
|
||||
|
||||
F0 --> F1 --> F2 --> F3 --> F4
|
||||
```
|
||||
|
||||
### Cómo leer el diagrama
|
||||
|
||||
- **Filas horizontales = fases en el tiempo** (de izquierda a derecha por el flujo, de arriba a abajo en pantalla).
|
||||
- **Cada bloque de fase contiene los stakeholders que necesitas** durante esa semana, con la decisión / dato concreto que aporta.
|
||||
- **Códigos de color por rol:**
|
||||
- 🟡 Amarillo = CEO (visión + clientes estratégicos)
|
||||
- 🟢 Verde = CFO (reglas de negocio + dinero)
|
||||
- 🔵 Azul = CTO (sistemas + infra)
|
||||
- 🔴 Rojo = Gerente Administrativo (operación día a día)
|
||||
- 🟣 Morado = Contador (contabilidad fiscal + BIND)
|
||||
- **Si un stakeholder no aparece en una fase**, no significa que no exista — significa que **no es bloqueante** para esa fase. Aun así puede recibir el demo de fin de semana.
|
||||
- **El CEO aparece solo 3 veces** (F0, F2, F4) — es deliberado: úsalo para kickoff, validación de tono comercial, y sign-off. No lo satures.
|
||||
|
||||
## 1.3 Detalle por fase
|
||||
|
||||
### Fase 0 — Discovery + Setup (Semana 1)
|
||||
|
||||
**Módulos involucrados:** ninguno todavía — es la fase de validar supuestos y dejar todo listo.
|
||||
|
||||
| Decisión / dato que necesitas | A quién | Cuándo | 🚩 Si no llega |
|
||||
|---|---|---|---|
|
||||
| Export real de BIND (anonimizado) + formato confirmado | CTO + contador | Día 1-3 | Replantear Fase 1 |
|
||||
| 2-3 PDFs anonimizados por banco (Banorte, BBVA, IBC) | Gerente admin (es quien los descarga) | Día 1-3 | Replantear Fase 3 |
|
||||
| Subscripción Azure + sponsor + región | CTO | Día 1-2 | No hay dónde desplegar |
|
||||
| Cuenta Stripe MX verificada (RFC + bancarios) | CFO + CTO | Día 1-5 | Bloqueas Fase 2 |
|
||||
| Lista blanca DEFINITIVA: ACUNTIA + Top 3 con nombre exacto + alias contables | CEO + CFO | Día 1-5 | Riesgo regulatorio comercial |
|
||||
| Manual de marca | Gerente admin o quien lo guarde | Día 1-3 | Branding genérico |
|
||||
| Aprobación uso Claude API con PDFs bancarios | CFO + CTO | Día 1-3 | Replantear Fase 3 |
|
||||
| Línea base medible de "tiempo de conciliación actual" + "errores manuales actuales" | CFO + gerente admin | Día 1-7 | Criterios de éxito ≥70%/60% no se pueden demostrar al cierre |
|
||||
| Política de manejo de datos financieros (auditoría externa, NDA, encripción) | CTO | Día 2-3 | Compliance gap |
|
||||
|
||||
> **Salida de F0:** un `docs/supuestos.md` firmado. Si algo no se valida, lo marcas como "asunción que se materializará en Change Request si cae".
|
||||
|
||||
---
|
||||
|
||||
### Fase 1 — Plataforma + Sync BIND (Semanas 2-3)
|
||||
|
||||
**Módulos:** `identity`, `catalog`, `bind-sync` + outbox base.
|
||||
|
||||
| Decisión / dato | A quién | Cuándo | 🚩 Si no llega |
|
||||
|---|---|---|---|
|
||||
| Roles exactos: ¿Finanzas, Dirección, Operaciones, Admin alcanzan? ¿Hay sub-roles? | CFO + CTO | Inicio S2 | Re-trabajo en RBAC |
|
||||
| ¿Quiénes (nombres + emails) tendrán acceso por rol? | Gerente admin | Inicio S2 | No puedes poblar usuarios reales |
|
||||
| Política de auth: ¿MFA obligatorio para Finanzas? ¿SSO con Google Workspace si lo usan? | CTO | Inicio S2 | Endurecimiento queda en F4 |
|
||||
| Validación del schema de invoice (qué campos del export son obligatorios) | Contador + gerente admin | Mid S2 | Modelo incompleto |
|
||||
| ¿Hay clientes duplicados en BIND por errores históricos? ¿Algún mecanismo de "cliente padre" / "cliente sucursal"? | Gerente admin + contador | Mid S2 | Conciliación falla en S5 |
|
||||
| Política de cancelación de facturas (¿se reflejan en plataforma?) | CFO + contador | Mid S2 | Estados inconsistentes |
|
||||
| TC: ¿DOF FIX está bien o usan otro para alguna cuenta específica (USD interno)? | CFO + contador | Mid S2 | Diferencias cambiarias erróneas |
|
||||
| Confirmación final de fuera-de-scope: EUR + emisión CFDI desde plataforma | CFO | Inicio S2 | Scope creep en S3-S4 |
|
||||
| **Demo de fin de S2** revisada por gerente admin | Gerente admin | Viernes S2 | Sorpresa en S3 |
|
||||
| **Demo de fin de S3** revisada por CFO | CFO | Viernes S3 | F2 arranca sobre base no validada |
|
||||
|
||||
---
|
||||
|
||||
### Fase 2 — Cobranza + Dashboard + Pago con link (Semana 4) — pico de stakeholders
|
||||
|
||||
**Módulos:** `collections`, `payments`, `reporting` (dashboard), `notifications`.
|
||||
|
||||
> Esta es la fase con **más decisiones de negocio**. CFO y gerente admin tienen que estar disponibles. Bloquea calendario suyo con anticipación desde F0.
|
||||
|
||||
| Decisión / dato | A quién | Cuándo | 🚩 Si no llega |
|
||||
|---|---|---|---|
|
||||
| **Aprobación final del template de correo** (tono, firma, asuntos) | CFO + CEO (porque toca clientes) | Lunes S4 | No puedes activar recordatorios |
|
||||
| Ciclo de recordatorios: ¿X días antes, Y días después de vencer, escalación humana al día Z? | CFO + gerente admin | Lunes S4 | Defaults arbitrarios |
|
||||
| Quién puede **modificar la lista blanca en producción** (rol + segundo factor) | CFO | Lunes S4 | Riesgo de envío accidental |
|
||||
| Cómo se reporta hoy un pago vía link Stripe en BIND (¿asiento manual del contador? ¿flujo separado?) | Contador + CFO | Martes S4 | Pagos Stripe quedan huérfanos contablemente |
|
||||
| Política para **pagos duplicados** (cliente paga por link + por transferencia en el mismo día) | Gerente admin + CFO | Mié S4 | Conciliación contradictoria en S5 |
|
||||
| ¿El gerente admin valida cada pago Stripe antes de marcarlo "aplicado", o auto? | Gerente admin | Mié S4 | UX equivocada |
|
||||
| Métricas exactas del dashboard (¿qué corte usa Dirección? ¿semanal? ¿por cliente?) | CFO + CEO | Mar S4 | Dashboard no usable |
|
||||
| Stripe webhook secret + cuenta de email para notificaciones | CTO | Mar S4 | Webhook no se puede recibir |
|
||||
| Política de manejo cuando webhook Stripe falla (¿conciliar al día siguiente vía dashboard Stripe?) | Gerente admin | Jue S4 | Sin runbook operativo |
|
||||
| **Demo viernes S4** con CFO + gerente admin + (idealmente) un cliente test | CFO + GA | Viernes S4 | Riesgo de descubrir gap en S5 cuando ya es tarde |
|
||||
|
||||
> **Tip:** el template de correo es donde más fricción suele haber. Pide un borrador del CFO en F0 (semana 1) para iterarlo durante F1, no improvises en S4.
|
||||
|
||||
---
|
||||
|
||||
### Fase 3 — Conciliación PDF con Claude API (Semana 5)
|
||||
|
||||
**Módulos:** `banking`, `reconciliation`.
|
||||
|
||||
| Decisión / dato | A quién | Cuándo | 🚩 Si no llega |
|
||||
|---|---|---|---|
|
||||
| Lista exhaustiva de **aliases por cliente** (cómo aparecen los pagos en cada banco) | Gerente admin + contador | Lunes S5 | Match por alias inútil → todo va a cola humana |
|
||||
| Tolerancia aceptada: ¿centavos? ¿±0.5%? ¿±2%? ¿depende de monto? | CFO | Lunes S5 | Auto-match muy laxo o muy estricto |
|
||||
| Ventana de fecha para auto-match (±3 días default, ¿es razonable para SPEI 24/7?) | Gerente admin | Lunes S5 | Auto-match pierde casos legítimos |
|
||||
| Política de traspasos internos: ¿qué hacen hoy en BIND con esos movimientos? | Contador + CFO | Mar S5 | Doble registro en conciliación |
|
||||
| ¿Quién aprueba un "match con flag" (medio match)? ¿Cualquiera de Finanzas, o solo CFO? | CFO | Mar S5 | Cola sin dueño |
|
||||
| Política de **retención de PDFs bancarios** (¿5 años SAT, indefinido, otra?) | CFO + contador | Mar S5 | Compliance fiscal |
|
||||
| Cifrado en reposo de PDFs en Azure Blob — confirmar política de Balam | CTO | Mar S5 | Hardening incompleto |
|
||||
| Catálogo de cuentas / clasificaciones de gasto que el contador usa hoy | Contador | Mié S5 | Anomalías por categoría no se pueden detectar |
|
||||
| Validación con datos reales: subir un mes completo de un banco y revisar match rate con gerente admin | Gerente admin | Jue S5 | Sales del rango y no te enteras |
|
||||
|
||||
> **Tip:** los aliases son oro y suelen vivir solo en la cabeza del gerente admin / contador. Pide una hora bloqueada con ellos en S5 para vaciar ese conocimiento a una tabla.
|
||||
|
||||
---
|
||||
|
||||
### Fase 4 — Reportes + Cierre (Semana 6)
|
||||
|
||||
**Módulos:** `reporting` (export BIND), `notifications` (reportes programados), seguridad final, capacitación.
|
||||
|
||||
| Decisión / dato | A quién | Cuándo | 🚩 Si no llega |
|
||||
|---|---|---|---|
|
||||
| **Validación del export para BIND** (que efectivamente cargue sin error en BIND real) | Contador | Lunes S6 | Entregable inservible |
|
||||
| Catálogo de cuentas final + mapeo evento → asiento que el contador necesita | Contador + CFO | Lunes S6 | Export incompleto |
|
||||
| Qué reportes quiere automáticos: ¿diario CxC? ¿semanal de movimientos no conciliados? ¿quién los recibe? | CFO + Dirección | Mar S6 | Reportes que nadie lee |
|
||||
| Validación de criterios de éxito (≥70% reducción errores, ≥60% reducción tiempo conciliación) | CFO | Mié S6 | No puedes cerrar el contrato |
|
||||
| Plan de quién opera el sistema post-MVP (gerente admin solo, o también el CTO interviene) | CTO + CFO | Mié S6 | Sin owner operativo |
|
||||
| Backups: confirmar política (frecuencia, retención, dónde se guardan, plan de recuperación) | CTO | Jue S6 | Compliance + riesgo operativo |
|
||||
| Sesión de capacitación grabada — quiénes asisten (contacto técnico + gerente admin obligatorios, contador deseable) | Todos los anteriores | Jue S6 | Capacitación no replicable |
|
||||
| Sign-off formal del MVP | CFO (o CEO) | Viernes S6 | Disputa de horas / scope |
|
||||
|
||||
## 1.4 Cadencia recomendada de contacto
|
||||
|
||||
| Persona | Cadencia base | Cuándo aumentar |
|
||||
|---|---|---|
|
||||
| **CTO (contacto técnico día a día)** | Daily async (1-2 mensajes) + sesión técnica quincenal de 1 h | F0 (acceso), F1 (BIND), inicio F2 (Stripe), F3 (seguridad PDF) |
|
||||
| **Gerente administrativo** | Demo semanal viernes + ad-hoc por bloqueadores | F2 completa (reglas operativas), F3 completa (aliases, validación) |
|
||||
| **CFO** | Demo semanal viernes + sesión validación al cierre de cada fase | F2 (templates + dashboard), F4 (export + criterios de éxito) |
|
||||
| **CEO** | Solo en kickoff + demo final F4 (+ ad-hoc si hay decisión de scope conflicto) | Si surge fricción con cliente estratégico |
|
||||
| **Contador** | Bloqueado para F0 (formato BIND), F3 (catálogo + aliases), F4 (export final) | Cuando toques cualquier flujo que termine en BIND |
|
||||
|
||||
## 1.5 Anti-patrones que cuestan caro
|
||||
|
||||
1. **Esperar al CFO/CEO solo en F4** — descubres en S6 que el template de correo no les gusta y replantear el motor de cobranza queda fuera de presupuesto. Inclúyelos desde F2.
|
||||
2. **Hablar solo con el CTO** — vas a tener un sistema técnicamente correcto que no refleja las reglas de negocio reales. El gerente admin sabe la operación que ni el CTO ni el CFO conocen al detalle.
|
||||
3. **Pedir lista blanca "en algún momento"** — si llegas a S4 sin tenerla formalizada, el riesgo regulatorio comercial es tuyo. Pídela el día 1.
|
||||
4. **No bloquear calendario de CFO/gerente admin con anticipación para S4 y S5** — son las semanas pico de decisión de negocio. Si están de viaje o saturados, F2/F3 se atrasan.
|
||||
5. **Asumir que el contador es interno** — muchas PyMEs en MX tienen contador externo que va una vez por semana. Si es el caso, agéndalo en F0 para que esté disponible en F4.
|
||||
|
||||
---
|
||||
|
||||
# Sección 2 · Preparación llamada CTO (pre-Fase 0)
|
||||
|
||||
> Esta es la llamada **antes de firmar** o antes del kickoff de Fase 0. El objetivo no es vender ni planear todavía; es validar que los 11 supuestos de la propuesta se sostienen.
|
||||
|
||||
## 2.1 Objetivo de la llamada
|
||||
|
||||
Salir con **decisión clara sobre si algún supuesto crítico de la propuesta ya hoy sabemos que no se cumple**. Es 10× más barato descubrirlo aquí que en semana 2.
|
||||
|
||||
Duración recomendada: **60-75 min**. Si solo hay 30, prioriza Bloque 1.
|
||||
|
||||
## 2.2 Bloque 1 — Sistemas y datos (25-30 min, el corazón de la llamada)
|
||||
|
||||
### BIND ERP
|
||||
|
||||
| Pregunta | Por qué importa | 🚩 Bandera roja |
|
||||
|---|---|---|
|
||||
| ¿BIND expone alguna API documentada o solo es UI + export? ¿Han hablado con BIND sobre roadmap de API? | Define si Fase 2 es realista en 3 meses o 1 año | No hay API ni planes |
|
||||
| ¿Cómo exportan hoy facturas y catálogo de clientes? ¿Formato (CSV, Excel, XML SAT)? ¿Frecuencia? ¿Manual o programado? | Es el input principal del MVP | Solo se puede descargar a mano factura por factura |
|
||||
| ¿Puedes mandarme un export real (anonimizado) en la próxima semana? | El parsing real es la diferencia entre 18 y 30 h en Fase 0 | "Tengo que pedirlo, no sé cuándo lo tengamos" |
|
||||
| ¿Tienen sandbox de BIND o solo producción? | Define si podemos probar contra datos reales sin riesgo | Solo producción |
|
||||
| ¿Quién es el admin de BIND internamente? ¿Tiene tiempo para apoyar dudas técnicas? | Necesitas a alguien que valide formatos de export | Ningún dueño técnico claro |
|
||||
| ¿BIND timbra las facturas (CFDI 4.0) sin costo adicional según el volumen actual? ¿Manejará el crecimiento? | Confirma el supuesto #4 — si no, hay que sumar PAC | No tienen claro el límite |
|
||||
|
||||
### Bancos (3 cuentas — 2 MX + IBC Texas)
|
||||
|
||||
| Pregunta | Por qué importa | 🚩 Bandera roja |
|
||||
|---|---|---|
|
||||
| ¿Cuáles 2 bancos MX exactamente? ¿BBVA, Banorte, Banamex, Santander? | Cada uno tiene formato de PDF distinto | Banco regional poco común |
|
||||
| ¿Tienen PDFs históricos (últimos 3-6 meses) de los 3 bancos para validar parsing? | Necesitamos muestras reales en Fase 0 | No tienen históricos digitales |
|
||||
| ¿IBC Bank Texas permite descargar PDFs estructurados o solo print del web? | IBC es el riesgo mayor del MVP | Solo "imprimir como PDF" del portal |
|
||||
| ¿Quién descarga hoy los estados de cuenta? ¿Cada cuándo? ¿Lo siguen haciendo manual durante el MVP? | El flujo de upload manual depende de esto | "No sabemos quién lo hace consistente" |
|
||||
| ¿Hay traspasos internos frecuentes entre las 3 cuentas? ¿Cuál es el patrón? | Define complejidad del motor de conciliación | Traspasos diarios sin patrón claro |
|
||||
| ¿Algún banco ya integrado con Belvo/Plaid o ya tienen credenciales API en algún lado? | Atajo potencial para Fase 2 | — |
|
||||
|
||||
### BUK y Jira (para validar que Fase 2 sea creíble, no para MVP)
|
||||
|
||||
| Pregunta | Por qué importa |
|
||||
|---|---|
|
||||
| ¿BUK expone API? ¿Han pedido roadmap? | El caso de uso #1 del PRD original depende de esto |
|
||||
| ¿Jira es Cloud o Server? | Cloud tiene API limpia; Server es más complicado |
|
||||
| ¿Hay registro de horas por colaborador-cliente en Jira hoy, o eso vive en otro lado? | Define si Jira→Factura es viable en Fase 2 |
|
||||
|
||||
### Stripe
|
||||
|
||||
| Pregunta | Por qué importa | 🚩 Bandera roja |
|
||||
|---|---|---|
|
||||
| ¿Ya tienen cuenta Stripe MX verificada (RFC + bancarios) o hay que crearla? | Verificación de Stripe MX toma 1-3 semanas | No la tienen y la necesitamos para semana 4 |
|
||||
| ¿Algún convenio o pricing especial con Stripe? | Ajuste a la sección de costos operativos | — |
|
||||
|
||||
## 2.3 Bloque 2 — Infra y compliance (15 min)
|
||||
|
||||
| Pregunta | Por qué importa |
|
||||
|---|---|
|
||||
| ¿Tienen subscripción Azure activa? ¿Quién la administra? ¿Centro de costos? | Si no, hay que crearla en Fase 0 |
|
||||
| ¿Preferencia de región Azure? (mexicocentral, southcentralus, eastus) | Latencia y compliance — IBC Texas puede sugerir US |
|
||||
| ¿Cómo manejan secretos hoy? (Key Vault, .env, 1Password, nada) | Define el estándar a aplicar |
|
||||
| ¿Tienen política interna de manejo de datos financieros / PII? ¿Auditoría externa? | Compliance — afecta cómo se modela el audit log y backups |
|
||||
| ¿NDA — usan el suyo o el mío? ¿Hay restricciones de portafolio? | Cierre legal antes de iniciar |
|
||||
| Para el manejo de **datos reales** en Fase 3 con Claude API, ¿hay alguna política interna que choque con enviar PDFs bancarios a un LLM (aunque sea Anthropic con no-training)? | El supuesto #11 de la propuesta — si choca, replanteamos |
|
||||
| ¿Quién recibe el handoff técnico al final del MVP? ¿Tienen DevOps interno o lo opera el contador? | Define qué tan robusta debe ser la operación + capacitación |
|
||||
|
||||
## 2.4 Bloque 3 — Realidades operativas (10 min)
|
||||
|
||||
| Pregunta | Por qué importa |
|
||||
|---|---|
|
||||
| De las ~50 facturas/mes: ¿distribución? ¿2-3 grandes y 47 chicas, o uniforme? | Define dónde concentrar esfuerzo de cobranza |
|
||||
| ¿Cuántos clientes activos hay hoy? ¿Cuántos están "siempre en cobranza"? | Tamaño del catálogo y reglas de cobranza |
|
||||
| ¿Cuánto tiempo toma conciliar **hoy** los 3 estados de cuenta del mes? ¿Quién lo hace? | Línea base del criterio de éxito ≥60% — **pide medirlo formalmente las próximas 2 semanas si no está medido** |
|
||||
| ¿Qué % de facturas requiere re-trabajo por error contable hoy? | Línea base del criterio de éxito ≥70% |
|
||||
| Pagos parciales: ¿qué tan frecuentes? ¿Cómo los registran hoy? | Define la UX del módulo de cobranza |
|
||||
|
||||
## 2.5 Bloque 4 — Reglas de negocio que el CTO sabe pero no están escritas (10 min)
|
||||
|
||||
| Pregunta | Por qué importa |
|
||||
|---|---|
|
||||
| Lista blanca ACUNTIA + Top 3: ¿quiénes son los Top 3 exactos? ¿Hay clientes "grises" (importantes pero no Top)? | Necesitas esto en Fase 0, no en Fase 2 |
|
||||
| ¿Hay clientes con condiciones de pago no-estándar? (90 días, retenciones, factoring) | Afecta el motor de recordatorios |
|
||||
| ¿Cuál es el ciclo de cobranza actual? (1er recordatorio a los X días, 2do a los Y, escalación humana cuándo) | Define defaults del motor |
|
||||
| ¿Qué hacen hoy cuando entra un pago no identificado? | Necesitas la cola humana clara |
|
||||
|
||||
## 2.6 Bloque 5 — Personas, proceso y riesgo (10 min)
|
||||
|
||||
| Pregunta | Por qué importa |
|
||||
|---|---|
|
||||
| ¿Quién es el **contacto técnico día a día** durante el MVP? ¿Tú directamente o alguien de tu equipo? | Define velocidad de bloqueo |
|
||||
| ¿Quién es el **gerente administrativo** que validará reglas de cobranza/conciliación? ¿SLA de respuesta? | El otro stakeholder del supuesto #9 |
|
||||
| ¿Ya intentaron antes este proyecto internamente o con otro proveedor? ¿Qué pasó? | Lecciones gratis + por qué llegaron a ti |
|
||||
| ¿Cuál es el **peor escenario** que les preocupa con esto? | Te dice dónde están las heridas reales |
|
||||
| Si tuviéramos que cortar alcance en semana 5 por un imprevisto, ¿qué sacrificas primero entre cobranza, conciliación y dashboard? | Te da el orden de prioridad real, no el oficial |
|
||||
| ¿Hay cambios fiscales conocidos en pipeline (SAT, Texas) en los próximos 6 meses? | Riesgo de re-trabajo |
|
||||
|
||||
## 2.7 Lo que pides cerrar antes de colgar
|
||||
|
||||
1. **Compromiso de envío** en 5-7 días hábiles de:
|
||||
- 1 export real anonimizado de BIND (facturas + clientes)
|
||||
- 1 PDF de estado de cuenta por cada uno de los 3 bancos (3 archivos)
|
||||
- Lista de clientes en lista blanca (ACUNTIA + Top 3 con nombre exacto)
|
||||
2. **Acceso o creación de subscripción Azure** con un sponsor identificado
|
||||
3. **Borrador de NDA** si aplica
|
||||
4. **Cadencia confirmada**: 2-3 standups async/semana + demo viernes + sesión técnica quincenal
|
||||
5. **Próxima sesión técnica agendada** (idealmente día 1 de Fase 0)
|
||||
|
||||
## 2.8 Lo que NO conviene hacer en esta llamada
|
||||
|
||||
- **No prometer fechas exactas** antes de ver el export real de BIND y los PDFs
|
||||
- **No entrar en debate de stack** (Next.js vs. lo que sea) — eso es tuyo
|
||||
- **No discutir tarifa** — ya está en la propuesta, si lo abren responde corto
|
||||
- **No ofrecer scope creep** aunque suene tentador (ej. "¿también podrías hacer X?") → "Lo agendamos para Fase 2"
|
||||
|
||||
## 2.9 Una pregunta-trampa-útil al final
|
||||
|
||||
> *"Si dentro de 6 meses esta plataforma está funcionando exactamente como esperan, ¿qué métrica concreta tendría que estar moviéndose para que sintieras que valió la pena?"*
|
||||
|
||||
Te da el norte real del proyecto y suele revelar prioridades que no están en el PRD.
|
||||
|
||||
---
|
||||
|
||||
# Apéndice · Artefactos críticos a recibir antes de iniciar Fase 0
|
||||
|
||||
Checklist para confirmar antes de facturar el anticipo:
|
||||
|
||||
- [ ] Export real anonimizado de BIND (clientes + facturas)
|
||||
- [ ] 2-3 PDFs anonimizados de cada uno de los 3 bancos
|
||||
- [ ] Subscripción Azure con sponsor identificado
|
||||
- [ ] Cuenta Stripe MX verificada (o compromiso de tenerla en 2 semanas)
|
||||
- [ ] Lista definitiva: ACUNTIA + Top 3 con nombre legal + aliases bancarios conocidos
|
||||
- [ ] Manual de marca
|
||||
- [ ] NDA firmado (si aplica) + acuerdo Claude API
|
||||
- [ ] Línea base medida: tiempo de conciliación + % errores actuales (para los criterios de éxito ≥70%/60%)
|
||||
- [ ] Contacto técnico día a día designado con disponibilidad confirmada
|
||||
- [ ] Gerente administrativo identificado con SLA de respuesta <48 h
|
||||
- [ ] Contador identificado, interno o externo, con disponibilidad para F0, F3 y F4
|
||||
@@ -0,0 +1,256 @@
|
||||
# Agenda · Llamada CTO (martes 19 mayo 2026)
|
||||
|
||||
> Documento de preparación personal para la **llamada de pre-arranque** del proyecto Balam.
|
||||
> Complementa `03 - GUIA-STAKEHOLDERS.md` (Sección 2). La Guía tiene la lista exhaustiva de preguntas; este documento tiene **lo que ya investigué para no llegar en cero**, las preguntas concretas que se derivan de esa investigación, y el orden para los 60-75 min.
|
||||
>
|
||||
> Hallazgo principal: **BIND ERP sí tiene API documentada**. Esto cambia el tono de la llamada — la pregunta deja de ser "¿hay API?" y pasa a ser "¿qué módulos están expuestos, cuál es el plan de uso?".
|
||||
|
||||
---
|
||||
|
||||
## 0. Mentalidad para entrar a la llamada
|
||||
|
||||
- **No vendas, valida.** La propuesta ya está firmada (o por firmar); esta llamada existe para detectar si algún supuesto crítico hoy no se cumple. Mejor descubrirlo aquí que en semana 2.
|
||||
- **No prometas fechas exactas** antes de ver el export real de BIND y los PDFs.
|
||||
- **No discutas tarifa ni stack.**
|
||||
- **Apunta hacia los artefactos** del cierre (Sección 7) — todo lo que NO sea uno de esos 5 entregables es ruido.
|
||||
|
||||
---
|
||||
|
||||
## 1. Estado de lo investigado (lo que YA sé antes de entrar)
|
||||
|
||||
Esta sección es para que entres a la llamada con contexto real, no asunciones. Cada hallazgo viene con la pregunta que se le deriva.
|
||||
|
||||
### 1.1 BIND ERP — **tiene API pública** ⚡ (cambia el supuesto #2)
|
||||
|
||||
| Hecho confirmado | Fuente | Implicación |
|
||||
|---|---|---|
|
||||
| API documentada en `developers.bind.com.mx` | [Portal BIND](https://developers.bind.com.mx/) · [Ayuda BIND](https://ayuda.bind.com.mx/hc/es/articles/360007437754-api-de-bind-erp) | Fase 1 puede ir vía API en vez de export, **si** los módulos que necesitamos están expuestos |
|
||||
| Auth: Bearer Token (API Key) | Ayuda BIND | API Key se saca desde Perfil → Integraciones |
|
||||
| Rate limit: 20,000 req/día | Ayuda BIND | Más que suficiente para ~50 facturas/mes |
|
||||
| Endpoints confirmados: `/api/Invoices`, `/api/Invoices/{idOrNumber}` con UUID/folio fiscal · `/api/inventory` · módulo Customers (consultar, agregar, actualizar) | API tracker / Ayuda BIND | Cubre **facturación + clientes**, que es exactamente Fase 1 |
|
||||
| **NO confirmado**: webhooks, endpoint de pagos, endpoint de asientos contables, sandbox, timbrado CFDI 4.0 vía API | — | Son las 5 preguntas clave de la llamada para BIND |
|
||||
|
||||
**Preguntas concretas al CTO sobre BIND** (en orden de prioridad):
|
||||
|
||||
1. ¿Han usado la API de BIND antes, o solo el export? ¿Tienen ya un API Key activo?
|
||||
2. ¿Saben si BIND expone **webhooks** (factura creada, factura pagada, factura cancelada)? Si no, voy a tener que hacer polling — afecta cadencia y costo de Fase 1.
|
||||
3. ¿Hay endpoint en BIND para **registrar pagos** y para **subir/generar asientos contables**? Si sí, Fase 4 cambia (en lugar de export Excel para el contador, escribimos directo). Si no, mantenemos el plan actual.
|
||||
4. ¿BIND ofrece **sandbox**, o solo producción? — Define cómo trabajamos en Fase 0/1 sin tocar datos reales.
|
||||
5. ¿El **timbrado CFDI 4.0** está expuesto vía API o sigue siendo solo botón en la UI? — Importa para visión Fase 2 (que la plataforma emita directo en lugar de "trigger humano en BIND").
|
||||
|
||||
> **Si NO conoce la API o nunca la han usado:** no es bandera roja por sí solo, pero pídele acceso ese mismo día para inspeccionarla yo.
|
||||
|
||||
### 1.2 BUK — tiene API REST documentada ✅ (supuesto #6 sostiene)
|
||||
|
||||
| Hecho confirmado | Implicación |
|
||||
|---|---|
|
||||
| BUK ofrece API RESTful para exportación de datos | Visión Fase 2 (BUK → factura automática) es viable |
|
||||
| Plataforma BUK México activa (`buk.mx`) | No hay riesgo de no-cobertura geográfica |
|
||||
| 30+ integraciones nativas + flujos configurables | Hay precedente, no es greenfield |
|
||||
|
||||
**Preguntas concretas al CTO sobre BUK:**
|
||||
|
||||
1. ¿Quién administra BUK internamente? ¿Tienen ya credenciales API o hay que solicitarlas?
|
||||
2. ¿Qué disparador de BUK marcaría "nómina aprobada lista para facturar al cliente"? (Es el caso de uso #1 del PRD original — viable solo si ese evento existe en BUK.)
|
||||
3. ¿Cómo registran hoy en BUK las horas por colaborador-cliente? ¿Lo hace BUK, Jira, o vive en una hoja aparte?
|
||||
|
||||
### 1.3 IBC Bank Texas — sin API, pero hay 2 alternativas a PDF ⚠️
|
||||
|
||||
Esto es el riesgo más alto del MVP según la propuesta. Lo que ya sé:
|
||||
|
||||
| Hecho confirmado | Fuente | Implicación |
|
||||
|---|---|---|
|
||||
| IBC ofrece eStatements PDF/PNG, retención 18 meses online | [IBC Online Banking](https://www.ibc.com/online-banking/online-banking-services) | Lo que asumimos en la propuesta |
|
||||
| IBC permite **export a Quicken/QuickBooks** (formato `.QBO`/`.QFX`/`.OFX`) | [IBC Online Banking](https://www.ibc.com/online-banking/online-banking-services) | **Esto es enorme** — parsear `.QBO` (XML estructurado) es 10× más barato y robusto que parsear PDF con Claude |
|
||||
| Plaid cubre marginalmente bancos MX, pero **sí cubre la mayoría de US banks** — IBC posiblemente sí esté en Plaid | [Plaid Docs](https://plaid.com/docs/institutions/) | Plan B si `.QBO` no funciona y si están dispuestos a compartir credenciales |
|
||||
|
||||
**Preguntas concretas al CTO sobre IBC:**
|
||||
|
||||
1. ⚡ **¿Hoy descargan estado de cuenta IBC en PDF, o también en formato `.QBO`/Quicken?** Si pueden descargar `.QBO`, **eliminamos el riesgo de parsing con Claude para IBC**. Cambia el alcance de Fase 3 significativamente.
|
||||
2. ¿IBC ofrece "Direct Connect" para QuickBooks (vía OFX server) o solo "Web Connect" (descarga manual del archivo)? — Direct Connect = automatizable. Web Connect = sigue siendo descarga manual pero con archivo bueno.
|
||||
3. ¿Estarían dispuestos a compartir credenciales IBC con un agregador tipo Plaid? (Si la respuesta es no, no insistir — política de seguridad típica.)
|
||||
|
||||
### 1.4 Bancos MX — Belvo cubre el universo posible ✅
|
||||
|
||||
| Hecho confirmado | Fuente |
|
||||
|---|---|
|
||||
| Belvo cubre **32 instituciones MX** para data + payments, incluyendo BBVA, Banorte, Citibanamex, Santander, HSBC, Scotiabank, Banregio, Inbursa, Banco del Bajío, Mifel | [Belvo Direct Debit Institutions](https://developers.belvo.com/products/payments_mexico/direct-debit-institutions) |
|
||||
|
||||
**Preguntas concretas al CTO sobre bancos MX:**
|
||||
|
||||
1. ¿**Cuáles 2 bancos MX exactos** son? (Si están en la lista de Belvo arriba, hay plan B viable.)
|
||||
2. ¿Conocen Belvo o han evaluado integración bancaria previamente? — Posicionarlo como Fase 2 (no MVP), pero útil saber si hay apertura. La objeción típica es "no compartimos credenciales con terceros".
|
||||
3. ¿Tienen PDFs históricos de los últimos 3-6 meses de los 3 bancos para validar parsing en Fase 0?
|
||||
|
||||
### 1.5 Stripe MX — timeline manejable, pero hay que arrancar ya ✅
|
||||
|
||||
| Hecho confirmado | Fuente | Implicación |
|
||||
|---|---|---|
|
||||
| Aprobación típica: **horas a 2 días**, máximo **2 semanas** en casos complejos | [Stripe MX requisitos](https://support.stripe.com/questions/required-information-to-open-your-stripe-account-in-mexico) | Si arrancan el trámite hoy, semana 4 (cobranza + pago link) está cubierta |
|
||||
| Requisitos: entidad mexicana + RFC + CLABE + representante legal | Stripe Support | Si **falta uno solo**, Stripe MX no opera |
|
||||
| Comisión: 3.6% + $3 MXN, sin IVA sobre la comisión | [Stripe pricing](https://stripe.com/pricing) | — |
|
||||
| Alternativas si Stripe no aprueba: **Conekta** (100% MX, OXXO/SPEI nativo, 3.4% + $3 + IVA) o **Mercado Pago** | [Comparativa Stripe vs Conekta vs MP 2026](https://atempora.studio/blog/stripe-vs-mercado-pago-vs-conekta) | Plan B documentado |
|
||||
|
||||
**Preguntas concretas al CTO sobre Stripe:**
|
||||
|
||||
1. ¿La empresa ya tiene **RFC + CLABE + representante legal con CURP** listos? Si sí, abrimos cuenta esta semana y empezamos verificación.
|
||||
2. ¿Algún convenio o pricing especial con Stripe? ¿O ya tienen cuenta?
|
||||
3. Si Stripe MX rechaza o se tarda más de 2 semanas, ¿hay apertura a Conekta como Plan B?
|
||||
|
||||
### 1.6 Jira — variable crítica es Cloud vs Server
|
||||
|
||||
No requiere research técnico (Jira es estándar), pero confirmar:
|
||||
|
||||
1. ¿Jira es **Cloud o Server**? (Cloud = API limpia OAuth 2.0; Server = más complicado, depende de versión.)
|
||||
2. ¿Hay registro de horas por colaborador-cliente en Jira hoy, o eso vive en otro lado (hoja de cálculo, BUK)?
|
||||
|
||||
---
|
||||
|
||||
## 2. Estructura de los 60-75 min (orden propuesto)
|
||||
|
||||
Asume que el CTO da máximo 60 min reales. Si te dan más, expandes Bloques 4 y 5.
|
||||
|
||||
### Min 0-5 · Apertura
|
||||
|
||||
- Saludo, agradecimiento por el tiempo.
|
||||
- **Encuadre claro** (en menos de 60 segundos): *"El objetivo de hoy no es vender ni planear el proyecto — eso ya está en la propuesta. El objetivo es validar conmigo, sistema por sistema, que los supuestos de la propuesta se sostienen. Cada minuto que invertimos aquí me ahorra 10 minutos en semana 2."*
|
||||
- Permiso para tomar nota / grabar (siempre pídelo).
|
||||
|
||||
### Min 5-30 · Bloque 1 — Sistemas y datos (el corazón)
|
||||
|
||||
Orden interno (no negociable, va de menor a mayor riesgo):
|
||||
|
||||
1. **BIND ERP** (8-10 min) — usa las 5 preguntas de 1.1
|
||||
2. **Bancos MX** (5 min) — qué bancos exactos, PDFs históricos, posición sobre Belvo
|
||||
3. **IBC Texas** (5 min) — la pregunta del `.QBO` es la más importante de toda la llamada
|
||||
4. **BUK + Jira** (3-5 min) — son Fase 2, no MVP, no profundices
|
||||
5. **Stripe** (3 min) — RFC/CLABE/representante listos sí/no
|
||||
|
||||
### Min 30-45 · Bloque 2 — Infra, compliance, seguridad
|
||||
|
||||
Usa la tabla de Sección 2.3 de `03 - GUIA-STAKEHOLDERS.md`. Los críticos:
|
||||
|
||||
- ¿Azure activa? ¿Quién la administra? ¿Centro de costos?
|
||||
- ¿Política interna sobre enviar PDFs bancarios a un LLM externo (Claude API)? — **supuesto #11 de la propuesta**.
|
||||
- ¿Cómo manejan secretos hoy?
|
||||
- ¿NDA — el suyo o el mío?
|
||||
|
||||
### Min 45-55 · Bloque 3 — Realidades operativas y reglas no escritas
|
||||
|
||||
Lo mínimo crítico (ver Sección 2.4 y 2.5 de la Guía):
|
||||
|
||||
- Distribución de las ~50 facturas: ¿concentradas o uniformes?
|
||||
- Tiempo actual de conciliación + % retrabajo (línea base para criterios de éxito 60%/70%).
|
||||
- **Lista blanca: ¿Top 3 exactos?**
|
||||
- ¿Cuál es el peor escenario que les preocupa? (Esta pregunta abre cosas no escritas.)
|
||||
|
||||
### Min 55-65 · Bloque 4 — Cierre operativo
|
||||
|
||||
Pide explícitamente los 5 entregables de Sección 7. **No salgas de la llamada sin esto.**
|
||||
|
||||
### Min 65-70 · Pregunta-trampa
|
||||
|
||||
> *"Si dentro de 6 meses esta plataforma está funcionando exactamente como esperan, ¿qué métrica concreta tendría que estar moviéndose para que sintieras que valió la pena?"*
|
||||
|
||||
Esta pregunta revela la prioridad real. A veces sale algo que no está en el PRD.
|
||||
|
||||
---
|
||||
|
||||
## 3. Banderas rojas a escuchar activamente
|
||||
|
||||
Si oyes cualquiera de estas, **no las negocies en la llamada** — anótalas y replantea después.
|
||||
|
||||
| Si escuchas... | Significa | Acción |
|
||||
|---|---|---|
|
||||
| "BIND no, eso lo administra el contador externo" | No tienes acceso técnico real | Pedir contacto del contador antes de Fase 0 |
|
||||
| "No sabemos quién descarga los PDFs hoy" | No hay dueño operativo | Bloqueador para Fase 0 — necesitas dueño |
|
||||
| "No podemos compartir PDFs reales todavía" | Supuesto #1 en riesgo | Posponer fecha de arranque hasta tenerlos |
|
||||
| "Azure la administra otro proveedor" | Latencia + permisos | Pedir sponsor interno antes de Fase 0 |
|
||||
| "Tenemos que consultar con legal sobre enviar datos a Claude API" | Supuesto #11 en riesgo | Plan B: extracción local (Tesseract + reglas) — replantear costos |
|
||||
| "No tenemos RFC todavía / lo está tramitando la contadora" | Stripe MX no opera | Bloqueador para Fase 2 — Conekta Plan B inmediato |
|
||||
| "IBC solo lo veo cuando entro al portal y le doy print" | El peor caso | Confirma `.QBO` antes de aceptar este peor caso |
|
||||
| "Ya intentamos esto antes con otro proveedor" | Hay historia | Pregunta qué pasó — lecciones gratis |
|
||||
|
||||
---
|
||||
|
||||
## 4. Banderas verdes (señales de que el proyecto va a fluir)
|
||||
|
||||
| Si escuchas... | Significa |
|
||||
|---|---|
|
||||
| "El admin de BIND es Juanito y le digo que te ayude esta semana" | Dueño técnico claro |
|
||||
| "Aquí tienes mi API Key de BIND, úsala" | Velocidad máxima en Fase 0/1 |
|
||||
| "Tenemos sandbox de BIND" | Reduce 50% el riesgo de Fase 1 |
|
||||
| "IBC sí permite descargar `.QBO`" | Fase 3 se simplifica 30-40% |
|
||||
| "Stripe ya está creada y verificada" | Fase 2 sin bloqueador |
|
||||
| "El gerente admin se llama X y está disponible miércoles y viernes" | Cadencia de validación realista |
|
||||
| "Hay un Slack/Teams con el equipo que te van a meter" | Comunicación async funcionando |
|
||||
|
||||
---
|
||||
|
||||
## 5. Demostraciones de preparación (cosas que dices para mostrar que sí investigaste)
|
||||
|
||||
Úsalas cuando aplique. **No las metas todas a fuerza** — son munición, no checklist.
|
||||
|
||||
- *"Vi que BIND tiene un portal en `developers.bind.com.mx` con auth Bearer y rate limit de 20K req/día. ¿Ya tienen API Key o lo sacamos juntos esta semana?"*
|
||||
- *"Belvo cubre BBVA, Banorte, Santander, Citibanamex, HSBC y Scotiabank en MX. ¿Cuáles son los 2 que ustedes usan? Si están en la lista, hay plan B para Fase 2."*
|
||||
- *"IBC ofrece export a Quicken/QuickBooks en `.QBO`. Si me confirmas que sí está disponible para su cuenta business, **eliminamos el mayor riesgo del MVP** — ya no dependemos de OCR sobre PDF para Texas."*
|
||||
- *"Stripe MX típicamente aprueba en 1-2 días si los datos están limpios. Conekta es el Plan B si hay algún tema con RFC/CLABE."*
|
||||
|
||||
> **Cuidado:** decir demasiado puede sonar a "ya tengo todo resuelto" → puede bajarles la urgencia de mandarte artefactos. Equilibrar.
|
||||
|
||||
---
|
||||
|
||||
## 6. Lo que NO conviene hacer (recordatorios)
|
||||
|
||||
- **No prometer fechas exactas** antes de ver el export real de BIND y los PDFs.
|
||||
- **No entrar en debate de stack** (Next.js vs. otra cosa) — eso es decisión tuya.
|
||||
- **No discutir tarifa** — está en la propuesta. Si lo abren, respondes corto y rediriges.
|
||||
- **No aceptar scope creep** ("¿también podrías hacer X?") → *"Lo agendamos para Fase 2."*
|
||||
- **No dar opinión técnica fuerte** sobre cómo operan hoy — vienes a entender, no a juzgar.
|
||||
|
||||
---
|
||||
|
||||
## 7. Lo que pides cerrar antes de colgar (entregables de la llamada)
|
||||
|
||||
Estas son las **5 promesas concretas** que necesitas salir con ellas en mano (idealmente con dueño y fecha):
|
||||
|
||||
1. **Compromiso de envío en 5-7 días hábiles:**
|
||||
- [ ] 1 export real anonimizado de BIND (facturas + clientes), o acceso vía API Key
|
||||
- [ ] 1 PDF de estado de cuenta por cada uno de los 3 bancos (3 archivos) — preferentemente últimos 3 meses
|
||||
- [ ] **Si aplica:** 1 archivo `.QBO` de IBC Texas para validar formato
|
||||
- [ ] Lista de clientes en lista blanca (ACUNTIA + Top 3 con nombre exacto)
|
||||
2. **Acceso o creación de subscripción Azure** con un sponsor identificado.
|
||||
3. **Borrador de NDA** (si aplica) + posición sobre el uso de Claude API.
|
||||
4. **Cadencia confirmada**: 2-3 standups async/semana + demo viernes + sesión técnica quincenal.
|
||||
5. **Próxima sesión técnica agendada** (idealmente día 1 de Fase 0) **con el contacto técnico día a día designado**.
|
||||
|
||||
---
|
||||
|
||||
## 8. Cosas a hacer YO antes de la llamada (mañana antes de entrar)
|
||||
|
||||
- [ ] Revisar la propuesta firmada (00 - PROPUESTA-COMERCIAL.md) para tener los 11 supuestos frescos.
|
||||
- [ ] Tener `03 - GUIA-STAKEHOLDERS.md` abierto en otra pestaña por si necesito profundizar una pregunta.
|
||||
- [ ] Tener este documento abierto en otra pestaña.
|
||||
- [ ] Crear un Postman collection mínimo apuntando a `developers.bind.com.mx` para mostrarlo en pantalla si la conversación lo amerita. (Opcional, pero impresiona.)
|
||||
- [ ] Confirmar el link de la videollamada y prueba audio/cámara 10 min antes.
|
||||
- [ ] Tener una hoja en blanco a mano para anotar nombres, fechas, números.
|
||||
|
||||
---
|
||||
|
||||
## 9. Post-llamada (mismo día, antes de dormir)
|
||||
|
||||
- [ ] Mandar correo de **resumen + compromisos** al CTO en menos de 4 horas — formato: 5 bullets de lo que acordamos + 5 bullets de lo que cada uno entrega y para cuándo.
|
||||
- [ ] Actualizar `00 - PROPUESTA-COMERCIAL.md` con cualquier supuesto que haya cambiado.
|
||||
- [ ] Si cambian supuestos críticos (BIND con API rica, IBC con `.QBO`, política contra Claude API, etc.), abrir `02 - PLAN-EJECUCION.md` y ajustar Fase 0/1/3 según corresponda.
|
||||
- [ ] Anotar en una sección de "riesgos abiertos" del proyecto las banderas rojas que escuchaste.
|
||||
|
||||
---
|
||||
|
||||
## Apéndice · Fuentes investigadas
|
||||
|
||||
- BIND ERP API: [Ayuda BIND](https://ayuda.bind.com.mx/hc/es/articles/360007437754-api-de-bind-erp) · [Portal Devs](https://developers.bind.com.mx/) · [API Tracker](https://apitracker.io/a/bind-erp)
|
||||
- BUK: [buk.mx](https://www.buk.mx/) · [Plataforma RRHH](https://www.buk.co/productos/plataforma-de-rrhh)
|
||||
- IBC Bank: [Online Banking Services](https://www.ibc.com/online-banking/online-banking-services) · [Business Banking](https://www.ibc.com/business/treasury-management/online-business-banking)
|
||||
- Belvo: [Direct Debit Institutions MX](https://developers.belvo.com/products/payments_mexico/direct-debit-institutions) · [Banking Product](https://belvo.com/products/banking/)
|
||||
- Plaid: [Institutions Coverage](https://plaid.com/docs/institutions/)
|
||||
- Stripe MX: [Required Info](https://support.stripe.com/questions/required-information-to-open-your-stripe-account-in-mexico) · [Pricing](https://stripe.com/pricing) · [Comparativa MX 2026](https://atempora.studio/blog/stripe-vs-mercado-pago-vs-conekta)
|
||||
@@ -0,0 +1,223 @@
|
||||
# Checklist · Preguntas para CTO (19 mayo 2026)
|
||||
|
||||
> Lista en orden. Cada pregunta tiene un espacio para anotar la respuesta. Después de la llamada, regreso a la conversación con Claude y pego las respuestas para que actualicemos la propuesta.
|
||||
>
|
||||
> Tiempo objetivo: 60-75 min. Si solo dan 30, llegar hasta la pregunta 14 (Bloque 1 completo).
|
||||
|
||||
---
|
||||
|
||||
## Bloque 0 · Apertura (min 0-5)
|
||||
|
||||
**Encuadre que digo yo, no pregunta:**
|
||||
> "El objetivo de hoy es validar contigo, sistema por sistema, que los supuestos de la propuesta se sostienen. Cada minuto aquí me ahorra 10 minutos en semana 2. Voy a tomar nota — ¿te parece?"
|
||||
|
||||
---
|
||||
|
||||
## Bloque 1 · Sistemas y datos (min 5-30, núcleo de la llamada)
|
||||
|
||||
### BIND ERP (min 5-15)
|
||||
|
||||
**1.** ¿Han usado la **API de BIND** antes, o solo el export manual? ¿Tienen ya un API Key activo?
|
||||
> _Respuesta:_
|
||||
|
||||
**2.** ¿Saben si BIND expone **webhooks** (factura creada / pagada / cancelada)?
|
||||
> _Respuesta:_
|
||||
|
||||
**3.** ¿BIND tiene endpoint para **registrar pagos** y para **subir asientos contables**? Si sí, ¿quieren que el MVP escriba directo o nos quedamos en export Excel para el contador?
|
||||
> _Respuesta:_
|
||||
|
||||
**4.** ¿BIND ofrece **sandbox**, o solo producción?
|
||||
> _Respuesta:_
|
||||
|
||||
**5.** ¿El **timbrado CFDI 4.0** está expuesto vía API o sigue siendo solo botón en la UI?
|
||||
> _Respuesta:_
|
||||
|
||||
**6.** ¿Cómo exportan **hoy** facturas y catálogo de clientes? ¿Formato (CSV, Excel, XML SAT)? ¿Frecuencia?
|
||||
> _Respuesta:_
|
||||
|
||||
**7.** ¿Pueden mandarme un **export real anonimizado** de BIND en los próximos 5-7 días?
|
||||
> _Respuesta:_
|
||||
|
||||
**8.** ¿Quién es el **admin de BIND** internamente? ¿Tiene tiempo para apoyar dudas técnicas durante el MVP?
|
||||
> _Respuesta:_
|
||||
|
||||
**9.** ¿BIND timbra las facturas (CFDI 4.0) **sin costo adicional** según el volumen actual? ¿Cubrirá el crecimiento esperado?
|
||||
> _Respuesta:_
|
||||
|
||||
---
|
||||
|
||||
### Bancos — los 2 MX (min 15-20)
|
||||
|
||||
**10.** ¿**Cuáles 2 bancos MX exactamente**? (BBVA, Banorte, Banamex, Santander, HSBC, Scotiabank…)
|
||||
> _Respuesta:_
|
||||
|
||||
**11.** ¿Tienen **PDFs históricos (últimos 3-6 meses)** de los 2 bancos MX que puedan enviarme la próxima semana?
|
||||
> _Respuesta:_
|
||||
|
||||
**12.** ¿Hay traspasos internos frecuentes entre las 3 cuentas? ¿Cuál es el patrón?
|
||||
> _Respuesta:_
|
||||
|
||||
---
|
||||
|
||||
### Banco — IBC Texas (min 20-25) ⚡ CRÍTICO
|
||||
|
||||
**13.** ⚡ ¿Hoy descargan el estado de cuenta IBC en **PDF, o también en formato `.QBO`/Quicken**?
|
||||
> _Respuesta:_
|
||||
|
||||
**14.** ¿IBC ofrece **"Direct Connect" para QuickBooks** (vía OFX server) o solo "Web Connect" (descarga manual del archivo)?
|
||||
> _Respuesta:_
|
||||
|
||||
**15.** ¿Tienen apertura a evaluar un agregador (Belvo MX, Plaid US para IBC) en Fase 2, o hay política contra compartir credenciales con terceros?
|
||||
> _Respuesta:_
|
||||
|
||||
**16.** ¿Quién descarga **hoy** los estados de cuenta? ¿Con qué frecuencia? ¿Lo seguirá haciendo durante el MVP?
|
||||
> _Respuesta:_
|
||||
|
||||
---
|
||||
|
||||
### BUK + Jira (min 25-28, no profundizar — son Fase 2)
|
||||
|
||||
**17.** ¿Quién administra BUK internamente? ¿Tienen credenciales API o hay que solicitarlas?
|
||||
> _Respuesta:_
|
||||
|
||||
**18.** ¿Qué evento en BUK marcaría **"nómina aprobada lista para facturar al cliente"**? (¿Existe ese trigger?)
|
||||
> _Respuesta:_
|
||||
|
||||
**19.** ¿Jira es **Cloud o Server**? ¿Hay registro de horas por colaborador-cliente hoy en Jira?
|
||||
> _Respuesta:_
|
||||
|
||||
---
|
||||
|
||||
### Stripe (min 28-30)
|
||||
|
||||
**20.** ¿Ya tienen cuenta Stripe MX verificada, o hay que crearla? ¿RFC + CLABE + representante legal con CURP están listos?
|
||||
> _Respuesta:_
|
||||
|
||||
**21.** Si Stripe MX rechaza o tarda más de 2 semanas, ¿hay apertura a **Conekta** como Plan B?
|
||||
> _Respuesta:_
|
||||
|
||||
---
|
||||
|
||||
## Bloque 2 · Infraestructura, compliance, seguridad (min 30-45)
|
||||
|
||||
**22.** ¿Tienen subscripción **Azure** activa? ¿Quién la administra? ¿Centro de costos asignado?
|
||||
> _Respuesta:_
|
||||
|
||||
**23.** ¿Preferencia de **región Azure** (mexicocentral, southcentralus, eastus)?
|
||||
> _Respuesta:_
|
||||
|
||||
**24.** ¿Cómo manejan **secretos** hoy? (Key Vault, .env, 1Password, ninguno)
|
||||
> _Respuesta:_
|
||||
|
||||
**25.** ¿Hay **política interna** que choque con enviar PDFs bancarios a Claude API (Anthropic, sin entrenamiento)?
|
||||
> _Respuesta:_
|
||||
|
||||
**26.** ¿**NDA** — usan el suyo o el mío?
|
||||
> _Respuesta:_
|
||||
|
||||
**27.** ¿Quién recibe el **handoff técnico** al final del MVP? ¿Hay DevOps interno o lo opera otra persona?
|
||||
> _Respuesta:_
|
||||
|
||||
---
|
||||
|
||||
## Bloque 3 · Realidad operativa (min 45-55)
|
||||
|
||||
**28.** De las ~50 facturas/mes: ¿distribución? (¿2-3 grandes y 47 chicas, o uniforme?)
|
||||
> _Respuesta:_
|
||||
|
||||
**29.** ¿Cuántos **clientes activos** hay hoy? ¿Cuántos están "siempre en cobranza"?
|
||||
> _Respuesta:_
|
||||
|
||||
**30.** ¿Cuánto tiempo toma conciliar **hoy** los 3 estados de cuenta del mes? ¿Quién lo hace?
|
||||
> _Respuesta:_
|
||||
|
||||
**31.** ¿Qué % de facturas requiere **re-trabajo por error contable** hoy?
|
||||
> _Respuesta:_
|
||||
|
||||
**32.** **Pagos parciales**: ¿qué tan frecuentes? ¿Cómo los registran hoy?
|
||||
> _Respuesta:_
|
||||
|
||||
---
|
||||
|
||||
### Reglas de negocio no escritas
|
||||
|
||||
**33.** **Lista blanca: ¿quiénes son los Top 3 exactos** además de ACUNTIA? ¿Hay clientes "grises"?
|
||||
> _Respuesta:_
|
||||
|
||||
**34.** ¿Hay clientes con **condiciones de pago no-estándar** (90 días, retenciones, factoring)?
|
||||
> _Respuesta:_
|
||||
|
||||
**35.** ¿Cuál es el **ciclo de cobranza actual**? (1er recordatorio a los X días, 2do a los Y, escalación humana cuándo)
|
||||
> _Respuesta:_
|
||||
|
||||
**36.** ¿Qué hacen hoy cuando entra un **pago no identificado**?
|
||||
> _Respuesta:_
|
||||
|
||||
---
|
||||
|
||||
## Bloque 4 · Personas, proceso, riesgo (min 55-65)
|
||||
|
||||
**37.** ¿Quién es el **contacto técnico día a día** durante el MVP? ¿Tú directamente o alguien de tu equipo?
|
||||
> _Respuesta:_
|
||||
|
||||
**38.** ¿Quién es el **gerente administrativo** que validará reglas de cobranza/conciliación? ¿SLA de respuesta esperado?
|
||||
> _Respuesta:_
|
||||
|
||||
**39.** ¿Ya intentaron este proyecto antes (internamente o con otro proveedor)? ¿Qué pasó?
|
||||
> _Respuesta:_
|
||||
|
||||
**40.** Si tuviéramos que cortar alcance en semana 5 por un imprevisto, ¿qué **sacrificas primero** entre cobranza, conciliación y dashboard?
|
||||
> _Respuesta:_
|
||||
|
||||
**41.** ¿Hay cambios fiscales conocidos en pipeline (SAT, Texas) en los próximos 6 meses?
|
||||
> _Respuesta:_
|
||||
|
||||
---
|
||||
|
||||
## Bloque 5 · Pregunta-trampa final (min 65-68)
|
||||
|
||||
**42.** *"Si dentro de 6 meses esta plataforma está funcionando exactamente como esperan, ¿qué métrica concreta tendría que estar moviéndose para que sintieras que valió la pena?"*
|
||||
> _Respuesta:_
|
||||
|
||||
---
|
||||
|
||||
## Cierre · Compromisos que necesito salir con ellos (min 68-75)
|
||||
|
||||
Antes de colgar, **confirmar los 5 entregables**. No salgo sin esto:
|
||||
|
||||
**C1.** ¿Cuándo me envían el **export real anonimizado de BIND** (facturas + clientes), o me dan acceso API?
|
||||
> _Compromiso (fecha + dueño):_
|
||||
|
||||
**C2.** ¿Cuándo me envían **1 PDF por banco** (3 archivos)? ¿Y un **`.QBO` de IBC** si aplica?
|
||||
> _Compromiso (fecha + dueño):_
|
||||
|
||||
**C3.** ¿Cuándo me dan **acceso o creación de subscripción Azure** con sponsor identificado?
|
||||
> _Compromiso (fecha + dueño):_
|
||||
|
||||
**C4.** ¿Cuándo me llega el **borrador de NDA** + posición sobre Claude API?
|
||||
> _Compromiso (fecha + dueño):_
|
||||
|
||||
**C5.** ¿Cuándo es la **próxima sesión técnica** (idealmente día 1 de Fase 0) y con quién?
|
||||
> _Compromiso (fecha + dueño):_
|
||||
|
||||
**C6.** **Lista blanca**: ¿cuándo me mandan ACUNTIA + Top 3 con nombre legal + aliases bancarios?
|
||||
> _Compromiso (fecha + dueño):_
|
||||
|
||||
**C7.** **Cadencia**: ¿confirmamos 2-3 standups async/semana + demo viernes + sesión técnica quincenal?
|
||||
> _Compromiso (fecha + dueño):_
|
||||
|
||||
---
|
||||
|
||||
## Notas adicionales (cualquier cosa que surja)
|
||||
|
||||
> _Anota aquí cosas que no encajan en las preguntas pero importan: nombres mencionados, sistemas adicionales, sentimientos del CTO sobre alcance, etc._
|
||||
|
||||
---
|
||||
|
||||
## Post-llamada — lo que mando de regreso a Claude
|
||||
|
||||
1. Las respuestas de las 42 preguntas + 7 compromisos
|
||||
2. Cualquier sorpresa o señal que percibí (banderas rojas/verdes)
|
||||
3. Mi nivel de confianza con el proyecto (1-10) después de la llamada
|
||||
|
||||
Con eso actualizamos `00 - PROPUESTA-COMERCIAL.md` y `02 - PLAN-EJECUCION.md` para reflejar la realidad.
|
||||
Binary file not shown.
@@ -0,0 +1,306 @@
|
||||
**Product Requirements Document**
|
||||
|
||||
**Plataforma de Automatización Financiera**
|
||||
|
||||
**1\. Resumen Ejecutivo**
|
||||
|
||||
Desarrollar una aplicación centralizada para automatizar procesos administrativos y financieros clave de una empresa de headhunting y staff augmentation con operaciones internacionales.
|
||||
|
||||
El sistema busca eliminar procesos manuales y desconectados en:
|
||||
|
||||
* Generación de cotización a través del ERP para posterior convertirla en facturación
|
||||
* Cobranza
|
||||
* Conciliación Bancaria (detectar gastos fuera de patrón, duplicados errores contables e incluir reportes de cuentas por cobrar y cuentas por pagar, diarios, semanales).
|
||||
|
||||
El objetivo es reducir errores operativos, costos y retrabajo, así como habilitar escalabilidad y eventual comercialización como producto.
|
||||
|
||||
**2\. Objetivos del Producto**
|
||||
|
||||
**2.1 Objetivo General**
|
||||
|
||||
Automatizar e integrar los procesos financieros críticos en una plataforma única con trazabilidad completa.
|
||||
|
||||
**2.2 Objetivos Específicos**
|
||||
|
||||
* Reducir errores humanos en procesos contables
|
||||
* Eliminar conciliaciones manuales
|
||||
* Integrar facturación, cobranza y contabilidad (se cuentan con 3 bancos diferentes uno de ellos americano)
|
||||
* Generar reportes y alertas automáticas (5 días antes de vencimiento de la factura)
|
||||
* Mejorar visibilidad operativa en tiempo real
|
||||
* Preparar la solución para escalabilidad y venta futura
|
||||
|
||||
**3\. Alcance del producto mínimo viable (MVP)**
|
||||
|
||||
Duración estimada: 4 a 6 semanas
|
||||
|
||||
|
||||
|
||||
**3.1 Funcionalidades Incluidas**
|
||||
|
||||
**Facturación**
|
||||
|
||||
* Generación automatizada de facturas
|
||||
* Integración con clientes internacionales (cuando son clientes extranjeros se factura en USD sin IVA) multimoneda
|
||||
* Descarga automática de facturas (que se entregue un reporte automático)
|
||||
|
||||
**Cobranza**
|
||||
|
||||
* Registro automático de pagos
|
||||
* Identificación de pagos por cliente
|
||||
* Seguimiento de cuentas por cobrar (un template de correo para que sea el canal de cobranza y que cuente con las reglas para ACUNTIA y top 3 de clientes NUNCA reciban recordatorios automáticos masivos, gestión humana solamente, para evitar el riesgo de dañar la relación con el cliente)
|
||||
|
||||
**Conciliación Bancaria**
|
||||
|
||||
* Conciliación automática de pagos vs facturas
|
||||
* Integración con estados de cuenta
|
||||
* Identificación de discrepancias
|
||||
|
||||
**Contabilidad**
|
||||
|
||||
* Generación automática de asientos contables (ERP BIND)
|
||||
* Integración básica con sistema contable existente
|
||||
|
||||
**Reportes y Alertas**
|
||||
|
||||
* Dashboard de estado financiero
|
||||
* Alertas automáticas:
|
||||
|
||||
* Pagos pendientes
|
||||
* Errores en conciliación
|
||||
* Facturas no cobradas
|
||||
|
||||
**4\. Problemas Identificados**
|
||||
|
||||
* Procesos desconectados entre sistemas
|
||||
* Conciliación bancaria manual
|
||||
* Errores recurrentes en registros contables
|
||||
* Retrabajo operativo costoso
|
||||
* Falta de visibilidad en tiempo real
|
||||
* Baja escalabilidad de procesos actuales
|
||||
* Uso de tickets físicos en pagos con tarjeta
|
||||
|
||||
**5\. Usuarios del Sistema**
|
||||
|
||||
**Rol**
|
||||
|
||||
**Necesidades**
|
||||
|
||||
Finanzas
|
||||
|
||||
Automatización, precisión, conciliación
|
||||
|
||||
Dirección
|
||||
|
||||
Reportes, visibilidad, control
|
||||
|
||||
Operaciones
|
||||
|
||||
Integración con procesos existentes
|
||||
|
||||
RRHH
|
||||
|
||||
Integración con nómina y contratos
|
||||
|
||||
|
||||
|
||||
**6\. Requerimientos Funcionales**
|
||||
|
||||
**6.1 Gestión de Facturación**
|
||||
|
||||
* RF-01: Generar facturas automáticamente desde eventos de negocio
|
||||
* RF-02: Soporte multimoneda (USD, EUR, MXN)
|
||||
* RF-03: Integración con sistemas existentes (ej. BUK donde se consolidan pagos de nómina)
|
||||
|
||||
**6.2 Gestión de Cobranza**
|
||||
|
||||
* RF-04: Registrar pagos automáticamente desde fuentes bancarias
|
||||
* RF-05: Asociar pagos a facturas
|
||||
* RF-06: Identificar pagos parciales y completos
|
||||
|
||||
**6.3 Conciliación Bancaria**
|
||||
|
||||
* RF-07: Conciliar automáticamente transacciones bancarias
|
||||
* RF-08: Detectar discrepancias
|
||||
* RF-09: Generar reportes de conciliación
|
||||
|
||||
**6.4 Contabilidad**
|
||||
|
||||
* RF-10: Generar asientos contables automáticos
|
||||
* RF-11: Integración con sistema contable
|
||||
|
||||
**6.5 Reportes y Alertas**
|
||||
|
||||
* RF-12: Dashboard financiero en tiempo real
|
||||
* RF-13: Alertas automáticas configurables
|
||||
* RF-14: Reportes exportables
|
||||
|
||||
**7\. Requerimientos No Funcionales**
|
||||
|
||||
* RNF-01: Arquitectura modular y escalable
|
||||
* RNF-02: Alta disponibilidad
|
||||
* RNF-03: Seguridad de datos financieros
|
||||
* RNF-04: Cumplimiento fiscal (México y Texas)
|
||||
* RNF-05: Soporte para integración con APIs externas
|
||||
* RNF-06: Trazabilidad completa de operaciones
|
||||
|
||||
**8\. Arquitectura Propuesta (Inicial)**
|
||||
|
||||
**Enfoque**
|
||||
|
||||
* Aplicación web centralizada
|
||||
|
||||
**Componentes**
|
||||
|
||||
* Backend (API)
|
||||
* Frontend (Dashboard)
|
||||
* Motor de automatización (reglas + IA)
|
||||
* Integraciones externas (bancos, facturación, contabilidad)
|
||||
|
||||
**IA / Agentes**
|
||||
|
||||
* Uso opcional para:
|
||||
|
||||
* Clasificación de transacciones
|
||||
* Detección de anomalías
|
||||
* Automatización de procesos
|
||||
|
||||
**Estrategia de Infraestructura**
|
||||
|
||||
* Evaluar después del MVP:
|
||||
|
||||
* Nube (OpenAI, Gemini, Anthropic)
|
||||
* Modelos locales (ARM / open source)
|
||||
|
||||
**9\. Costos Estimados**
|
||||
|
||||
* Infraestructura inicial: **$200 – $500 USD / mes**
|
||||
* Escalable según uso de IA y volumen de transacciones
|
||||
|
||||
**10\. Supuestos**
|
||||
|
||||
* Disponibilidad de APIs bancarias o archivos exportables
|
||||
* Acceso a sistemas actuales (Book, Jira, contabilidad)
|
||||
* Definición clara de reglas contables
|
||||
* Colaboración del equipo interno
|
||||
|
||||
**11\. Riesgos**
|
||||
|
||||
**Riesgo**
|
||||
|
||||
**Mitigación**
|
||||
|
||||
Integraciones complejas
|
||||
|
||||
Fase de discovery técnica
|
||||
|
||||
Costos de IA crecientes
|
||||
|
||||
Evaluación post-MVP
|
||||
|
||||
Datos inconsistentes
|
||||
|
||||
Validación y limpieza inicial
|
||||
|
||||
Cambio organizacional
|
||||
|
||||
Capacitación y adopción
|
||||
|
||||
|
||||
|
||||
**12\. Roadmap del MVP**
|
||||
|
||||
**Fase 1 – Levantamiento (Semana 1)**
|
||||
|
||||
* Requerimientos detallados
|
||||
* Casos de uso
|
||||
|
||||
**Fase 2 – Desarrollo Base (Semanas 2-4)**
|
||||
|
||||
* Facturación + Cobranza
|
||||
* Integraciones iniciales
|
||||
|
||||
**Fase 3 – Automatización (Semana 5)**
|
||||
|
||||
* Conciliación automática
|
||||
* Asientos contables
|
||||
|
||||
**Fase 4 – Validación (Semana 6)**
|
||||
|
||||
* Pruebas
|
||||
* Ajustes
|
||||
* Entregas parciales
|
||||
|
||||
**5\. Entregables**
|
||||
|
||||
* MVP funcional
|
||||
* Documentación técnica
|
||||
* Manual de usuario básico
|
||||
* Métricas de uso y consumo
|
||||
|
||||
**13\. Criterios de Éxito**
|
||||
|
||||
* Reducción de errores manuales ≥ 70%
|
||||
* Disminución del tiempo de conciliación ≥ 60%
|
||||
* Visibilidad en tiempo real operativa
|
||||
* MVP funcional en ≤ 6 semanas
|
||||
|
||||
**Arquitectura técnica detallada**
|
||||
|
||||
**1\. Visión General**
|
||||
|
||||
La solución propuesta es una aplicación web centralizada que conecte los procesos de:
|
||||
|
||||
* Facturación
|
||||
* Cobranza
|
||||
* Conciliación bancaria
|
||||
* Generación de asientos contables
|
||||
* Reporteo y alertas
|
||||
* Automatización con IA/agentes
|
||||
|
||||
El enfoque recomendado para el MVP es una arquitectura modular, inicialmente preparada para evolucionar a microservicios si el volumen lo justifica.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
2\. Diagrama General de Arquitectura
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
U["Usuarios<br/>Finanza/Direccion"] --> F["Frontend Web<br/>Dashboard/Reportes"]
|
||||
F --> A["API Backend<br/>Autenticacion/Logica"]
|
||||
|
||||
A --> FAC["Facturacion<br/>Modulo"]
|
||||
A --> COB["Cobranza<br/>Modulo"]
|
||||
A --> CON["Conciliacion<br/>Modulo"]
|
||||
|
||||
FAC --> DB["Base de datos central (ERP)<br/>Clientes/Facturas/Pagos/Bancos/Conciliaciones"]
|
||||
COB --> DB
|
||||
CON --> DB
|
||||
|
||||
DB --> B["APIs Bancos<br/>CSV/API"]
|
||||
DB --> S["SAT/ERP<br/>Contabilidad"]
|
||||
DB --> IA["Motor IA<br/>Agentes/LLM"]
|
||||
```
|
||||
@@ -0,0 +1,83 @@
|
||||
Solicitud de cotización
|
||||
Tue, May 19, 2026
|
||||
|
||||
0:03 - Pedro Alberto Ayala Elizondo
|
||||
Johann, ¿qué tal?
|
||||
|
||||
0:04 - Noe Rocha
|
||||
Buenos días. Pues listo, Johann. Sabemos que tienes agenda apretada. Si quieres, vamos arrancando en la sesión para ir expandiendo el tema de lo que queremos hacer y de los dudas que pudiste haber tenido. Aquí para esta sesión voy a involucrar a Pedro Ayala. Pedro Ayala ve con nosotros temas de muchos de los procesos a dar cuenta que Pedro hace un levantamiento para después llevarlo a gira dentro de un flujo y un proceso y de lo que compete a este tipo de cosas que vamos a ver contigo, Pedro en la parte técnica va a estar más involucrado porque seguramente va a requerirse accesos, se va a requerir algún tipo de conversación con alguna parte interna, digamos que para la parte del seguimiento del proyecto ESERICA, para la parte técnica contigo como la relación de qué necesitas para seguir avanzando, vas a para irle poniendo orden y cabeza. ¿Sí? Ok. Muy bien.
|
||||
|
||||
1:05 - Unidentified Speaker
|
||||
Listo.
|
||||
|
||||
1:05 - Noe Rocha
|
||||
Pues ahora sí. Platiquemos, Johann. ¿Qué era el tema que querías ir aclarando?
|
||||
|
||||
1:13 - Johann
|
||||
Claro. Me gustaría principalmente platicar acerca de hoy cómo se tienen los datos. Principalmente por cómo se van a extraer para trabajarlos en la plataforma que se pretende construir, ¿cierto? Pues, por ejemplo, me platican que están trabajando con Book, ¿cierto? Combined, y están investigando acerca de APIs, por su parte, o si tienen sandboxes que pudiésemos usar. Y, por ejemplo, revisé que, un momento, aquí lo tengo, que, por ejemplo, Bind, que tiene una API para desarrolladores. Entonces, por ejemplo, me gustaría preguntar, o partir de las asumciones de que pudiésemos usar esas APIs, o me gustaría también entender cómo hoy pudiésemos exportar esos datos para introducirlos o para importarlos dentro de la plataforma.
|
||||
|
||||
2:16 - Noe Rocha
|
||||
Puesto que conseguir esas herramientas dentro de las seis semanas y el contacto con esta plataformas pudiese de pronto extender el periodo entonces me gustaría platicar un poquito del estado de cómo se está ahora en esa parte muy bien pero tú que estuviste más involucrado en el rp la mayor parte de la información hoy por hoy pues es simplemente a través de la web y si hay que bajar o hacer algún tipo de dato pues es extracción directa verdad no no tiene una conectividad como tal cuando yo estuve en esa parte no exploré ninguna API, ninguna creación o algo así.
|
||||
|
||||
2:55 - Unidentified Speaker
|
||||
Simplemente la forma en que yo analizaba la data era mediante exportaciones así, crudas, de archivos planos. Entonces, yo ya los metía a otras herramientas, entonces, pero dentro de ahí pasó una conectividad, no encontraba la opción.
|
||||
|
||||
3:11 - Noe Rocha
|
||||
Ahora, Johann, lo que sí podemos hacer es, digo, ya traemos la intención de acercarnos tanto con Vine para... Si tú ya investigaste algo o te adelantaste con este tema del API, pues nada más es formalizarlo nosotros como cliente. Oye, vamos a hacer un desarrollo y necesitamos saber si tienes un API. Lo mismo para Book. Book, no estoy tan seguro si tiene o no. La verdad es que ha sido un tema problemático últimamente su servicio. Entonces, bueno, vamos a ver si ellos ofrecen algo. Pero en pocas palabras hay un tema muy recurrente aquí que creo que es el foco. Proceso de facturación, que requiere a su vez una conciliación tanto de la entrada de los bancos como la salida de los bancos, que esa es otra variante aquí. Los bancos también son, son, son bancos, manejamos dos bancos distintos, hasta tres bancos, pero creo que los operativos son dos bancos distintos, ¿no? En esta fórmula. BUK, no. BAIN, que es el ERP, como tal no tiene integración con bancos. Entonces eso nos da, nos genera pues un seguimiento en la plataforma con unas cuentas por cobrar, pero finalmente tenemos que ir a revisar si hay una conciliación en el banco. Y luego eso nos lo tenemos que llevar a un tema contable, que también implica que a lo mejor, no sé si venía aquí contigo, pero creo que también va a tener que ponerse más adelante en este tema. No le queremos estar poniendo estrellitas al pino, nada más estrictamente lo que se necesita. Pero hay una parte muy importante también de que uno de los bancos tenemos tarjetas corporativas y es un rollo el tema de las comprobaciones. Bueno, pero un punto de aparte de eso, lo más relevante ahorita es este tema de facturación. Déjame ver el correo para no estar en un minuto. Erika, ¿Arturo se convocó? No, ¿verdad? Vamos a dar una repasada a las preguntas, porque nosotros si queremos facilitar las cosas que no es un tema muy complejo. Por ejemplo, mencionabas, aquí ya se ve, mencionabas si Vine tiene API habilitada o trabaja por exportación de archivos. Al día de hoy, como no tenemos integración con nada, lo hacemos con exportación de archivos. ¿Tiene API habilitada? No lo he investigado, siéntate sincero, pero es algo trabajar con ellos. Si lo tiene, pues ya sería ver cómo lo ponemos en la mesa para que sea algo más sencillo. Si no lo tienen, el tema es que la única forma de extraer los datos es mediante eso. O, pues también creo que sí pueden desarrollar ellos los APIs. ¿Nos costaría? Sí, pero tendría que ser muy puntual la solicitud. ¿Sí? Entiendo. ¿Bugis pone APIs? También. Desconozco, no he tenido la oportunidad de tener esta reunión desde aquí. De hecho aquí, Pedro, sí te pediría que me ayudes a acelerar el paso con este tema de ir a buscar con Elsie o con Pau o con Arturo. Una sesión con el soporte de cada uno para disparar este tema, porque yo entiendo, Johann, que si no tienes las APIs lo vuelve más complejo, entonces es más sencillo tener una integración para poder juntar la información a través de estas APIs. Y bueno, de los tres bancos, estabas de cuenta, bueno, hasta el momento PDFs, misma situación, no sé si frescan APIs, Y se mencionan... Creo que era Intercam. ¿Cuál era el otro banco? Panorte. Panorte sí ofrece hasta donde yo sé. Sí tiene integraciones, pero creo que ellos sí la ponen más estrictas. Sí. El Banco Americano... El BC Bank, sí. ¿Dónde lo puso? Ah, no lo contestó sobre este correo, sí. Sí, creo que sí lo contestó, Ara. Déjeme ver. Sí, sí lo contestó Inge. Viene ahí mismo. Déjeme... Ah, lo complementó acá. Sí, lo complementó. Sí, es IBC Bank en Texas. Y ahorita solamente tiene vía web, porque es una cuenta básica, ¿no? La que tiene. ¿Pueden dar acceso a sandbox o box? Mismo tema. Que ahorita solamente tenemos producción y seguramente si fuera el caso nos lo cotizarían. No creo que nos lo den. Entonces sería un tema cotizar. Como son soluciones SAS, pues sí, a lo mejor aquí sería un tema de cotizarlo y ver cuánto nos salva. ¿Qué tan necesario lo consideras que es el sandbox?
|
||||
|
||||
8:50 - Johann
|
||||
¿Solamente de pruebas? Pudiésemos o para hacer pruebas de pronto hacer pruebas muy pequeñas en el sentido para no afectar tanto a producción de pronto pudiésemos encontrar otra solución nada más sería déjame pasarlo de mi lado y ver cómo pudiésemos encontrar una alternativa de en donde el ambiente sandbox no sea factible.
|
||||
|
||||
9:21 - Noe Rocha
|
||||
Sí, este sí. Pues sí tendríamos que hablarlo con ellos, porque lo más seguro es que si nos dicen que sí, nos lo van a cobrar. Y pues bueno, vamos a ver cuánto nos cuesta. Bueno, la cuenta PAC de contrato para Timberlade está integrada dentro del mismo Eso es correcto. La facturación en clientes en Texas es Taxas estándar. Bueno, al menos así lo confirma Araceli. Soporte de euro, facturación. Sí, ahorita solamente sería puro dólar para no hacerlo tan tan complejo porque realmente incluso nuestro proveedor europeo nos pagan en dólar no nos ha pagado en euro y al menos la negociación ha sido así pero pero pues no sabemos si llegue a cambiar las reglas pero ahorita para no hacerlo tan complejo vamos a dejarlo en USD y bueno creo que eso es lo más relevante no sé tú qué opinas Johann que crees que facilita necesitaría para ti esto, las APIs y los sandbox, verdad?
|
||||
|
||||
10:44 - Johann
|
||||
Sí, incluso la parte de APIs, ahora que me comentan que manejan la información a través de exportación de archivos, me facilitaría poder conocer el formato que se tienen esos archivos, porque por ejemplo, algo en lo que me importaba conocer, o lo que podría ser un en un futuro, o en las primeras etapas, es que los datos no tuviesen todos un mismo formato.
|
||||
|
||||
11:14 - Unidentified Speaker
|
||||
Y agregar como...
|
||||
|
||||
11:15 - Johann
|
||||
Sí. Entonces, lo que se tendría que hacer ahí sería centralizar los dos en un mismo... Con una misma estructura, sí. Entonces, si me comentan que, por ejemplo, todos los datos de facturación tienen una misma estructura, entonces de pronto podemos manejarlo desde ahí. Y para mí va a ser más fácil que esa parte de datos esté un poquito más centralizada, para que, por ejemplo, dentro de las primeras etapas, el tiempo de ir recopilando, por así decirlo, de dónde vamos a extraer todos los datos, no sea tan largo, sino que ya esté como centralizado, por así decirlo, o no centralizado, pero que me pudiesen facilitar de aquí vas a sacar los datos que vas a necesitar para el proceso de facturación. Por ejemplo, y de aquí para el otro paso. Entonces eso era mi intención con acercarme a ti y preguntar cómo se tienen los datos actualmente y de dónde los vamos a extraer para ingresarlos o ingestarlos a la aplicación.
|
||||
|
||||
12:23 - Unidentified Speaker
|
||||
Ya, muy bien.
|
||||
|
||||
12:24 - Noe Rocha
|
||||
Mira, creo que definitivamente estar manejando documentos con formatos diferentes no es lo más práctico. Y directamente del sistema sería lo más sencillo para todos, para ti, para nosotros, y para que un sistema esté muy bien integrado. Entonces, nos vamos a ir a buscar la gente de Book. Vamos a pedir, oye, yo quiero esto. Estoy desarrollando un tema que voy a extraer de tu solución, porque lo tuve que integrar. ¿Tienes API? ¿Tienes AMPUX? ¿No lo tienes? ¿Cuánto me cuesta? Y entonces ya con eso podemos volver más claramente contigo porque si hoy me dices hoy tengo una estructura de datos ya de dónde está la información pues probablemente sí es una exportación directa del portal. ¿Tú alcanzaste a ver esa parte de facturación con el CIENZO en su momento, Pedro?
|
||||
|
||||
13:18 - Unidentified Speaker
|
||||
De esa parte creo que no.
|
||||
|
||||
13:20 - Noe Rocha
|
||||
No, ¿verdad? ¿Solamente con ella? Sí. Bueno, mira, la más rápida para mí, la opción A, es directamente irnos La opción B, voy a checar la estructura de datos como viene, pero creo que para que esto sea funcional, va a ser un API. Entonces voy con los de Book, voy con los de Vine, vuelvo contigo para no tardarnos mucho. Yo creo que con esto, ¿qué más necesitarías tú como para poder estimar este esfuerzo en tiempo? ¿API, Sandbox, qué más?
|
||||
|
||||
13:54 - Johann
|
||||
Sí, creo que eso es lo lo que necesitaba para, principalmente, el esfuerzo y el tiempo que esto tomaría.
|
||||
|
||||
14:03 - Noe Rocha
|
||||
Ya, ok. API y Sandbox, ok. Entonces, voy, vuelvo.
|
||||
|
||||
14:07 - Noe Rocha
|
||||
¿No hay algo más aquí que haya quedado alguna duda?
|
||||
|
||||
14:12 - Noe Rocha
|
||||
No, ¿verdad? Creo que era todo. Sí. No, por esa parte no. Ok. Sí. Entonces, programamos esas llamadas. Vuelvo contigo, Johann. Y ya te respondo, te he hecho una llamada muy rápida. Y mira, sí, sí, lo tenemos así.
|
||||
|
||||
14:29 - Johann
|
||||
Y yo creo que ya con eso cerramos para esta misma semana tener avance.
|
||||
|
||||
14:34 - Noe Rocha
|
||||
Ok, me parece. Me parece muy bien. Órale.
|
||||
|
||||
14:36 - Johann
|
||||
Bueno, pues te agradezco el tiempo, Johann.
|
||||
|
||||
14:38 - Noe Rocha
|
||||
Muchas gracias a ustedes también.
|
||||
|
||||
14:40 - Johann
|
||||
Gracias. Gracias. Agradezco su tiempo mañana.
|
||||
|
||||
14:42 - Unidentified Speaker
|
||||
Hasta luego. No hay.
|
||||
Binary file not shown.
Reference in New Issue
Block a user