Compare commits
2
Commits
26e6d3a9bf
...
9023384de9
| Author | SHA1 | Date | |
|---|---|---|---|
 urieljarethandClaude Opus 5
|
9023384de9 | ||
|
urieljarethandClaude Opus 5
|
0ff783fd65 |
@@ -7,15 +7,19 @@
|
|||||||
| `npm run dev` | Start Next.js dev server on port 3000 |
|
| `npm run dev` | Start Next.js dev server on port 3000 |
|
||||||
| `npm run build` | Production build (runs TypeScript check) |
|
| `npm run build` | Production build (runs TypeScript check) |
|
||||||
| `npm run lint` | ESLint (flat config, eslint-config-next) |
|
| `npm run lint` | ESLint (flat config, eslint-config-next) |
|
||||||
| `npx tsx prisma/seed.ts` | Run seed (upserts all data, idempotent) |
|
| `npm run db:seed` | Run seed (upserts all data, idempotent) |
|
||||||
| `npx prisma migrate dev` | Create/apply migration |
|
| `npm run db:migrate` | Create/apply migration (`prisma migrate dev`) |
|
||||||
| `npx prisma generate` | Regenerate Prisma client |
|
| `npm run db:generate` | Regenerate Prisma client |
|
||||||
| `npx prisma studio` | Prisma Studio GUI |
|
| `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`.
|
**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`.
|
**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 7 — Critical Gotchas
|
||||||
|
|
||||||
- **Prisma client is NOT at `@prisma/client`.** It's generated to `src/generated/prisma/` and imported as `@/generated/prisma/client`.
|
- **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).
|
- **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.
|
- **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
|
## 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).
|
- **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/
|
src/
|
||||||
app/
|
app/
|
||||||
(app)/ # Authed route group: dashboard, cotizaciones, clientes, catalogo, configuracion (has its own layout.tsx + Sidebar)
|
(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, configuracion, paquetes, export, import
|
api/ # Next.js route handlers (REST): auth, catalogo, categorias, cotizaciones (+ horas, nota-horas, precio),
|
||||||
|
# configuracion, paquetes, export, import, health
|
||||||
login/ # Public login page
|
login/ # Public login page
|
||||||
components/ # CotizacionForm, ExportButtons, EstadoBadge, layout/Sidebar
|
components/ # CotizacionForm (~1.4k lines), ExportButtons, EstadoBadge, layout/Sidebar, ui/DialogProvider
|
||||||
lib/ # auth, db, store, calculators, pdf-generator, schemas, config-helpers
|
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)
|
generated/prisma/ # Prisma client output (gitignored)
|
||||||
prisma/
|
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,
|
# ServicioCatalogo, ServicioPaquete, ServicioCotizado, PlanBucefaloCotizacion,
|
||||||
# Configuracion, Bono, FinanciamientoPlan)
|
# RegistroHoras, Configuracion, Bono, FinanciamientoPlan)
|
||||||
seed.ts # All catalog data (services, categorias, bonos, planes, config) — idempotent upserts
|
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)
|
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`.
|
- **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).
|
- **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
|
## Python API (`api/`) — Optional Second Backend
|
||||||
|
|
||||||
|
|||||||
+13
-2
@@ -246,8 +246,18 @@ async def _crear_cotizacion(conn, args: dict) -> dict:
|
|||||||
|
|
||||||
|
|
||||||
async def _obtener_cotizacion(conn, args: dict) -> dict:
|
async def _obtener_cotizacion(conn, args: dict) -> dict:
|
||||||
|
# Lista blanca de columnas: esta herramienta devuelve la fila completa al agente
|
||||||
|
# (result = dict(cot) mas abajo), asi que un SELECT c.* publicaria cualquier
|
||||||
|
# columna nueva sin que nadie lo decida. Espeja CotizacionResponse del REST
|
||||||
|
# (app/models/cotizacion.py) y excluye deliberadamente "observacionesInternas",
|
||||||
|
# que es texto que no debe salir de la app.
|
||||||
cot = await conn.fetchrow(
|
cot = await conn.fetchrow(
|
||||||
"""SELECT c.*, cl.nombre as cliente_nombre, cl.empresa as cliente_empresa,
|
"""SELECT c.id, c.numero, c.fecha, c.vigencia, c.moneda, c."tipoCambio",
|
||||||
|
c.proyecto, c."esquemaPago", c.estado, c."incluirBonos",
|
||||||
|
c."incluirFinanciamiento", c."incluirIva", c."esDoble",
|
||||||
|
c."opcionesMetadata", c.observaciones, c."clienteId", c."asesorId",
|
||||||
|
c."createdAt", c."updatedAt",
|
||||||
|
cl.nombre as cliente_nombre, cl.empresa as cliente_empresa,
|
||||||
cl.email as cliente_email, cl.telefono as cliente_telefono
|
cl.email as cliente_email, cl.telefono as cliente_telefono
|
||||||
FROM "Cotizacion" c
|
FROM "Cotizacion" c
|
||||||
LEFT JOIN "Cliente" cl ON c."clienteId" = cl.id
|
LEFT JOIN "Cliente" cl ON c."clienteId" = cl.id
|
||||||
@@ -266,7 +276,8 @@ async def _obtener_cotizacion(conn, args: dict) -> dict:
|
|||||||
)
|
)
|
||||||
|
|
||||||
plan = await conn.fetchrow(
|
plan = await conn.fetchrow(
|
||||||
'SELECT * FROM "PlanBucefaloCotizacion" WHERE "cotizacionId" = $1',
|
"""SELECT id, "cotizacionId", nivel, precio, seleccionado, "createdAt", "updatedAt"
|
||||||
|
FROM "PlanBucefaloCotizacion" WHERE "cotizacionId" = $1""",
|
||||||
args["cotizacion_id"],
|
args["cotizacion_id"],
|
||||||
)
|
)
|
||||||
|
|
||||||
|
|||||||
+10
-3
@@ -9,10 +9,11 @@ from __future__ import annotations
|
|||||||
from contextlib import asynccontextmanager
|
from contextlib import asynccontextmanager
|
||||||
from datetime import datetime, timezone
|
from datetime import datetime, timezone
|
||||||
|
|
||||||
from fastapi import FastAPI, Request
|
from fastapi import Depends, FastAPI, Request
|
||||||
from fastapi.middleware.cors import CORSMiddleware
|
from fastapi.middleware.cors import CORSMiddleware
|
||||||
from fastapi.responses import JSONResponse
|
from fastapi.responses import JSONResponse
|
||||||
|
|
||||||
|
from app.auth import require_auth
|
||||||
from app.config import settings
|
from app.config import settings
|
||||||
from app.database import close_db, init_db
|
from app.database import close_db, init_db
|
||||||
|
|
||||||
@@ -105,8 +106,14 @@ try:
|
|||||||
from mcp.server.streamable_http import StreamableHTTPServerTransport
|
from mcp.server.streamable_http import StreamableHTTPServerTransport
|
||||||
|
|
||||||
@app.post("/mcp")
|
@app.post("/mcp")
|
||||||
async def mcp_endpoint(request: Request):
|
async def mcp_endpoint(request: Request, _auth: dict = Depends(require_auth)):
|
||||||
"""MCP (Model Context Protocol) endpoint for AI agents."""
|
"""MCP (Model Context Protocol) endpoint for AI agents.
|
||||||
|
|
||||||
|
Requiere autenticacion (X-API-Key o Bearer JWT), igual que el resto del API.
|
||||||
|
Sin esto el endpoint quedaba abierto a internet: el servicio recibe dominio
|
||||||
|
publico en produccion (docker-compose.coolify.yml, SERVICE_FQDN_API_8000) y
|
||||||
|
las herramientas MCP leen y escriben cotizaciones directamente.
|
||||||
|
"""
|
||||||
transport = StreamableHTTPServerTransport(mcp_server)
|
transport = StreamableHTTPServerTransport(mcp_server)
|
||||||
return await transport.handle_request(request)
|
return await transport.handle_request(request)
|
||||||
|
|
||||||
|
|||||||
@@ -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*
|
||||||
@@ -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 `<style>`. Validar `/^#[0-9a-fA-F]{3,8}$/` en el punto de
|
||||||
|
inyección y caer al default del seed si no cumple.
|
||||||
|
|
||||||
|
**Anexo interno:** archivo separado, `INTERNO-NO-ENVIAR.html`, visualmente inconfundible. Nunca una
|
||||||
|
sección oculta ni `display: none`.
|
||||||
|
|
||||||
|
### 5.7 Ergonomía del script
|
||||||
|
|
||||||
|
```
|
||||||
|
npx tsx scripts/propuesta-consultiva.ts \
|
||||||
|
--cotizacion UJ2607UJ003 \
|
||||||
|
--transcripcion contexto/UJ2607UJ003/reunion.txt \
|
||||||
|
--salida salidas/UJ2607UJ003/
|
||||||
|
```
|
||||||
|
|
||||||
|
Banderas: `--cotizacion --transcripcion --salida --desde-paso --solo-validar`. Nada más.
|
||||||
|
`--desde-paso` y `--solo-validar` se ganan su lugar: son la diferencia entre iterar el prompt del
|
||||||
|
paso 3 veinte veces o cuatro.
|
||||||
|
|
||||||
|
Artefactos: `propuesta.html`, `INTERNO-NO-ENVIAR.html`, `propuesta.json` (con la traza embebida),
|
||||||
|
`REPORTE.md`, y `traza/pasoN.json` porque `--desde-paso` los necesita.
|
||||||
|
|
||||||
|
Consola: los tres pasos tardan; imprime progreso por paso, tokens consumidos y aciertos de caché.
|
||||||
|
|
||||||
|
`contexto/` y `salidas/` van a `.gitignore` **y** a `.megaignore` (D11), con la exclusión
|
||||||
|
verificada empíricamente antes de colocar material real.
|
||||||
|
|
||||||
|
### 5.8 Prompts y caché
|
||||||
|
|
||||||
|
Tres capas por estabilidad: estable (filosofía, frameworks, reglas, contrato, ejemplos),
|
||||||
|
semi-estable (catálogo), volátil (cotización y transcripción). Dos breakpoints de `cache_control`.
|
||||||
|
|
||||||
|
MiniMax soporta caché con `cache_control` (4 breakpoints, TTL 5 min, verificable con
|
||||||
|
`usage.cache_read_input_tokens`), pero el prefijo arranca en `tools`, no en `system`.
|
||||||
|
|
||||||
|
**Invalidadores a prevenir:** `new Date()` en la capa 1, `JSON.stringify` con orden de llaves no
|
||||||
|
determinista, el número de cotización en la capa estable, cambio de modelo a media ejecución.
|
||||||
|
Serializar el catálogo con orden explícito (`orden`, `id`).
|
||||||
|
|
||||||
|
**Los ejemplos few-shot deben validar contra su propio schema Zod al arrancar el script.** Cuesta
|
||||||
|
diez líneas y es el único test que este proyecto va a tener. Un ejemplar defectuoso no produce un
|
||||||
|
error: produce N documentos parecidos entre sí y se diagnostica tarde. El análisis encontró tres
|
||||||
|
defectos en los ejemplos propuestos —uno que no valida, uno que mete el nombre de pila de una
|
||||||
|
empleada en un campo del cliente, y uno que dispara el filtro de montos con `"400 pesos"`— que hay
|
||||||
|
que corregir antes de la primera corrida.
|
||||||
|
|
||||||
|
También hay que pasar el **texto fijo de la plantilla** por el catálogo de PII una vez antes de la
|
||||||
|
primera corrida, o la primera ejecución devolverá bloqueos que vienen del footer y no del modelo.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 6. Supuestos sin verificar
|
||||||
|
|
||||||
|
Se documentan porque el diseño se apoya en ellos y la primera corrida debe medirlos.
|
||||||
|
|
||||||
|
| # | Supuesto | Qué hacer |
|
||||||
|
|---|---|---|
|
||||||
|
| V1 | MiniMax devuelve `cache_read_input_tokens` con `tools` fijo y 2 breakpoints | Primera medición obligatoria. Si no cachea, mandar las tres herramientas en cada petición es costo puro |
|
||||||
|
| V2 | Con `stop_reason: "max_tokens"` el SDK entrega `input` como objeto parcial | Probar a propósito con `max_tokens: 200` |
|
||||||
|
| V3 | `countTokens` existe en el endpoint compatible | Degradar a estimador local y marcar las cifras como estimadas en la traza |
|
||||||
|
|
||||||
|
Verificados durante el análisis, sin acción pendiente: `z.toJSONSchema` preserva lo necesario;
|
||||||
|
`z.prettifyError` emite multi-error con ruta; `tsx` resuelve el alias `@/`; `core.autocrlf=true`
|
||||||
|
exige normalizar saltos de línea.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 7. Riesgos aceptados
|
||||||
|
|
||||||
|
| Riesgo | Por qué se acepta | Mitigación |
|
||||||
|
|---|---|---|
|
||||||
|
| La transcripción cruda con datos de empleados viaja a MiniMax | El modelo necesita el contexto para diagnosticar (D6) | Queda escrito aquí, no solo en la conversación. El filtro de salida protege el documento, no el tránsito |
|
||||||
|
| El PDF de una cotización ya enviada deja de ser reproducible | Fase 0 cambia el renderizador; el sistema no archiva los PDF emitidos | Que el asesor archive lo enviado. Documentar en AGENTS.md que los exportadores no son reproducibles en el tiempo |
|
||||||
|
| El hábito del asesor no migra solo | Tras Fase 0, el textarea donde lleva meses escribiendo contexto interno pasa a imprimirse en el PDF | Avisar por el canal del equipo, no solo cambiar la etiqueta |
|
||||||
|
| Fase 1 añade una tercera superficie solo en TypeScript | AGENTS.md ya exige paridad entre dos backends | Documentar la divergencia. Si Fase 4 expone esto por MCP, la validación tendrá que existir del lado Python |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 8. Criterios de éxito
|
||||||
|
|
||||||
|
**Fase 0** — verificable de inmediato:
|
||||||
|
|
||||||
|
- `POST /mcp` sin credencial devuelve 401; con credencial, `obtener_cotizacion` no expone el campo interno.
|
||||||
|
- El total del PDF y el del Excel coinciden dígito por dígito en cotizaciones reales.
|
||||||
|
- Una cotización con `incluirIva: false` no muestra IVA en ningún exportador.
|
||||||
|
- Las notas internas no aparecen en ningún archivo exportable.
|
||||||
|
- El texto del cliente aparece en el PDF, con saltos de línea correctos y sin romper el footer.
|
||||||
|
|
||||||
|
**Fase 1** — el criterio es cualitativo y es el que importa:
|
||||||
|
|
||||||
|
> El asesor revisa 5-10 documentos generados sobre cotizaciones reales pasadas y dice
|
||||||
|
> *"esto lo mandaría a un cliente después de editarlo 10 minutos."*
|
||||||
|
|
||||||
|
Métricas de apoyo: cero afirmaciones sin evidencia, cero citas no verificables, y tasa de edición
|
||||||
|
del asesor por debajo del 30%.
|
||||||
|
|
||||||
|
Si el criterio no se cumple, la conclusión correcta es iterar el prompt — no construir Fase 2.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 9. Fuera de alcance
|
||||||
|
|
||||||
|
Modelos `PropuestaIA` y `ContextoCotizacion`; carga de archivos en la UI; route handler con patrón
|
||||||
|
de job; vista de revisión con semáforo de salud; dashboard de BI agregado; herramienta MCP
|
||||||
|
`generar_propuesta_consultiva`; sugerencia de esquema de 2-3 opciones; alerta de subcotización.
|
||||||
|
|
||||||
|
También difierido: migrar los cinco consumidores restantes de totales duplicados, y el semáforo de
|
||||||
|
salud de §5.1 del documento de negocio — es una función de producto, no una validación, y no hace
|
||||||
|
falta para saber si el texto generado sirve.
|
||||||
@@ -30,6 +30,7 @@
|
|||||||
"prisma": "^7.8.0",
|
"prisma": "^7.8.0",
|
||||||
"react": "19.2.4",
|
"react": "19.2.4",
|
||||||
"react-dom": "19.2.4",
|
"react-dom": "19.2.4",
|
||||||
|
"zod": "^4.3.6",
|
||||||
"zustand": "^5.0.12"
|
"zustand": "^5.0.12"
|
||||||
},
|
},
|
||||||
"devDependencies": {
|
"devDependencies": {
|
||||||
|
|||||||
@@ -0,0 +1,20 @@
|
|||||||
|
-- Fase 0-C, Despliegue A: separar el texto que ve el cliente del contexto interno.
|
||||||
|
--
|
||||||
|
-- ESTA MIGRACION ES PURAMENTE ADITIVA. No modifica ni una sola fila existente.
|
||||||
|
-- El movimiento de datos (observaciones -> observacionesInternas) seria un
|
||||||
|
-- Despliegue B posterior y NO se incluye aqui, por dos razones:
|
||||||
|
--
|
||||||
|
-- 1. Rollback seguro. No hay migraciones `down` en este repo ni servicio de
|
||||||
|
-- backup en docker-compose.coolify.yml. Si un UPDATE vaciara "observaciones"
|
||||||
|
-- y el despliegue se revirtiera, el codigo anterior leeria NULL en todas las
|
||||||
|
-- filas y el asesor veria sus notas desaparecidas: sin error y sin log.
|
||||||
|
--
|
||||||
|
-- 2. El dato real no lo necesita. Al momento de escribir esto la unica fila de
|
||||||
|
-- produccion con "observaciones" no vacias (UJ2606AG777, aprobada) contiene
|
||||||
|
-- condiciones de pago dirigidas al cliente en segunda persona. Moverlas a
|
||||||
|
-- "internas" ocultaria terminos ya acordados en un documento emitido.
|
||||||
|
-- Esa fila ya esta clasificada correctamente donde esta.
|
||||||
|
--
|
||||||
|
-- IF NOT EXISTS hace la sentencia idempotente si alguien la aplica a mano.
|
||||||
|
|
||||||
|
ALTER TABLE "Cotizacion" ADD COLUMN IF NOT EXISTS "observacionesInternas" TEXT;
|
||||||
@@ -49,7 +49,13 @@ model Cotizacion {
|
|||||||
incluirIva Boolean @default(true)
|
incluirIva Boolean @default(true)
|
||||||
esDoble Boolean @default(false)
|
esDoble Boolean @default(false)
|
||||||
opcionesMetadata Json?
|
opcionesMetadata Json?
|
||||||
|
// Texto que SI ve el cliente: se imprime en el PDF y en el Excel.
|
||||||
observaciones String?
|
observaciones String?
|
||||||
|
// Contexto de discovery, notas del asesor, riesgos. NO sale de la app: ningun
|
||||||
|
// exportador declara este campo en su interfaz de datos (CotizacionPDFData /
|
||||||
|
// ExcelData) y la herramienta MCP obtener_cotizacion usa lista blanca de
|
||||||
|
// columnas. La garantia es estructural, no depende de recordar filtrarlo.
|
||||||
|
observacionesInternas String?
|
||||||
clienteId String
|
clienteId String
|
||||||
asesorId String
|
asesorId String
|
||||||
createdAt DateTime @default(now())
|
createdAt DateTime @default(now())
|
||||||
|
|||||||
@@ -45,6 +45,7 @@ export default async function EditarCotizacionPage({
|
|||||||
incluirBonos: cot.incluirBonos,
|
incluirBonos: cot.incluirBonos,
|
||||||
incluirFinanciamiento: cot.incluirFinanciamiento,
|
incluirFinanciamiento: cot.incluirFinanciamiento,
|
||||||
observaciones: cot.observaciones || "",
|
observaciones: cot.observaciones || "",
|
||||||
|
observacionesInternas: cot.observacionesInternas || "",
|
||||||
planBucefaloNivel: cot.planBucefalo?.nivel || null,
|
planBucefaloNivel: cot.planBucefalo?.nivel || null,
|
||||||
esDoble: cot.esDoble,
|
esDoble: cot.esDoble,
|
||||||
opciones: (cot.opcionesMetadata as { "1"?: object; "2"?: object } | null) ?? {},
|
opciones: (cot.opcionesMetadata as { "1"?: object; "2"?: object } | null) ?? {},
|
||||||
|
|||||||
@@ -226,10 +226,29 @@ export default async function CotizacionDetailPage({
|
|||||||
|
|
||||||
{cot.observaciones && (
|
{cot.observaciones && (
|
||||||
<div className="bg-card-bg rounded-xl border border-border p-5">
|
<div className="bg-card-bg rounded-xl border border-border p-5">
|
||||||
<h3 className="font-semibold mb-2">Observaciones</h3>
|
<h3 className="font-semibold mb-2 flex items-center gap-2">
|
||||||
|
Observaciones
|
||||||
|
<span className="text-[11px] font-semibold uppercase tracking-wide px-2 py-0.5 rounded-full bg-primary-light text-primary">
|
||||||
|
Las ve el cliente
|
||||||
|
</span>
|
||||||
|
</h3>
|
||||||
<p className="text-sm text-muted whitespace-pre-wrap">{cot.observaciones}</p>
|
<p className="text-sm text-muted whitespace-pre-wrap">{cot.observaciones}</p>
|
||||||
</div>
|
</div>
|
||||||
)}
|
)}
|
||||||
|
|
||||||
|
{/* Unico lugar donde se muestran las notas internas. No van a ningun
|
||||||
|
exportador: ni CotizacionPDFData ni ExcelData declaran el campo. */}
|
||||||
|
{cot.observacionesInternas && (
|
||||||
|
<div className="rounded-xl border border-amber-300 bg-amber-50 p-5">
|
||||||
|
<h3 className="font-semibold mb-2 flex items-center gap-2 text-amber-900">
|
||||||
|
Notas internas
|
||||||
|
<span className="text-[11px] font-semibold uppercase tracking-wide px-2 py-0.5 rounded-full bg-amber-200 text-amber-900">
|
||||||
|
No sale de la app
|
||||||
|
</span>
|
||||||
|
</h3>
|
||||||
|
<p className="text-sm text-amber-900/80 whitespace-pre-wrap">{cot.observacionesInternas}</p>
|
||||||
|
</div>
|
||||||
|
)}
|
||||||
</div>
|
</div>
|
||||||
);
|
);
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -100,6 +100,7 @@ export async function PUT(
|
|||||||
esDoble,
|
esDoble,
|
||||||
opciones,
|
opciones,
|
||||||
observaciones,
|
observaciones,
|
||||||
|
observacionesInternas,
|
||||||
cliente,
|
cliente,
|
||||||
servicios,
|
servicios,
|
||||||
planBucefalo,
|
planBucefalo,
|
||||||
@@ -158,6 +159,7 @@ export async function PUT(
|
|||||||
...(esDoble !== undefined && { esDoble }),
|
...(esDoble !== undefined && { esDoble }),
|
||||||
...(esDoble !== undefined && { opcionesMetadata: esDoble ? opciones ?? {} : undefined }),
|
...(esDoble !== undefined && { opcionesMetadata: esDoble ? opciones ?? {} : undefined }),
|
||||||
...(observaciones !== undefined && { observaciones }),
|
...(observaciones !== undefined && { observaciones }),
|
||||||
|
...(observacionesInternas !== undefined && { observacionesInternas }),
|
||||||
...(estado && ESTADOS_COTIZACION.includes(estado as typeof ESTADOS_COTIZACION[number]) && { estado }),
|
...(estado && ESTADOS_COTIZACION.includes(estado as typeof ESTADOS_COTIZACION[number]) && { estado }),
|
||||||
},
|
},
|
||||||
});
|
});
|
||||||
|
|||||||
@@ -26,6 +26,7 @@ export async function POST(request: NextRequest) {
|
|||||||
esDoble,
|
esDoble,
|
||||||
opciones,
|
opciones,
|
||||||
observaciones,
|
observaciones,
|
||||||
|
observacionesInternas,
|
||||||
cliente,
|
cliente,
|
||||||
asesorId,
|
asesorId,
|
||||||
servicios,
|
servicios,
|
||||||
@@ -81,6 +82,7 @@ export async function POST(request: NextRequest) {
|
|||||||
esDoble: esDoble ?? false,
|
esDoble: esDoble ?? false,
|
||||||
opcionesMetadata: esDoble ? opciones ?? {} : undefined,
|
opcionesMetadata: esDoble ? opciones ?? {} : undefined,
|
||||||
observaciones: observaciones || null,
|
observaciones: observaciones || null,
|
||||||
|
observacionesInternas: observacionesInternas || null,
|
||||||
clienteId: clienteIdFinal,
|
clienteId: clienteIdFinal,
|
||||||
asesorId,
|
asesorId,
|
||||||
estado: "borrador",
|
estado: "borrador",
|
||||||
|
|||||||
@@ -17,7 +17,12 @@ export async function GET(
|
|||||||
include: {
|
include: {
|
||||||
cliente: true,
|
cliente: true,
|
||||||
asesor: true,
|
asesor: true,
|
||||||
servicios: { include: { servicioCatalogo: true } },
|
// Mismo orderBy que el PDF: los dos documentos van en el mismo correo y
|
||||||
|
// deben listar las partidas en el mismo orden.
|
||||||
|
servicios: {
|
||||||
|
include: { servicioCatalogo: true },
|
||||||
|
orderBy: [{ fase: "asc" }, { createdAt: "asc" }],
|
||||||
|
},
|
||||||
planBucefalo: true,
|
planBucefalo: true,
|
||||||
},
|
},
|
||||||
}),
|
}),
|
||||||
@@ -67,6 +72,9 @@ export async function GET(
|
|||||||
planBucefaloPrecio: cot.planBucefalo?.precio ?? null,
|
planBucefaloPrecio: cot.planBucefalo?.precio ?? null,
|
||||||
colorPrimario: branding.colorPrimario || "#2563eb",
|
colorPrimario: branding.colorPrimario || "#2563eb",
|
||||||
colorSecundario: branding.colorSecundario || "#1e293b",
|
colorSecundario: branding.colorSecundario || "#1e293b",
|
||||||
|
incluirIva: cot.incluirIva,
|
||||||
|
// El Excel es un documento del cliente: solo el texto del cliente.
|
||||||
|
observaciones: cot.observaciones,
|
||||||
};
|
};
|
||||||
|
|
||||||
const buffer = await buildCotizacionExcel(data);
|
const buffer = await buildCotizacionExcel(data);
|
||||||
|
|||||||
@@ -80,6 +80,7 @@ export async function POST(request: NextRequest) {
|
|||||||
planBucefaloNivel: draft.planBucefaloNivel,
|
planBucefaloNivel: draft.planBucefaloNivel,
|
||||||
colorPrimario: branding.colorPrimario || "#2563eb",
|
colorPrimario: branding.colorPrimario || "#2563eb",
|
||||||
colorSecundario: branding.colorSecundario || "#1e293b",
|
colorSecundario: branding.colorSecundario || "#1e293b",
|
||||||
|
observaciones: draft.observaciones,
|
||||||
};
|
};
|
||||||
|
|
||||||
const buffer = await buildCotizacionExcel(data);
|
const buffer = await buildCotizacionExcel(data);
|
||||||
|
|||||||
@@ -10,18 +10,25 @@ export async function GET(
|
|||||||
) {
|
) {
|
||||||
try {
|
try {
|
||||||
const { id } = await params;
|
const { id } = await params;
|
||||||
const [cot, config, branding] = await Promise.all([
|
const [cot, config, branding, bonos] = await Promise.all([
|
||||||
prisma.cotizacion.findUnique({
|
prisma.cotizacion.findUnique({
|
||||||
where: { id },
|
where: { id },
|
||||||
include: {
|
include: {
|
||||||
cliente: true,
|
cliente: true,
|
||||||
asesor: true,
|
asesor: true,
|
||||||
servicios: { include: { servicioCatalogo: true } },
|
// orderBy explicito: drawSection abre un encabezado de fase nuevo cada vez
|
||||||
|
// que cambia serv.fase, o sea que asume el array agrupado. Sin esto el orden
|
||||||
|
// lo decide Postgres y el PDF puede salir distinto del Excel del mismo envio.
|
||||||
|
servicios: {
|
||||||
|
include: { servicioCatalogo: true },
|
||||||
|
orderBy: [{ fase: "asc" }, { createdAt: "asc" }],
|
||||||
|
},
|
||||||
planBucefalo: true,
|
planBucefalo: true,
|
||||||
},
|
},
|
||||||
}),
|
}),
|
||||||
getConfigBancaria(),
|
getConfigBancaria(),
|
||||||
getConfigBranding(),
|
getConfigBranding(),
|
||||||
|
prisma.bono.findMany({ where: { activo: true }, orderBy: { numero: "asc" } }),
|
||||||
]);
|
]);
|
||||||
|
|
||||||
if (!cot) {
|
if (!cot) {
|
||||||
@@ -61,6 +68,10 @@ export async function GET(
|
|||||||
planBucefaloNivel: cot.planBucefalo?.nivel || null,
|
planBucefaloNivel: cot.planBucefalo?.nivel || null,
|
||||||
planBucefaloPrecio: cot.planBucefalo?.precio || 0,
|
planBucefaloPrecio: cot.planBucefalo?.precio || 0,
|
||||||
incluirBonos: cot.incluirBonos,
|
incluirBonos: cot.incluirBonos,
|
||||||
|
bonos,
|
||||||
|
incluirIva: cot.incluirIva,
|
||||||
|
// Solo el texto del cliente. observacionesInternas no se pasa nunca.
|
||||||
|
observaciones: cot.observaciones,
|
||||||
configBancaria: config,
|
configBancaria: config,
|
||||||
...branding,
|
...branding,
|
||||||
});
|
});
|
||||||
|
|||||||
@@ -1,7 +1,8 @@
|
|||||||
import { NextRequest, NextResponse } from "next/server";
|
import { NextRequest, NextResponse } from "next/server";
|
||||||
|
import { prisma } from "@/lib/db";
|
||||||
import { generateCotizacionPDF } from "@/lib/pdf-generator";
|
import { generateCotizacionPDF } from "@/lib/pdf-generator";
|
||||||
import { calcularVigencia, bucefaloPrecio, sanitizeFilename } from "@/lib/calculators";
|
import { calcularVigencia, bucefaloPrecio, sanitizeFilename } from "@/lib/calculators";
|
||||||
import { getConfigBranding } from "@/lib/config-helpers";
|
import { getConfigBranding, getConfigBancaria } from "@/lib/config-helpers";
|
||||||
|
|
||||||
export async function POST(request: NextRequest) {
|
export async function POST(request: NextRequest) {
|
||||||
try {
|
try {
|
||||||
@@ -42,7 +43,14 @@ export async function POST(request: NextRequest) {
|
|||||||
const fechaCot = new Date(draft.fecha);
|
const fechaCot = new Date(draft.fecha);
|
||||||
const vigencia = calcularVigencia(fechaCot);
|
const vigencia = calcularVigencia(fechaCot);
|
||||||
|
|
||||||
const branding = await getConfigBranding();
|
// El borrador leia solo el branding, asi que imprimia los datos bancarios
|
||||||
|
// hardcodeados del generador en vez de los configurados. El Excel de borrador
|
||||||
|
// si leia ambos: esto empareja los dos.
|
||||||
|
const [branding, configBancaria, bonos] = await Promise.all([
|
||||||
|
getConfigBranding(),
|
||||||
|
getConfigBancaria(),
|
||||||
|
prisma.bono.findMany({ where: { activo: true }, orderBy: { numero: "asc" } }),
|
||||||
|
]);
|
||||||
const empresa = draft.clienteEmpresa || draft.clienteNombre;
|
const empresa = draft.clienteEmpresa || draft.clienteNombre;
|
||||||
const nombre = `${sanitizeFilename(empresa)} - ${sanitizeFilename(draft.clienteNombre)} - BORRADOR`;
|
const nombre = `${sanitizeFilename(empresa)} - ${sanitizeFilename(draft.clienteNombre)} - BORRADOR`;
|
||||||
|
|
||||||
@@ -63,6 +71,10 @@ export async function POST(request: NextRequest) {
|
|||||||
planBucefaloNivel: draft.planBucefaloNivel,
|
planBucefaloNivel: draft.planBucefaloNivel,
|
||||||
planBucefaloPrecio: draft.planBucefaloNivel ? bucefaloPrecio(draft.planBucefaloNivel) : 0,
|
planBucefaloPrecio: draft.planBucefaloNivel ? bucefaloPrecio(draft.planBucefaloNivel) : 0,
|
||||||
incluirBonos: draft.incluirBonos,
|
incluirBonos: draft.incluirBonos,
|
||||||
|
bonos,
|
||||||
|
// El cliente ya mandaba observaciones en el body; el generador nunca las recibia.
|
||||||
|
observaciones: draft.observaciones,
|
||||||
|
configBancaria,
|
||||||
...branding,
|
...branding,
|
||||||
});
|
});
|
||||||
|
|
||||||
|
|||||||
@@ -17,6 +17,8 @@ import {
|
|||||||
Clock,
|
Clock,
|
||||||
Plus,
|
Plus,
|
||||||
Trash2,
|
Trash2,
|
||||||
|
Eye,
|
||||||
|
Lock,
|
||||||
} from "lucide-react";
|
} from "lucide-react";
|
||||||
import clsx from "clsx";
|
import clsx from "clsx";
|
||||||
import {
|
import {
|
||||||
@@ -82,6 +84,7 @@ export interface ExistingData {
|
|||||||
incluirBonos: boolean;
|
incluirBonos: boolean;
|
||||||
incluirFinanciamiento: boolean;
|
incluirFinanciamiento: boolean;
|
||||||
observaciones: string;
|
observaciones: string;
|
||||||
|
observacionesInternas?: string;
|
||||||
planBucefaloNivel: string | null;
|
planBucefaloNivel: string | null;
|
||||||
estado: string;
|
estado: string;
|
||||||
servicios: ServicioSeleccionado[];
|
servicios: ServicioSeleccionado[];
|
||||||
@@ -165,6 +168,7 @@ export function CotizacionForm({
|
|||||||
store.setField("incluirBonos", existingData.incluirBonos);
|
store.setField("incluirBonos", existingData.incluirBonos);
|
||||||
store.setField("incluirFinanciamiento", existingData.incluirFinanciamiento);
|
store.setField("incluirFinanciamiento", existingData.incluirFinanciamiento);
|
||||||
store.setField("observaciones", existingData.observaciones);
|
store.setField("observaciones", existingData.observaciones);
|
||||||
|
store.setField("observacionesInternas", existingData.observacionesInternas ?? "");
|
||||||
store.setField("planBucefaloNivel", existingData.planBucefaloNivel);
|
store.setField("planBucefaloNivel", existingData.planBucefaloNivel);
|
||||||
store.setField("esDoble", existingData.esDoble ?? false);
|
store.setField("esDoble", existingData.esDoble ?? false);
|
||||||
store.setField("opciones", existingData.opciones ?? {});
|
store.setField("opciones", existingData.opciones ?? {});
|
||||||
@@ -333,6 +337,7 @@ export function CotizacionForm({
|
|||||||
esDoble: store.draft.esDoble,
|
esDoble: store.draft.esDoble,
|
||||||
opciones: store.draft.esDoble ? store.draft.opciones : undefined,
|
opciones: store.draft.esDoble ? store.draft.opciones : undefined,
|
||||||
observaciones: store.draft.observaciones,
|
observaciones: store.draft.observaciones,
|
||||||
|
observacionesInternas: store.draft.observacionesInternas,
|
||||||
cliente: {
|
cliente: {
|
||||||
nombre: store.draft.clienteNombre,
|
nombre: store.draft.clienteNombre,
|
||||||
empresa: store.draft.clienteEmpresa,
|
empresa: store.draft.clienteEmpresa,
|
||||||
@@ -1217,20 +1222,52 @@ export function CotizacionForm({
|
|||||||
</div>
|
</div>
|
||||||
</div>
|
</div>
|
||||||
|
|
||||||
<div className="bg-card-bg rounded-xl border border-border p-5">
|
{/* Dos campos deliberadamente distintos. El de arriba se imprime en el PDF y
|
||||||
<label className="block text-sm font-medium text-muted mb-1">
|
el Excel que recibe el cliente; el de abajo no sale de la aplicacion.
|
||||||
|
La diferencia visual es la barrera contra escribir en el equivocado. */}
|
||||||
|
<div className="bg-card-bg rounded-xl border border-border p-5 space-y-5">
|
||||||
|
<div>
|
||||||
|
<label className="flex items-center gap-2 text-sm font-medium mb-1">
|
||||||
|
<Eye className="w-4 h-4 text-primary" />
|
||||||
Observaciones
|
Observaciones
|
||||||
|
<span className="text-[11px] font-semibold uppercase tracking-wide px-2 py-0.5 rounded-full bg-primary-light text-primary">
|
||||||
|
Las ve el cliente
|
||||||
|
</span>
|
||||||
</label>
|
</label>
|
||||||
|
<p className="text-xs text-muted mb-2">
|
||||||
|
Se imprime en el PDF y en el Excel que le envias. Condiciones, supuestos y
|
||||||
|
aclaraciones del acuerdo.
|
||||||
|
</p>
|
||||||
<textarea
|
<textarea
|
||||||
value={store.draft.observaciones}
|
value={store.draft.observaciones}
|
||||||
onChange={(e) =>
|
onChange={(e) => store.setField("observaciones", e.target.value)}
|
||||||
store.setField("observaciones", e.target.value)
|
|
||||||
}
|
|
||||||
rows={3}
|
rows={3}
|
||||||
placeholder="Notas adicionales para la cotizacion..."
|
placeholder="Ej: El anticipo es del 50%. El avance queda condicionado a la entrega de accesos."
|
||||||
className={INPUT_CLS}
|
className={INPUT_CLS}
|
||||||
/>
|
/>
|
||||||
</div>
|
</div>
|
||||||
|
|
||||||
|
<div className="rounded-lg border border-amber-300 bg-amber-50 p-4">
|
||||||
|
<label className="flex items-center gap-2 text-sm font-medium mb-1 text-amber-900">
|
||||||
|
<Lock className="w-4 h-4" />
|
||||||
|
Notas internas
|
||||||
|
<span className="text-[11px] font-semibold uppercase tracking-wide px-2 py-0.5 rounded-full bg-amber-200 text-amber-900">
|
||||||
|
No sale de la app
|
||||||
|
</span>
|
||||||
|
</label>
|
||||||
|
<p className="text-xs text-amber-800 mb-2">
|
||||||
|
Contexto de la reunion, con quien hablar, riesgos, recordatorios. No se imprime
|
||||||
|
en ningun documento ni se expone por el API.
|
||||||
|
</p>
|
||||||
|
<textarea
|
||||||
|
value={store.draft.observacionesInternas}
|
||||||
|
onChange={(e) => store.setField("observacionesInternas", e.target.value)}
|
||||||
|
rows={3}
|
||||||
|
placeholder="Ej: El que decide es el socio, no el que vino a la reunion. Pidio descuento antes de ver el alcance."
|
||||||
|
className={INPUT_CLS}
|
||||||
|
/>
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
</div>
|
</div>
|
||||||
|
|
||||||
<div className="hidden lg:block w-80 shrink-0">
|
<div className="hidden lg:block w-80 shrink-0">
|
||||||
|
|||||||
@@ -112,6 +112,69 @@ export function calcularTotalesOpcion(
|
|||||||
};
|
};
|
||||||
}
|
}
|
||||||
|
|
||||||
|
// ----- Totales de una cotizacion: FUENTE DE VERDAD UNICA -----
|
||||||
|
// Antes este calculo estaba duplicado a mano con .filter().reduce() en siete
|
||||||
|
// consumidores (PDF, Excel, detalle, PreciosEditables, formulario, lista y dashboard),
|
||||||
|
// con criterios que no coincidian, y el IVA estaba hardcodeado como * 1.16 en los dos
|
||||||
|
// exportadores ignorando IVA_RATE y el flag incluirIva. Toda comparacion de totales
|
||||||
|
// (y cualquier documento que deba coincidir con el PDF) debe pasar por aqui.
|
||||||
|
//
|
||||||
|
// Nota: los subtotales son SIN IVA, que es como los exportadores presentan hoy los
|
||||||
|
// totales de una cotizacion simple ("los precios no incluyen IVA" en la nota al pie).
|
||||||
|
export interface TotalesCotizacion {
|
||||||
|
subtotalUnico: number;
|
||||||
|
subtotalMensual: number;
|
||||||
|
ivaUnico: number;
|
||||||
|
ivaMensual: number;
|
||||||
|
totalUnico: number;
|
||||||
|
totalMensual: number;
|
||||||
|
/** Desembolso real a 12 meses: unico + mensual x 12, con IVA si aplica.
|
||||||
|
* Es la base del ratio precio/valor de la propuesta consultiva. */
|
||||||
|
totalPrimerAnio: number;
|
||||||
|
incluyeIva: boolean;
|
||||||
|
}
|
||||||
|
|
||||||
|
export function calcularTotalesCotizacion(
|
||||||
|
servicios: Array<{ tipoPago: string; precio: number; seleccionado?: boolean }>,
|
||||||
|
opciones?: { incluirIva?: boolean }
|
||||||
|
): TotalesCotizacion {
|
||||||
|
const incluyeIva = opciones?.incluirIva !== false;
|
||||||
|
const activos = servicios.filter((s) => s.seleccionado !== false);
|
||||||
|
|
||||||
|
const suma = (tipo: string) =>
|
||||||
|
r2(activos.filter((s) => s.tipoPago === tipo).reduce((a, s) => a + (s.precio || 0), 0));
|
||||||
|
|
||||||
|
const subtotalUnico = suma("unico");
|
||||||
|
const subtotalMensual = suma("mensual");
|
||||||
|
|
||||||
|
const ivaUnico = incluyeIva ? r2(subtotalUnico * IVA_RATE) : 0;
|
||||||
|
const ivaMensual = incluyeIva ? r2(subtotalMensual * IVA_RATE) : 0;
|
||||||
|
|
||||||
|
const totalUnico = r2(subtotalUnico + ivaUnico);
|
||||||
|
const totalMensual = r2(subtotalMensual + ivaMensual);
|
||||||
|
|
||||||
|
return {
|
||||||
|
subtotalUnico,
|
||||||
|
subtotalMensual,
|
||||||
|
ivaUnico,
|
||||||
|
ivaMensual,
|
||||||
|
totalUnico,
|
||||||
|
totalMensual,
|
||||||
|
totalPrimerAnio: r2(totalUnico + totalMensual * 12),
|
||||||
|
incluyeIva,
|
||||||
|
};
|
||||||
|
}
|
||||||
|
|
||||||
|
function r2(n: number): number {
|
||||||
|
return Math.round(n * 100) / 100;
|
||||||
|
}
|
||||||
|
|
||||||
|
/** Aplica IVA a un monto respetando el flag de la cotizacion.
|
||||||
|
* Sustituye a los `* 1.16` hardcodeados que habia en pdf-generator y excel-builder. */
|
||||||
|
export function conIva(monto: number, incluirIva: boolean = true): number {
|
||||||
|
return r2((monto || 0) * (incluirIva ? 1 + IVA_RATE : 1));
|
||||||
|
}
|
||||||
|
|
||||||
export const FASES: Record<number, string> = {
|
export const FASES: Record<number, string> = {
|
||||||
0: "FASE 0 - Auditoria / Acompanamiento",
|
0: "FASE 0 - Auditoria / Acompanamiento",
|
||||||
1: "FASE 1 - Setup e Infraestructura",
|
1: "FASE 1 - Setup e Infraestructura",
|
||||||
|
|||||||
+29
-11
@@ -1,5 +1,5 @@
|
|||||||
import ExcelJS from "exceljs";
|
import ExcelJS from "exceljs";
|
||||||
import { bucefaloPrecio, describirRetainer, formatCurrency, calcularTotalesOpcion, type MetaOpcion } from "@/lib/calculators";
|
import { bucefaloPrecio, conIva, detalleModelo as detalleModeloCanonico, formatCurrency, calcularTotalesOpcion, type MetaOpcion } from "@/lib/calculators";
|
||||||
|
|
||||||
// ─────────────────────────────────────────────────────────────────────────────
|
// ─────────────────────────────────────────────────────────────────────────────
|
||||||
// Forma normalizada de los datos que necesita el Excel. Tanto la ruta de borrador
|
// Forma normalizada de los datos que necesita el Excel. Tanto la ruta de borrador
|
||||||
@@ -44,6 +44,11 @@ export interface ExcelData {
|
|||||||
planBucefaloPrecio?: number | null;
|
planBucefaloPrecio?: number | null;
|
||||||
colorPrimario: string;
|
colorPrimario: string;
|
||||||
colorSecundario: string;
|
colorSecundario: string;
|
||||||
|
incluirIva?: boolean;
|
||||||
|
/** Texto que SI ve el cliente. El Excel es un documento del cliente (lleva razon
|
||||||
|
* social, "En atencion a:", domicilio fiscal y nota legal), no una herramienta
|
||||||
|
* interna: por eso `observacionesInternas` NO se declara aqui. */
|
||||||
|
observaciones?: string | null;
|
||||||
}
|
}
|
||||||
|
|
||||||
// Convierte "#RRGGBB" a ARGB de 8 caracteres. `alpha` es el canal alfa (2 hex):
|
// Convierte "#RRGGBB" a ARGB de 8 caracteres. `alpha` es el canal alfa (2 hex):
|
||||||
@@ -54,15 +59,10 @@ function argb(hex: string, alpha = "FF"): string {
|
|||||||
return alpha + h.toUpperCase();
|
return alpha + h.toUpperCase();
|
||||||
}
|
}
|
||||||
|
|
||||||
// Texto de desglose por modelo de cobro (horas / retainer) para mostrar junto al servicio.
|
// Delega en la version canonica de calculators.ts. La copia local que habia aqui
|
||||||
|
// omitia la rama "demanda", igual que la del PDF.
|
||||||
function detalleModelo(serv: ExcelServicio): string {
|
function detalleModelo(serv: ExcelServicio): string {
|
||||||
if (serv.modeloCobro === "retainer") {
|
return detalleModeloCanonico(serv);
|
||||||
return describirRetainer(serv.montoMinimo ?? 0, serv.horasIncluidas ?? 0, serv.tarifaHora ?? 0);
|
|
||||||
}
|
|
||||||
if ((serv.modeloCobro === "horas" || serv.esPersonalizado) && serv.horas && serv.tarifaHora) {
|
|
||||||
return `${serv.horas} h x ${formatCurrency(serv.tarifaHora)}/hr`;
|
|
||||||
}
|
|
||||||
return "";
|
|
||||||
}
|
}
|
||||||
|
|
||||||
function applyThinBorder(cell: ExcelJS.Cell, color?: string) {
|
function applyThinBorder(cell: ExcelJS.Cell, color?: string) {
|
||||||
@@ -374,8 +374,10 @@ export async function buildCotizacionExcel(data: ExcelData): Promise<Buffer> {
|
|||||||
row++;
|
row++;
|
||||||
};
|
};
|
||||||
compRow("Concepto", `Opcion 1${t1Tit ? " - " + t1Tit : ""}`, `Opcion 2${t2Tit ? " - " + t2Tit : ""}`, boldFont);
|
compRow("Concepto", `Opcion 1${t1Tit ? " - " + t1Tit : ""}`, `Opcion 2${t2Tit ? " - " + t2Tit : ""}`, boldFont);
|
||||||
compRow("Total unico (c/IVA)", formatCurrency(t1.totalUnico * 1.16), formatCurrency(t2.totalUnico * 1.16), valueFont);
|
// IVA via conIva() y no `* 1.16`: respeta Cotizacion.incluirIva y usa IVA_RATE.
|
||||||
compRow("Total mensual (c/IVA)", formatCurrency(t1.totalMensual * 1.16), formatCurrency(t2.totalMensual * 1.16), valueFont);
|
const ivaLbl = data.incluirIva === false ? "" : " (c/IVA)";
|
||||||
|
compRow(`Total unico${ivaLbl}`, formatCurrency(conIva(t1.totalUnico, data.incluirIva)), formatCurrency(conIva(t2.totalUnico, data.incluirIva)), valueFont);
|
||||||
|
compRow(`Total mensual${ivaLbl}`, formatCurrency(conIva(t1.totalMensual, data.incluirIva)), formatCurrency(conIva(t2.totalMensual, data.incluirIva)), valueFont);
|
||||||
compRow("Horas estimadas", `${t1.horas} h`, `${t2.horas} h`, valueFont);
|
compRow("Horas estimadas", `${t1.horas} h`, `${t2.horas} h`, valueFont);
|
||||||
row++;
|
row++;
|
||||||
} else {
|
} else {
|
||||||
@@ -402,6 +404,22 @@ export async function buildCotizacionExcel(data: ExcelData): Promise<Buffer> {
|
|||||||
ws.getCell(`B${row}`).font = smallFont;
|
ws.getCell(`B${row}`).font = smallFont;
|
||||||
setWrapped(ws, row, "B", notaResumen, mergedWidth(ws, "B", "K"), { fontSize: 9 });
|
setWrapped(ws, row, "B", notaResumen, mergedWidth(ws, "B", "K"), { fontSize: 9 });
|
||||||
|
|
||||||
|
// Observaciones del cliente. Solo este campo: el Excel lleva razon social,
|
||||||
|
// "En atencion a:" y domicilio fiscal, o sea que es un documento que el cliente
|
||||||
|
// recibe. observacionesInternas no existe en ExcelData a proposito.
|
||||||
|
if (data.observaciones && data.observaciones.trim()) {
|
||||||
|
row += 2;
|
||||||
|
ws.mergeCells(`B${row}:K${row}`);
|
||||||
|
ws.getCell(`B${row}`).value = "OBSERVACIONES";
|
||||||
|
ws.getCell(`B${row}`).font = { ...boldFont, color: { argb: PRIMARY } };
|
||||||
|
row++;
|
||||||
|
ws.mergeCells(`B${row}:K${row}`);
|
||||||
|
const texto = data.observaciones.trim();
|
||||||
|
ws.getCell(`B${row}`).value = texto;
|
||||||
|
ws.getCell(`B${row}`).font = smallFont;
|
||||||
|
setWrapped(ws, row, "B", texto, mergedWidth(ws, "B", "K"), { fontSize: 9 });
|
||||||
|
}
|
||||||
|
|
||||||
// ═══════════════════════════════════════════════════════════════════════════
|
// ═══════════════════════════════════════════════════════════════════════════
|
||||||
// HOJAS DETALLADAS POR SERVICIO
|
// HOJAS DETALLADAS POR SERVICIO
|
||||||
// ═══════════════════════════════════════════════════════════════════════════
|
// ═══════════════════════════════════════════════════════════════════════════
|
||||||
|
|||||||
+64
-19
@@ -1,5 +1,5 @@
|
|||||||
import PDFDocument from "pdfkit";
|
import PDFDocument from "pdfkit";
|
||||||
import { FASES_SHORT as FASES, describirRetainer, formatCurrency, calcularTotalesOpcion, type MetaOpcion } from "./calculators";
|
import { FASES_SHORT as FASES, conIva, detalleModelo, calcularTotalesOpcion, type MetaOpcion } from "./calculators";
|
||||||
|
|
||||||
interface ServicioPDF {
|
interface ServicioPDF {
|
||||||
nombre: string;
|
nombre: string;
|
||||||
@@ -18,14 +18,11 @@ interface ServicioPDF {
|
|||||||
}
|
}
|
||||||
|
|
||||||
// Texto de desglose por modelo de cobro (horas / retainer) para la sub-linea del servicio.
|
// Texto de desglose por modelo de cobro (horas / retainer) para la sub-linea del servicio.
|
||||||
|
// Delega en la version canonica de calculators.ts. La copia local que habia aqui
|
||||||
|
// omitia la rama "demanda", asi que esa partida se imprimia sin desglose y con
|
||||||
|
// precio $0, sin explicar que se factura segun consumo.
|
||||||
function detalleModeloPDF(serv: ServicioPDF): string {
|
function detalleModeloPDF(serv: ServicioPDF): string {
|
||||||
if (serv.modeloCobro === "retainer") {
|
return detalleModelo(serv);
|
||||||
return describirRetainer(serv.montoMinimo ?? 0, serv.horasIncluidas ?? 0, serv.tarifaHora ?? 0);
|
|
||||||
}
|
|
||||||
if ((serv.modeloCobro === "horas" || serv.esPersonalizado) && serv.horas && serv.tarifaHora) {
|
|
||||||
return `${serv.horas} h x ${formatCurrency(serv.tarifaHora)}/hr`;
|
|
||||||
}
|
|
||||||
return "";
|
|
||||||
}
|
}
|
||||||
|
|
||||||
interface CotizacionPDFData {
|
interface CotizacionPDFData {
|
||||||
@@ -45,6 +42,13 @@ interface CotizacionPDFData {
|
|||||||
planBucefaloNivel: string | null;
|
planBucefaloNivel: string | null;
|
||||||
planBucefaloPrecio: number;
|
planBucefaloPrecio: number;
|
||||||
incluirBonos: boolean;
|
incluirBonos: boolean;
|
||||||
|
/** Bonos desde la tabla Bono. Si no se pasan, se usa la lista de respaldo. */
|
||||||
|
bonos?: { numero: number; descripcion: string }[];
|
||||||
|
incluirIva?: boolean;
|
||||||
|
/** Texto que SI ve el cliente. `observacionesInternas` NO se declara aqui a
|
||||||
|
* proposito: si el generador no puede verlo, no puede filtrarlo. La garantia
|
||||||
|
* es estructural, no depende de la disciplina de quien dibuje. */
|
||||||
|
observaciones?: string | null;
|
||||||
configBancaria?: Record<string, string>;
|
configBancaria?: Record<string, string>;
|
||||||
colorPrimario?: string;
|
colorPrimario?: string;
|
||||||
colorSecundario?: string;
|
colorSecundario?: string;
|
||||||
@@ -324,9 +328,11 @@ export async function generateCotizacionPDF(data: CotizacionPDFData): Promise<Bu
|
|||||||
doc.text(`Opcion 1${t1Tit ? " - " + t1Tit : ""}`, cOp1, y + 4, { width: W * 0.27 - 4 });
|
doc.text(`Opcion 1${t1Tit ? " - " + t1Tit : ""}`, cOp1, y + 4, { width: W * 0.27 - 4 });
|
||||||
doc.text(`Opcion 2${t2Tit ? " - " + t2Tit : ""}`, cOp2, y + 4, { width: W * 0.28 - 4 });
|
doc.text(`Opcion 2${t2Tit ? " - " + t2Tit : ""}`, cOp2, y + 4, { width: W * 0.28 - 4 });
|
||||||
y += 18;
|
y += 18;
|
||||||
|
// IVA via conIva() y no `* 1.16`: respeta Cotizacion.incluirIva y usa IVA_RATE.
|
||||||
|
const ivaLbl = data.incluirIva === false ? "" : " (c/IVA)";
|
||||||
const filas: [string, string, string][] = [
|
const filas: [string, string, string][] = [
|
||||||
["Total unico (c/IVA)", fmt(t1.totalUnico * 1.16), fmt(t2.totalUnico * 1.16)],
|
[`Total unico${ivaLbl}`, fmt(conIva(t1.totalUnico, data.incluirIva)), fmt(conIva(t2.totalUnico, data.incluirIva))],
|
||||||
["Total mensual (c/IVA)", fmt(t1.totalMensual * 1.16), fmt(t2.totalMensual * 1.16)],
|
[`Total mensual${ivaLbl}`, fmt(conIva(t1.totalMensual, data.incluirIva)), fmt(conIva(t2.totalMensual, data.incluirIva))],
|
||||||
["Horas estimadas", `${t1.horas} h`, `${t2.horas} h`],
|
["Horas estimadas", `${t1.horas} h`, `${t2.horas} h`],
|
||||||
];
|
];
|
||||||
for (const [lab, v1, v2] of filas) {
|
for (const [lab, v1, v2] of filas) {
|
||||||
@@ -374,21 +380,60 @@ export async function generateCotizacionPDF(data: CotizacionPDFData): Promise<Bu
|
|||||||
doc.rect(L, y, 3, 10).fill(PRIMARY);
|
doc.rect(L, y, 3, 10).fill(PRIMARY);
|
||||||
doc.font("Helvetica-Bold").fontSize(9).fillColor(DARK).text("Bonos (Pago en una exhibicion)", L + 10, y);
|
doc.font("Helvetica-Bold").fontSize(9).fillColor(DARK).text("Bonos (Pago en una exhibicion)", L + 10, y);
|
||||||
y += 16;
|
y += 16;
|
||||||
const bonos = [
|
// Fuente de verdad: la tabla Bono. La lista de abajo es solo respaldo por si
|
||||||
"Bono 1: 30 min mensuales en servicios Centinela (Sitio Web)",
|
// la consulta no trajo nada; antes estaba hardcodeada aqui y su texto ya no
|
||||||
"Bono 2: Workshop Estrategico de Buyer Persona",
|
// coincidia con el del seed (bono 5).
|
||||||
"Bono 3: Workshop de Propuestas de Valor y Oferta Irresistible",
|
const RESPALDO = [
|
||||||
"Bono 4: 1 ano de Membresia Premium",
|
"30 min mensuales en servicios Centinela (Sitio Web)",
|
||||||
"Bono 5: Un mes gratis de Bucefalo CRM",
|
"Workshop Estrategico de Buyer Persona",
|
||||||
"Bono 6: Script de Ventas con mas de 100 complementos",
|
"Workshop de Propuestas de Valor y Oferta Irresistible",
|
||||||
];
|
"1 ano de Membresia Premium",
|
||||||
|
"Un mes gratis de Bucefalo CRM, Marketing y Ventas",
|
||||||
|
"Script de Ventas con mas de 100 complementos",
|
||||||
|
].map((d, i) => `Bono ${i + 1}: ${d}`);
|
||||||
|
|
||||||
|
const bonos = data.bonos?.length
|
||||||
|
? data.bonos.map((b) => `Bono ${b.numero}: ${b.descripcion}`)
|
||||||
|
: RESPALDO;
|
||||||
|
|
||||||
for (const b of bonos) {
|
for (const b of bonos) {
|
||||||
y = need(11, y);
|
y = need(11, y);
|
||||||
doc.font("Helvetica").fontSize(7).fillColor(DARK).text(`\u2713 ${b}`, L + 8, y, { width: W - 16 });
|
// Vinneta "\u2022" y no la palomita "\u2713": en las fuentes estandar de PDFKit
|
||||||
|
// la palomita mide 0pt de ancho, o sea que hoy salia como dos espacios.
|
||||||
|
doc.font("Helvetica").fontSize(7).fillColor(DARK).text(`\u2022 ${b}`, L + 8, y, { width: W - 16 });
|
||||||
y += 11;
|
y += 11;
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
|
// ── OBSERVACIONES (solo el texto del cliente) ──
|
||||||
|
// Va al final de la Hoja Resumen, junto a los totales y antes de T&C, que es
|
||||||
|
// donde el cliente espera leer un mensaje del asesor. Nunca imprime
|
||||||
|
// observacionesInternas: ese campo ni siquiera existe en CotizacionPDFData.
|
||||||
|
if (data.observaciones && data.observaciones.trim()) {
|
||||||
|
y = sectionTitle("Observaciones", y);
|
||||||
|
const usable = maxY - m.top;
|
||||||
|
const parrafos = data.observaciones
|
||||||
|
.split(/\r?\n/)
|
||||||
|
.map((p) => p.trim())
|
||||||
|
.filter(Boolean);
|
||||||
|
|
||||||
|
for (const p of parrafos) {
|
||||||
|
const h = txtHeight(p, W - 4, 7.5);
|
||||||
|
if (h > usable) {
|
||||||
|
// Parrafo mas alto que una pagina entera: need() no sabe partir, asi que
|
||||||
|
// se deja fluir a pdfkit y se resincroniza el contador con doc.y.
|
||||||
|
y = need(20, y);
|
||||||
|
doc.font("Helvetica").fontSize(7.5).fillColor(DARK).text(p, L + 2, y, { width: W - 4 });
|
||||||
|
y = doc.y + 4;
|
||||||
|
} else {
|
||||||
|
y = need(h + 4, y);
|
||||||
|
doc.font("Helvetica").fontSize(7.5).fillColor(DARK).text(p, L + 2, y, { width: W - 4 });
|
||||||
|
y += h + 4;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
y += 4;
|
||||||
|
}
|
||||||
|
|
||||||
// ── T&C PAGE ──────────────────────────────────
|
// ── T&C PAGE ──────────────────────────────────
|
||||||
doc.addPage();
|
doc.addPage();
|
||||||
y = m.top;
|
y = m.top;
|
||||||
|
|||||||
@@ -43,6 +43,7 @@ export const cotizacionPostSchema = z.object({
|
|||||||
esDoble: z.boolean().optional(),
|
esDoble: z.boolean().optional(),
|
||||||
opciones: opcionesSchema,
|
opciones: opcionesSchema,
|
||||||
observaciones: z.string(),
|
observaciones: z.string(),
|
||||||
|
observacionesInternas: z.string().optional(),
|
||||||
asesorId: z.string().min(1),
|
asesorId: z.string().min(1),
|
||||||
cliente: z.object({
|
cliente: z.object({
|
||||||
nombre: z.string().min(1, "Cliente nombre es requerido"),
|
nombre: z.string().min(1, "Cliente nombre es requerido"),
|
||||||
@@ -73,6 +74,7 @@ export const cotizacionPutSchema = z.object({
|
|||||||
esDoble: z.boolean().optional(),
|
esDoble: z.boolean().optional(),
|
||||||
opciones: opcionesSchema,
|
opciones: opcionesSchema,
|
||||||
observaciones: z.string(),
|
observaciones: z.string(),
|
||||||
|
observacionesInternas: z.string().optional(),
|
||||||
cliente: z.object({
|
cliente: z.object({
|
||||||
nombre: z.string().min(1, "Cliente nombre es requerido"),
|
nombre: z.string().min(1, "Cliente nombre es requerido"),
|
||||||
empresa: z.string(),
|
empresa: z.string(),
|
||||||
|
|||||||
@@ -42,6 +42,7 @@ export interface CotizacionDraft {
|
|||||||
planBucefaloNivel: string | null;
|
planBucefaloNivel: string | null;
|
||||||
servicios: ServicioSeleccionado[];
|
servicios: ServicioSeleccionado[];
|
||||||
observaciones: string;
|
observaciones: string;
|
||||||
|
observacionesInternas: string;
|
||||||
// Doble propuesta: dos opciones comparables dentro de una misma cotizacion.
|
// Doble propuesta: dos opciones comparables dentro de una misma cotizacion.
|
||||||
esDoble: boolean;
|
esDoble: boolean;
|
||||||
opciones: { "1"?: MetaOpcion; "2"?: MetaOpcion };
|
opciones: { "1"?: MetaOpcion; "2"?: MetaOpcion };
|
||||||
@@ -79,6 +80,7 @@ const initialDraft: CotizacionDraft = {
|
|||||||
planBucefaloNivel: null,
|
planBucefaloNivel: null,
|
||||||
servicios: [],
|
servicios: [],
|
||||||
observaciones: "",
|
observaciones: "",
|
||||||
|
observacionesInternas: "",
|
||||||
esDoble: false,
|
esDoble: false,
|
||||||
opciones: {},
|
opciones: {},
|
||||||
};
|
};
|
||||||
|
|||||||
Reference in New Issue
Block a user