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`](Seguimiento-horas.csv)
**Última actualización:** 2026-10-02 (corte 16-sep → 2-oct 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 2-oct (reconstruido, por validar)

Del 16-sep al 2-oct no se capturó nada en el CSV. El 2-oct se agregaron **15.25 h**, en 21 filas con la nota `Corte 2-oct`:
- 13.50 h `reconstruida`.
- 0.50 h `validada`: Johann dio la duración el 2-oct.
- 1.25 h `confirmada`: tiempo real de la sesión del 2-oct (solo lo que se cobra).

Las fuentes fueron:
- los registros de las sesiones de Claude Code de esta máquina (marcas de tiempo de cada mensaje; las sesiones paralelas se unieron para no contar doble);
- los commits de ambos repos;
- los rangos horarios que anota la bitácora (#83–#90);
- el informe de Read AI del 29-sep.

**Johann debe validar las horas `reconstruida`** antes de reportarlas. El corte del 16-sep (94.58 h) no se tocó.

| Etapa | Horas al corte | Rango | Avance | Estado |
|---|---:|---:|---:|---|
| Etapa 0 | **21.83 h** | 18–22 h | 100% | Cerrada y validada |
| Etapa 1 | **32.50 h** | 32–39 h | 97% | Capa de escritura completa; Azure entregado, falta desplegar (75%); CI/CD 50% |
| Etapa 2 (sin ajuste Jira) | **43.50 h** | 38–46 h | 97% | Cadena completa validada en real: Pedro timbró desde la plataforma el 2-oct ([#91](../bitacora/REGISTRO.md)); quedan ajustes de UI/UX (fila nueva) |
| » Ajuste Jira → BIND | **10.50 h** | 7–10 h | 100% | 0.5 h arriba del tope: webhook en producción, vista previa automática y modal "Aceptar" |
| Etapa 3 | **1.50 h** | 24–29 h | 13% | Solo cartera por moneda (25%), endurecimiento y runbook |
| **Total** | **109.83 h** |  | 81% | 55.00 h desde el 6-ago: 52.25 `reconstruida` + 2.25 `confirmada` + 0.50 `validada` |

Movimientos entre etapas en este corte (el total no cambia): 7.75 h de cotización contra BIND salen del ajuste Jira hacia la Etapa 2, y 1.75 h de documentación técnica salen de la gestión de la Etapa 1 hacia la Etapa 2 (ver abajo).

**De dónde salen las 15.25 h:**
- **9/10-sep (3.25 h) — no entraron al corte del 15-sep.** El puente a la web app de BIND para la prefactura (`BindUiClient`, contrato de `AddInvoiceTransaction`, sonda op #12) se construyó en esta máquina y se quedó sin commit hasta el 29-sep (`4d6b3d8`). Por eso la reconstrucción del 15-sep, hecha en la otra máquina, no lo vio. Las dos sesiones con Pedro de esos días ya estaban en el CSV y no se duplican.
- **29-sep (4.25 h):** la sesión de las 7:00 con Pedro (login web a BIND) y el cierre de huecos de la bitácora. Luego, en esta máquina, la primera prefactura real (folio 2467) y el piloto del webhook. Esas dos sesiones corrieron en paralelo y se cuentan una sola vez.
- **30-sep (5.25 h), en la otra máquina:** el webhook pasa a producción, con la vista previa automática y el modal en vivo. Hubo una llamada de 15 min con Pedro a las 7:26. Después, el puente se encendió en producción con cuatro bugs corregidos y se construyó el timbrado.
- **1-oct (0.25 h):** prueba completa con Balam, de unos 20 min según Johann. Llegó a prefactura; el timbrado no se intentó.
- **2-oct (2.25 h):**
  - Prefacturas en lote (1.00 h).
  - Este corte en sí (0.75 h). La proyección de costos, la reclasificación y los ajustes posteriores del Excel (~0.75 h) **no se cobran** (decisión de Johann, 2-oct).
  - El manual de usuario en PDF (0.50 h, `manual/Manual-usuario-Balam.pdf`).
  - El acompañamiento por WhatsApp a Pedro mientras timbraba (3:28–3:46 pm) **no se cobra** (decisión de Johann, 2-oct).
- **Reparto CSV → filas del Excel** (`generar_avance_2026_10_02.py`; el script se detiene si no cuadra):
  - E1-05 → seguimiento semanal
  - E2-03 → conversión cotización→factura
  - E2-04 → pruebas integrales + manual
  - AJ-01 → disparador → cotización automática
  - Además se movieron 0.25 h de "Creación de cotizaciones" a "Tipo de cambio" (el TC se resolvió el 12-ago dentro de ese bloque), para que ninguna fila cerrada quede con 0 h.

**Reclasificación del 2-oct (Johann):** las 7.75 h que el corte del 15-sep cargó al ajuste Jira (`AJ-01`) y que en realidad fueron cotización contra el API de BIND pasan a la Etapa 2 como `E2-02`, a la fila «Creación de cotizaciones». Son las sesiones acompañadas del 12-ago, las dos del 21-ago y las dos del 3-sep, el Excel de catálogos, el diagnóstico del 500 y la investigación hasta el folio 1026. Así quedan:

| Línea | Antes | Ahora | Rango |
|---|---:|---:|---:|
| Ajuste Jira → BIND | 18.25 h | **10.50 h** ($6,300) | 7–10 h |
| Disparador → cotización automática | 8.00 h | **3.50 h** (webhook, vista previa, modal) | 3–4 h |
| Trazabilidad | 4.75 h | **1.50 h** | 2–3 h |
| Etapa 2 | 34.00 h | **41.75 h** | 38–46 h |
| Creación de cotizaciones | 7.75 h | **15.50 h** | 5–6 h |

El total del proyecto no cambia. Lo que Balam aprobó y controla es el rango por etapa, y ninguna etapa queda rebasada. A nivel fila, «Creación de cotizaciones» y «Conversión cotización→factura» superan su estimado: el API de BIND no documentaba cómo cotizar ni permitía crear prefacturas.

**Fila de seguimiento y gestión (2-oct, Johann):** la fila «Demostración semanal (viernes) + reporte de horas» no tenía demostraciones: las sesiones con Pedro se cargan a las filas técnicas. Lo que tenía era gestión. Por eso:
- Se renombra a «Seguimiento y gestión: reportes de horas, bitácora y comunicación con Balam».
- Lo técnico se va a su fila (regla 7):
  - 20-ago: 1.00 h del registro #65 y el guion de la sesión del 21-ago pasan a «Creación de cotizaciones». La fila del CSV se dividió según los commits: 5d846ec 23:02 para el cruce del buzón; a03f81f, cabe0fe y 072a3cd para lo de cotización.
  - 29-sep: 0.75 h (registros #71–#83 e investigación del SDK de BIND para la prefactura) pasan a «Conversión».
- La fila queda en **8.00 h**, unos 40 minutos por semana en 12 semanas:

| Qué | Horas | Fechas y evidencia |
|---|---:|---|
| Cortes de horas y Excel de avance | 3.75 | 15-jul 0.50 · 16-jul 1.00 (Excel y mensaje a Erika) · 21-jul 0.25 · 15-sep 0.75 · 16-sep 0.50 (Google Sheets) · 2-oct 0.75 |
| Bitácora | 2.25 | 1-ago 0.50 (#59–#60, commit 2b862ee) · 11-ago 0.75 (#62–#63, commits f28fcc5 y a2f338f) · 20-ago 1.00 (cruce del buzón, commit 5d846ec) |
| Comunicación con Balam | 2.00 | 28-jul 0.25 (Azure a Erika) · 29-jul 0.75 (envío de la v1.3) · 20-ago 0.50 (WhatsApp con Pedro) · 25-ago 0.50 (correo de Azure a Noé) |
| **Total** | **8.00** | El estimado de 2–3 h de la propuesta era para demostraciones y reporte, no para la gestión de 12 semanas |

**Decisiones de Johann sobre el Excel (2-oct):**
- **Fechas reales.** Inicio = primer día trabajado. Fin = día en que se terminó el entregable según la bitácora y los commits; en las tareas en curso, el último día trabajado.
- **Orden.** Las filas van en orden cronológico dentro de cada etapa; el bloque del ajuste Jira → BIND sigue al frente de la Etapa 2.
- **Avance de los encabezados.** Es el promedio de sus filas ponderado por las horas estimadas (regla 4). Antes se calculaba con horas consumidas entre horas estimadas.
- **Al 100%.**
  - Capa de escritura, Disparador → cotización automática, Creación de cotizaciones, Pruebas integrales + manual y Demostración semanal (al día).
  - Conversión cotización→factura y Trazabilidad: se cerraron al 100% el 2-oct, cuando Pedro timbró desde la plataforma y completó todo el proceso. Los ajustes de UI/UX que quedan (botones «Ver en Jira» / «Ver en BIND» y las pantallas de Solicitudes, Cotizaciones y Facturas) no reabren esas filas: van en una fila nueva de la Etapa 2, «Ajustes de UI/UX de la emisión» (⚪ Próxima, 0%, 1–2 h estimadas), que deja la Etapa 2 en 97%.
  - Con alcance ajustado: Catálogo de clientes (Balam eliminó la lista blanca el 6-jul), Detalle de factura (el XML se consulta en BIND), Exportación (queda CSV) y Tipo de cambio (sale del catálogo de monedas de BIND; el proceso del DOF sale del alcance).
- **Otros avances.**
  - Azure sube a 75%: Balam ya dio el acceso, aunque falta volver a pedir la contraseña.
  - CI/CD queda en 50%.
  - Cobranza queda en 25%: la cartera con vencidos existe desde el 1-ago.
  - Endurecimiento y documentación técnica se quedan como estaban.

**Sin registro de horas:**
- Timbrado del 30-sep (#89): se dejó en 0.75 h (10:00–10:45 pm según el respaldo y el último commit). Johann no recuerda si siguió hasta las 12:50 am, como dice el título del registro.
- Comunicación del 16 al 28-sep (convocatoria del 28-sep, credenciales en TXT, autorización escrita de Pedro para el webhook) y la fecha en que Balam dio el acceso a Azure.
- Las duraciones salen de la actividad dentro de las sesiones de trabajo. Una pausa de más de 20 minutos corta el bloque, así que el tiempo de revisar o pensar fuera de la sesión no aparece (regla 7). Johann puede subirlas.

## Corte al 16-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** (más 0.50 h del 16-sep: Excel publicado en Google Sheets) 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.75 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.58 h** |  | 39.75 h nuevas desde el 6-ago: 38.75 `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.