Remove FirmaEC debug markers and document backend restart

2026-05-22 16:59:05 -05:00
parent 848441d593
commit 8d17393d5f
8 changed files with 127 additions and 17 deletions
@@ -170,3 +170,110 @@ Always suggest when a skill can be applied.
 ## Goal

 Build a secure, scalable, production-ready digital signing platform suitable for multi-user environments and legal compliance.
+
+---
+
+## Guía rápida: nuevo tipo de estampado
+
+Cuando se cree o ajuste un nuevo estampado visual de firma, revisar siempre estas capas:
+
+### 1. Vista previa en configuración
+
+- Archivo: `frontend/src/components/ui/SignatureStylePicker.jsx`
+- Aquí se agrega el nuevo estilo al arreglo `STYLES`
+- Cambiar:
+  - `id`
+  - `label`
+  - `desc`
+  - `preview(...)`
+
+### 2. Vista previa al colocar la firma sobre el PDF
+
+- Archivo: `frontend/src/components/ui/PdfSignaturePlacer.jsx`
+- Aquí se dibuja el estampado que el usuario ve antes de firmar
+- Cambiar:
+  - rama `if (signatureStyle === 'nuevo-estilo')`
+  - ancho dinámico si aplica en `getSignatureWidth(...)`
+  - partición de nombre o textos fijos si aplica
+
+### 3. Estilos CSS de las vistas previas
+
+- Archivo: `frontend/src/index.css`
+- Aquí viven:
+  - `.sig-preview-*`
+  - `.sp-*`
+- Cambiar:
+  - borde
+  - fondo
+  - tipografía
+  - separadores
+  - layout del QR y textos
+
+### 4. PDF final real que se incrusta al firmar
+
+- Archivo: `backend/src/modules/signing/signing.service.js`
+- Este es el archivo clave del sello visible real dentro del PDF
+- Cambiar:
+  - función nueva tipo `drawStyleNuevo(...)`
+  - selección del estilo en `signPdf(...)`
+  - helper de líneas/nombre si aplica
+  - QR, bordes, divisor, tipografía y textos fijos
+
+### 5. Flujo backend que llama al generador PDF
+
+- Firma normal web:
+  - `backend/src/modules/signatures/signatures.service.js`
+- Firma por invitación:
+  - `backend/src/modules/invitations/invitations.service.js`
+- PDF legal firmado:
+  - `backend/src/modules/legal/legal.service.js`
+
+Si el estampado no cambia en el PDF final, verificar primero que el flujo usado realmente pase por `backend/src/modules/signing/signing.service.js`.
+
+### 6. Orden correcto de trabajo
+
+1. Ajustar preview en `SignatureStylePicker.jsx`
+2. Ajustar preview de estampado en `PdfSignaturePlacer.jsx`
+3. Ajustar CSS en `frontend/src/index.css`
+4. Ajustar sello PDF real en `backend/src/modules/signing/signing.service.js`
+5. Validar:
+   - `cd frontend && npm run build`
+   - `cd backend && node -e "require('./src/app')"`
+6. Si va a producción:
+   - `commit`
+   - `push`
+   - deploy web
+
+### 7. Regla práctica importante
+
+Si el cambio se ve en la web pero no en el PDF firmado:
+
+- casi seguro falta tocar `backend/src/modules/signing/signing.service.js`
+- o el backend runtime de producción quedó desalineado respecto a `source`
+
+### 8. Verificación obligatoria en producción para cambios backend
+
+Cuando el cambio afecta el PDF final o cualquier lógica backend:
+
+1. hacer deploy
+2. reiniciar `linkedsign-backend`
+3. confirmar que el `PID` cambió:
+   - `ps -ef | grep 'node .*src/server.js' | grep -v grep`
+4. revisar que el proceso activo escucha en `:4000`
+5. recién después hacer la prueba funcional
+
+Caso ya confirmado en producción:
+
+- el archivo en disco puede tener el fix correcto
+- pero si `linkedsign-backend` no reinicia de verdad, el proceso sigue firmando con código viejo en memoria
+
+### 9. Método recomendado para depurar un estampado nuevo
+
+Si un sello no refleja cambios y hay duda de ruta:
+
+1. agregar una marca visual temporal en `backend/src/modules/signing/signing.service.js`
+2. desplegar
+3. reiniciar backend y confirmar cambio de `PID`
+4. firmar un PDF nuevo
+5. comprobar si la marca aparece en el PDF final
+6. quitar la marca temporal antes de cerrar el trabajo
@@ -2,10 +2,14 @@

 ## Versión actual

- Versión base: `1.2.34`
+- Versión base: `1.2.35`

 ## Historial

