mdominguez/ars-report-kit
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
ars-report-kit/AGENT_GUIDE.md
Mario Daniel Dominguez Sosa a2bd6cb697 ars-report-kit: kit portátil de branding para reportes/cotizaciones 
Extraído de autosanta-stack (agente de santa) para reusarlo en cualquier
proyecto: plantilla base + 2 ejemplos + logo + Paged.js, sin dependencias de
servidor. Ver AGENT_GUIDE.md.
2026-07-23 16:06:53 +00:00

8.5 KiB
Raw Blame History

AGENT_GUIDE — Generar reportes y cotizaciones con la plantilla ARS Integradores

Eres un agente que produce documentos ejecutivos (reportes técnicos, incidentes, cotizaciones, propuestas) con la identidad visual de ARS Integradores. Los entregables se ven en el navegador y se exportan a PDF tamaño carta con encabezado y pie de página en cada hoja.

Esta capacidad NO depende de ningún servidor: es un archivo HTML autocontenido que abres en Chrome. Trabaja en español.

Archivos del kit (deben estar juntos en la misma carpeta)

Archivo Para qué
ars_report_base.html Plantilla maestra. Cópiala y rellénala. No la edites en su lugar.
logo-report.jpg Logo ARS. Referenciado como src="logo-report.jpg".
paged.polyfill.js Motor de paginación (Paged.js). Necesario sólo al exportar a PDF.
example_cotizacion.html Ejemplo completo de una cotización.
example_reporte.html Ejemplo completo de un reporte técnico.

Regla de oro: cada documento que generes es una copia de ars_report_base.html guardada con otro nombre (p. ej. COT-2026-014.html), en la misma carpeta que logo-report.jpg y paged.polyfill.js.

Cómo generar un documento (flujo)

  1. Copia ars_report_base.html → <FOLIO>.html.
  2. Rellena las ZONAS DE EDICIÓN marcadas con <!-- EDIT ... -->:
    • <title> de la pestaña.
    • Título / subtítulo (.title-block).
    • Barra de folio (.folio-bar): folio, fecha, referencia, clasificación.
    • Info de cliente (.contract-info).
    • Cuerpo (.body): una .section por tema, usando los componentes de abajo.
    • Mes/año del pie (.footer .right) si aplica.
  3. Si necesitas estilos propios, agrégalos en el <style> donde dice /* EDIT: agrega aquí CSS extra */. Nunca toques los colores base ni la lógica de @page/.ars-header/.ars-footer.
  4. Exporta a PDF (ver más abajo).

Reglas de marca — OBLIGATORIAS

  • Fuente: 'Century Gothic', CenturyGothic, 'Apple Gothic', 'Trebuchet MS', Arial, sans-serif (fuente de sistema). Prohibido importar Google Fonts o cualquier recurso externo.
  • Color primario: #c81b74 (rosa magenta), variable CSS --pink. No lo cambies.
  • Logo: logo-report.jpg, esquina superior derecha, altura 70px.
  • URL: texto arsintegradores.com arriba a la izquierda (prefijo ars en negrita oscura).
  • Título: parallelogramo rosa (.title-block con clip-path).
  • Encabezados de sección: 15px, MAYÚSCULAS, rosa, borde izquierdo 3px solid var(--pink).
  • Cuerpo: 12px.
  • Pie de página (fijo, no lo inventes): Oficina (81) 8123 2899 · Tepatitlán 201 Col. Mitras Sur, Mty. NL, 64020 · arsintegradores.com.

Regla #1 de PAGINACIÓN — no la reinventes

La plantilla YA logra encabezado + pie en CADA página impresa mediante "running elements": .ars-header { position: running(arsHeader) } / .ars-footer { ... } combinado con @page { @top-left { content: element(arsHeader) } @bottom-left { ... } }. Esto se activa poniendo class="paged" en <html> (lo hace el botón "Exportar PDF").

PROHIBIDO para conseguir header/footer por página:

  • <table> con <thead>/<tfoot>.
  • pie con position: fixed.
  • el enfoque "sin running elements" (el pie sale SÓLO en la última página — está mal).

Para forzar que una sección empiece en página nueva, añádele la clase page-break: <div class="section page-break">.

Evita Chart.js / <canvas> — rompen la paginación de Paged.js. Usa KPIs y tablas CSS.

Convención de folios

Prefijo Tipo de documento
INC-YYYY-NNN Reporte de incidente
SOL-YYYY-NNN Reporte de solución / corrección
RPT-YYYY-NNN Reporte ejecutivo general (inventario, auditoría, análisis)
COT-YYYY-NNN Cotización
PROP-YYYY-NNN Propuesta / plan de trabajo

NNN es correlativo por año. Fecha en formato "15 de julio de 2026". Clasificación típica: Confidencial.

Componentes disponibles (copia y pega dentro de .body)

Barras de estado (arriba del cuerpo, ancho completo)

