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: 🟢 Discovery en marcha (Etapa 0) — contrato firmado (26-jun), kickoff realizado (1-jul), primera sesión de Discovery realizada (6-jul: proceso de facturación mapeado end-to-end con Ara y Arturo). Cambios de reglas del 6-jul: lista blanca eliminada (recordatorios a todos) y cotización BIND obligatoria. Johann trabaja el prototipo con el flujo real. Bloqueadores: (1) token BIND — ya en gestión por Erika (6-jul; entrega esperada lun 6–mar 7 jul, por correo), además de repo y Azure; (2) confirmación de Balam a la propuesta v1.2 (enviada 2-jul) para emitir la factura de 30 h. Última actualización: 2026-07-06.

---

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 de ejecución: Plan-actividades.xlsx (+ .md) — actividades por etapa (0–3) con fechas, responsables y sesiones, para el seguimiento con Erika (Jira/Gantt).
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/.

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 (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.

6. Próximos pasos

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

1. Johann: trabajar el prototipo (Etapa 0) con el flujo real del 6-jul (Jira → cotización BIND → prefactura → CFDI → envío) y sus validaciones (PPD default, IVA 16%/0%).
2. Balam: entregar el token de BIND (bloqueador técnico, sin respuesta desde el kickoff), repo GitHub y Azure; Ara+Arturo: enviar el Excel de particularidades de envío por cliente (comprometido para el 6-jul).
3. Johann: esperar la confirmación de Balam a la propuesta v1.2 (enviada 2-jul) y entonces emitir la factura de 30 h; mientras, no facturar.
4. Johann: aclarar con Balam la expectativa de recordatorios a clientes (Anexo B, no MVP) antes de que se consolide como supuesto.
5. Johann: configurar Jira (con Pedro), cambiar régimen fiscal; confirmar con Erika si la sesión del martes 7-jul sigue en pie.

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.