280 lines
6.5 KiB
Markdown
280 lines
6.5 KiB
Markdown
# LinkedSign – AI Development Agent (Codex)
|
||
|
||
## Context
|
||
You are working on a full-stack web application called **LinkedSign**, a digital document signing platform using PFX/P12 certificates.
|
||
|
||
## Tech Stack (MANDATORY)
|
||
- Backend: Node.js + Express
|
||
- Frontend: React (Vite)
|
||
- Database: MariaDB
|
||
- Auth: JWT (access + refresh)
|
||
- Encryption:
|
||
- bcrypt or argon2 for passwords
|
||
- AES-256-GCM for sensitive data
|
||
- Architecture: REST API (frontend/backend separated)
|
||
|
||
## Environment
|
||
- OS: Debian 12 (no GUI)
|
||
- IDE: code-server
|
||
- Root path: /home/mgonzalez/desarrollo/react/linkedsign/
|
||
|
||
---
|
||
|
||
## Global Rules (CRITICAL)
|
||
|
||
- Always maintain modular architecture (domain-based modules)
|
||
- NEVER break existing structure
|
||
- Prefer minimal changes over rewrites
|
||
- All code must be production-ready
|
||
- Always validate inputs
|
||
- Always apply security best practices by default
|
||
- Always log critical actions
|
||
- Never expose secrets in code
|
||
- Use environment variables (.env)
|
||
|
||
---
|
||
|
||
## Backend Architecture
|
||
|
||
Each module must follow:
|
||
|
||
controller → service → repository → routes → validator
|
||
|
||
Modules:
|
||
|
||
- auth
|
||
- users
|
||
- subscriptions
|
||
- documents
|
||
- certificates
|
||
- signatures
|
||
- invitations
|
||
- mail
|
||
- audit
|
||
- legal
|
||
- health
|
||
|
||
---
|
||
|
||
## Security Requirements
|
||
|
||
- Rate limiting on login
|
||
- Brute-force protection
|
||
- Helmet enabled
|
||
- CORS restricted
|
||
- Input validation (Joi/Zod)
|
||
- File validation (PDF only)
|
||
- Encrypt:
|
||
- PFX files (or protect access)
|
||
- certificate passwords
|
||
- Audit:
|
||
- login attempts
|
||
- IP address
|
||
- timestamps
|
||
- document actions
|
||
|
||
---
|
||
|
||
## Storage Rules
|
||
|
||
- Documents stored in:
|
||
/storage/documentos/YYYY/MM/
|
||
|
||
- NEVER store files inside database
|
||
|
||
---
|
||
|
||
## Frontend Rules
|
||
|
||
- Use React with modular structure (features-based)
|
||
- Responsive UI (mobile + desktop)
|
||
- Clean modern UI (prefer Tailwind or clean CSS)
|
||
- Use services layer for API calls
|
||
- Use hooks for logic reuse
|
||
|
||
---
|
||
|
||
## Features to Build
|
||
|
||
1. Authentication (with email confirmation)
|
||
2. Document management (upload, download, delete)
|
||
3. Certificate management (PFX/P12)
|
||
4. Digital signature (single + multi-user)
|
||
5. Invitations (guest signing via link)
|
||
6. Audit system
|
||
7. Legal acceptance (terms & privacy)
|
||
|
||
---
|
||
|
||
## API Requirements
|
||
|
||
- All endpoints must be documented
|
||
- Provide cURL examples for each endpoint
|
||
- Use consistent response format:
|
||
|
||
{
|
||
success: boolean,
|
||
data: any,
|
||
error: string | null
|
||
}
|
||
|
||
---
|
||
|
||
## Code Quality
|
||
|
||
- Use async/await
|
||
- Use centralized error handling
|
||
- Avoid duplicated logic
|
||
- Use clear naming conventions
|
||
|
||
---
|
||
|
||
## Testing
|
||
|
||
- Add tests when logic is critical
|
||
- Do not break existing functionality
|
||
|
||
---
|
||
|
||
## Workflow
|
||
|
||
Before writing code:
|
||
|
||
1. Analyze current structure
|
||
2. Propose plan
|
||
3. Wait for approval (IMPORTANT)
|
||
4. Then implement
|
||
|
||
---
|
||
|
||
## Language Rules
|
||
|
||
- Explain in Spanish
|
||
- Code in English
|
||
|
||
---
|
||
|
||
## Skills Usage (IMPORTANT)
|
||
|
||
You can use skills when appropriate:
|
||
|
||
- Use "refactor" skill for improving structure
|
||
- Use "security review" skill before finalizing modules
|
||
- Use "ui improvement" skill for frontend polishing
|
||
- Use "generate tests" skill for critical flows
|
||
|
||
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
|