Reorganiza repo como fuente de la verdad + propuesta v1.0 con emisión de facturas

- Estructura nueva: README maestro, bitacora/ (REGISTRO, PENDIENTES, plantillas),
  propuesta/, fuentes/; material superado a _archivado/
- Propuesta v1.0: MVP BIND-first con emisión asistida MXN/USD (dry-run +
  confirmación, timbra PAC de BIND), 112-136 h / $67,200-$81,600 + IVA,
  stack .NET 10 + EF Core + Angular 21 + PostgreSQL 17 sobre Azure
- Bitácora: historial de correos + 2 llamadas (incl. revisión 4-jun) y pendientes
- Prototipo y diagrama actualizados a v1.0; precios de Azure verificados
- Archivo ajeno (proyecto EOS) retirado del repo

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
JohannVelazquez
2026-06-04 10:57:27 -06:00
parent 404e6f3b89
commit 633d05e330
47 changed files with 32977 additions and 472 deletions
+74
View File
@@ -0,0 +1,74 @@
# 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** · **67 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.