<div class="alert-bar"><span class="dot"></span> Incidente activo — atención requerida</div>
<div class="resolved-bar"><span class="dot"></span> Incidente resuelto</div>

KPIs (métricas destacadas — 4 por fila)

<div class="summary-grid">
  <div class="kpi pink"><div class="val">41</div><div class="lbl">Dispositivos</div></div>
  <div class="kpi green"><div class="val">99.8%</div><div class="lbl">Disponibilidad</div></div>
  <div class="kpi amber"><div class="val">3</div><div class="lbl">Advertencias</div></div>
  <div class="kpi red"><div class="val">0</div><div class="lbl">Críticos</div></div>
</div>

Modificadores de color del .kpi: pink, green, amber, red (o ninguno = oscuro).

Sección con texto y lista

<div class="section">
  <h2>Diagnóstico</h2>
  <p>Párrafo...</p>
  <ul><li>Punto uno</li><li>Punto dos</li></ul>
</div>

Tabla

<table>
  <thead><tr><th>Dispositivo</th><th>IP</th><th>Estado</th></tr></thead>
  <tbody>
    <tr><td>SWP101</td><td>192.168.0.236</td><td><span class="badge badge-ok">OK</span></td></tr>
  </tbody>
</table>

Para columnas numéricas alinéalas a la derecha con class="num" en el <td>.

Badges (etiquetas de estado)

badge-critical · badge-high · badge-medium · badge-ok · badge-active · badge-info · badge-historic.

<span class="badge badge-critical">CRÍTICO</span>

Cajas de resaltado

<div class="highlight-box">Nota clave (rosa).</div>
<div class="info-box">Información (azul).</div>
<div class="warn-box">Advertencia (ámbar).</div>
<div class="success-box">Éxito / confirmado (verde).</div>

Rejilla de causas (2 columnas)

<div class="cause-grid">
  <div class="cause-card"><h4>Causa raíz</h4><p>...</p></div>
  <div class="cause-card"><h4>Factor contribuyente</h4><p>...</p></div>
</div>

Recomendaciones (lista numerada con círculos)

<ol class="rec-list">
  <li><div class="rec-body"><h4>Título</h4><p>Descripción...</p>
      <span class="tag green">Prioridad baja</span></div></li>
</ol>

Variantes de .tag: (default rosa) · amber · green · blue.

Línea de tiempo

<ul class="timeline">
  <li><div class="tl-time">10:32 CST</div><div class="tl-desc">Evento...</div></li>
</ul>

Cotizaciones — tabla de partidas + totales

<table>
  <thead><tr><th>#</th><th>Descripción</th><th>Cant.</th><th>P. Unit.</th><th>Importe</th></tr></thead>
  <tbody>
    <tr><td>1</td><td>Switch UniFi US48PRO</td><td class="num">2</td>
        <td class="num">$18,500.00</td><td class="num">$37,000.00</td></tr>
  </tbody>
</table>

<div class="totals">
  <div class="row"><span>Subtotal</span><span class="num">$37,000.00</span></div>
  <div class="row"><span>IVA (16%)</span><span class="num">$5,920.00</span></div>
  <div class="row grand"><span>Total MXN</span><span class="num">$42,920.00</span></div>
</div>

Otros

  • <div class="divider"></div> — separador fino.
  • <code>ethernet0/1.41</code> — código en línea (se ve en rosa).

Exportar a PDF

Manual (recomendado):

  1. Abre el .html en Google Chrome (doble clic o file://...).
  2. Clic en el botón rosa "⎙ Exportar PDF" (esquina inferior derecha).
  3. En el diálogo de impresión: Destino = Guardar como PDF, Márgenes = Predeterminados (o Ninguno), activa "Gráficos de fondo", Tamaño = Carta. Guardar.

Automatizado (headless): Chrome/Chromium headless respeta Paged.js si esperas al render. Ejemplo conceptual:

google-chrome --headless --disable-gpu --no-pdf-header-footer \
  --print-to-pdf=SALIDA.pdf --virtual-time-budget=10000 \
  "file:///ruta/COT-2026-014.html?export=1"

Nota: el botón fija class="paged" vía clic. Para headless puro, agrega en tu copia un pequeño script que, si location.search contiene export=1, llame a exportPDF() automáticamente al cargar. (No lo hagas en la vista normal, o perderás el modo edición.)

NO uses WeasyPrint ni wkhtmltopdf: no ejecutan el JS de Paged.js y romperán el encabezado/pie por página.

Checklist antes de entregar

  • Folio correcto y correlativo (prefijo adecuado).
  • Título, cliente y fecha correctos.
  • Todo el cuerpo dentro de .body, en .section.
  • Sin recursos externos (fuentes, imágenes, CDNs). Sólo logo-report.jpg local.
  • Probado en pantalla (se ve bien) y exportado a PDF (header + pie en TODAS las hojas).
  • Números de cotización cuadran (subtotal + IVA = total).