+### 1.2.35 - 2026-05-22
+
+- `FirmaEC` retira las marcas temporales de control del PDF final y mantiene documentado el flujo correcto para depurar nuevos estampados y verificar reinicio real del backend en producción.
+
 ### 1.2.34 - 2026-05-22

 - Backend agrega el marcador de log `FIRMAEC_PDF_RENDER` para rastrear en producción si `drawStyleFirmaEC` realmente corre durante la firma PDF.
@@ -33,6 +33,11 @@
 9. Reinicia servicios:
   - `sudo systemctl restart linkedsign-frontend`
   - `sudo systemctl restart linkedsign-backend`
+   - Si hubo cambios en `backend/`, este reinicio es obligatorio
+   - Verifica que el backend sí reinició de verdad:
+     - `ps -ef | grep 'node .*src/server.js' | grep -v grep`
+     - confirma que cambió el `PID`
+     - `sudo systemctl status linkedsign-backend --no-pager -n 20`
 10. Limpia archivos `.md` en producción:
   - `find /opt/apps/linkedsign -type f -iname '*.md' -delete`
 11. Verifica:
@@ -48,6 +53,9 @@
 - Si cambias rutas del APK o storage, revisa también `PRODUCCION.md`.
 - En producción no debe quedar código fuente Android; solo el APK release en `/opt/apps/linkedsign/android/apk/`.
 - Si en el despliegue hay cambios Android, recuerda que a producción solo pasa el `APK release` versionado; no el proyecto Android completo.
+- En cambios de backend no basta con copiar archivos o correr el script de deploy:
+  - el proceso `node src/server.js` debe reiniciarse sí o sí
+  - si el `PID` no cambia, el backend puede seguir firmando con código viejo en memoria aunque el archivo en disco ya esté actualizado
 - El deploy web no debe tocar ni reemplazar:
  - `/opt/apps/linkedsign/backend/.env`
  - `/opt/apps/linkedsign/storage/`
@@ -1 +1 @@
-1.2.34
+1.2.35
@@ -18,8 +18,8 @@ android {
        applicationId "net.linkedcorp.linkedsign"
        minSdk 26
        targetSdk 35
-        versionCode 10234
-        versionName "1.2.34"
+        versionCode 10235
+        versionName "1.2.35"

        buildConfigField "String", "API_BASE_URL", "\"${apiBaseUrl}\""
    }
@@ -1,6 +1,6 @@
 {
  "name": "linkedsign-backend",
-  "version": "1.2.34",
+  "version": "1.2.35",
  "private": true,
  "description": "Initial backend for LinkedSign",
  "main": "src/server.js",
@@ -356,24 +356,15 @@ async function drawStyleFirmaEC(pdfDoc, page, sx, sy, sw, sh, { signerName, veri
  const textX = qrOnRight ? sx + 6 : divX + 5;
  const textW  = sw - qrSize - 18;

-  page.drawText('0 Validar unicamente en FirmaEC.', { x: textX, y: sy + sh - 12, size: 6, font: fReg, color: rgb(0.12, 0.12, 0.14) });
-  page.drawText('0 Firmado electronicamente por:', { x: textX, y: sy + sh - 21, size: 6, font: fReg, color: rgb(0.12, 0.12, 0.14) });
+  page.drawText('Validar unicamente en FirmaEC.', { x: textX, y: sy + sh - 12, size: 6, font: fReg, color: rgb(0.12, 0.12, 0.14) });
+  page.drawText('Firmado electronicamente por:', { x: textX, y: sy + sh - 21, size: 6, font: fReg, color: rgb(0.12, 0.12, 0.14) });

  // Name — bold, uppercase, word-wrapped up to 2 lines
  const nameSize  = 8.5;
  const nameLines = getFirmaEcNameLines(signerName, fBold, nameSize, textW);
-  console.info('[FIRMAEC_PDF_RENDER]', JSON.stringify({
-    signerName,
-    qrPosition,
-    qrBackground,
-    qrBorder,
-    nameLines,
-    rect: { x: sx, y: sy, width: sw, height: sh },
-  }));
  nameLines.forEach((line, i) => {
    page.drawText(line, { x: textX, y: sy + sh - 34 - (i * 13), size: nameSize, font: fBold, color: rgb(0.05, 0.05, 0.07) });
  });
-  page.drawText('prueba', { x: textX, y: sy + 8, size: 6, font: fReg, color: rgb(0.18, 0.18, 0.18) });
 }

 // ── Main sign function ─────────────────────────────────────────────────────────
@@ -1,7 +1,7 @@
 {
  "name": "frontend",
  "private": true,
-  "version": "1.2.34",
+  "version": "1.2.35",
  "type": "module",
  "scripts": {
    "dev": "vite",
@@ -1 +1 @@
 .2.34
 .2.35