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](bitacora/). 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`](README.md) | **Este archivo** — estado y datos clave del proyecto. |
| [`bitacora/`](bitacora/) | **Registro vivo**: [REGISTRO.md](bitacora/REGISTRO.md) (cronología de comunicaciones), [PENDIENTES.md](bitacora/PENDIENTES.md) (acciones abiertas), [README.md](bitacora/README.md) (cómo registrar + plantillas). |
| [`propuesta/`](propuesta/) | [Propuesta (MD)](propuesta/00%20-%20PROPUESTA-COMERCIAL.md) — contenido fuente v1.1. [PDF enviado](propuesta/Propuesta-Balam.pdf), regenerable desde su fuente reproducible ([HTML](propuesta/Propuesta-Balam.html) + [config](propuesta/pdf.config.json), build con el skill `proposal-pdf`). [Prototipo](propuesta/prototipo-mvp-fase1.html), [diagrama Fase 1 vs PRD](propuesta/diagrama-fase1-vs-prd.html). |
| [`fuentes/`](fuentes/) | Material crudo: PRD, transcripciones de llamadas, `.eml`. Evidencia, no se edita. |
| [`bind-api-sandbox/`](bind-api-sandbox/) | Prototipo técnico del cliente/mock de la API de BIND (TypeScript; el productivo será .NET). |
| [`.claude/skills/proposal-pdf/`](.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](.claude/skills/proposal-pdf/SKILL.md) (incluye nota de Windows). |
| [`planeacion/`](planeacion/) | **Plan y seguimiento:** [Excel oficial consolidado](planeacion/Plan-actividades-avance-2026-07-10-ajustado.xlsx), [plan legible](planeacion/Plan-actividades.md), [control de horas](planeacion/Seguimiento-horas.md) ([CSV](planeacion/Seguimiento-horas.csv)) y [hallazgos/ADRs de Etapa 0](planeacion/Hallazgos-y-decisiones-Etapa0.md). |
| [`marca/`](marca/) | **Tokens de marca** ([Marca-Balam.md](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/`](fuentes/). |
| [`prototipo/`](prototipo/) | **Prototipo visual navegable (Etapa 0):** [Prototipo-Etapa0.html](prototipo/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](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`](planeacion/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.