balam/planeacion/Seguimiento-horas.md

Seguimiento de horas

Fuente local de horas efectivamente trabajadas para el proyecto Balam. Se mantiene mientras Johann obtiene acceso al flujo de Jira; después, Jira será el registro operativo y este archivo/CSV servirá para conciliación y facturación.

Tarifa contractual: $600 MXN/h + IVA Cadencia: corte semanal; factura los viernes; pago a 30 días Datos tabulares: Seguimiento-horas.csv Última actualización: 2026-09-15 (corte 6-ago → 15-sep reconstruido, por validar)

Reglas de captura

1. Registrar el tiempo el mismo día, en incrementos de 0.25 h.
2. Separar sesiones, desarrollo, análisis, documentación y gestión técnica.
3. Vincular cada registro con una actividad del plan y una evidencia cuando exista.
4. No convertir porcentajes de avance en horas: el avance mide entregable; las horas miden esfuerzo real.
5. No completar retrospectivamente una duración sin respaldo. Si solo se conoce la actividad, dejarla en la lista de reconstrucción hasta que Johann confirme el tiempo.
6. Al habilitarse Jira, conciliar ambos registros y evitar duplicados.
7. El esfuerzo real de una sesión incluye TODO su alrededor, no solo el desarrollo: el análisis/pensamiento previo para decidir qué se hace, la documentación de cada parte (bitácora, pendientes, investigación), y la comunicación asociada (cada correo, cada mensaje de WhatsApp, minutas y reportes). Definido por Johann el 6-ago.
8. Para proyectar el costo final del proyecto, las horas no comprimibles (sesiones con Balam, pruebas acompañadas, capacitación, demos, gestión y comunicación) son el piso, y el objetivo de cierre es ese piso y un poco más — no el piso pelón ni el rango completo de la propuesta. Los cortes ya reportados a Erika nunca se recalculan retroactivamente (ajustado por Johann el 6-ago).

Corte al 15-sep (reconstruido, por validar)

Del 10-ago al 15-sep no se capturó nada en el CSV; el 15-sep se reconstruyeron 39.25 h con evidencia fechada (commits de ambos repos, correos, informes de reunión de Read AI y mtimes de archivos) y quedaron marcadas reconstruida (salvo la sesión del 12-ago, confirmada por transcript). Johann debe validarlas (o ajustarlas) antes de reportarlas; el corte del 6-ago (54.83 h) no se tocó.

Etapa	Horas al corte	Rango	Estado
Etapa 0	21.83 h	18–22 h	Cerrada y validada
Etapa 1	32.25 h	32–39 h	Capa de escritura implementada; publicación provisional en paputec.mx (3-sep)
Etapa 2 (sin ajuste Jira)	23.75 h	38–46 h	Cotización individual y en lote; prefactura por API bloqueada por BIND
» Ajuste Jira → BIND	14.75 h	7–10 h	⚠️ Rebasado: semánticas indocumentadas del API y 5 sesiones acompañadas
Etapa 3	1.50 h	24–29 h	Endurecimiento y runbook hechos en la publicación
Total	94.08 h		39.25 h nuevas: 38.25 reconstruida + 1.00 confirmada (transcript del 12-ago)

Criterios usados en la reconstrucción:

• Sesiones con Balam: duración acotada por la hora de inicio de la convocatoria y la hora en que llegó el informe de Read AI (redondeada a 0.25 h). Sin transcript no se infló nada; Johann puede subirlas si duraron más.
• Bloques de desarrollo: del primer archivo tocado (mtime) o del inicio estimado al último commit del bloque; incluyen la documentación del mismo bloque (regla 7).
• Seis sesiones no tienen registro en la bitácora (21-ago 1 pm, 24-ago, 26-ago, 3-sep 7 am y 1:30 pm, 9-sep, 10-sep): están en PENDIENTES.md como huecos de registro.
• Actividades nuevas: E1-09 publicación provisional, E2-02 creación de cotizaciones desde la plataforma, E2-03 conversión cotización→prefactura/factura, E3-01 endurecimiento, E3-02 documentación técnica. El reparto CSV → filas del Excel vive en generar_avance_2026_09_15.py.

Corte al 27-jul

Etapa	Horas al corte	Rango estimado de la etapa	Estado
Etapa 0	21.83 h	18–22 h	Cerrada y validada por Balam el 24-jul; dentro del rango
Etapa 1	19.75 h	32–39 h	En curso; 6 de 8 entregables terminados
Total	41.58 h

Estado de validación de las horas (27-jul):

Estado	Horas	Significado
confirmada	9.13 h	Duración documentada (transcripts, sesiones calendarizadas, tiempo de sesión)
validada	32.45 h	Reconstruida por actividad y confirmada por Johann el 27-jul contra evidencia fechada
Total	41.58 h	Sin horas pendientes de validar

Distribución al 27-jul

