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:** 🟢 **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 **generado** (6-jul, 12:10 pm); Erika lo envía por correo — quedan 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`](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 de ejecución:** [Plan-actividades.xlsx](planeacion/Plan-actividades.xlsx) (+ [`.md`](planeacion/Plan-actividades.md)) — actividades por etapa (0–3) con fechas, responsables y sesiones, para el seguimiento con Erika (Jira/Gantt). |
| [`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/). |

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