diff --git a/AGENTS.md b/AGENTS.md index a01f808..dab671c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -7,15 +7,19 @@ | `npm run dev` | Start Next.js dev server on port 3000 | | `npm run build` | Production build (runs TypeScript check) | | `npm run lint` | ESLint (flat config, eslint-config-next) | -| `npx tsx prisma/seed.ts` | Run seed (upserts all data, idempotent) | -| `npx prisma migrate dev` | Create/apply migration | -| `npx prisma generate` | Regenerate Prisma client | -| `npx prisma studio` | Prisma Studio GUI | +| `npm run db:seed` | Run seed (upserts all data, idempotent) | +| `npm run db:migrate` | Create/apply migration (`prisma migrate dev`) | +| `npm run db:generate` | Regenerate Prisma client | +| `npm run db:studio` | Prisma Studio GUI | + +**There is no test suite** — no runner, no test files, in either backend. Verification is `npm run build` (typechecks) + `npm run lint`. Don't claim a change is verified on the strength of a build alone; exercise the affected route or page. **Windows environment.** Use `start.bat` / `stop.bat` to manage Docker PostgreSQL + Next.js together. PowerShell is the shell. Paths with brackets (e.g. `[id]`) require `-LiteralPath` in PowerShell, not `-Path`. **Two backends, one database.** The Next.js app (`src/`, port 3000) and a standalone Python FastAPI service (`api/`, port 8000) both talk to the same PostgreSQL DB. Prisma owns the schema/migrations; the Python API reads/writes the same tables independently. `docker-compose.yml` runs `postgres` + the `api` service; Next.js is run separately via `npm run dev` / `start.bat`. +**Three compose files, and two of them are the same file.** `docker-compose.yaml` is a byte-identical copy of `docker-compose.coolify.yml` — it exists only so Coolify's default detection finds the production stack. Local dev is `docker-compose.yml` (postgres with port 5432 published + api). Because `.yml` and `.yaml` both exist, a bare `docker compose` warns about ambiguity before resolving to `docker-compose.yml`; pass `-f docker-compose.yml` explicitly, as `start.bat` does. **When you edit the Coolify stack, edit both `docker-compose.coolify.yml` and `docker-compose.yaml`** or Coolify deploys the stale copy. + ## Prisma 7 — Critical Gotchas - **Prisma client is NOT at `@prisma/client`.** It's generated to `src/generated/prisma/` and imported as `@/generated/prisma/client`. @@ -46,6 +50,25 @@ - **Bucéfalo CRM plan prices** (in `calculators.ts`, NOT the DB): basico=$1,000, estandar=$3,500, premium=$4,500, empresarial=$7,500 (monthly). - **Financing** lives in the `FinanciamientoPlan` table (3/6/9/12 months). Formula: `comisionTotal = monto × comision%`, `pagoMensual = (monto + comisionTotal) × (1 + tasa) / meses`, then add 16% IVA. Both backends must keep this formula identical. +### Charge models (`ServicioCotizado.modeloCobro`) + +A quoted line item is `fijo` (default), `horas`, `retainer`, or `demanda` — see `MODELOS_COBRO` in `calculators.ts`. The time-based three are `MODELOS_COBRO_TIEMPO`. Supporting fields: `esPersonalizado`, `horas`, `tarifaHora`, `montoMinimo`, `horasIncluidas`. `TARIFA_HORA_DEFAULT = 700`. + +**`precio` is always the authoritative total.** For retainer and demanda lines, `horas × tarifaHora` is display/comparison metadata only — never re-derive a total from it. `calcularTotalesOpcion` and the PDF/Excel builders all sum `precio`. + +### Doble propuesta (two-option quotes) + +`Cotizacion.esDoble` turns one quote into two comparable proposals. Each `ServicioCotizado.opcion` is `"1"`, `"2"`, or `"ambas"` (shared by both). `opcionesMetadata` (Json) holds per-option `titulo` / `descripcion` / `noIncluye` (`MetaOpcion`). `calcularTotalesOpcion(servicios, "1" | "2")` sums lines matching that option **plus** all `"ambas"` lines. Anything that renders or totals a quote must handle both the single and double shape. + +### Registro de horas (hours log → payment notes) + +`RegistroHoras` tracks worked time against a quote so the client can be billed for it. Only offered when `esCotizacionPorTiempo(servicios)` is true (i.e. some line uses a time-based `modeloCobro`). + +- `estadoPago` is `"por_pagar"` (default) or `"pagada"`, with `fechaPago` stamped on transition. The two buckets must stay separated in totals — pending is what goes on the payment note, paid is history. `resumenPagoHoras` / `esPagada` in `calculators.ts` are the only place that logic should live. +- Routes: `GET|POST /api/cotizaciones/[id]/horas` (GET takes `?from=&to=` day filters), `PATCH|DELETE .../horas/[registroId]`, and `POST .../nota-horas` which renders the PDF **server-side** via `src/lib/nota-horas-pdf.ts` (no browser URL). +- Hours are entered as `horaInicio`/`horaFin` strings and converted by `calcularHorasRango`. Dates come in as `YYYY-MM-DD` and must go through `fechaRegistroDesdeISO` to avoid UTC off-by-one — don't `new Date(iso)` directly. +- Grouping for display/PDF: `ModoAgrupacion` = `detalle | dia | semana | mes` via `periodoAgrupacion`. + ## Auth - **JWT sessions** (`src/lib/auth.ts`) signed with `jose` (HS256, 7-day expiry), stored in the `cotizador-session` httpOnly cookie. `JWT_SECRET` env var is **required** (throws at startup if missing). @@ -66,23 +89,33 @@ ``` src/ app/ - (app)/ # Authed route group: dashboard, cotizaciones, clientes, catalogo, configuracion (has its own layout.tsx + Sidebar) - api/ # Next.js route handlers (REST): auth, catalogo, categorias, cotizaciones, configuracion, paquetes, export, import + (app)/ # Authed route group: dashboard, cotizaciones, clientes, catalogo, configuracion (has its own layout.tsx + Sidebar + DialogProvider) + api/ # Next.js route handlers (REST): auth, catalogo, categorias, cotizaciones (+ horas, nota-horas, precio), + # configuracion, paquetes, export, import, health login/ # Public login page - components/ # CotizacionForm, ExportButtons, EstadoBadge, layout/Sidebar - lib/ # auth, db, store, calculators, pdf-generator, schemas, config-helpers + components/ # CotizacionForm (~1.4k lines), ExportButtons, EstadoBadge, layout/Sidebar, ui/DialogProvider + lib/ # auth, db, store, calculators, schemas, config-helpers, + # pdf-generator (quote PDF), nota-horas-pdf (hours-note PDF), excel-builder generated/prisma/ # Prisma client output (gitignored) prisma/ - schema.prisma # 13 models (User, Cliente, Cotizacion, Categoria, Paquete, FasePaquete, + schema.prisma # 14 models (User, Cliente, Cotizacion, Categoria, Paquete, FasePaquete, # ServicioCatalogo, ServicioPaquete, ServicioCotizado, PlanBucefaloCotizacion, - # Configuracion, Bono, FinanciamientoPlan) + # RegistroHoras, Configuracion, Bono, FinanciamientoPlan) seed.ts # All catalog data (services, categorias, bonos, planes, config) — idempotent upserts - migrations/ # 3 migrations + migrations/ # 10 migrations api/ # Standalone Python FastAPI + MCP server (see below) +docs/ # Business/product notes (Spanish), not code docs ``` - **Zustand store** (`src/lib/store.ts`) holds the cotización draft. Used by both the new (`cotizaciones/nueva`) and edit (`cotizaciones/[id]/editar`) pages, both of which render `CotizacionForm.tsx`. - **ExportButtons.tsx** has 4 variants: `ExportExcelButtonSaved` / `ExportPDFButtonSaved` (GET by ID) and `ExportExcelButtonDraft` / `ExportPDFButtonDraft` (POST with body). +- **Business logic belongs in `calculators.ts`**, not in components or route handlers. It's the shared source of truth for totals, charge models, hours, phases, and formatting — and the file the Python `calculators.py` mirrors. + +## UI Conventions + +- **Never use the browser's native `confirm()` / `alert()` / `prompt()`.** They render as "«domain» dice…" and break the brand. Use the platform's own dialogs: `useConfirm()`, `usePrompt()`, `useToast()` from `@/components/ui/DialogProvider`, mounted once in `src/app/(app)/layout.tsx`. `confirm` and `prompt` return promises (`boolean` / `string | null`); pass `danger: true` for destructive actions. +- Everything user-facing is in **Spanish**. Code identifiers are Spanish too (`cotizacion`, `servicio`, `horas`) — match the surrounding naming rather than introducing English terms. +- Icons come from `lucide-react`. Colors use the CSS custom properties from `globals.css` (`bg-card-bg`, `border-border`, `text-primary`, `text-muted`), not hardcoded Tailwind palette values. ## Python API (`api/`) — Optional Second Backend diff --git a/docs/BI-propuesta-consultiva-IA.md b/docs/BI-propuesta-consultiva-IA.md new file mode 100644 index 0000000..3cb312e --- /dev/null +++ b/docs/BI-propuesta-consultiva-IA.md @@ -0,0 +1,859 @@ +# Business Intelligence — Plugin de Propuesta Consultiva con IA + +> **Qué es este documento:** el análisis de negocio, la filosofía y los lineamientos para una **futura** implementación de un plugin que, a partir de transcripciones de reuniones y notas de texto, genere un **segundo documento** de cotización — narrativo y consultivo — como complemento al documento económico que hoy produce el Cotizador E3 de forma manual. +> +> **Qué NO es:** una especificación técnica cerrada ni un plan de implementación. No hay código aquí. Es el mapa que debe leerse antes de escribir la primera línea. +> +> **Fuentes analizadas:** +> - Proyecto real: `H:\MegaSync\Proyectos\Cotizador` (Next.js 16 + Prisma 7 + PostgreSQL, con API Python/MCP paralela) +> - Plantilla de referencia: `D:\Documents\plantilla_cotizacion.html` +> - Base de conocimiento: `Guia_Onboarding_Cliente_y_Ruta_de_Trabajo.md`, `08-Monetizacion-Onboarding-Pricing-Seguimiento.md`, `Onboarding-Cliente/04-Sesion-Propuesta-y-Continuidad.md`, `sintesis/s2-Pricing-Cobranza.md`, `sintesis/s8-Prompts-Plantillas.md`, `00-Guia-de-Uso-y-Checklist-Calidad.md` +> +> **Fecha:** 2026-07-28 · **Estado:** análisis previo a implementación + +--- + +## 1. Resumen ejecutivo + +El Cotizador E3 hoy resuelve muy bien **el qué y el cuánto**: un catálogo de servicios por fase, precios, IVA, financiamiento, planes Bucéfalo, exportación a PDF y Excel. Es un motor contable y comercial sólido. + +Lo que no resuelve —y lo que la base de conocimiento identifica como el factor que multiplica el ticket entre 3x y 15x— es **el por qué**: el diagnóstico del dolor del cliente en sus propias palabras, la cuantificación del costo de no hacer nada, el anclaje del precio en el valor anual, y la narrativa que permite al cliente defender la inversión internamente. + +Ese "por qué" ya se está capturando de forma parcial pero **se está tirando a la basura**: + +- El campo `observaciones` de `Cotizacion` y el campo `notas` de cada `ServicioCotizado` se guardan en la base de datos y **no se imprimen ni en el PDF ni en el Excel** (verificado por búsqueda en `src/lib/pdf-generator.ts` y `src/lib/excel-builder.ts`: cero coincidencias). +- Las reuniones de discovery generan transcripciones que hoy viven fuera del sistema. +- La plantilla HTML de `D:\Documents\` ya tiene la estructura narrativa correcta (diagnóstico con semáforo, exclusiones explícitas, argumentos de venta, estado de materiales) pero se llena **a mano**, una por una. + +**La oportunidad:** un plugin que lea el contexto humano disperso (transcripción + notas + observaciones + la cotización ya armada) y genere un segundo archivo —el documento consultivo— siguiendo la filosofía de la plantilla HTML, sin tocar un solo número. + +**La tesis central, en una frase:** + +> El documento manual es la **fuente de verdad económica**. El documento de IA es la **fuente de verdad narrativa**. La IA nunca inventa un precio; sólo explica el que ya existe. + +--- + +## 2. Inventario: los tres activos que ya existen + +### 2.1 El Cotizador real (`H:\MegaSync\Proyectos\Cotizador`) + +**Stack.** Next.js 16 (App Router) + React 19 + Tailwind v4 + Zustand · Prisma 7 (cliente generado en `src/generated/prisma`, driver adapter `PrismaPg`) · PostgreSQL 16 en Docker · JWT con `jose` en cookie httpOnly · PDFKit server-side · despliegue en Coolify. + +**Segundo backend.** Un servicio FastAPI en `api/` que expone el mismo dominio como REST **y un servidor MCP en `/mcp`** con 12 herramientas y 3 recursos para agentes de IA. Esto es el hallazgo arquitectónico más importante del inventario: **el proyecto ya tiene una superficie diseñada para que una IA lo opere.** + +Herramientas MCP existentes: `buscar_servicios`, `crear_cotizacion`, `obtener_cotizacion`, `listar_cotizaciones`, `cambiar_estado_cotizacion`, `actualizar_precio_servicio`, `duplicar_cotizacion`, `calcular_financiamiento`, `generar_pdf_cotizacion`, `obtener_configuracion`, `listar_bonos`, `listar_planes_bucefalo`. Recursos: `cotizador://servicios`, `cotizador://categorias`, `cotizador://configuracion`. + +**Modelo de datos relevante.** + +| Modelo | Campos que importan para el plugin | +|---|---| +| `Cotizacion` | `numero`, `fecha`, `vigencia`, `moneda`, `esquemaPago`, `estado`, `esDoble`, `opcionesMetadata` (JSON), **`observaciones`** | +| `ServicioCotizado` | `nombre`, `fase`, `tipoPago`, `precio`, `tiempoEntrega`, `entregables` (JSON), `beneficios` (JSON), **`notas`**, `modeloCobro`, `horas`, `tarifaHora`, `opcion` | +| `ServicioCatalogo` | `precioBase`, `descripcion`, `entregablesDefault`, `fase`, `nivel`, `variante` | +| `Cliente` | `nombre`, `empresa`, `email`, `telefono`, `rfc` | +| `RegistroHoras` | `fecha`, rango horario, `horas`, `tarifaHora`, `descripcion`, `estadoPago` | +| `PlanBucefaloCotizacion` | `nivel`, `precio` | +| `FinanciamientoPlan` | `meses` (3/6/9/12), `tasa`, `comision`, `montoMinimo`, `iva` | +| `Bono` | `numero`, `titulo`, `descripcion` | +| `Configuracion` | key-value: `color_primario`, `color_secundario`, `logo_base64` | + +**Reglas de negocio ya codificadas** (`src/lib/calculators.ts`): +- `IVA_RATE = 0.16` +- `TARIFA_HORA_DEFAULT = 700` +- Número de cotización: `UJ{YY}{MM}{InicialesAsesor}{seq}` (ej. `UJ2605AG001`) +- Vigencia = 15 días hábiles desde la fecha (excluye sábado y domingo) +- 4 fases: F0 Auditoría · F1 Setup/Infra · F2 Publicidad/Manejo · F3 Contenido/SEO +- Planes Bucéfalo mensuales: básico $1,000 · estándar $3,500 · premium $4,500 · empresarial $7,500 (hardcodeados en `calculators.ts`, **no en la BD**) +- Modelos de cobro: `fijo`, `horas`, `retainer`, `demanda` +- 6 paquetes PyME pre-armados + paquete "General" con todo el catálogo + +**El hallazgo clave: `esDoble` ya existe.** El sistema soporta cotización de doble propuesta: `esDoble: boolean` + `opcionesMetadata` con estructura `{ "1": {titulo, descripcion, noIncluye}, "2": {...} }`, y cada `ServicioCotizado` puede asignarse a la opción `"1"`, `"2"` o `"ambas"`. La herramienta MCP `crear_cotizacion` ya acepta `es_doble=true`. **Ya hay una vía nativa para presentar opciones comparables** — y la base de conocimiento dice que 3 opciones cierran 16-28% más alto. Está a mitad de camino. + +### 2.2 La plantilla HTML (`D:\Documents\plantilla_cotizacion.html`) + +Un documento de 690 líneas, autocontenido, con tokens CSS, tipografía editorial (Playfair Display serif + DM Sans), tema oscuro (`--bg: #0a0f1e`), responsive y con reglas `@media print` (`page-break-inside: avoid`). + +Su valor no es el CSS. Es **la arquitectura argumental**: + +| # | Sección | Función retórica | +|---|---|---| +| Hero | Título + subtítulo + 4 metadatos (elaborado por / cliente / plataforma / vigencia) | Encuadre y contexto | +| 01 | **Diagnóstico del proyecto** — un `.quote` con el insight clave + filas con semáforo (`dot-red` problema crítico, `dot-amber` área de mejora, `dot-blue` oportunidad, `dot-green` ventaja existente) | Demuestra que entendiste el negocio antes de vender | +| 02 | **Alcance y desglose económico** — filas categoría / entregable+descripción / precio, más caja de totales (subtotal, descuento, IVA, total) | El qué y el cuánto | +| 03 | **Qué no incluye esta propuesta** — lista con ✕ | Anti-scope-creep, preventivo | +| 04 | **Por qué tiene sentido esta solución** — pares etiqueta/explicación | Argumentos de venta traducidos a beneficio | +| 05 | **Plan de mantenimiento opcional** — dos tarjetas (mensual vs anual, una `.featured`) con features `highlight` / `good` / `muted` | Siembra de recurrencia, con límites explícitos | +| 06 | **Estado de materiales del cliente** — dos tarjetas: materiales (`done`/`pend`) y decisiones pendientes (`pend`/`neutral`) | Transparencia y transferencia de responsabilidad | +| Footer | Datos de contacto + condiciones (50/50, CFDI, avance condicionado a materiales, cambios se cotizan aparte) | Blindaje comercial | + +**El semáforo de la sección 01 es el activo intelectual más valioso de la plantilla.** Obliga a clasificar cada hallazgo por urgencia — exactamente lo que la base de conocimiento pide en las 3 Preguntas de Oro. Y el marcador `dot-green` ("ventaja existente") obliga a reconocer lo que el cliente ya hizo bien, que es el detalle que convierte una propuesta en una conversación entre pares. + +**La sección 06 es la que resuelve la honestidad de la IA.** Ver §10.2. + +### 2.3 La base de conocimiento (vault de Obsidian) + +Sintetizada desde 91 transcripts. Lo que aporta al plugin, en orden de utilidad: + +**Framework de diagnóstico (Fase 2 del playbook):** +- Las 3 Preguntas de Oro: (1) ¿cuál es el problema de **negocio**, no técnico? (2) ¿cuánto le está costando hoy? (3) ¿cuánto ingreso/ahorro esperas en 12 meses? +- Costo desglosado en 4 dimensiones: dinero directo · tiempo del equipo · costo de oportunidad · costo de error humano +- Filtro de viabilidad de 4 preguntas: costo de no hacer nada · ¿los datos existen HOY? · ¿quién es el usuario final real? · ¿qué pasa si funciona? +- The Mom Test: preguntas ancladas en el pasado ("¿cómo lo resolvieron la última vez?"), no en el futuro hipotético + +**Framework de pricing:** +- `Valor Anual = (horas/mes × costo horario × 12) + costo anual de errores + ingresos recuperados` +- `Precio objetivo = 15% a 25% del Valor Anual` +- Marco VALOR (techo) / COSTO real (piso, 2-3× horas técnicas) / MERCADO +- Anclaje: presentar A (2× objetivo) → B (objetivo, se elige 60%) → C (50% del objetivo) +- 3 opciones cierran **16-28% más alto** que una sola + +**Reglas transversales de comunicación** (del checklist de calidad): +1. Hablar de resultados, no de herramientas +2. **Usar las palabras del cliente** — registrar frases textuales del dolor y reutilizarlas +3. Investigar hechos pasados +4. 80% habla el cliente / 20% el consultor +5. **Distinguir evidencia de hipótesis** — etiquetar cifras como confirmadas, estimadas o pendientes de validar +6. No prometer solución antes de validar +7. Recapitular y confirmar +8. Comunicar riesgos temprano + +**Separación de tres conceptos** (Sesión 4 de onboarding): proyecto inicial ≠ mantenimiento ≠ evolución/retainer. Cada uno con su alcance, precio y forma de contratación explícitos. + +**Criterio ético de monetización:** una mejora posterior se propone sólo si hay evidencia de que resuelve un problema real, el cliente puede decidir libremente, y el nuevo alcance/precio/plazo quedan claros. + +**Los 15 errores de monetización más caros** — de los cuales el plugin puede prevenir directamente: mandar propuesta con 1 sola opción (#4), aceptar scope creep sin orden de cambio (#7), entregar sin documentación (#8), no ofrecer retainer post-entrega (#9), vender habilidades técnicas en vez de resultados (#13). + +--- + +## 3. Diagnóstico: la brecha entre los tres activos + +Aplico a este proyecto el mismo semáforo de la plantilla. + +### 🔴 Problema crítico — el contexto humano se captura y se descarta + +`Cotizacion.observaciones` y `ServicioCotizado.notas` existen en el esquema, se llenan en el formulario (`CotizacionForm.tsx:1222`, placeholder literal *"Notas adicionales para la cotizacion..."*) y **no aparecen en ningún exportador**. Es información de discovery que el asesor ya se tomó el trabajo de escribir y que muere en la base de datos. + +Esto no es sólo desperdicio: es la evidencia de que el sistema fue diseñado como calculadora y no como instrumento de venta consultiva. El plugin no tiene que crear el canal de entrada — **tiene que empezar a leerlo.** + +### 🔴 Problema crítico — el pricing es de menú, la filosofía es de valor + +El Cotizador calcula desde `ServicioCatalogo.precioBase`: precio fijo por servicio, sumado. Es pricing de catálogo. La base de conocimiento predica pricing por valor: 15-25% del valor anual del problema. + +**No son incompatibles, pero hoy no se hablan.** El precio de catálogo es el piso operativo y la base de facturación (con CFDI, IVA, RFC — cosas que un porcentaje del valor anual no te da). El valor anual es el argumento que justifica ese precio ante el cliente. + +El plugin no debe reemplazar uno por el otro. Debe **superponer la capa de valor sobre la capa contable**: tomar el total que el humano ya fijó y demostrar que representa X% del valor anual del problema. Si el asesor cotizó $50,000 MXN y la IA detecta en la transcripción un dolor de ~$400,000 MXN/año, la propuesta escribe *"la inversión equivale al 12.5% del costo anual del problema"* — sin mover el $50,000. + +### 🟠 Área de mejora — la doble propuesta existe pero está subutilizada + +`esDoble` + `opcionesMetadata` da dos opciones. La filosofía pide tres, con anclaje psicológico (cara primero). El plugin puede generar el **argumento** de las tres opciones en su documento narrativo aun cuando el documento económico sólo tenga dos, o recomendar al asesor cómo estructurar las dos que sí caben. + +Aquí hay que ser honesto: **no** hay que forzar tres opciones si el proyecto no las admite. La Sesión 4 lo dice explícito: *"Cuando haya alternativas reales, usa tres opciones… las otras no son una trampa ni una lista de extras artificiales."* + +### 🟠 Área de mejora — la base de conocimiento es de otro negocio + +Esto es una tensión real que hay que documentar antes de que alguien la descubra a medio proyecto: + +| | Base de conocimiento | Cotizador E3 | +|---|---|---| +| Negocio | Freelance/consultoría de automatización con Python | Consultoría de digitalización y marketing digital | +| Geografía | LATAM, cobro internacional | Querétaro, MX | +| Moneda | USD (Wise/Stripe/Payoneer) | MXN con IVA 16% y CFDI | +| Rangos | $300 – $25,000 USD | $7,490 – $90,800 MXN (paquetes) | +| Servicios | Scripts, RAG, dashboards, APIs | Ads, SEO, WordPress, CRM Bucéfalo, contenido | +| Recurrencia | Retainer de mantenimiento de software | Mensualidades de manejo de pauta y CRM | + +**Los frameworks son transferibles; las cifras no.** La IA debe importar el *método* de diagnóstico, el *marco* de pricing y las *reglas* de comunicación — y jamás las tablas de precios en USD. Si el plugin sugiere "$1,800 USD" en una cotización de E3, es un bug, no una feature. + +### 🔵 Oportunidad — el servidor MCP ya está construido + +`api/app/mcp/server.py` (453 líneas) + `tools.py` (305 líneas) exponen el catálogo, las cotizaciones y la configuración a agentes. El plugin no necesita una capa de acceso a datos nueva: puede consumir la que existe. Y como los cálculos viven duplicados en `src/lib/calculators.ts` y `api/app/services/calculators.py` con paridad obligatoria, la IA puede **leer** totales sin riesgo de recalcularlos mal. + +### 🔵 Oportunidad — la plantilla HTML es un contrato de salida listo + +No hay que diseñar el formato del segundo documento. La plantilla ya define las secciones, la jerarquía y el vocabulario visual. El trabajo es mapear cada sección a su fuente de datos (ver §7) y dejar que la IA llene el contenido, no la estructura. + +### 🟢 Ventaja existente — el asesor ya hace el trabajo difícil + +El humano ya: califica al cliente, corre la reunión, elige servicios del catálogo, ajusta precios, decide el esquema de pago. El plugin no reemplaza ese juicio. **Se monta sobre él.** Esto reduce drásticamente el riesgo: si la IA falla, el documento manual sigue siendo entregable. + +### 🟢 Ventaja existente — el vault ya tiene el system prompt esbozado + +`sintesis/s8-Prompts-Plantillas.md` §1 tiene un system prompt maestro, §3 un prompt de diagnóstico de proyecto, §4 un prompt de propuesta comercial y §9 una plantilla de output estándar. No hay que empezar de cero — hay que **adaptar de USD/Python a MXN/marketing digital**. + +--- + +## 4. Filosofía: los 10 principios del plugin + +Estos son los principios no negociables. Si una decisión de implementación los contradice, la decisión está mal. + +### P1 · La IA no toca los números + +La IA **lee** precios, totales, IVA, vigencia y financiamiento. **Nunca los calcula, propone ni modifica.** Todo número que aparezca en el documento de IA debe ser byte-por-byte el mismo que produjo `calculators.ts`. + +*Por qué:* un precio inventado por la IA en un documento con el logo de E3 es un pasivo comercial y potencialmente fiscal. Además destruye la confianza en todo el resto del documento. + +*Implicación técnica:* los totales se inyectan como datos ya calculados en el prompt y se instruye a la IA a citarlos literalmente; idealmente el render final los toma del objeto de cotización, no del texto generado. + +### P2 · Dos documentos, dos trabajos, cero solapamiento + +| | Documento 1 (manual, PDF/Excel) | Documento 2 (IA, HTML) | +|---|---|---| +| Autor | Asesor humano | IA, revisada por el asesor | +| Función | Contractual y económica | Consultiva y narrativa | +| Contenido | Servicios, precios, totales, condiciones | Diagnóstico, valor, argumentos, exclusiones, pendientes | +| Números | **Fuente de verdad** | Espejo, sólo citados | +| Si se contradicen | Gana este | Se corrige este | +| Vive en | `pdf-generator.ts` / `excel-builder.ts` | Nuevo generador | + +El documento 2 es un **superconjunto narrativo** y un **subconjunto numérico** del documento 1. + +### P3 · Toda afirmación es trazable + +Cada dato que la IA escriba sobre el cliente debe apuntar a su origen: una línea de transcripción, un archivo de notas, un campo del formulario, o el catálogo. Si no hay origen, no se escribe. + +*Implicación:* el contrato de salida (§8) lleva un campo `evidencia` por afirmación. El documento renderizado puede ocultarlo al cliente, pero el asesor debe poder auditarlo antes de enviar. + +### P4 · Evidencia, estimación e hipótesis se etiquetan distinto + +Directo de la regla 5 del checklist de calidad. Tres estados: + +- **Confirmado** — el cliente lo dijo textualmente o hay un dato duro. +- **Estimado** — se derivó de algo que el cliente dijo, con un cálculo explícito. +- **Por validar** — hipótesis del consultor que aún nadie confirmó. + +Un "estimado" presentado como "confirmado" es la forma más rápida de perder credibilidad en una reunión de presentación. La IA debe marcar cada cifra. + +### P5 · Las palabras del cliente son sagradas + +La sección de diagnóstico debe usar frases textuales del cliente, no paráfrasis corporativas. Si en la transcripción dice *"se nos van los clientes porque nadie contesta el WhatsApp el fin de semana"*, eso va entre comillas — no *"oportunidades de mejora en la gestión omnicanal de la comunicación"*. + +*Regla operativa:* el bloque `.quote` de la sección 01 debe ser **siempre** una cita literal, nunca una síntesis de la IA. + +### P6 · Se vende resultado, no herramienta + +Error #13 de la lista de errores de monetización. Traducir toda capacidad técnica a tiempo recuperado, errores evitados, ingresos protegidos o tranquilidad operativa. + +*Malo:* "Configuración de Google Ads con estructura SKAG y scripts de puja automatizada." +*Bueno:* "Cada peso de pauta se dirige a las búsquedas que sí compran, en lugar de repartirse entre términos que sólo generan clics. Reportamos costo por prospecto real, no impresiones." + +### P7 · Lo que NO incluye vale tanto como lo que sí + +La sección 03 de la plantilla no es un trámite: es prevención de scope creep, que según la base de conocimiento promedia **27% de sobrecosto** en proyectos sin control de alcance. La IA debe generar exclusiones **específicas del proyecto**, no genéricas. + +*Malo:* "No incluye servicios no mencionados." +*Bueno:* "No incluye la migración del histórico de 4 años de pedidos que mencionaron en la reunión; eso se evalúa como fase 2 cuando el sistema base esté operando." + +### P8 · Mantenimiento y evolución van separados, con límites por escrito + +De la Sesión 4: *"No prometas mantenimiento gratuito indefinido y no vendas un retainer como si incluyera trabajo ilimitado."* La sección 05 debe listar explícitamente qué **no** cubre el plan (la plantilla ya tiene la clase `.plan-feat.muted` con ✕ para eso). El backlog de evolución se registra aparte y **no se compromete**. + +### P9 · La incertidumbre se declara, no se rellena + +Si falta información, la IA **no la inventa ni la omite silenciosamente**: la escribe en la sección 06 como material o decisión pendiente. Ver §10.2 — esto es el mecanismo central de honestidad del sistema. + +### P10 · El asesor aprueba antes de enviar + +El documento de IA nace en estado borrador. Nadie lo manda al cliente sin que un humano lo lea. El plugin es un copiloto de redacción, no un autopiloto de ventas. + +*Corolario:* el flujo de UI debe hacer que revisar sea fácil (diff, semáforo de confianza, evidencia expandible), no que aprobar sea rápido. + +--- + +## 5. Insights de monetización que hay que codificar + +Estos son los mecanismos concretos de la base de conocimiento que el plugin debe hacer operativos. Cada uno con su traducción a comportamiento del sistema. + +| # | Insight de la base de conocimiento | Cómo lo codifica el plugin | +|---|---|---| +| M1 | El cliente describe síntomas; tu trabajo es diagnosticar la enfermedad | La sección 01 nunca repite la petición del cliente ("quiero una página web"); reformula al problema de negocio ("pierden prospectos porque no tienen dónde mandarlos desde los anuncios") | +| M2 | El costo del problema se desglosa en 4 dimensiones | La IA busca en la transcripción las 4 dimensiones y las presenta con su etiqueta de confianza; las que faltan van a la sección 06 como pendiente de validar | +| M3 | Precio = 15-25% del valor anual | La IA calcula el **ratio inverso**: dado el total que fijó el humano y el valor anual detectado, reporta qué porcentaje representa. Si sale <10%, señala al asesor que probablemente subcotizó. Si sale >40%, señala que va a haber objeción de precio | +| M4 | 3 opciones cierran 16-28% más alto | Si `esDoble = false`, el plugin sugiere al asesor un esquema de 2-3 opciones basado en los servicios ya elegidos (quitando o agregando del mismo catálogo, sin inventar servicios) | +| M5 | Anclaje: la opción cara primero | En el render de la sección de opciones, el orden es A (mayor) → B (recomendada, `.featured`) → C (esencial) | +| M6 | La objeción de precio se responde con alcance, no con descuento | El documento incluye, en notas internas para el asesor (no visibles al cliente), el "plan de recorte": qué servicios quitar primero si el cliente pide bajar el precio, ordenados por menor impacto en el resultado prometido | +| M7 | Anticipo 50% obligatorio antes de empezar | El footer lo enuncia siempre; no es opcional ni negociable por la IA | +| M8 | Updates 2×/semana aumentan confiabilidad percibida +125% | La propuesta incluye el compromiso de cadencia de comunicación como **parte del alcance**, no como cortesía | +| M9 | El retainer se ofrece a las 2 semanas post-entrega, no al inicio | La sección 05 presenta el mantenimiento como **opción con límites explícitos**, nunca como requisito ni como amenaza velada ("para que no se rompa") | +| M10 | Las 3 capas de documentación triplican la tarifa | Los entregables documentales (README ejecutivo, registro de decisiones, guía de mantenimiento — adaptados a marketing digital: manual de operación de campañas, bitácora de decisiones de segmentación, guía de qué puede ajustar el cliente solo) se listan como entregables con valor, no como anexos | +| M11 | Red flags del cliente | El plugin genera, en notas internas, una sección de riesgo: red flags detectadas en la transcripción (pidió descuento antes de entender el valor, no hay decisor presente, no hay cifra del problema, "hagan todo y luego vemos") | +| M12 | Separar proyecto / mantenimiento / evolución | Tres bloques distintos en el documento, con encabezados que lo hagan obvio. El backlog de evolución dice explícitamente "no comprometido en esta propuesta" | +| M13 | Criterio ético: sólo se propone lo que hay evidencia de que resuelve un problema real | La IA **no puede** agregar un servicio del catálogo que el asesor no eligió. Puede señalar en notas internas *"el cliente mencionó X, que el catálogo cubre con el servicio Y; considera si aplica"* — pero no lo mete en la propuesta | + +### 5.1 El indicador de salud de la cotización + +De M3 y M11 sale la feature más útil para el negocio y la más fácil de implementar: un semáforo interno, sólo para el asesor, que evalúa la cotización antes de enviarla. + +| Señal | Cómo se calcula | Qué significa | +|---|---|---| +| Ratio precio/valor | `total / valor_anual_detectado` | <10% subcotizado · 15-25% en rango · >40% objeción probable | +| Dolor cuantificado | ¿hay al menos una cifra confirmada del costo del problema? | Si no: no hay ancla de valor; la propuesta va a competir por precio | +| Usuario final entrevistado | ¿la transcripción incluye a quien operará, no sólo al que firma? | Si no: riesgo de baja adopción | +| Decisor presente | ¿se identificó a quien autoriza el gasto? | Si no: riesgo de "voy a preguntar" | +| Exclusiones definidas | ¿hay al menos 3 exclusiones específicas? | Si no: riesgo de scope creep | +| Materiales pendientes | conteo de la sección 06 | Alto: la fecha de entrega es irreal | +| Red flags | conteo de señales de la lista | ≥2: evaluar si conviene el proyecto | + +Esto no es un adorno. Es **business intelligence real** sobre el pipeline: agregado en el tiempo, dice qué tipo de cotizaciones cierran y cuáles no. + +--- + +## 6. Anatomía del documento de IA + +El documento 2 hereda la estructura de la plantilla HTML, con tres cambios. Marcados **[NUEVO]** los que no existen en la plantilla. + +| Sección | Origen del contenido | Notas | +|---|---|---| +| **Hero** | `Cliente`, `Cotizacion.numero`, `fecha`, `vigencia`, `proyecto`, asesor | El subtítulo lo redacta la IA: una o dos oraciones que enmarcan el problema en lenguaje del cliente | +| **01 · Diagnóstico** | Transcripción + notas + observaciones | `.quote` = cita literal obligatoria. Filas con semáforo: al menos 1 rojo, 1 ámbar, 1 azul, 1 verde. Cada fila con etiqueta de confianza | +| **01b · Valor del problema** **[NUEVO]** | Transcripción, con las 4 dimensiones de costo | Tabla: dimensión / cifra / estado (confirmado/estimado/por validar) / evidencia. Cierra con el valor anual y el ratio de M3 | +| **02 · Resultados a lograr** **[NUEVO]** | Derivado del diagnóstico + entregables de los servicios elegidos | 3-5 resultados de negocio cuantificados. Es el puente entre problema y precio. La plantilla no lo tiene y la base de conocimiento lo pide en toda propuesta | +| **03 · Alcance y desglose económico** | `ServicioCotizado[]`, agrupado por fase y `tipoPago` | **Números literales del documento 1.** La IA sólo reescribe las descripciones en lenguaje de resultado (P6). Separar pago único de mensual, como ya hace el PDF | +| **04 · Opciones de inversión** | `esDoble` + `opcionesMetadata` | Sólo si hay opciones reales. Orden A → B(`.featured`) → C | +| **05 · Qué no incluye** | Transcripción (menciones fuera de alcance) + `opcionesMetadata.noIncluye` | Exclusiones específicas, nunca genéricas (P7) | +| **06 · Por qué tiene sentido** | `ServicioCotizado.beneficios` + diagnóstico | Cada beneficio amarrado a un hallazgo del diagnóstico. Si un beneficio no responde a ningún dolor detectado, se elimina | +| **07 · Plan de mantenimiento** | `PlanBucefaloCotizacion`, servicios `tipoPago: mensual`, `modeloCobro: retainer` | Con exclusiones explícitas (`.plan-feat.muted`). Mensual vs anual si aplica | +| **08 · Estado de materiales y decisiones** | Todo lo que la IA no pudo determinar + menciones de dependencias en la transcripción | **El canal de honestidad.** Ver §10.2 | +| **09 · Backlog de evolución** **[NUEVO]** | Fricciones mencionadas por el cliente que no entran en fase 1 | Con encabezado explícito: "registrado, no comprometido en esta propuesta" | +| **Footer** | `Configuracion` (logo, colores) + condiciones fijas | 50/50, CFDI, avance condicionado a materiales, cambios se cotizan aparte, MXN | +| **Anexo interno** **[NUEVO]** | Todo lo de §5.1 + M6 + M11 | **No se entrega al cliente.** Semáforo de salud, plan de recorte, red flags, evidencia completa. Puede ser una segunda página o un archivo aparte | + +### 6.1 Nota sobre el anexo interno + +Esta es la parte del diseño que más valor operativo tiene y la que más cuidado necesita. Un documento con "plan de recorte de precio" y "red flags del cliente" enviado por error al cliente es un incidente serio. + +Recomendación: **archivo separado**, nombre distinto y visualmente inconfundible (fondo distinto, marca de agua "INTERNO — NO ENVIAR"). No una sección oculta del mismo archivo, no un `display: none`, no un comentario HTML. + +--- + +## 7. Arquitectura de ingesta de contexto + +### 7.1 Las cuatro fuentes + +| Fuente | Formato | Volumen típico | Confianza | +|---|---|---|---| +| **Transcripción de reunión** | `.txt`, `.md`, `.vtt`, `.srt` | 60 min ≈ 9,000 palabras ≈ 13K tokens | Alta para citas; media para cifras (la gente redondea al hablar) | +| **Notas del asesor** | `.md`, `.txt` | 200-2,000 palabras | Alta — es interpretación experta | +| **Campos del formulario** | `Cotizacion.observaciones`, `ServicioCotizado.notas` | 50-500 palabras | Alta — escrito con intención | +| **Cotización estructurada** | JSON desde Prisma/MCP | 3-5K tokens | **Absoluta** — es la fuente de verdad | + +### 7.2 Precedencia en caso de conflicto + +Cuando dos fuentes se contradicen: + +``` +Cotización estructurada > Notas del asesor > Observaciones > Transcripción +``` + +*Razón:* la cotización es dato validado; las notas son interpretación experta posterior a la reunión; la transcripción es materia prima cruda con ruido de ASR, muletillas y correcciones en vivo ("son como 20 horas… no, más bien 30"). + +Si el conflicto es sobre una **cifra**, la IA no elige: lo reporta en la sección 08 como decisión pendiente. *"En la reunión se mencionaron 20 y 30 horas semanales en momentos distintos; confirmar la cifra antes de calcular el valor anual."* + +### 7.3 Pipeline de preprocesamiento + +Antes de que un token llegue al modelo: + +1. **Normalización de formato** — VTT/SRT a texto plano con marcas de tiempo opcionales; Markdown se conserva. +2. **Sanitización de PII** — Esto es obligatorio, no opcional. Las transcripciones contienen nombres de empleados, comentarios sobre desempeño, cifras salariales, quejas sobre terceros. Se redactan nombres de personas que no son el interlocutor comercial, y se marca cualquier mención de temas laborales, legales o de salud como bloque excluido del documento final. +3. **Segmentación por hablante** cuando el formato lo permite — permite aplicar la regla 80/20 y detectar si se entrevistó al usuario operativo o sólo al decisor. +4. **Conteo de tokens** con `client.messages.countTokens` (nunca con estimadores de otros proveedores) para decidir si cabe entero o requiere segmentación. +5. **Detección de idioma** — si la transcripción tiene mezcla, se preserva; el documento final va en español. + +### 7.4 Dónde se suben los archivos + +Tres opciones, en orden de preferencia: + +1. **Nuevo campo en la UI de cotización** — una zona de drop en la pestaña de observaciones. Los archivos se guardan como adjuntos vinculados a la `Cotizacion`. Requiere un modelo nuevo (`ContextoCotizacion`: `cotizacionId`, `tipo`, `nombreArchivo`, `contenido`/`ruta`, `createdAt`). +2. **Carpeta convenida en disco** — más simple para un MVP, peor para el despliegue en Coolify (contenedor sin volumen persistente por defecto). Sirve para probar localmente. +3. **Files API de Anthropic** (beta `files-api-2025-04-14`) — útil si se quiere pasar un PDF de reunión sin extraer texto; límite 500 MB. Requiere el header beta tanto en el upload como en el `messages.create` que lo referencia. + +Para el MVP: opción 2 para validar la calidad del output; opción 1 para producción. + +--- + +## 8. Contrato de salida + +La IA **no genera HTML**. Genera un objeto estructurado que un renderizador convierte a HTML usando la plantilla. Esto es crítico por tres razones: valida la estructura antes de renderizar, permite que el asesor edite campo por campo, y evita que la IA rompa el CSS o inyecte markup arbitrario. + +La API soporta esto nativamente con `output_config: { format: { type: "json_schema", schema: {...} } }` (structured outputs), disponible en Opus 5, Sonnet 5 y Haiku 4.5. En TypeScript hay helper de Zod: `zodOutputFormat()` + `client.messages.parse()`, que devuelve el objeto ya validado en `response.parsed_output`. + +### 8.1 Forma conceptual del schema + +``` +PropuestaConsultiva +├─ meta: { numeroCotizacion, cliente, empresa, proyecto, vigencia, asesor } +├─ hero: { titulo, subtitulo } +├─ diagnostico: +│ ├─ citaLiteral: { texto, origen } ← obligatorio, literal +│ └─ hallazgos[]: { urgencia: rojo|ambar|azul|verde, +│ titulo, descripcion, +│ confianza: confirmado|estimado|por_validar, +│ evidencia } +├─ valorProblema: +│ ├─ dimensiones[]: { tipo: dinero|tiempo|oportunidad|error, +│ descripcion, montoAnualMXN|null, +│ confianza, evidencia } +│ ├─ valorAnualEstimadoMXN: number|null +│ └─ notaMetodologia: string ← cómo se llegó a la cifra +├─ resultados[]: { enunciado, metrica, lineaBase|null, periodoMedicion } +├─ alcance: +│ └─ items[]: { fase, categoria, nombre, +│ descripcionResultado, ← reescritura en lenguaje de beneficio +│ precioMXN, tipoPago, tiempoEntrega } +├─ totales: { subtotal, descuento, iva, total, moneda } ← COPIADO, nunca calculado +├─ opciones[]|null: { etiqueta, titulo, descripcion, paraQuien, +│ incluye[], noIncluye[], recomendada: bool } +├─ exclusiones[]: { texto, razon, origen } ← específicas del proyecto +├─ beneficios[]: { etiqueta, texto, hallazgoRelacionado } ← amarrado al diagnóstico +├─ mantenimiento|null: +│ └─ planes[]: { nombre, periodicidad, precioMXN, incluye[], noIncluye[], destacado } +├─ pendientes: +│ ├─ materiales[]: { texto, estado: recibido|pendiente, bloqueaEntrega: bool } +│ └─ decisiones[]: { texto, quienDecide, fechaSugerida } +├─ backlogEvolucion[]: { problema, impactoPosible, evidencia, momentoSugerido } +└─ interno: ← NUNCA en el documento del cliente + ├─ salud: { ratioPrecioValor, dolorCuantificado, usuarioFinalEntrevistado, + │ decisorPresente, exclusionesDefinidas, materialesPendientes } + ├─ planRecorte[]: { servicio, impactoEnResultado: bajo|medio|alto, ordenSugerido } + ├─ redFlags[]: { señal, evidencia, severidad } + └─ huecos[]: { queFalta, porQueImporta, comoObtenerlo } +``` + +### 8.2 Restricciones del JSON Schema en la API + +Hay que diseñar el schema con estos límites en mente: + +- **Soportado:** tipos básicos, `enum`, `const`, `anyOf`, `allOf`, `$ref`/`$def`, formatos de string (`date`, `date-time`, `email`, `uri`, `uuid`). +- **No soportado:** esquemas recursivos, restricciones numéricas (`minimum`, `maximum`, `multipleOf`), restricciones de string (`minLength`, `maxLength`), restricciones complejas de array. +- **Obligatorio:** `additionalProperties: false` en todos los objetos. +- Los SDK de Python y TypeScript quitan automáticamente las restricciones no soportadas del schema enviado y las validan del lado del cliente — así que se pueden usar en Zod, sabiendo que la validación es local. +- Incompatible con citations (devuelve 400) y con prefill de mensaje de asistente. +- Primera petición con un schema nuevo tiene costo de compilación; después hay caché de 24h. + +### 8.3 Reglas de validación post-generación (código, no IA) + +Después de recibir el objeto y antes de renderizar: + +1. `totales` debe ser **idéntico** al de la cotización en BD. Si no, se descarta el objeto y se registra el fallo. Sin excepciones. +2. Cada `alcance.items[].precioMXN` debe existir en `ServicioCotizado`. Ningún item nuevo, ningún precio distinto. +3. `diagnostico.citaLiteral.texto` debe encontrarse como substring (normalizado) en alguna fuente de contexto. Si no aparece, se marca como no verificada y se pide revisión. +4. Todo `hallazgo` con `confianza: confirmado` debe tener `evidencia` no vacía. +5. `interno` se separa del objeto antes de pasar al renderizador del documento del cliente. +6. Si `valorProblema.valorAnualEstimadoMXN` es `null`, el documento **no** puede afirmar un ratio precio/valor. + +--- + +## 9. Lineamientos del prompt + +### 9.1 Estructura de capas + +El prompt se arma en tres capas, ordenadas por estabilidad (esto importa para el caché — ver §11.3): + +``` +Capa 1 — ESTABLE (idéntica en toda cotización, cacheable) + · Identidad y rol + · Filosofía (los 10 principios de §4) + · Frameworks de diagnóstico y pricing + · Reglas de marca y confidencialidad + · Contrato de salida y reglas de validación + · Catálogo de servicios activo (snapshot) + · Ejemplos de buena y mala redacción + +Capa 2 — SEMI-ESTABLE (por cliente o sector) + · Historial del cliente si es recurrente + · Notas del sector + +Capa 3 — VOLÁTIL (por cotización) + · Cotización estructurada (JSON) + · Transcripción sanitizada + · Notas y observaciones + · Instrucción específica del asesor +``` + +Nada dinámico —fechas, IDs, timestamps— debe entrar en la capa 1. Una fecha interpolada en el system prompt invalida el caché de todo lo que viene después. + +### 9.2 Reglas del system prompt + +Adaptando el prompt maestro de `s8-Prompts-Plantillas.md` §1 al contexto de E3: + +**Identidad.** Consultor senior de digitalización de negocios para PyMEs mexicanas. Redacta propuestas comerciales consultivas para Consultoría E3 (Querétaro, MX). No es vendedor: es diagnosticador. + +**Reglas de contenido.** +1. Cita fuentes internamente para cada dato del cliente. Si no hay fuente, no se escribe. +2. Etiqueta toda cifra como confirmada, estimada o por validar. +3. Traduce toda capacidad técnica a dinero, tiempo, riesgo evitado o tranquilidad operativa. +4. Usa las palabras textuales del cliente en el diagnóstico. +5. Nunca proponer un servicio que el asesor no eligió. +6. Nunca calcular, sugerir ni modificar un precio. +7. Cuando falte información, escribirla como pendiente — jamás rellenarla. +8. Español de México, tono cercano y profesional, tuteo con el cliente cuando el registro de la reunión lo permita. Sin lenguaje corporativo vacío (*sinergias*, *holístico*, *stakeholders*, *ecosistema*, *disruptivo*). +9. Moneda: MXN. IVA 16%. Facturación CFDI. +10. El CRM se llama **Bucéfalo**. No se menciona ninguna otra plataforma de CRM. +11. E3 ofrece únicamente servicios digitales. Si en la reunión se pidió algo de marketing tradicional o diseño para imprenta, va a la sección de exclusiones aclarando que no es un servicio de E3. + +**Prohibiciones explícitas.** +- No importar rangos de precio en USD de ninguna base de conocimiento. +- No incluir datos personales de empleados del cliente, información salarial, ni temas legales o de prestaciones. Si la reunión los tocó, se omiten del documento y se anota en el bloque interno que el tema debe manejarse por el canal correspondiente. +- No prometer resultados garantizados en pauta o posicionamiento (número de ventas, posición #1 en Google). Se prometen entregables, procesos y métricas de seguimiento. +- No prometer soporte ilimitado. +- No usar la palabra "garantizado" sobre resultados de mercado. + +**Formato de razonamiento.** Con `claude-opus-5` el thinking está activo por defecto. Conviene dejarlo así: el diagnóstico requiere razonamiento multi-paso (leer transcripción → detectar dolor → cuantificar → cruzar con servicios elegidos → redactar). No hay que desactivarlo. + +### 9.3 Descomposición en tareas + +Un solo prompt monolítico va a producir un documento mediocre en todas sus partes. Mejor pipeline de 3 pasos, cada uno con su schema: + +| Paso | Entrada | Salida | Modelo sugerido | +|---|---|---|---| +| **1 · Extracción** | Transcripción + notas | Hechos estructurados: dolores, cifras con confianza, citas literales, materiales mencionados, decisiones pendientes, red flags, menciones fuera de alcance | Opus 5 (`effort: high`) — es el paso que determina la calidad de todo lo demás | +| **2 · Diagnóstico y valoración** | Hechos del paso 1 + cotización estructurada + catálogo | Hallazgos con semáforo, valor del problema, resultados a lograr, ratio precio/valor, semáforo de salud | Opus 5 (`effort: high`) | +| **3 · Redacción** | Salida de pasos 1 y 2 | `PropuestaConsultiva` completa | Opus 5 (`effort: medium`) — con el análisis hecho, esto es principalmente escritura | + +Ventajas de separar: cada paso se evalúa por separado, el paso 1 se puede cachear si sólo cambia la cotización, y el asesor puede corregir los hechos del paso 1 antes de que se propaguen. + +### 9.4 Ejemplos en el prompt + +La base de conocimiento es enfática en que los **ejemplos positivos** funcionan mejor que las prohibiciones. Hay que incluir en la capa 1 al menos: + +- 2 ejemplos de diagnóstico bien escrito (uno con dolor cuantificado, uno donde falta la cifra y se declara) +- 2 ejemplos de descripción de servicio traducida a resultado +- 2 ejemplos de exclusión específica vs. genérica +- 1 ejemplo de sección 08 bien poblada +- 1 ejemplo de qué se ve cuando la transcripción es pobre (documento honesto con muchos pendientes, en lugar de documento inventado) + +Ese último ejemplo es el más importante y el que se suele omitir. + +--- + +## 10. Guardarraíles y riesgos + +### 10.1 Matriz de riesgos + +| Riesgo | Severidad | Mitigación | +|---|---|---| +| **La IA inventa un precio** | Crítica | P1 + validación programática §8.3.1. Los totales se toman del objeto de cotización en el render, no del texto generado | +| **La IA inventa una cifra del cliente** | Crítica | Etiqueta de confianza obligatoria + campo `evidencia` + validación de que las citas existan en las fuentes | +| **Fuga de datos personales de empleados** | Crítica | Sanitización de PII previa (§7.3.2) + prohibición explícita en el prompt + revisión humana | +| **El anexo interno llega al cliente** | Crítica | Archivo separado con marca visual inconfundible, nunca sección oculta (§6.1) | +| **Promesa de resultado garantizado en pauta/SEO** | Alta | Prohibición explícita + lista de palabras vetadas en validación post-generación | +| **Importación de precios en USD desde el vault** | Alta | Prohibición explícita + validación: ningún monto del documento puede estar en USD ni ser un número que no exista en la cotización | +| **Se menciona una plataforma de CRM que no es Bucéfalo** | Alta | Regla de marca en prompt + validación por lista de términos prohibidos | +| **La propuesta contradice el PDF manual** | Alta | Los dos documentos se generan del mismo objeto de cotización; el de IA se regenera si la cotización cambia (invalidación por `updatedAt`) | +| **Scope creep porque las exclusiones son genéricas** | Media | Requerir mínimo 3 exclusiones con campo `origen` no vacío; si la IA no puede justificarlas, el documento se marca como incompleto | +| **La IA propone servicios que el asesor no eligió** | Media | P1 + validación §8.3.2. Las sugerencias van sólo al bloque interno | +| **Costo de API descontrolado** | Baja | Ver §11.4: el costo es despreciable frente al ticket. Aun así: caché de prefijo + límite de tamaño de transcripción + conteo previo de tokens | +| **El asesor aprueba sin leer** | Media | La UI debe hacer visible el semáforo de salud y el conteo de afirmaciones sin evidencia **antes** del botón de aprobar | +| **Rechazo por clasificador de seguridad** | Baja | Manejar `stop_reason: "refusal"` antes de leer `content`; activar `fallbacks: "default"`. Poco probable en este dominio pero el código debe no reventar | + +### 10.2 El mecanismo central de honestidad + +Este es el diseño del que depende que el sistema sea confiable, y merece su propia sección. + +**El problema.** Todo generador de documentos con LLM tiene la misma tentación: cuando falta información, rellenar con plausible. Una propuesta comercial con una cifra inventada del negocio del cliente no es un error cosmético — es una mentira con el logo de E3 encima, que el cliente puede refutar en la reunión de presentación. + +**La solución.** La plantilla HTML ya trae el canal de salida para la incertidumbre: la **sección 06, Estado de materiales del cliente**, con sus dos tarjetas y tres estados (`done` ✓, `pend` ○, `neutral` ·). + +Se convierte esa sección en el destino obligatorio de todo hueco de información: + +``` +¿La IA no encontró el dato? + ├─ ¿Es un material que el cliente debe entregar? + │ → sección 08, tarjeta "Materiales", estado pendiente + ├─ ¿Es una decisión que el cliente debe tomar? + │ → sección 08, tarjeta "Decisiones", con quién decide y fecha sugerida + ├─ ¿Es una cifra del negocio que nadie confirmó? + │ → sección 01b con confianza "por_validar", y punto a confirmar en la 08 + └─ ¿Es información que el asesor necesita conseguir? + → bloque interno, campo `huecos`, con "qué falta / por qué importa / cómo obtenerlo" +``` + +**Lo elegante del diseño:** un hueco de información deja de ser un defecto del documento y se vuelve **contenido de valor**. Un cliente que recibe una propuesta con una sección clara de "esto necesitamos de ustedes, y esto está pendiente de decidir" percibe rigor, no incompetencia. Y de paso transfiere la responsabilidad del retraso a donde corresponde — que es exactamente lo que dice el footer de la plantilla: *"El avance queda condicionado a la entrega de materiales por parte del cliente."* + +**La regla de oro operativa:** una propuesta con 8 pendientes honestos es infinitamente mejor que una con 8 cifras inventadas. El prompt debe decir esto literalmente, y el ejemplo de §9.4 debe demostrarlo. + +--- + +## 11. Consideraciones técnicas + +### 11.1 Elección de modelo + +Recomendación: **`claude-opus-5`** para los tres pasos del pipeline. + +| Modelo | Precio (entrada / salida por MTok) | Contexto | Cuándo usarlo aquí | +|---|---|---|---| +| `claude-opus-5` | $5 / $25 | 1M | **Recomendado.** Los tres pasos. Es una cotización de decenas de miles de pesos; la diferencia de costo con Sonnet es de centavos | +| `claude-sonnet-5` | $3 / $15 (intro $2 / $10 hasta 2026-08-31) | 1M | Alternativa si el volumen crece mucho. Probar en el paso 3 (redacción) antes que en el 1 (extracción) | +| `claude-haiku-4-5` | $1 / $5 | 200K | Sólo para tareas mecánicas auxiliares: detectar idioma, clasificar tipo de archivo, sanitizar formato | + +**Por qué Opus 5 y no el más barato:** la calidad del diagnóstico es el producto. Un diagnóstico mediocre produce una propuesta que compite por precio, y eso cuesta miles de pesos de margen. Ahorrar $0.15 USD por documento para perder 10% de ticket es una decisión de negocio terrible. El costo del modelo no es la variable a optimizar aquí. + +**Detalles de la API que importan:** +- El thinking está **activo por defecto** en Opus 5 — no hay que configurarlo. `output_config: { effort: "high" }` para pasos 1 y 2, `"medium"` para el 3. +- `max_tokens` limita thinking + texto juntos. Para el paso 3, que produce un documento completo, hay que dar holgura: **usar streaming** con `max_tokens` alto (>16K obliga a streaming para no chocar con timeouts HTTP del SDK). +- No usar `temperature`, `top_p` ni `top_k` — están removidos en Opus 5 y devuelven 400. +- No usar prefill de mensaje de asistente — devuelve 400. Para forzar formato: structured outputs. +- Manejar `stop_reason: "refusal"` antes de leer `content`, y activar `fallbacks: "default"` con el header beta `server-side-fallback-2026-07-01`. + +### 11.2 SDK y punto de integración + +El proyecto es TypeScript/Next.js → **`@anthropic-ai/sdk`**. Nada de llamadas HTTP crudas ni de shims compatibles con otros proveedores. + +Dos alternativas de arquitectura: + +**Opción A — Route handler en Next.js.** `src/app/api/propuesta-ia/[id]/route.ts`, siguiendo el patrón de `export/pdf/[id]`. Más simple, un solo despliegue, comparte auth JWT y middleware. Riesgo: un paso de 3 llamadas con `effort: high` puede tardar minutos; requiere streaming al cliente o un patrón de job asíncrono (crear job → poll de estado → descargar). + +**Opción B — En el servicio Python de `api/`.** Ya tiene MCP y auth por API key, y está pensado para agentes. Ventaja: la generación no bloquea el servidor web. Desventaja: duplica la lógica del prompt en otro lenguaje, y el proyecto ya sufre de duplicación de `calculators`. + +**Recomendación:** Opción A con patrón de job. Un modelo nuevo (`PropuestaIA`: `cotizacionId`, `estado`, `objetoGenerado` JSON, `htmlRenderizado`, `costoTokens`, `createdAt`, `aprobadaPor`, `aprobadaAt`) permite historial, auditoría y regeneración sin perder versiones anteriores. + +### 11.3 Caché de prompt + +El caché es prefix match: cualquier cambio de un byte invalida todo lo que sigue. Orden de render: `tools` → `system` → `messages`. + +Diseño para este caso: + +| Contenido | Tamaño estimado | Cacheable | Notas | +|---|---|---|---| +| Filosofía + frameworks + reglas + contrato + ejemplos | 12-20K tokens | **Sí** — breakpoint aquí | Congelado. Cambia sólo cuando se edita la filosofía | +| Catálogo de servicios activo | 3-6K tokens | **Sí** — segundo breakpoint | Cambia cuando se edita el catálogo; serializar con orden determinista (por `orden`, `id`) | +| Cotización estructurada | 3-5K tokens | No | Varía por cotización | +| Transcripción + notas | 5-20K tokens | No | Varía por cotización | + +Notas operativas: +- El mínimo cacheable en Opus 5 es **512 tokens** (bajó desde 1024 en Opus 4.8). La capa 1 lo supera con holgura. +- Máximo 4 breakpoints por petición. Con dos alcanza. +- Lectura de caché ≈ 0.1× del precio de entrada; escritura 1.25× (TTL 5 min) o 2× (TTL 1h). Con 2+ peticiones el TTL de 5 minutos ya sale a favor — y el pipeline de 3 pasos garantiza al menos 3 peticiones seguidas con el mismo prefijo. +- **Invalidadores silenciosos a evitar:** `new Date()` en el system prompt, `JSON.stringify` de un objeto con orden de llaves no determinista, el número de cotización en la capa 1, cambio de modelo a media conversación. +- Verificar con `response.usage.cache_read_input_tokens`. Si sale 0 en peticiones repetidas con el mismo prefijo, hay un invalidador escondido. + +### 11.4 Costos estimados + +Escenario base por documento (una cotización con transcripción de 60 min): + +``` +Entrada: capa estable ~18K + catálogo ~5K + cotización ~4K + contexto ~15K ≈ 42K tokens +Salida: objeto estructurado + razonamiento ≈ 8K tokens +Peticiones: 3 (pipeline de §9.3), las 3 comparten prefijo de 23K +``` + +| Configuración | Costo estimado por documento | +|---|---| +| Opus 5 sin caché, 1 petición | ≈ $0.41 USD | +| Opus 5 con caché, pipeline de 3 pasos | ≈ **$0.30 – $0.55 USD** | +| Sonnet 5 con caché (precio intro) | ≈ $0.12 – $0.22 USD | +| Batch API (50% descuento) si se generan en lote nocturno | ≈ mitad de lo anterior | + +A 20 MXN/USD: **entre $6 y $11 MXN por documento** con Opus 5. + +**El insight de negocio:** el paquete PyME más barato del catálogo es de ~$7,490 MXN. El costo de generar su propuesta consultiva es **0.1% del ticket**. En el paquete de escalamiento ($90,800 MXN) es 0.01%. + +Con 40 cotizaciones al mes: **~$12–22 USD/mes** (~$240–440 MXN). Menos que una comida. + +Conclusión: **el costo del modelo no es una restricción de diseño.** Cualquier decisión que sacrifique calidad de output para ahorrar tokens está optimizando la variable equivocada. Optimizar para calidad, medir con `countTokens` para no llevarse sorpresas, y ya. + +### 11.5 Renderizado del documento + +La plantilla HTML es autocontenida (CSS inline, sin dependencias externas más que Google Fonts). Dos rutas: + +1. **HTML directo** — un renderizador toma el objeto validado y produce el HTML usando la plantilla como base. Ventajas: fiel al diseño, imprimible con `@media print`, editable, ligero. Requiere sustituir Google Fonts por fuentes embebidas si se quiere funcionamiento offline o dentro de un PDF. +2. **PDF vía PDFKit** — reutiliza `pdf-generator.ts`. Coherente con el resto del sistema, pero la plantilla HTML tiene gradientes, radial-gradients y tipografía serif/sans mezclada que en PDFKit son trabajo considerable. + +**Recomendación:** HTML como entregable primario (se ve mejor, se comparte por link o adjunto, y el cliente lo abre en el celular). Si se necesita PDF, imprimir el HTML desde el navegador o con un headless — no reimplementar el diseño en PDFKit. + +Nota heredada del proyecto: en `pdf-generator.ts` hay un bug documentado de auto-page-break en el footer (`doc.text()` en `y > page.height - margins.bottom` dispara página nueva). Si se va por PDFKit, ese bug ya tiene workaround en el código: poner `margins.bottom = 0` temporalmente. + +Los colores y el logo salen de `Configuracion` (`color_primario`, `color_secundario`, `logo_base64`), así que el documento respeta la marca sin hardcodear. + +--- + +## 12. Métricas de éxito del plugin + +Si no se puede medir, no se sabe si sirvió. Estas son las métricas, separadas por qué preguntan. + +### 12.1 ¿La IA escribe bien? (calidad del output) + +| Métrica | Cómo medirla | Meta inicial | +|---|---|---| +| Tasa de edición del asesor | % de campos del objeto modificados antes de aprobar | <30% | +| Afirmaciones sin evidencia | Conteo por documento (validación automática) | 0 | +| Citas no verificables | Citas que no aparecen en las fuentes | 0 | +| Rechazos completos | Documentos descartados y regenerados desde cero | <10% | +| Tiempo de revisión | Minutos entre generación y aprobación | <15 min | + +### 12.2 ¿Sirvió comercialmente? (impacto en el negocio) + +| Métrica | Cómo medirla | Por qué importa | +|---|---|---| +| Tasa de cierre con vs. sin documento consultivo | Comparar `estado: aprobada` entre cotizaciones con y sin propuesta de IA | La prueba central de la tesis | +| Ticket promedio | Total promedio de cotizaciones aprobadas, ambos grupos | La base de conocimiento predice +16-28% con opciones bien presentadas | +| Objeciones de precio | Registrar en `observaciones` si el cliente pidió descuento | Un buen anclaje de valor debería reducirlas | +| Tiempo de ciclo | Días entre `fecha` y cambio a `aprobada`/`rechazada` | Una propuesta clara decide más rápido, en cualquier dirección | +| Scope creep | Cotizaciones que requirieron orden de cambio | El objetivo de las exclusiones específicas | +| Conversión a mensualidad | % de cotizaciones aprobadas que incluyen servicio `mensual` o plan Bucéfalo | El objetivo de la sección de mantenimiento | + +**Advertencia metodológica:** con 40 cotizaciones al mes, cualquier comparación de tasa de cierre tarda meses en ser significativa, y hay mil variables confundidas (el asesor, el sector, la temporada, el tamaño del cliente). No conviene tomar decisiones grandes con 3 semanas de datos. Lo honesto es empezar midiendo §12.1, que sí es medible de inmediato, y dejar §12.2 acumular. + +### 12.3 ¿Cuesta lo que debe? (operación) + +- Costo por documento generado (tokens de entrada/salida × precio, guardado en `PropuestaIA.costoTokens`) +- Tasa de aciertos de caché (`cache_read_input_tokens / total`) +- Latencia p50 y p95 del pipeline completo +- Tasa de fallos: refusals, timeouts, validaciones rechazadas + +--- + +## 13. Roadmap sugerido + +Cada fase entrega algo usable. Ninguna requiere la siguiente para tener valor. + +### Fase 0 — Ganancia inmediata sin IA (días) + +**Imprimir `observaciones` y `notas` en el PDF y el Excel.** Es un cambio de pocas líneas en `pdf-generator.ts` y `excel-builder.ts`, y recupera información que ya se está capturando y descartando. + +Esto no requiere nada de este documento. Debería hacerse ya, independientemente de si el plugin se construye. + +### Fase 1 — Validación de calidad (1-2 semanas) + +Sin UI, sin base de datos, sin despliegue. Un script que: +- Lee una cotización existente vía la API o Prisma +- Lee una transcripción de un archivo local +- Corre el pipeline de 3 pasos +- Escupe el objeto JSON y un HTML + +**El entregable real no es el script: son 5-10 documentos generados sobre cotizaciones reales pasadas, revisados por el asesor.** Si esos documentos no son buenos, nada de lo demás importa y hay que iterar el prompt, no construir infraestructura. + +Criterio de avance: el asesor dice *"esto lo mandaría a un cliente después de editarlo 10 minutos."* + +### Fase 2 — Integración mínima (2-3 semanas) + +- Modelo `PropuestaIA` y `ContextoCotizacion` en Prisma +- Zona de carga de archivos en `CotizacionForm.tsx` +- Route handler con patrón de job (crear → poll → descargar) +- Renderizador HTML desde la plantilla +- Vista de revisión con semáforo de salud y evidencia expandible +- Botón de aprobación que registra quién y cuándo + +### Fase 3 — Inteligencia comercial (3-4 semanas) + +- Anexo interno como archivo separado +- Semáforo de salud de §5.1 en el dashboard, agregado sobre todas las cotizaciones +- Sugerencia de esquema de 2-3 opciones cuando `esDoble = false` +- Alerta de subcotización (ratio precio/valor <10%) +- Métricas de §12.1 instrumentadas + +### Fase 4 — Cierre del ciclo (después, con datos) + +- Aprendizaje de las ediciones del asesor: qué corrige sistemáticamente → ajuste del prompt +- Comparación de tasa de cierre (sólo cuando haya volumen suficiente) +- Herramienta MCP nueva: `generar_propuesta_consultiva` en `api/app/mcp/tools.py`, para que un agente externo pueda pedirla +- Reutilización del documento en la conversación de retainer a las 2 semanas post-entrega (M9) + +--- + +## 14. Decisiones abiertas + +Cosas que hay que decidir antes de implementar y que este análisis no puede resolver solo. + +| # | Decisión | Opciones | Recomendación | +|---|---|---|---| +| D1 | ¿Dónde se genera? | Route handler en Next.js vs. servicio Python | Next.js con patrón de job (§11.2) | +| D2 | ¿Dónde viven las transcripciones? | Adjuntos en BD · disco · Files API | Disco para Fase 1, adjuntos en BD para Fase 2 | +| D3 | ¿Un documento o dos archivos? | Documento del cliente + anexo interno separados, o uno solo | **Dos archivos.** El riesgo de fuga del anexo es demasiado alto (§6.1) | +| D4 | ¿HTML o PDF como entregable? | HTML · PDF · ambos | HTML primario; PDF por impresión del navegador si se necesita | +| D5 | ¿El plugin puede sugerir servicios? | Sí en la propuesta · sólo en el anexo interno · no | **Sólo en el anexo interno** (M13, criterio ético) | +| D6 | ¿Se regenera al cambiar la cotización? | Automático · manual con aviso · manual silencioso | Manual con aviso de desincronización visible | +| D7 | ¿Quién puede aprobar? | Cualquier asesor · sólo el dueño de la cotización · rol admin | El asesor dueño; admin puede aprobar cualquiera | +| D8 | ¿Se guarda la transcripción cruda o sólo la sanitizada? | Cruda · sanitizada · ambas | Sólo sanitizada en BD. La cruda no debe persistir con datos de empleados | +| D9 | ¿Se versiona el prompt? | Sí, con las propuestas apuntando a su versión · no | Sí. Sin esto no se puede saber si un cambio de prompt mejoró o empeoró | +| D10 | ¿Qué pasa si no hay transcripción? | Bloquear · generar con lo que haya · generar sólo el esqueleto | Generar con lo que haya, con la sección 08 muy poblada y aviso claro de confianza baja | + +--- + +## Anexo A — Mapeo campo → sección + +Referencia rápida para implementación. + +| Sección del documento | Fuentes de datos | +|---|---| +| Hero | `Cliente.nombre`, `.empresa`, `Cotizacion.numero`, `.fecha`, `.vigencia`, `.proyecto`, `User.name` (asesor) | +| 01 Diagnóstico | Transcripción, `Cotizacion.observaciones`, `ServicioCotizado.notas`, archivos de notas | +| 01b Valor del problema | Transcripción (4 dimensiones), `totales.total` para el ratio | +| 02 Resultados | Derivado del diagnóstico + `ServicioCotizado.entregables` | +| 03 Alcance | `ServicioCotizado[]` (nombre, fase, tipoPago, precio, tiempoEntrega, entregables), `Categoria.nombre` | +| Totales | `calculators.ts` — copiados literalmente, `IVA_RATE`, descuentos | +| 04 Opciones | `Cotizacion.esDoble`, `.opcionesMetadata`, `ServicioCotizado.opcion` | +| 05 No incluye | Transcripción (menciones fuera de alcance), `opcionesMetadata[].noIncluye` | +| 06 Por qué tiene sentido | `ServicioCotizado.beneficios`, cruzado con hallazgos del diagnóstico | +| 07 Mantenimiento | `PlanBucefaloCotizacion`, servicios con `tipoPago: mensual`, `modeloCobro: retainer`, `Bono[]` | +| 08 Materiales y decisiones | Huecos detectados + dependencias mencionadas en la transcripción | +| 09 Backlog | Fricciones mencionadas fuera del alcance de fase 1 | +| Footer | `Configuracion.logo_base64`, `.color_primario`, `.color_secundario` + condiciones fijas | +| Financiamiento (si aplica) | `FinanciamientoPlan[]`, `Cotizacion.incluirFinanciamiento`, `calcularFinanciamiento()` | +| Anexo interno | Todo lo anterior + `RegistroHoras` si aplica + análisis de §5.1 | + +--- + +## Anexo B — Checklist de calidad antes de enviar + +Adaptado de `Onboarding-Cliente/00-Guia-de-Uso-y-Checklist-Calidad.md`. Este checklist debe estar visible en la UI de revisión, no enterrado en un documento. + +**Problema y valor** +- [ ] El problema está redactado en lenguaje del cliente, sin jerga técnica +- [ ] Hay al menos un ejemplo real y reciente del problema, citado +- [ ] Se estimó el costo anual, con las cifras etiquetadas por confianza +- [ ] La métrica de éxito tiene línea base, resultado deseado y periodo +- [ ] Consta si se habló con el usuario operativo, no sólo con quien autoriza + +**Viabilidad y alcance** +- [ ] Se sabe dónde viven los datos/accesos y quién los autoriza +- [ ] La fase 1 resuelve un cuello de botella prioritario, no todos +- [ ] Está explícito: incluido ahora / excluido ahora / backlog futuro +- [ ] Hay responsables del cliente y decisiones pendientes identificadas +- [ ] Está definido qué significa "terminado" y quién acepta + +**Propuesta comercial** +- [ ] Si hay opciones, cambian alcance o nivel de servicio — no sólo el precio +- [ ] La opción recomendada sí cumple el resultado de negocio definido +- [ ] El precio se sustenta en valor, costo real y mercado +- [ ] El mantenimiento aparece con servicios concretos, límites y tiempos de respuesta +- [ ] Se presentará en llamada, no como cifra suelta por mensajería + +**Integridad del documento generado** +- [ ] Todo número coincide con el documento manual +- [ ] Cero afirmaciones sin evidencia +- [ ] Cero cifras marcadas como confirmadas sin origen +- [ ] Ningún dato personal de empleados del cliente +- [ ] Ningún monto en USD +- [ ] Ninguna promesa de resultado garantizado +- [ ] El CRM se menciona como Bucéfalo +- [ ] El anexo interno está en archivo separado y no se va a enviar + +--- + +## Anexo C — Cruce con la base de conocimiento + +Para profundizar durante la implementación: + +- **Preguntas de diagnóstico completas:** `Base de Conocimiento - IA Negocios y Dev/03-Preguntas-Guia.md` +- **Playbooks de pricing y cierre:** `08-Monetizacion-Onboarding-Pricing-Seguimiento.md` +- **Errores a evitar:** `01-Errores-a-Evitar.md`, `sintesis/s3-Errores-Fatales.md` +- **Modelos de pricing detallados:** `sintesis/s2-Pricing-Cobranza.md` +- **Prompts y plantillas base:** `sintesis/s8-Prompts-Plantillas.md` (§1 system prompt, §3 diagnóstico, §4 propuesta, §9 output estándar) +- **Las cuatro sesiones de onboarding:** `Onboarding-Cliente/01` a `04`, con `00-Guia-de-Uso-y-Checklist-Calidad.md` como criterio de calidad +- **Playbook maestro:** `Guia_Onboarding_Cliente_y_Ruta_de_Trabajo.md` +- **Paquetes del catálogo:** `docs/paquetes-recomendados-pyme.md` (este repo) +- **Convenciones del proyecto:** `AGENTS.md` (este repo) + +--- + +## Cierre + +El Cotizador E3 ya sabe cuánto cobrar. Lo que le falta es explicar por qué vale. + +Ese "por qué" no se inventa: se extrae de lo que el cliente ya dijo en la reunión, de lo que el asesor ya anotó en el campo de observaciones, y del catálogo que ya está armado. Está todo ahí, disperso y sin usar. + +El plugin no es un generador de texto bonito. Es un **traductor**: convierte una lista de precios en un argumento de negocio, usando material que ya existe y sin tocar un solo número. Y cuando no tiene material suficiente, lo dice — porque una propuesta con pendientes honestos cierra mejor que una con cifras inventadas, y porque el día que un cliente refute un dato inventado, el costo no lo paga el modelo: lo paga la marca. + +--- + +*Documento de análisis previo a implementación · Consultoría E3 · 2026-07-28* diff --git a/docs/superpowers/specs/2026-07-28-propuesta-consultiva-ia-fase0-fase1-design.md b/docs/superpowers/specs/2026-07-28-propuesta-consultiva-ia-fase0-fase1-design.md new file mode 100644 index 0000000..9a79d48 --- /dev/null +++ b/docs/superpowers/specs/2026-07-28-propuesta-consultiva-ia-fase0-fase1-design.md @@ -0,0 +1,454 @@ +# Propuesta consultiva con IA — Diseño de Fase 0 y Fase 1 + +> **Qué es este documento:** la especificación técnica cerrada de las dos primeras fases del +> plugin descrito en [`docs/BI-propuesta-consultiva-IA.md`](../../BI-propuesta-consultiva-IA.md). +> Aquel documento es el análisis de negocio y dice explícitamente que no es un spec. Este sí lo es. +> +> **Alcance:** Fase 0 (recuperar el contexto humano que hoy se descarta, más los bloqueadores que +> el análisis destapó) y Fase 1 (script local que valida si la IA escribe documentos utilizables). +> Fases 2-4 quedan fuera y tendrán su propio ciclo. +> +> **Fecha:** 2026-07-28 · **Estado:** aprobado para planeación +> **Base verificada:** commit `26e6d3a9` + +--- + +## 1. Por qué el alcance es este + +El documento de negocio describe ocho subsistemas. Construirlos de una vez significa un mes de +trabajo antes de saber si la tesis funciona. Su propio §13 argumenta la salida: + +> *"El entregable real no es el script: son 5-10 documentos generados sobre cotizaciones reales, +> revisados por el asesor. Si esos documentos no son buenos, nada de lo demás importa y hay que +> iterar el prompt, no construir infraestructura."* + +Se adopta ese criterio. Fase 1 termina cuando el asesor puede decir *"esto lo mandaría a un +cliente después de editarlo 10 minutos"* — o cuando queda claro que no. + +El análisis previo a este spec encontró cuatro problemas que el documento de negocio no anticipaba. +Tres son bloqueadores y entran al alcance; el cuarto cambia dónde vive un dato. + +--- + +## 2. Hallazgos que modifican el plan original + +Los cuatro están verificados en disco, no inferidos. + +### 2.1 🔴 El endpoint MCP publica todas las cotizaciones sin autenticación + +| Eslabón | Evidencia | +|---|---| +| `POST /mcp` no valida nada | `api/main.py:107` — sin un solo `Depends()`. Cero coincidencias de `require_auth` en el archivo | +| La función de auth existe y no se usa ahí | `api/app/auth.py:45` define `require_auth` | +| La herramienta devuelve la fila completa | `api/app/mcp/server.py:250` — `SELECT c.*` seguido de `dict(cot)`, sin lista blanca | +| Tiene dominio público en producción | `docker-compose.coolify.yml:67` — `SERVICE_FQDN_API_8000` | + +El agujero **ya existe**: precios, catálogo y datos de clientes son legibles hoy por cualquiera. +Lo relevante para este spec es que `SELECT c.*` publicaría la columna nueva de notas internas sin +que nadie toque `server.py`. Entra al alcance como **Fase 0-A**, previa a todo lo demás. + +### 2.2 🟠 No existe una fuente de verdad para los totales + +La regla de validación §8.3.1 del documento de negocio exige comparar contra *"el total de la +cotización en BD"*. No hay tal cosa: + +- Ninguna función devuelve los totales de una cotización. El cálculo está duplicado con + `.filter().reduce()` en **siete** consumidores (PDF, Excel, detalle, PreciosEditables, el + formulario, la lista y el dashboard), con criterios que no coinciden. +- El IVA está hardcodeado como `* 1.16` en `pdf-generator.ts:328-329` y `excel-builder.ts:377-378`, + ignorando `IVA_RATE`. +- El flag `Cotizacion.incluirIva` no se respeta en esos cálculos. + +Hoy el PDF y el Excel de una misma cotización pueden discrepar y nada lo detecta. Entra como +**Fase 0-B**. + +### 2.3 🔴 El Excel es un documento del cliente, no una herramienta interna + +Este hallazgo corrigió un supuesto equivocado del diseño inicial, que proponía poner las notas +internas en el Excel. + +| Evidencia | Ubicación | +|---|---| +| Banner con la razón social de E3 | `excel-builder.ts:165` | +| `"En atencion a:"` + nombre del cliente | `excel-builder.ts:181` | +| Nota legal de precios, IVA y vigencia | `excel-builder.ts:400` | +| Razón social + domicilio fiscal al pie de cada hoja de detalle | `excel-builder.ts:539-547` | +| Nombre de archivo `{empresa} - {cliente} - {numero}.xlsx` | `src/app/api/export/excel/[id]/route.ts:76` | +| Botón en la misma fila que Preview PDF y PDF | `src/app/(app)/cotizaciones/[id]/page.tsx:93-95` | + +Escenario de fallo: el asesor exporta ambos, caen en Descargas con el mismo prefijo, los arrastra +juntos al correo, y el cliente abre la última pestaña y lee el plan de recorte de precio y las red +flags sobre él mismo. + +**Consecuencia:** en Fase 0 las notas internas no entran a **ningún** exportador. Viven solo en la +app. Es la misma garantía estructural que ya tiene el PDF. + +### 2.4 🟠 Las transcripciones se sincronizarían a la nube de MEGA + +El repo vive en `H:\MegaSync\Proyectos\Cotizador`. El `.megaignore` actual excluye únicamente +`.next`, `node_modules` y `.turbo`. Cualquier transcripción guardada dentro del repo se sube a la +nube: nombres de empleados, comentarios de desempeño, cifras salariales. `.gitignore` protege el +repositorio, no la sincronización. + +**Consecuencia:** `contexto/` y `salidas/` van a `.gitignore` **y** a `.megaignore`, y la exclusión +se verifica empíricamente antes de colocar material real. + +--- + +## 3. Decisiones cerradas + +Ninguna de estas se re-litiga durante la implementación. + +| # | Decisión | Resolución | Razón | +|---|---|---|---| +| D1 | Alcance del ciclo | Fase 0 + Fase 1 | Validar calidad antes de construir infraestructura | +| D2 | Separar interno de visible | Campo nuevo `observacionesInternas`; `observaciones` pasa a ser texto del cliente | Hace la fuga estructuralmente imposible en vez de depender de un marcador que se olvida | +| D3 | Dónde viven las notas internas | Solo en la app. Ningún exportador | §2.3 | +| D4 | Forzar el schema sin structured outputs | Tool-calling: `input_schema` de la herramienta = contrato. Zod valida siempre | MiniMax no soporta `output_config` | +| D5 | Proveedor | MiniMax-M3 vía endpoint compatible con Anthropic | Decisión del negocio (Token Plan contratado) | +| D6 | Sanitización de PII | Filtro de **salida** solamente | El modelo necesita el contexto completo para diagnosticar; el riesgo real es lo que llega al cliente | +| D7 | Seguridad del MCP | Cerrar el agujero primero: `require_auth` + lista blanca de columnas | §2.1 | +| D8 | Totales | Función canónica `calcularTotalesCotizacion()` + migrar PDF y Excel | §2.2 | +| D9 | Base del ratio precio/valor | Primer año **con IVA** (único + mensual × 12) | Es el desembolso real a 12 meses; hace comparable el ratio contra un valor *anual* | +| D10 | Nombres de empleados detectados | Advertir, no bloquear | Un bloqueo heurístico produce falsos positivos constantes y enseña a ignorar la alerta | +| D11 | Ubicación de transcripciones | Dentro del repo, en `.gitignore` **y** `.megaignore` | §2.4 | +| D12 | Migración de datos | Dos despliegues: A aditivo, B mueve datos | §4.3 | + +--- + +## 4. Fase 0 — Recuperar el contexto humano + +Cuatro bloques. A y B son prerrequisitos de C. + +### 4.1 Fase 0-A · Cerrar el MCP + +1. Aplicar `require_auth` (`api/app/auth.py:45`) al endpoint `POST /mcp` en `api/main.py:107`. +2. Sustituir el `SELECT c.*` de `_obtener_cotizacion` (`api/app/mcp/server.py:250`) por una lista + blanca de columnas explícita, con el mismo criterio que el REST ya aplica vía + `CotizacionResponse` (`api/app/models/cotizacion.py:130-152`). +3. Auditar el resto de `server.py` en busca de otros `SELECT *` y darles el mismo tratamiento. + +**Criterio de aceptación:** una petición `POST /mcp` sin credencial devuelve 401, y +`obtener_cotizacion` con credencial válida no incluye `observacionesInternas` en su salida. + +### 4.2 Fase 0-B · Totales canónicos + +Escribir en `src/lib/calculators.ts`: + +```ts +calcularTotalesCotizacion(cotizacion): { + subtotalUnico, subtotalMensual, + ivaUnico, ivaMensual, + totalUnico, totalMensual, + totalPrimerAnio, // totalUnico + totalMensual * 12, con IVA — base del ratio (D9) + moneda +} +``` + +Reglas: usa `IVA_RATE`, respeta `Cotizacion.incluirIva`, y solo suma partidas con +`seleccionado: true`. Para cotizaciones dobles se apoya en `calcularTotalesOpcion`. + +Migrar a ella `pdf-generator.ts` y `excel-builder.ts`, eliminando los `* 1.16`. Los otros cinco +consumidores se migran en un ciclo posterior; se documenta la deuda. + +**Criterio de aceptación:** para un conjunto de cotizaciones reales, el total del PDF y el del +Excel coinciden dígito por dígito, y una cotización con `incluirIva: false` no muestra IVA en +ninguno. + +### 4.3 Fase 0-C · El campo de contexto humano + +**Despliegue A — solo aditivo.** + +- `ALTER TABLE "Cotizacion" ADD COLUMN "observacionesInternas" TEXT;` — sin `UPDATE`. +- El formulario muestra dos textareas visualmente inconfundibles: *"Observaciones (las ve el + cliente)"* y *"Notas internas (no salen de la app)"*, con badge de color distinto. +- La vista de detalle muestra ambos campos; el histórico aparece etiquetado como + *"Observaciones (histórico, sin clasificar)"*. +- El PDF imprime **solo** `observaciones`. `CotizacionPDFData` (`pdf-generator.ts:31-53`) no + declara `observacionesInternas` — la garantía es estructural, no disciplinaria. +- Ningún exportador recibe el campo interno. + +**Despliegue B — movimiento de datos.** Solo cuando A lleve días estable: + +```sql +UPDATE "Cotizacion" + SET "observacionesInternas" = "observaciones", + "observaciones" = NULL + WHERE "observaciones" IS NOT NULL + AND btrim("observaciones") <> '' + AND "observacionesInternas" IS NULL; -- guarda de idempotencia, obligatoria +``` + +Antes de correr B, exportar y guardar **fuera de MegaSync**: + +```sql +COPY (SELECT id, numero, estado, observaciones FROM "Cotizacion" + WHERE observaciones IS NOT NULL AND btrim(observaciones) <> '') +TO STDOUT WITH CSV HEADER; +``` + +Ese CSV es el `down` que Prisma no da: no hay migraciones de reversa en el repo ni servicio de +backup en `docker-compose.coolify.yml`. + +**Por qué dos despliegues.** Si A mueve los datos y el despliegue falla, Coolify redespliega la +imagen anterior, el código viejo lee `observaciones` (NULL en el 100% de las filas) y el asesor ve +todas sus notas desaparecidas — sin error, sin log, en el momento de máximo estrés. + +**Puntos de integración del campo nuevo** (rastreados de punta a punta): +`prisma/schema.prisma`, `src/lib/schemas.ts` (los dos schemas), `src/lib/store.ts`, +`CotizacionForm.tsx`, `POST /api/cotizaciones`, `PUT /api/cotizaciones/[id]`, +`cotizaciones/[id]/page.tsx`, `cotizaciones/[id]/editar/page.tsx`, y en Python los tres modelos +Pydantic (`CotizacionCreate`, `CotizacionUpdate`, `CotizacionResponse`) más el `_add` del PUT. + +Los INSERT de Python **no** son urgentes: la columna es nullable y Postgres pone NULL. Los modelos +Pydantic sí lo son — hay precedente demostrado de que sin declararlos el campo nunca sale del API +(`incluirIva` existe en la tabla desde `20260630000000` y el API Python no lo devuelve). + +**Deuda declarada:** `zod` se importa en `src/lib/schemas.ts:1` y resuelve transitivamente a 4.3.6, +pero no está en `package.json`. Se declara explícitamente (`npm i zod@^4.3.6`); un +`npm ci --omit=dev` revienta hoy sin eso, y Fase 1 depende fuertemente de zod. + +### 4.4 Fase 0-D · Bugs vecinos aprobados + +| Bug | Arreglo | +|---|---| +| Orden de partidas | Ninguna consulta tiene `orderBy` en `servicios`, y `drawSection` (`pdf-generator.ts:216-268`) asume que vienen agrupadas por fase. Añadir `orderBy: [{fase}, {createdAt}]` en las cuatro rutas de export | +| Datos bancarios en borrador | `export/pdf/route.ts:45` llama solo a `getConfigBranding()`; el Excel llama a ambas. Añadir `getConfigBancaria()` | +| Partida por demanda en $0 | Las copias locales de `detalleModelo` en `pdf-generator.ts:21-29` y `excel-builder.ts:58-66` no manejan `modeloCobro === "demanda"`; la canónica de `calculators.ts:23-41` sí. Usar la canónica | +| Bonos con dos redacciones | `pdf-generator.ts:377-384` tiene seis bonos hardcodeados y la tabla `Bono` del seed dice otra cosa; la tabla no se consulta en `src/`. Definir la tabla como fuente de verdad | + +--- + +## 5. Fase 1 — Script local de validación de calidad + +Sin base de datos nueva, sin UI, sin despliegue. Un script que lee una cotización y una +transcripción, corre el pipeline, y escribe un JSON, un HTML y un reporte. + +### 5.1 Contratos compartidos + +Los cuatro diseños explorados compartían vocabulario pero no contratos. Estas resoluciones se +escriben **una vez**, en un solo archivo de tipos que todos importan. Sin esto el sistema arranca, +no falla, y valida el vacío. + +| # | Conflicto | Resolución | +|---|---|---| +| B1 | Clave de join partida ↔ IA | `refPartida`, formato `/^P\d{2}$/` → `"P01"`. El cuid de `ServicioCotizado` **nunca** sale hacia el proveedor: no es estable entre ediciones porque el PUT hace `deleteMany` + `createMany` | +| B2 | Forma de la evidencia | Arrays de IDs (`citas[]`, `hechos[]`), no prosa. Auditable por máquina, que es el punto de P3 | +| B3 | Cita literal | Referenciada por ID. Se **verifica en el paso 1**, donde vive el texto, y su fallo bloquea antes de gastar los pasos 2 y 3 | +| B4 | Árbol de módulos | `src/lib/propuesta/{ia,validacion,render}/`, entrada `scripts/propuesta-consultiva.ts`, tipo raíz `PropuestaConsultiva` | +| B5 | Códigos de salida | `0` limpio · `1` requiere revisión · `2` bloqueado · `3` error del proveedor · `64` error de uso | +| B6 | Variables de entorno | Solo `MINIMAX_API_KEY` / `MINIMAX_BASE_URL` / `MINIMAX_MODEL`, pasadas explícitas al constructor. **Nunca** prefijo `ANTHROPIC_*`: el SDK las lee por su cuenta y un `ANTHROPIC_BASE_URL` exportado en la shell mandaría la clave de MiniMax a Anthropic | +| B7 | `tool_choice` | No se envía en Fase 1. Fijarlo solo en el reintento le da al reintento un prefijo distinto, o sea que se paga el contexto completo justo cuando es más grande | +| B8 | Snapshot del catálogo | Sin `id` y sin `precioBase`. La resolución es por `nombre` + `fase`, reportando ambigüedad — `ServicioCatalogo.nombre` no es `@unique` | +| B9 | Valor anual del problema | `dimensiones[].calculo.montoAnualMXN`. El total se suma **en código**, nunca lo emite el modelo | + +### 5.2 El corte: qué copia el código y qué genera el modelo + +La protección más fuerte del principio P1 no es una regla de validación: es que **ningún schema +que llena el modelo contiene un solo campo de dinero de la cotización**. + +- **El modelo devuelve:** `refPartida` + prosa (diagnóstico, resultados, descripciones en lenguaje + de beneficio, exclusiones, pendientes, backlog). +- **El código inyecta después:** precios, totales, IVA, número de cotización, vigencia, fechas. + +Así P1 deja de ser algo que alguien puede olvidar validar y pasa a ser estructuralmente imposible +de violar. El ratio precio/valor también lo calcula el código (D9) y se imprime solo en el anexo +interno. + +### 5.3 El pipeline de tres pasos + +| Paso | Entrada | Salida | Por qué separado | +|---|---|---|---| +| 1 · Extracción | Transcripción + notas + observaciones | Hechos: dolores, cifras con confianza, citas literales con ID, materiales, decisiones, red flags, menciones fuera de alcance | Determina la calidad de todo lo demás. Es corregible por el asesor antes de propagarse | +| 2 · Diagnóstico | Hechos del paso 1 + cotización + catálogo | Hallazgos con semáforo, valor del problema, resultados a lograr | Razonamiento, no redacción | +| 3 · Redacción | Salidas de 1 y 2 | `PropuestaConsultiva` | Con el análisis hecho, esto es escritura | + +Cada paso define una herramienta cuyo `input_schema` es su contrato, derivado del Zod con +`z.toJSONSchema` nativo (verificado: preserva `additionalProperties` y `description`, inlinea +subschemas, omite `superRefine`, y emite un `$schema` que hay que borrar). **No hace falta +`zod-to-json-schema`.** + +### 5.4 El presupuesto de reintentos + +Hallazgo verificado que ningún diseño anticipó: **`.superRefine` no corre si la forma falla.** Eso +crea cuatro compuertas secuenciales: + +1. Forma Zod — siempre +2. `superRefine` (IDs únicos, refs internas) — solo si 1 pasa +3. Validación cruzada de runtime (`refPartida` reales) — solo si 2 pasa +4. Filtro de contenido y PII — solo si 3 pasa + +Con tres intentos y cuatro compuertas, el modo de fallo más probable del piloto es *"tres llamadas +pagadas, cero documento"* — justo lo que Fase 1 no puede permitirse, porque su criterio de éxito es +que el asesor lea algo. + +**Diseño adoptado:** + +- El filtro de contenido y PII corre sobre el objeto **crudo** aunque Zod haya fallado, recorriendo + rutas parciales. Los hallazgos de las cuatro compuertas se acumulan en **un solo** mensaje de + corrección. +- Presupuesto: **3 intentos totales** por paso (1 inicial + 2 reintentos). El paso 3 recibe **4 + intentos totales** (1 + 3) por ser el más largo y el que atraviesa más compuertas. +- Al agotarse los intentos se escribe igual el HTML del cliente **si y solo si** no hay bloqueantes + de PII, moneda, garantía ni marca. Salir con código 1, no con 2. +- En la rama `tool_incorrecta` hay que emitir un `tool_result` con `is_error: true` por **cada** + `tool_use` del turno antes del texto de corrección; un mensaje de usuario plano después de un + `tool_use` produce un 400. + +### 5.5 Validación post-generación + +Las seis reglas de §8.3 del documento de negocio, más una nueva que el análisis de riesgo destapó. + +| Regla | Qué comprueba | Al fallar | +|---|---|---| +| **R0** (nueva) | Ningún n-grama de 7 tokens de `observacionesInternas` ni de `ServicioCotizado.notas` aparece en el HTML del cliente | **Bloquea** | +| R1 | Todo monto en prosa pertenece al conjunto de la economía (BD) o al del valor (declarado y auditado por R4) | Bloquea | +| R2 | Todo `refPartida` existe en `ServicioCotizado`. Ninguna partida nueva | Bloquea | +| R3 | Cada cita literal existe en las fuentes, con normalización de 9 pasos (NFD sin diacríticos, minúsculas, puntuación, espacios, muletillas de ASR). Corre en el paso 1 | Bloquea si cruza hablantes | +| R4 | Todo hallazgo `confirmado` tiene `citas.length + hechos.length > 0`. Corre sobre el objeto del **paso 2** | Degrada a `por_validar` | +| R5 | El bloque `interno` se separa antes de renderizar el documento del cliente | Bloquea | +| R6 | Sin valor anual, ninguna afirmación de ratio en la prosa | Bloquea la afirmación | + +**R0 existe porque las otras seis no la cubren.** `R5` compara el bloque interno que *produjo el +modelo* contra el HTML; nunca compara `observacionesInternas`, que es una **entrada** que el modelo +recibe en el prompt y puede copiar literalmente en cualquier campo de prosa. + +**Filtro de PII de salida** (advertencia, no bloqueo — D10): montos en USD, promesas de resultado +garantizado, CRMs que no sean Bucéfalo, datos de empleados, temas salariales o legales. Los +patrones heurísticos se marcan como tales en el reporte, con su extracto, para que el asesor +juzgue. Se debe añadir a la cosecha de nombres las etiquetas de hablante del VTT y los dos campos +de notas, que hoy quedarían fuera. + +### 5.6 El renderizador HTML + +**Es el entregable primario y ningún diseño lo tenía.** Primer paso de Fase 1: copiar +`D:/Documents/plantilla_cotizacion.html` (27,100 bytes, hoy fuera del repo) a +`src/lib/propuesta/render/plantilla.ts` y congelar su CSS. Sin esto, Fase 1 termina con tres JSON +impecables y nada que enseñar. + +Cambios obligatorios sobre la plantilla: + +| Problema | Arreglo | +|---|---| +| 12 `rgba()` con canales escritos a mano duplican `--blue`, `--cream`, `--green`, `--amber` | Parametrizar de verdad, o `color_primario` produce un documento con dos azules | +| `.section { page-break-inside: avoid }` en secciones enteras | Con 15-20 partidas empuja la sección a hoja nueva y la parte igual. Aplicar a filas, no a secciones | +| No hay `@page` | Todo PDF impreso lleva `localhost:3000/...` estampado al pie de una propuesta comercial | +| Tema oscuro + "Gráficos de fondo" desactivado por defecto en Chrome | El PDF sale con texto crema sobre blanco. Necesita un modo de impresión claro | +| Cero hueco para el logo | El Anexo A del documento de negocio lo mapea como si existiera | +| `.plan-grid` fijo a `1fr 1fr` | La sección de opciones pide tres tarjetas (anclaje A → B → C) | +| Números de sección escritos a mano con cinco secciones condicionales | Un documento sin mantenimiento salta del 04 al 06. Numerar en el renderizador | +| "Valor del problema" pide tabla de cuatro columnas | No hay patrón CSS; hay que crearlo | + +Estrategia: template literals puros, sin motor de plantillas. El proyecto no tiene ninguno +instalado y no lo amerita. + +**Inyección CSS:** `PUT /api/configuracion` filtra las claves permitidas pero no valida los valores, +y esos valores terminan dentro de un `