vault

Instruction file imported from AlexAviles345/Gestor-Documental-Tipo-Google (.cursor/rules/vault.mdc). Copyright stays with the author.

Vault — Contexto para IAs

Qué es este proyecto

Sistema documental tipo Google Drive. Monorepo NX con microservicios NestJS y microfrontends Next.js.

Estructura del monorepo

Reglas obligatorias

Backend

• Todo ID BigInt lleva @db.BigInt en Prisma
• INET lleva @db.Inet en Prisma
• Los MFEs NUNCA llaman a MinIO directamente
• El gateway NO tiene lógica de negocio
• Cada servicio solo toca sus propias tablas de DB
• Las exportaciones y ZIPs NUNCA van en API Routes de Next.js
• Streams para todo archivo/exportación, nunca buffers completos en memoria

Documentación

• Nivel de Código: A medida que implementes lógica, documenta las funciones complejas usando JSDoc en el propio código (.ts).
• Nivel Funcional: No agregues detalles profundos de implementación en AGENTS.md. En su lugar, actualiza el archivo .md correspondiente en .docs/05-modules/ con decisiones de diseño, flujos o arquitectura conforme vayas construyendo los módulos.
• Swagger (OpenAPI): Es OBLIGATORIO que todos los endpoints y controladores estén documentados con @ApiTags, @ApiOperation, @ApiResponse, y que todo DTO tenga sus propiedades decoradas con @ApiProperty. El Gateway consolidará esta documentación.
• Evolución Arquitectónica: Sigue fielmente la arquitectura y estándares definidos en .docs/. Sin embargo, tienes autonomía: si encuentras una mejor forma de implementar algo o surge una funcionalidad no prevista, puedes hacerlo. En esos casos, tu obligación inquebrantable es actualizar o crear la documentación pertinente en .docs/ para reflejar la nueva realidad del sistema.
• Modificaciones de Base de Datos: Debes ceñirte al modelo documentado lo más fielmente posible. Sin embargo, si para implementar una funcionalidad es estrictamente necesario agregar un nuevo campo, tabla o relación, tienes la autonomía para hacerlo. La única condición innegociable es que, en el mismo paso, actualices: el schema.prisma, los scripts de poblado en libs/shared-prisma/prisma/seeds/ (si impacta catálogos o datos iniciales), y la documentación visual (diagrama Mermaid) junto con el diccionario de datos en .docs/01-architecture/entity-relationship.md.

Frontend

• Los editores (TipTap, FortuneSheet) siempre con ssr: false
• Los MFEs nunca llaman a svc-word o svc-excel por HTTP para colaboración
• La colaboración va siempre por WebSocket directo (bypass gateway)
• Toda petición HTTP usa apiClient.ts y toda mutación usa useRequestDeduper para evitar saturación.

Seguridad

• Todo endpoint privado requiere JwtAuthGuard
• Los IDs internos nunca se exponen en URLs públicas (usar external_id o public_share_token)
• Las contraseñas NUNCA se guardan en texto plano en audit_log
• Guards en shared-auth, nunca reimplementar en servicios individuales
• Payloads altamente sensibles deben encriptarse desde el FE con { encrypt: true } (Gateway los desencripta).

Auditoría

• Los eventos de negocio de alto impacto se deben guardar en audit_log de forma EXPLÍCITA pero NO INVASIVA.
• No ensucies la lógica de tus servicios (Services). En su lugar, usa el decorador @AuditAction('NOMBREDELACCION') y @UseInterceptors(AuditInterceptor) a nivel de Controlador.
• No inundar el Audit Log con operaciones masivas como creación o lectura de archivos. Para historial de archivos usa item_versions y para vistas usa item_recents.
• Los errores técnicos y stack traces van en SharedLoggerService (Winston), nunca usar console.log.
• FILE_PREVIEWED no se audita (demasiado ruido), se usa item_recents.

Entornos y Variables de Configuración

• Desarrollo Local (Monorepo): Se utiliza un único archivo .env en la raíz del proyecto (copiado de .env.example). Nx y NestJS leen este archivo global al ejecutar pnpm run start:base, proveyendo variables (ej. DATABASE_URL) a todos los servicios sin necesidad de duplicarlas. No anidar archivos .env en librerías compartidas (ej. libs/shared-prisma).
• Nuevos Servicios: Si creas un nuevo microservicio o microfrontend, DEBES crear su respectivo archivo .env.example interno. Este actúa como contrato de despliegue a producción, documentando exactamente qué variables necesita ese contenedor aislado (incluyendo DATABASE_URL si se conecta a Prisma).
• Nuevas Funcionalidades: Si agregas una funcionalidad que requiere una nueva variable, actualiza el .env.example del servicio correspondiente Y TAMBIÉN el .env.example maestro en la raíz. Nunca asumas que las variables simplemente "existirán".

Índice de documentación

Toda la documentación técnica vive en .docs/. Usar este índice para saber dónde buscar cada tipo de información.

.docs/00-overview/ — Visión general

.docs/01-architecture/ — Arquitectura

.docs/02-api/ — API

.docs/03-runbooks/ — Runbooks operativos

.docs/04-product/ — Producto

.docs/05-modules/ — Módulos funcionales

.docs/06-checklists/ — Validaciones

.docs/07-prompts/ — Prompts prefabricados

.docs/08-templates/ — Plantillas

Stack

NX · Next.js 14 · next-intl · NestJS · Prisma · PostgreSQL · MinIO · Redis · BullMQ · Yjs · WebSockets

Flujo de Trabajo (Workflow) para IAs

Cuando recibas una solicitud para implementar o modificar una funcionalidad, y no tengas el contexto completo, sigue estrictamente estos pasos:

1. Entender el Contexto: Revisa el índice de documentación en este archivo y lee el(los) archivo(s) .md de .docs/ que correspondan al módulo o la arquitectura en cuestión.
2. Revisar Código Existente: Antes de escribir código nuevo, busca en el monorepo (especialmente en libs/) si ya existe un componente, guard, o utilidad que resuelva el problema. (No reinventes la rueda).
3. Planificar (Si es necesario): Si la solicitud implica cambios arquitectónicos o la creación de un nuevo microservicio/microfrontend, presenta primero un plan de implementación detallado para aprobación.
4. Implementar: Escribe el código siguiendo fielmente las Reglas obligatorias de este documento (ej. BigInt, Guards, etc.).
5. Documentar: Como paso final obligatorio, agrega JSDoc al código complejo y actualiza los archivos Markdown pertinentes en .docs/ reflejando tus cambios.

Skills personalizadas

Si existe .ai/skills/<tu-nombre>/ (ej: .ai/skills/claude/, .ai/skills/cursor/), lee los archivos .md de esa carpeta como instrucciones adicionales específicas para ti. Estas skills son configuradas por cada usuario y no se suben al repositorio. Ver .ai/skills/README.md para más detalles.