diff --git a/.cursorrules b/.cursorrules new file mode 100644 index 0000000..2a5b2f8 --- /dev/null +++ b/.cursorrules @@ -0,0 +1,17 @@ +# Custom Rules for AI Agents (Antigravity, Claude, Cursor) + +# 1. Styling Guidelines +- Only write Vanilla CSS. Do not use TailwindCSS or utility libraries unless specifically asked. +- Put styling in Component-level CSS Modules (`*.module.css`) and import it locally (e.g. `import styles from './Button.module.css'`). +- Always use variables from [globals.css](file:///home/gabogg/Proyects/semillero-special-hotel/styles/globals.css) for spacing, colors, fonts, border radii, shadows, and animations. +- Implement smooth hover transitions and card lifts for interactive states (micro-animations). + +# 2. Architecture & decoupled design +- Next.js acts as the user interface and database state layer. +- Offload heavy operations, calculations, scheduling, and LLM evaluations to the external **n8n** engine by invoking webhook endpoints. +- Ensure the application is decoupled: read all connection strings, URLs, and secrets from environment variables (`process.env.DATABASE_URL`, `process.env.N8N_WEBHOOK_URL`). + +# 3. Auditing & DB operations +- Do not build custom audit logging tables or log triggers from scratch. +- Use the `@explita/prisma-audit-log` Prisma Client Extension. Let it automatically intercept database modifications and log snapshots to the `AuditLog` table. +- Always run `npx prisma generate` after modifying `schema.prisma`. diff --git a/docs/AI_DEVELOPER_WORKSTATION.md b/docs/AI_DEVELOPER_WORKSTATION.md new file mode 100644 index 0000000..b67c06d --- /dev/null +++ b/docs/AI_DEVELOPER_WORKSTATION.md @@ -0,0 +1,129 @@ +# AI & Developer Workstation Guide + +**Variable Remuneration, Compensation, and Commissions System - Hoteles Estelar** + +--- + +This document outlines the environment configurations (Development vs. Production), API keys, and recommended AI integration tools (like Model Context Protocol servers) designed to optimize this workspace for AI agents (such as Antigravity-cli / agy) and human developers alike. + +--- + +## 1. Environment Configurations (.env Blueprints) + +The Next.js application separates environment secrets between local active development and production servers. + +### 1.1. Development Environment (`.env.development`) +This file lives in the root directory during development. It configures connection strings to local/sandbox instances. + +```bash +# ----------------------------------------------------------------------------- +# Database Setup +# ----------------------------------------------------------------------------- +# Connection string pointing to your local development PostgreSQL instance. +# Prisma uses this URL to run migrations and execute DB queries. +DATABASE_URL="postgresql://postgres:postgres@localhost:5432/special_hotel_dev?schema=public" + +# ----------------------------------------------------------------------------- +# Next.js Application Settings +# ----------------------------------------------------------------------------- +# The host address of your local Next.js client (default dev port is 3000) +NEXT_PUBLIC_APP_URL="http://localhost:3000" + +# Secret token used by NextAuth / custom session helper to sign JWTs. +# Generate a secure key locally using: openssl rand -base64 32 +NEXTAUTH_SECRET="dev_secret_jwt_sign_key_change_me_locally" + +# ----------------------------------------------------------------------------- +# n8n Workflow Engine Integration +# ----------------------------------------------------------------------------- +# Webhook URL pointing to your local n8n instance where calculations and +# AI workflows are executed. +N8N_WEBHOOK_URL="http://localhost:5678/webhook/calculate-commissions" + +# Local authorization secret shared between Next.js and n8n. +# Incoming webhooks from n8n calling the Next.js API must provide this token +# in the 'x-n8n-signature' header. +N8N_WEBHOOK_SECRET="local_shared_signature_to_verify_n8n_callbacks" +``` + +--- + +### 1.2. Production Environment (`.env.production`) +Production values are configured inside the live environment (e.g. injected into the container via Dockge). + +```bash +# ----------------------------------------------------------------------------- +# Database Setup +# ----------------------------------------------------------------------------- +# Secure production database URL. Must be reachable only within the isolated +# network environment (e.g. via private container network aliases). +DATABASE_URL="postgresql://postgres:secure_db_prod_pass@postgres-vpn:5432/special_hotel?schema=public" + +# ----------------------------------------------------------------------------- +# Next.js Application Settings +# ----------------------------------------------------------------------------- +# The public or VPN-locked domain resolved by Caddy +NEXT_PUBLIC_APP_URL="https://special-hotel.gaboggamer.online" + +# High-entropy random secret key for production JWT signatures. +NEXTAUTH_SECRET="prod_high_entropy_session_secret_key" + +# ----------------------------------------------------------------------------- +# n8n Workflow Engine Integration +# ----------------------------------------------------------------------------- +# Production n8n calculation webhook endpoint (internally routed) +N8N_WEBHOOK_URL="http://n8n:5678/webhook/calculate-commissions" + +# Optional application-level security secret. +# NOTE: In production, since Next.js and n8n share a private Docker container +# network, Caddy blocks all public access to /api/n8n/* endpoints. +# Because of this network-level isolation, token-based verification is optional +# but recommended as a defense-in-depth practice. +N8N_WEBHOOK_SECRET="prod_shared_signature_to_verify_n8n_callbacks" +``` + +--- + +## 2. Optimizing the Workspace for AI Agents (Antigravity / agy) + +To make this codebase highly friendly for AI pair-programming, automated bug-fixing, and system changes, we recommend configuring the following Model Context Protocol (MCP) integrations. + +### 2.1. Recommended MCP Servers + +#### A. Prisma Postgres MCP Server (`@prisma/mcp`) +Exposes tools allowing AI agents to interact directly with the database using type-safe schemas. +* **Why use it**: Allows the AI agent to run natural language questions (e.g., "Show me the top 5 calculation rules in draft state" or "Run a dry-run check on the user goals schema"). +* **Key capabilities exposed**: `ListDatabases`, `ExecuteSqlQuery`, `IntrospectSchema`, and `ExecuteRawSql`. +* **Configuration snippet (`mcp.json`)**: + ```json + "prisma-postgres": { + "command": "npx", + "args": ["-y", "@prisma/mcp"], + "env": { + "DATABASE_URL": "postgresql://postgres:postgres@localhost:5432/special_hotel_dev?schema=public" + } + } + ``` + +#### B. PostgreSQL MCP Server (`@modelcontextprotocol/server-postgres`) +Provides raw, high-performance database connectivity tools. +* **Why use it**: Useful when running migrations or validating raw database logs directly through the AI chat context. +* **Configuration snippet (`mcp.json`)**: + ```json + "postgres": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://postgres:postgres@localhost:5432/special_hotel_dev"] + } + ``` + +--- + +## 3. IDE Rules & Agent Contexts (`.cursorrules` / `.clauderules`) + +Create a `.cursorrules` or `.clauderules` file in the root of the project. This guides the AI agent on architecture rules when editing files. + +### 3.1. Standard Prompts for the Agent: +* **Prisma Rule**: Always run `npx prisma generate` after editing `schema.prisma`. All DB queries must utilize Prisma Client. +* **Styling Rule**: Do not use utility classes or TailwindCSS. Write Vanilla CSS in `.module.css` and import it as local styles. Follow CSS variables from `globals.css`. +* **Calculation Engine Rule**: The Next.js API only handles inputs, DB commits, and triggers. Do not write complex multi-step calculation loops inside Next.js; offload these to n8n triggers. +* **Auditing Rule**: Never write manually triggered audit logging. Use the `@explita/prisma-audit-log` client extension attached to the prisma instance.