# 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:** 🟢 **Avanzando** — propuesta v1.0 enviada y revisada; **anticipo de Discovery aprobado**. Pendiente: formalización por correo de Balam + propuesta v1.1 con ajustes.
_Última actualización: 2026-06-04._

---

## 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 v1.0 (MD)](propuesta/00%20-%20PROPUESTA-COMERCIAL.md), [PDF enviado](propuesta/Propuesta-Balam.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). |
| [`_archivado/`](_archivado/) | Material superado (propuestas viejas, diagramas previos). Histórico. |

## 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) |
| 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.0)

- **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.
- **Anticipo:** 30 h de Discovery = **$18,000 MXN + IVA** ✅ aprobado.
- **Pagos:** anticipo a 7 días; avances a 30 días.
- **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 | **Anticipo de Discovery aprobado.** Pagos avances a 30 días. Gestión en Jira. |
| 2026-06-04 | Noe pide **evaluar conciliación dentro del MVP**, ajustar dashboard (vs Power BI) y renegociar vigencia de soporte → propuesta **v1.1**. |

## 6. Próximos pasos

Ver detalle y responsables en [bitacora/PENDIENTES.md](bitacora/PENDIENTES.md). En corto:
1. Johann: cambiar régimen fiscal → emitir factura de anticipo.
2. Balam (Noe): formalizar por correo (accesos + ajustes).
3. Johann: preparar **propuesta v1.1** (conciliación, dashboard, soporte).
4. Pedro: manual de marca, llaves API BIND, espacio en Jira.
5. Arrancar **Discovery**.

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