Actualiza cierre de Etapa 0 y control de horas

planeacion/Hallazgos-y-decisiones-Etapa0.md

@@ -0,0 +1,126 @@
+# Etapa 0 — Hallazgos y decisiones de arquitectura
+
+**Proyecto:** Plataforma de Automatización Financiera · Balam
+**Estado:** borrador para cerrar con la validación del prototipo
+**Última actualización:** 2026-07-15
+
+## 1. Resultado del Discovery
+
+El flujo operativo confirmado es:
+
+**Jira ITSM → cotización en BIND → prefactura → validación humana → CFDI → envío según reglas del cliente → cobranza**
+
+Reglas de negocio principales:
+
+- Toda factura debe partir de una cotización en BIND.
+- La prefactura es obligatoria antes de timbrar.
+- PPD es el método predeterminado; PUE requiere una decisión consciente.
+- IVA esperado: 16 % en operación nacional y 0 % para operación extranjera sin efectos fiscales, sujeto a las excepciones fiscales que confirme Balam.
+- El alta de un cliente nuevo es un flujo separado y requiere definición final de Arturo.
+- Los recordatorios se desean para todos los clientes; los correos automáticos externos permanecen fuera del MVP original (Anexo B) hasta confirmar alcance.
+- La cobranza se controla por factura y folio. Debe tolerar diferencias por comisiones/fees conforme a la regla que confirme Arturo.
+
+## 2. Resultado de la validación de BIND
+
+La prueba del 6-jul realizó 117 solicitudes exclusivamente GET contra la cuenta real, sin persistir datos de Balam.
+
+Confirmado:
+
+- Saldo por factura viable con `Total - Payments - CreditNotes`.
+- Cotizaciones, prefacturas, facturas, clientes, impuestos, PPD/PUE, vencimientos y PDF son consultables.
+- Aging y alertas internas son viables sin consultar pagos individuales.
+- El volumen proyectado de sincronización consume aproximadamente 5 % del límite de 20,000 solicitudes diarias.
+
+Restricciones:
+
+- No se encontró endpoint de pagos individuales ni complementos de pago (REP).
+- BIND no expone el vínculo cotización→factura; la plataforma deberá conservarlo.
+- Algunos campos clave solo aparecen en el detalle de cada factura.
+- No hay webhooks confirmados; el diseño base usará sincronización incremental por polling.
+- El token está acotado a una sola empresa.
+- La cuenta actual es de producción y puede tener privilegios elevados; no se autoriza escritura todavía.
+
+Detalle técnico: [`../bind-api-sandbox/VALIDACION-API.md`](../bind-api-sandbox/VALIDACION-API.md).
+
+## 3. Decisiones de arquitectura
+
+### ADR-001 · Lectura primero y escritura controlada
+
+**Decisión:** operar inicialmente en modo solo lectura. Toda escritura futura requiere autorización expresa, dry-run, confirmación humana y feature flag desactivado por defecto.
+
+**Motivo:** Balam no cuenta con sandbox y una operación incorrecta puede tener efecto fiscal.
+
+### ADR-002 · Sincronización incremental
+
+**Decisión:** persistir en PostgreSQL el último punto de sincronización y consultar únicamente registros nuevos o modificados. Paginar siempre con lotes de hasta 100.
+
+**Motivo:** BIND no ofrece conteos ni `nextLink`; PPD/PUE y días de crédito requieren consultas de detalle.
+
+### ADR-003 · Trazabilidad propia
+
+**Decisión:** almacenar las relaciones `ticket Jira → cotización BIND → factura BIND` en la base de datos de la plataforma.
+
+**Motivo:** la API de BIND no expone de forma confiable el vínculo cotización→factura.
+
+### ADR-004 · Detección de pagos
+
+**Decisión:** para el MVP, detectar pagos mediante cambios de estatus y saldo residual. Registrar la fecha de detección, no presentarla como fecha valor.
+
+**Motivo:** no se encontró un recurso de pagos/REP. La fecha contable real requerirá información adicional o una ampliación.
+
+### ADR-005 · Separación por empresa
+
+**Decisión:** el MVP opera únicamente con la empresa Balam asociada al token. Multiempresa queda fuera del alcance.
+
+**Motivo:** cada empresa requiere su propia cuenta/token de BIND.
+
+### ADR-006 · Integración Jira→BIND pendiente de alcance
+
+**Decisión:** diseñar el modelo para conservar el identificador del ticket, pero no comprometer todavía la automatización que crea cotizaciones desde Jira.
+
+**Motivo:** el Discovery confirmó a Jira como entrada del proceso, pero la integración automática no estaba incluida explícitamente en el MVP. Antes de desarrollarla se requiere:
+
+- Confirmación de alcance.
+- Cuenta técnica y acceso API/OAuth a Jira.
+- Webhook o regla de automatización.
+- Mapeo de campos y estatus disparador.
+- Acceso controlado de escritura a BIND.
+
+## 4. Preguntas que deben cerrarse
+
+### Con Arturo / CEO — sesión del 22-jul
+
+1. Flujo definitivo de alta de cliente nuevo.
+2. Tratamiento en BIND de diferencias por comisión/fee.
+3. Particularidades de envío por cliente.
+4. Estatus de Jira que autoriza crear una cotización.
+5. Campos obligatorios y manejo de tickets incompletos.
+
+### Con Pedro / Noé
+
+1. Endpoint de pagos individuales o REP.
+2. Mapeo interno de `CFDIUse` a clave SAT.
+3. Formato de respuesta de `/{id}/xml`.
+4. Disponibilidad de webhooks en BIND.
+5. Token utilizado por Power BI y decisión sobre usuario de solo lectura.
+6. Permisos e identidad técnica para Jira, si se aprueba la integración.
+
+## 5. Dependencias de infraestructura
+
+| Dependencia | Estado al 15-jul | Impacto |
+|---|---|---|
+| Token BIND | Entregado; uso solo lectura | Desbloquea consultas y cliente BIND |
+| Repositorio privado GitHub | Autorizado por Noé; invitación pendiente | Necesario para publicar backend/frontend |
+| Azure | Programado para semana del 21-jul | No bloquea desarrollo local |
+| CI/CD y secretos | Actividad separada para 24-jul | Depende de repo y Azure |
+| Jira técnico | No solicitado todavía | Solo bloquea integración automática Jira→BIND |
+
+## 6. Criterio de cierre de Etapa 0
+
+La Etapa 0 se cierra cuando:
+
+- Balam valida el prototipo o registra ajustes.
+- Se incorporan las decisiones de la sesión del 22-jul.
+- Se valida el prototipo en la sesión del 23-jul.
+- Este documento se actualiza con las respuestas finales.
+- Se emite un plan refinado con alcance explícito para Jira, recordatorios externos y escritura en BIND.