balam/README.md

Proyecto Balam — Plataforma de Automatización Financiera

Fuente de la verdad del proyecto. Este repositorio concentra todo: propuesta, comunicaciones, fuentes y prototipos. Si pasa algo (llamada, correo, mensaje, decisión), se registra en la bitácora. Empieza por aquí.

Estado: 🟢 En arranque — contrato firmado (26-jun), kickoff con Noé el 1-jul (7am), plan de actividades (4 etapas) entregado. Falta que Balam entregue los accesos para iniciar el Discovery (sem del 6-jul). Última actualización: 2026-06-30.

---

1. Qué es

Plataforma web para centralizar y automatizar facturación y cobranza de Balam sobre BIND ERP. MVP enfocado en facturación (consulta + emisión asistida MXN/USD), cobranza operativa, dashboard, reportes y trazabilidad. Conciliación bancaria, pagos en línea, BUK e IA quedan para fases posteriores.

2. Estructura del repo

Carpeta / archivo	Contenido
README.md	Este archivo — estado y datos clave del proyecto.
bitacora/	Registro vivo: REGISTRO.md (cronología de comunicaciones), PENDIENTES.md (acciones abiertas), README.md (cómo registrar + plantillas).
propuesta/	Propuesta (MD) — contenido fuente v1.1. PDF enviado. PDF regenerado con el skill + su fuente reproducible (HTML + config, build con el skill proposal-pdf). Prototipo, diagrama Fase 1 vs PRD.
fuentes/	Material crudo: PRD, transcripciones de llamadas, .eml. Evidencia, no se edita.
bind-api-sandbox/	Prototipo técnico del cliente/mock de la API de BIND (TypeScript; el productivo será .NET).
_archivado/	Material superado (propuestas viejas, diagramas previos). Histórico.
.claude/skills/proposal-pdf/	Skill que genera el PDF de la propuesta/cotización con diseño editorial (portada full-bleed, TOC con páginas reales, footers "Confidential"). Pipeline Chromium + 2 pasos. Setup y uso en su SKILL.md (incluye nota de Windows).
planeacion/	Plan de ejecución: Plan-actividades.xlsx (+ .md) — actividades por etapa (0–3) con fechas, responsables y sesiones, para el seguimiento con Erika (Jira/Gantt).

3. Datos clave

Cliente: Balam (gestión de talento · headhunting/staff augmentation). ~45 colaboradores + 5 freelancers, ~50 facturas/mes. Jurisdicciones MX + Texas.

Stakeholders y contactos

Rol	Persona	Función en el proyecto
CTO	Noe Rocha	Decisión técnica, arquitectura, comercial
CEO / Operaciones	Araceli "Ara" Sánchez	Reglas de negocio, validación directiva; cuenta maestra de BIND
Project Manager	Erika Chávez	Contacto principal, valida entregables
Desarrollador / técnico	Pedro Ayala	Contacto técnico día a día, BIND, Jira, tablero Power BI
Negocio / bancos	Arturo	Reglas de negocio + bancos (conciliación)
Recursos Humanos	Paola	Coordinación administrativa; firma del contrato (WhatsApp)
Proveedor	Johann Velazquez	Diseño, desarrollo, integración, entrega

Comunicación: canal de WhatsApp (ágil) + correo para evidencia formal. Gestión de avances en Jira.

4. Alcance y comercial (propuesta v1.1)

