JohannVelazquez
e057fb9127
- Plan-Etapa1.md: plan detallado por fases/bloques (B0-B9) con horas, decisiones de arquitectura y lo bloqueado hasta el 22-jul - Avance-Etapa1-2026-07-16.md + Excel de avance ordenado por fechas (con script generador y de ordenamiento) - WhatsApp 16-jul: invitación al Git recibida, procedimientos de clientes enviados por correo, Erika pide avance de Etapa 1 - Actualiza PENDIENTES y REGISTRO
73 lines
9.2 KiB
Markdown
73 lines
9.2 KiB
Markdown
# Plan: Documento "Plan-Etapa1.md" — plan fiel y completo de la Etapa 1
|
||
|
||
## Contexto
|
||
|
||
Johann necesita el plan de trabajo de la **Etapa 1 — "Plataforma base y sincronización con BIND"** (32–39 h contractuales, semanas 2–3, ventana 13–24 jul). Hoy 16-jul solo 1 de los 8 entregables contractuales está terminado (el cliente API de BIND, portado a C# con 13 pruebas) y hay 8 h registradas de la etapa; quedan ~24–31 h y la demo semanal del **viernes 18-jul** es el compromiso más cercano. El usuario pidió un plan "lo más fiel posible" a toda la documentación (propuesta comercial v1.2, ADRs de Etapa 0, VALIDACION-API.md, bitácora, seguimiento de horas) — se revisó todo con 2 agentes de exploración y 1 de diseño.
|
||
|
||
**Decisión del usuario:** generar SOLO el documento (no arrancar implementación todavía), guardado en el repo privado de gestión `../balam` (nunca en el repo del cliente `balam-plataforma` — regla del CLAUDE.md de ese repo).
|
||
|
||
## Qué se hará
|
||
|
||
1. **Crear `planeacion/Plan-Etapa1.md`** en `c:\Users\JohannVelazquez\Desktop\Personal\balam` con el contenido detallado abajo.
|
||
2. **Agregar 1 línea de referencia** en `planeacion/Plan-actividades.md` (sección Etapa 1) apuntando al nuevo documento: `> Plan detallado de ejecución: [Plan-Etapa1.md](Plan-Etapa1.md)`.
|
||
3. Nada más: sin commits al repo del cliente, sin código. (El repo bitácora tiene cambios sin commitear del usuario; NO commitear nada ahí tampoco, solo dejar los archivos.)
|
||
|
||
## Contenido del documento Plan-Etapa1.md
|
||
|
||
Estructura y contenido esencial (redactado en español MX, estilo de los docs existentes de `planeacion/`):
|
||
|
||
### §1 Resumen y estado (al 16-jul)
|
||
- Entregable contractual de la etapa (propuesta L142–157): plataforma que ingiere clientes/facturas de BIND, los normaliza, mantiene trazabilidad y habilita capa de escritura controlada. 32–39 h · $19,200–$23,400.
|
||
- Horas: 8.00 h registradas (reconstruidas) → quedan ~24–31 h. Tabla de los 8 entregables contractuales con estado real (solo cliente BIND ✅; scaffold/DbContext/entidades semilla ✅ como avance parcial; resto ❌).
|
||
- Hechos del repo de código: solución .NET 10 compilando, 13 pruebas verdes, API con /health y /api/bind/status, Angular 21 con tema de marca.
|
||
|
||
### §2 Calendario e hitos externos
|
||
| Fecha | Hito |
|
||
|---|---|
|
||
| jue 17-jul | Fin de ventana planeada de backend base + multi-tenant |
|
||
| vie 18-jul | **Demo semanal (30 min, Pedro + gerencia)** — meta: login+roles, sync real de BIND en Postgres, endpoint de cartera |
|
||
| sem 21-jul | Acceso Azure (Pedro+Noé) — no bloquea trabajo local |
|
||
| mié 22-jul | **Sesión de definiciones Etapa 1** (Arturo + CEO): alta cliente, fee, envío, alcance Jira→BIND |
|
||
| jue 23-jul 7pm | Validación del prototipo Etapa 0 |
|
||
| vie 24-jul | CI/CD + secretos · demo/cierre de etapa |
|
||
|
||
### §3 Plan de construcción por bloques (B0–B9, fases F1–F6)
|
||
Incluir el plan técnico completo producido en el diseño (resumido aquí; el documento lo lleva íntegro):
|
||
|
||
- **F1 (16-jul) — B0 Preparación (0.5–1 h) + B1 Modelo de datos (3.5–4.5 h):** docker-compose Postgres 17 local; entidades `Tenant`, `Client`, `Invoice` (modelo central con estados), `Quote`, `QuoteInvoiceLink` (ADR-003), `InvoiceStatusChange` (ADR-004), `WriteOperation`; extender `SyncCheckpoint`/`AuditLogEntry` con TenantId; `BalamDbContext` → `IdentityDbContext<BalamUser,…>`; convenciones de fechas Npgsql (BIND sin zona → `timestamp without time zone`) y decimales; migración `Inicial` + `DbSeeder` idempotente (tenant Balam, 4 roles, 5 usuarios ficticios).
|
||
- **F2 (17-jul) — B2 Auth+roles+bitácora (4–5 h) + B3 Sync clientes (2.5–3.5 h):** ASP.NET Core Identity + JWT propio (sin MapIdentityApi, sin refresh tokens en E1); roles `Finanzas/Direccion/Operaciones/Administracion` (sin acentos como identificador); policies nombradas + matriz de acceso por endpoint; `AuditMiddleware` (mutantes + 401/403) + `IAuditLogger` explícito (login, ciclos de sync, escritura) — NO interceptor EF (inundaría con upserts del sync); sync de clientes: full-scan barato de lista (sin campo fecha filtrable) + `SourceHash` + detalle solo nuevos/cambiados + normalización RFC/nombre + dedup por RFC exacto excluyendo genéricos (`DuplicateOfClientId`).
|
||
- **F3 (18-jul am) — B4 Sync facturas/cotizaciones + cartera (4.5–5.5 h) → DEMO:** delta `Date ge` desde checkpoint + re-barrido de ventana de facturas abiertas (los pagos caen en facturas viejas) + detalle solo nuevas/cambiadas con tope por ciclo; mapeo de estados plataforma (Emitida=prefactura, Vigente, Vencida=derivada con fecha MX, Pagada, Cancelada) como **función pura con pruebas** (frontera Emitida/Vigente a confirmar el 22-jul); detección de pagos por transición → `InvoiceStatusChange` con fecha de DETECCIÓN (ADR-004); endpoints `GET /api/cartera` (agregados POR MONEDA, nunca mezclarlas), `/api/invoices`, `/api/clients`, `/api/quotes`, `POST /api/sync/run`; **sync inicial del histórico (>1,000 facturas) se corre el jueves en la noche, nunca en vivo**.
|
||
- **F4 (21-jul) — B5 Scheduler (2–3 h) + B6 RLS (1.5–2.5 h):** `BackgroundService` + `PeriodicTimer` 15 min (NO Quartz/Hangfire — un solo job, estado en checkpoints), `SemaphoreSlim` anti-solape, guarda de cuota vía `BindQuotaTracker` (reserva configurable), backfill gradual de detalle histórico; RLS REAL de Postgres (contractual): políticas `tenant_isolation` por tabla con `current_setting('app.tenant_id')` + `FORCE` + `WITH CHECK`, `TenantConnectionInterceptor` con `set_config`, más filtro global EF (`ITenantOwned`) como segunda capa; fuera: CRUD tenants, resolución por request.
|
||
- **F5 (22-jul, post-sesión) — B7 Capa de escritura controlada (3–4 h):** pipeline `Draft → DryRun → Confirm` persistido en `WriteOperations`, todo auditado; `BindWriteClient : BindClient` (reusa `RequestAsync` protected y sus salvaguardas); feature flags `BindWrite:Enabled=false` default; PPD default, PUE solo con confirmación explícita (salvaguarda 4); CERO llamadas reales a BIND — shapes provisionales marcados TODO hasta doc del portal con Pedro; conversión mock registra `QuoteInvoiceLink`.
|
||
- **F6 (23–24 jul) — B8 Suite de pruebas (2.5–3.5 h) + B9 datos de prueba + runbook (1–2 h):** nuevo proyecto `tests/Balam.Api.Tests` con `WebApplicationFactory` + **SQLite in-memory** (no EF InMemory — no valida FKs/únicos; no Testcontainers — exige red/Docker en tests); cobertura contractual: matriz de roles, sync (delta/checkpoint/detección de pago), multimoneda, salvaguardas de escritura; `DevDataSeeder` ficticio multimoneda/multi-estado (respaldo de demo); runbook de demo.
|
||
|
||
### §4 Presupuesto de horas
|
||
Tabla B0–B9 (nominal ~27.5 h, rango 25–31) + recortes identificados (≈ −5 h): audit endpoint y quotes-sync pueden moverse post-demo; dedup solo RFC; backfill mínimo. B6 (RLS) NO recortable a cero por ser contractual.
|
||
|
||
### §5 Decisiones de arquitectura (con porqués, citables)
|
||
Scheduler BackgroundService vs Quartz; RLS real en dos capas; Identity+JWT sin refresh tokens (diferidos a Etapa 2 con la UI); bitácora middleware+servicio vs interceptor EF; SQLite en pruebas con costo aceptado (RLS/timestamptz se verifican manual en runbook); trampas Npgsql (fechas), "hoy" con zona México, `partial class Program`.
|
||
|
||
### §6 Bloqueado hasta el 22-jul y fuera de alcance
|
||
- Bloqueado: escritura real a BIND (ADR-001), reglas de alta de cliente/fee/envío, alcance Jira→BIND, semántica exacta Emitida/Vigente, mapeo `CFDIUse`→SAT.
|
||
- Fuera de Etapa 1: UI (E2), refresh tokens (E2), recordatorios a clientes (Anexo B), multiempresa (ADR-005), fecha valor de pagos/REP (ADR-004), aging/tablero (E3), conciliación, CI/CD+Azure (actividades propias 21–24 jul), envío de PDF.
|
||
|
||
### §7 Riesgos y gestión (no técnico, en el mismo doc)
|
||
- Riesgos: primera corrida de sync en vivo (mitigado: jueves noche); filtro `CreationDate` de Quotes no validado (fallback full-scan); repo visible al cliente (solo datos ficticios, sin co-autoría en commits).
|
||
- Pendientes de gestión que tocan la etapa: correo formal a Noé (salvaguardas — borrador listo), 5 preguntas técnicas a Pedro (REP/pagos, `CFDIUse`, `/xml`, webhooks, token Power BI), borrar `bind_token_api.txt` del disco, registrar horas diario en `Seguimiento-horas.csv`, preparar sesión 22-jul (ya existe `Sesion-Etapa1-2026-07-22.md` — referenciarla).
|
||
|
||
## Archivos a crear/modificar
|
||
|
||
| Archivo | Acción |
|
||
|---|---|
|
||
| `c:\Users\JohannVelazquez\Desktop\Personal\balam\planeacion\Plan-Etapa1.md` | Crear (documento completo) |
|
||
| `c:\Users\JohannVelazquez\Desktop\Personal\balam\planeacion\Plan-actividades.md` | Agregar 1 línea de referencia en la sección Etapa 1 |
|
||
|
||
## Verificación
|
||
|
||
1. El documento existe, abre bien en Markdown y sus tablas renderizan (revisión visual).
|
||
2. Cifras contractuales cuadran con la propuesta: 32–39 h, entregables L148–155, roles y stack (verificar contra `propuesta/00 - PROPUESTA-COMERCIAL.md`).
|
||
3. Cifras de horas cuadran con `Seguimiento-horas.md` (8.00 h E1, 30 h totales).
|
||
4. Fechas cuadran con `bitacora/REGISTRO.md` #42–#43 (22-jul, 23-jul, Azure sem 21, CI/CD 24).
|
||
5. El enlace desde `Plan-actividades.md` navega al nuevo documento.
|
||
6. Confirmar que NADA se escribió en el repo del cliente (`balam-plataforma` limpio: `git -C ...balam-plataforma status`).
|