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