• MVP Fase 1: integración BIND vía API · emisión de facturas MXN (con IVA) / USD (sin IVA) con dry-run + confirmación humana (timbra el PAC de BIND) · catálogo de clientes + lista blanca configurable (ACUNTIA + Top 3) · cobranza operativa (aging + alertas internas) · dashboard · reportes CSV/XLSX · bitácora · multimoneda con TC DOF.
• Inversión: $67,200 – $81,600 MXN + IVA · 6–7 semanas (~20 h/sem) · tarifa $600 MXN/h · modelo Time & Materials con tope por etapa (monto final se confirma en Discovery).
• Sin anticipo (política Balam): se factura la Etapa 0 (30 h, $18,000 + IVA) al inicio. Arranque condicionado a contrato firmado.
• Pagos: a 30 días post-factura. Por contrato, facturación semanal (viernes) por horas efectivamente trabajadas (la Etapa 0 puede facturarse al inicio).
• Garantía: 45 días por etapa. Soporte: bolsa de horas a $600/h, vigencia 12 meses (sin caducidad mensual).
• Stack: C#/.NET 10 + Entity Framework Core + Angular 21 + PostgreSQL 17, sobre Azure.
• Diferido (Anexo B): conciliación bancaria, pagos en línea (Stripe), recordatorios a clientes, asientos contables, BUK, IA/agentes. La automatización por reglas sí entra; la IA/LLM no.

5. Decisiones clave

Fecha	Decisión
2026-05-25	MVP acotado a facturación, solo BIND ERP primero (indicación de Noe). BIND tiene API (20K req/día).
2026-05-29	Se incluye emisión asistida de facturas (no solo lectura), con candados fiscales.
2026-06-04	Pagos de avances a 30 días. Gestión en Jira. (El "anticipo aprobado" en la llamada fue revertido el 8-jun: Balam no maneja anticipos.)
2026-06-04	Noe pide evaluar conciliación dentro del MVP, ajustar dashboard (vs Power BI) y renegociar vigencia de soporte → propuesta v1.1.
2026-06-08	Términos acordados: sin anticipo, pago 30 días, garantía 45 días, soporte como bolsa de horas (vigencia 12 meses). Arranque tras contrato firmado. Reflejado en propuesta v1.1.
2026-06-10	Propuesta v1.1 enviada. Johann acepta los 4 ajustes (inversión supeditada a Discovery, soporte bolsa 12 meses, garantía 45 días, sin anticipo/pago 30 días) y condiciona el arranque a contrato firmado. Responde las 3 preguntas técnicas.
2026-06-16	Balam acepta la v1.1. Redacta el documento para firmar; pide a Johann esperar. Pedro armará el tablero de seguimiento en Jira con Erika.
2026-06-25	Balam envía el contrato de servicios para firma (vía Paola, RH). Recoge los términos v1.1 + facturación semanal (viernes).
2026-06-26	Contrato FIRMADO por Johann. Se agregan 2 ajustes finales: pago de horas al terminar y aceptación a 10 días naturales (correcciones sobre alcance).
2026-06-29	Arranque de ejecución: Erika pide el plan de actividades con fechas (Etapa 0 y 1). Bloqueador: que Balam entregue los accesos.
2026-06-30	Plan de actividades (4 etapas) entregado. Kickoff con Noé agendado (1-jul, 7am). Erika = intermediaria de sesiones; tablero Kanban en Jira.

6. Próximos pasos

Ver detalle y responsables en bitacora/PENDIENTES.md. En corto:

1. Kickoff con Noé — mié 1-jul, 7am (arranque del proyecto).
2. Balam: entregar los accesos (API BIND vía ARA, Azure con Guajardo/Erika, manual de marca de Pedro) y reglas/bancos con Arturo. Bloqueador del arranque.
3. Johann: cambiar régimen fiscal y confirmar permisos de Azure.
4. Johann: arrancar el Discovery (Etapa 0) la semana del 6-jul, en cuanto lleguen los accesos.
5. Erika: coordina sesiones (Discovery, reglas con Arturo) y el tablero Kanban en Jira.

7. Riesgos / puntos abiertos

• Sin sandbox de BIND (solo producción) → estrategia lectura primero + escritura con dry-run/confirmación/feature flag; validar comportamiento de escritura en Discovery.
• Conciliación: depende de procesar PDFs bancarios (sin API directa) + involucrar a Arturo.
• Solapamiento dashboard con el Power BI existente de Pedro.
• Límite de API BIND (1 llave por usuario, 20K req/día) → documentar llaves y monitorear consumo.