Etapa	Actividad	ID	Horas
0	Kickoff y preparación	E0-01	2.00
0	Discovery de facturación, envío y cobranza	E0-02	3.83
0	Accesos y salvaguardas	E0-03	1.00
0	Validación técnica de la API de BIND	E0-04	4.50
0	Prototipo navegable (incl. pulido final del 10-jul)	E0-05	7.50
0	Entregable de cierre: PDF, hallazgos, plan y correo	E0-06	1.50
0	Validación del prototipo con Balam (guion + sesión)	E0-07	1.50
1	Backend base, auth, roles, bitácora y syncs (B0–B4)	E1-01	6.50
1	Coordinación del repositorio	E1-02	0.50
1	Arquitectura multi-tenant y RLS (B6)	E1-03	2.00
1	Cliente productivo de la API de BIND	E1-04	2.00
1	Gestión, cortes de avance y sesión de reglas	E1-05	3.30
1	Entorno local, scaffold y Scalar	E1-06	3.25
1	Sesión de API de Jira	E1-07	0.20
1	Diseño del plan de ejecución de Etapa 1	E1-08	2.00
	Total		41.58

Ajustes a la baja aplicados por Johann el 27-jul: el análisis del Discovery de facturación bajó de 1.92 a 1.00 h, la documentación del de cobranza de 1.50 a 0.75 h, y el guion de validación de 0.75 a 0.45 h. Las duraciones de sesión documentadas en transcript no se tocaron. Con esto Etapa 0 vuelve a quedar dentro del rango contractual de 18–22 h.

Nota sobre las sesiones asistidas por IA

Los bloques B0–B6 de Etapa 1 (auth, RLS, cliente de BIND, sincronización de 1,494 facturas de producción) se ejecutaron en 3.50 h de tiempo de reloj contra una estimación manual de 4–5.5 h por bloque. Se registra el tiempo efectivamente trabajado, conforme al contrato. El trabajo intelectual que hizo posible esa velocidad —diseño de arquitectura, decisión de ADRs y plan de ejecución— se registra por separado en E1-08 (2.00 h).

Consecuencia a vigilar: Etapa 1 cerrará por debajo del rango de 32–39 h. Conviene reportar avance por entregable (6 de 8) y no solo por horas, para que la eficiencia no se lea como alcance faltante.

Nota sobre el mapeo CSV → Excel

El CSV agrupa por actividad contractual; el Excel desglosa por tarea de proyecto, y no mapean 1:1. El reparto vive en HORAS_POR_FILA dentro de generar_avance_2026_07_27.py, con la trazabilidad comentada línea por línea, y el script aborta si la suma del detalle no cuadra con el CSV.

Dos casos que conviene recordar:

• E1-06 (entorno, scaffold, Scalar — 3.25 h) no tiene fila propia: se carga a "Backend base", que se renombró y amplió su rango a 8–9 h.
• E1-08 (diseño del plan — 2.00 h) se reparte en dos: 1.00 h de diseño general va a "Arquitectura multi-tenant y diseño de la solución" (rango 3–4 h) y 1.00 h del análisis de B7 —pipeline Draft→DryRun→Confirm, flags, regla PPD/PUE, ADR-001— va a la fila del entregable 4 (capa de escritura), para que muestre el trabajo hecho aunque la implementación siga en pausa. La entidad WriteOperation y la policy PuedeOperarEscritura no se contabilizan ahí: se hicieron en B1/B2 y ya están en "Backend base" (evita doble conteo).
• La fila de seguimiento semanal se queda solo con gestión y cortes de avance (1.75 h). Antes acumulaba 7.00 h de trabajo técnico bajo un nombre que no lo describía, lo que se leía como sobrecosto en una actividad trivial.
• La sesión B4 (1.00 h) se reparte entre "Sincronización de facturas" (0.50 h) y "Modelo de facturas" (0.50 h): produjo ambas cosas —el sync y el InvoiceStatusMapper con sus 13 pruebas más la migración DetalleSyncPendiente—, y antes el modelo aparecía al 85 % con 0 h.

Criterio general: ninguna fila debe mostrar avance con 0 h trabajadas. Las únicas excepciones legítimas son Azure y CI/CD, que están en 0 % y 0 h porque dependen de accesos del lado de Balam.

Corte comercial

• La propuesta v1.2 contempla una facturación inicial de 30 h ($18,000 + IVA) que cubre Etapa 0 e inicio de Etapa 1.
• Al 27-jul hay 41.58 h trabajadas, es decir 11.58 h por encima de esa facturación inicial. A tarifa de $600/h son $6,948 + IVA aún no facturados.
• Todas las horas están validadas (ninguna pendiente de confirmar), por lo que el desglose ya es presentable para facturación.
• Pendiente: conciliar contra Jira cuando Pedro lo habilite, y confirmar con Balam si la segunda factura va por el excedente o por corte de etapa.
• La emisión de la factura inicial sigue pendiente de confirmación de Balam al correo del 2-jul.