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: 🟢 Etapa 0 en validación + Etapa 1 iniciada en local. Discovery de facturación, envío y cobranza completo (6–7 jul); prototipo entregado el 10-jul y sesión de validación confirmada para el 23-jul, 7:00 pm. Sesión de reglas/dudas de Etapa 1 confirmada para el 22-jul con Arturo y CEO. Token BIND validado en solo lectura; repo GitHub autorizado por Noé y pendiente de invitación para Johann-28; Azure programado para la semana del 21-jul. La confirmación para emitir la factura inicial de 30 h sigue pendiente por viaje de Noé y CEO. Control local de horas iniciado. Última actualización: 2026-07-15.

---

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, regenerable desde 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).
.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 y seguimiento: Excel oficial consolidado, plan legible, control de horas (CSV) y hallazgos/ADRs de Etapa 0.
marca/	Tokens de marca (Marca-Balam.md) destilados del manual de imagen corporativa: color (Amarillo #F7BD0C, Café #331F0E), tipografía (Poppins) y uso del logo, para el prototipo y la UI. Manual crudo en fuentes/.
prototipo/	Prototipo visual navegable (Etapa 0): Prototipo-Etapa0.html — HTML autocontenido (doble clic) con el flujo real del Discovery 6-jul: Jira → cotización BIND → prefactura → validación humana → CFDI → envío por cliente + cobranza y bitácora. Marca Balam (café/amarillo, Poppins), datos ficticios. Para validar con Ara, Arturo y Pedro.

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.2)

• 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 (al 6-jul: vacía — Ara decidió recordatorios a todos, sin excepciones) · cobranza operativa (aging + alertas internas) · dashboard · reportes CSV/XLSX · bitácora · multimoneda con TC DOF. Flujo objetivo validado en Discovery (6-jul): Jira (disparador) → cotización BIND (obligatoria) → prefactura → validación humana → CFDI → envío.
• 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.
2026-07-01	Kickoff realizado. BIND: token de Arturo (solo consulta, se prueba primero); Balam crea el repo (GitHub privado) y gestiona Azure (Pedro+Noé); horas de Johann en Jira (corte lunes de Erika); Discovery con Arturo + Araceli. Manual de marca recibido. Abierto: vincular la factura de 30 h (contrato vs propuesta) antes de emitir — Johann espera correo de Balam.
2026-07-02	Propuesta v1.2 enviada por correo (30 h de facturación inicial explícitas, condiciones comerciales en §3.3). En espera de confirmación para facturar.
2026-07-06	Discovery #1 realizado (proceso de facturación). Flujo mapeado: Jira ITSM mandatorio → prefactura BIND → CFDI → envío por correo con particularidades por cliente. Lista blanca ELIMINADA (recordatorios a todos — decisión de Ara) y cotización BIND obligatoria como inicio del flujo. Validaciones de oro: PPD default (requerimiento SAT previo por PUE erróneo), IVA 16%/0% manual en BIND. Volumen real: ~55 facturas/mes de 4–6 clientes. Pendiente de Balam: Excel de particularidades de envío.
2026-07-07	Discovery de cobranza completado. Aging por factura, conciliación por folio, diferencias por fee y pagos registrados manualmente por el despacho.
2026-07-10	Prototipo Etapa 0 entregado por correo; Balam lo revisa internamente.
2026-07-13	Johann inicia trabajo local de Etapa 1 sin esperar la validación visual. La factura de 30 h sigue pendiente de visto bueno.
2026-07-14	Sesiones confirmadas: reglas/dudas Etapa 1 el 22-jul y validación del prototipo el 23-jul.
2026-07-15	Noé autoriza el repositorio privado de GitHub; invitación pendiente para Johann-28. Se inicia control local de horas.

6. Próximos pasos

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

1. Johann: continuar backend local y publicar en cuanto llegue la invitación al repo.
2. Johann: validar el corte reconstruido de 30 h en Seguimiento-horas.csv, capturar diariamente en adelante y conciliar con Jira cuando Pedro habilite el flujo.
3. Johann: preparar la sesión del 22-jul (alta de cliente, fee, envíos y alcance Jira→BIND) y la validación del prototipo del 23-jul.
4. Balam: completar repo, Azure, Excel de particularidades de envío y confirmación para emitir la factura de 30 h.
5. Johann/Balam: cerrar explícitamente qué pertenece al MVP: Jira automático, recordatorios externos y escritura en BIND.

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.
• Integración Jira→BIND no incluida explícitamente: requiere decisión de alcance, cuenta técnica de Jira, mapeo de campos y escritura autorizada en BIND.
• Horas históricas reconstruidas: corte de 30 h distribuido por actividad; solo 3.08 h tienen duración documental directa. Johann debe validar las otras 26.92 h antes de facturar.