188 lines
8.3 KiB
Markdown
188 lines
8.3 KiB
Markdown
# AI & Developer Workstation Guide
|
|
|
|
**Variable Remuneration, Compensation, and Commissions System - Hoteles Estelar**
|
|
|
|
---
|
|
|
|
This document outlines the environment configurations (Development vs. Production), active 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, development containers, and production servers. All credentials reside in a centralized `.env` file at the project root.
|
|
|
|
### 1.1. Dual-Stack Configuration Layout (.env)
|
|
This file configs connection parameters for both production (`app-prod`) and development (`app-dev`) containers.
|
|
|
|
```bash
|
|
# -----------------------------------------------------------------------------
|
|
# Database Setup (Fallback / Local Development)
|
|
# -----------------------------------------------------------------------------
|
|
DATABASE_URL="postgresql://special_hotel_user:SpecialHotel1235%2F%2A-%2B@pg.gaboggamer.online/special_hotel_dev?schema=public"
|
|
|
|
# -----------------------------------------------------------------------------
|
|
# Production Stack Environment Variables (for Docker Compose app-prod)
|
|
# -----------------------------------------------------------------------------
|
|
# Connection string pointing to the production PostgreSQL instance
|
|
DATABASE_URL_PROD="postgresql://special_hotel_user:SpecialHotel1235%2F%2A-%2B@pg.gaboggamer.online/special_hotel?schema=public"
|
|
|
|
# Production domain resolved by the Caddy reverse proxy
|
|
NEXT_PUBLIC_APP_URL="https://hotels.gaboggamer.online"
|
|
|
|
# Secret token used to sign NextAuth / custom session JWTs in production
|
|
NEXTAUTH_SECRET="0qqPRY4NIbCEFag33Q6EB1ea7dUQR1J6Z8h4NogrgCg="
|
|
|
|
# Production n8n calculation webhook endpoint
|
|
N8N_WEBHOOK_URL="https://n8n.gaboggamer.online/webhook/calculate-commissions"
|
|
|
|
# Token to authorize and verify n8n webhook payload signatures in production
|
|
N8N_WEBHOOK_SECRET="Ecjb2s33tHJppNBDJ/DxXEjHWKow8bNWmsQrk1sQKyQ="
|
|
|
|
# Internal container networking URL for production app mapping
|
|
APP_PROD_INTERNAL_URL="http://special-hotel-prod:3000"
|
|
|
|
# -----------------------------------------------------------------------------
|
|
# Development Stack Environment Variables (for Docker Compose app-dev)
|
|
# -----------------------------------------------------------------------------
|
|
# Connection string pointing to the development PostgreSQL instance
|
|
DATABASE_URL_DEV="postgresql://special_hotel_user:SpecialHotel1235%2F%2A-%2B@pg.gaboggamer.online/special_hotel_dev?schema=public"
|
|
|
|
# Dedicated connection string for the isolated test/sandbox database
|
|
TEST_DATABASE_URL="postgresql://special_hotel_user:SpecialHotel1235%2F%2A-%2B@pg.gaboggamer.online/special_hotel_test?schema=public"
|
|
|
|
# Local host address for development
|
|
NEXT_PUBLIC_APP_URL_DEV="http://localhost:3001"
|
|
|
|
# JWT session signing key for development
|
|
NEXTAUTH_SECRET_DEV="TdD2xx0rZYCGkYxFFB7y9Sm8L+HGyXaXInqB9lYLJsk="
|
|
|
|
# Sandbox n8n testing webhook endpoint
|
|
N8N_TEST_WEBHOOK_URL="https://n8n.gaboggamer.online/webhook-test/calculate-commissions"
|
|
|
|
# Signature token to authorize development webhook payloads
|
|
N8N_WEBHOOK_SECRET_DEV="qUHuPqPjA65psdtwQU7zgp/DVkvd1xXk2WP/vzbnEdc="
|
|
|
|
# Internal container networking URL for development app mapping
|
|
APP_DEV_INTERNAL_URL="http://special-hotel-dev:3000"
|
|
```
|
|
|
|
---
|
|
|
|
## 2. Optimizing the Workspace for the Antigravity Agent (agy)
|
|
|
|
To make this codebase highly friendly for the **Antigravity agent (`agy`)**, you can configure the following Model Context Protocol (MCP) servers. Once registered in the agent's active configuration, `agy` is equipped with specialized tools to inspect database schemas, execute and debug n8n workflows, manage git versions, and run automated browser checks.
|
|
|
|
### 2.1. Recommended MCP Servers for agy
|
|
|
|
#### A. n8n MCP Server (`n8n`)
|
|
Exposes tools to read, execute, and write workflows directly on the n8n canvas.
|
|
* **Use Case**: Allows `agy` to trigger calculation runs, inspect failing nodes on the canvas, check webhook logs, and modify workflows dynamically.
|
|
* **Harness Registration**:
|
|
```json
|
|
"n8n": {
|
|
"command": "npx",
|
|
"args": ["-y", "n8n-mcp"],
|
|
"env": {
|
|
"N8N_API_KEY": "your_n8n_api_key_here",
|
|
"N8N_URL": "https://n8n.gaboggamer.online"
|
|
}
|
|
}
|
|
```
|
|
|
|
#### B. Prisma Postgres MCP Server (`prisma-postgres`)
|
|
Exposes tools allowing `agy` to interact with the database using type-safe schemas.
|
|
* **Use Case**: Allows `agy` to run schema checks, dry-run validations, and automatically inspect database tables during development.
|
|
* **Harness Registration**:
|
|
```json
|
|
"prisma-postgres": {
|
|
"command": "npx",
|
|
"args": ["-y", "@prisma/mcp"],
|
|
"env": {
|
|
"DATABASE_URL": "postgresql://special_hotel_user:SpecialHotel1235%2F%2A-%2B@pg.gaboggamer.online/special_hotel_dev?schema=public"
|
|
}
|
|
}
|
|
```
|
|
|
|
#### C. PostgreSQL MCP Server (`postgres`)
|
|
Provides raw PostgreSQL connection and querying tools.
|
|
* **Use Case**: Enables `agy` to query migration status, seed verification, and raw audit log verification directly.
|
|
* **Harness Registration**:
|
|
```json
|
|
"postgres": {
|
|
"command": "npx",
|
|
"args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://special_hotel_user:SpecialHotel1235%2F%2A-%2B@pg.gaboggamer.online/special_hotel_dev"]
|
|
}
|
|
```
|
|
|
|
#### D. Git MCP Server (`git`)
|
|
Provides local Git operations tools (clone, commit, diff, log, status).
|
|
* **Use Case**: Allows `agy` to review local branches, examine diffs of modified code files, and make structured, micro-commits during development.
|
|
* **Harness Registration**:
|
|
```json
|
|
"git": {
|
|
"command": "npx",
|
|
"args": ["-y", "@modelcontextprotocol/server-git", "/home/gabogg/Proyects/semillero-special-hotel"]
|
|
}
|
|
```
|
|
|
|
#### E. Puppeteer MCP Server (`puppeteer`)
|
|
Exposes browser automation tools (take screenshots, click, type, fill forms).
|
|
* **Use Case**: Allows `agy` to start a headless browser, render our Next.js pages, and verify layout responsiveness and style details against the style guide without manual developer steps.
|
|
* **Harness Registration**:
|
|
```json
|
|
"puppeteer": {
|
|
"command": "npx",
|
|
"args": ["-y", "@modelcontextprotocol/server-puppeteer"]
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 3. Testing Procedures & Webhook Testing Flow
|
|
|
|
Testing must occur in complete isolation from production data. We achieve this by splitting execution paths using dedicated test hooks in both Next.js and n8n.
|
|
|
|
### 3.1. Testing Scripts Command List
|
|
Run these commands from the repository root using `pnpm` (or `npm` / `yarn`):
|
|
* **Run Row-Level Security Tests**:
|
|
```bash
|
|
pnpm run test:rls
|
|
```
|
|
Tests tenant read boundaries across admin, gerente, and colaborador roles, and verifies that update/delete actions on `audit_logs` are blocked.
|
|
* **Run Auth & API RLS Integration Tests**:
|
|
```bash
|
|
pnpm run test:auth-rls
|
|
```
|
|
Runs a Next.js instance on test port `3009` and asserts cookies, authorization blocks, and API-level data filtration.
|
|
* **Run UI End-to-End Tests**:
|
|
```bash
|
|
pnpm run test:ui
|
|
```
|
|
Compiles Next.js and runs automated Puppeteer scripts (`test-phase3-ui.js`, `test-phase4-ui.js`, `test-phase5-ui.js`) to verify pages, styles, translations, and modals.
|
|
* **Run n8n Webhook Integration Tests**:
|
|
```bash
|
|
pnpm run test:n8n
|
|
```
|
|
Fires sales validation and settlement calculation jobs directly at the n8n webhook test endpoint.
|
|
* **Run All Tests**:
|
|
```bash
|
|
pnpm run test
|
|
```
|
|
|
|
### 3.2. n8n Testing Webhook Routing
|
|
All calculations triggered by test suites route to n8n via `/webhook-test` path segments:
|
|
1. **Trigger**: Test suite invokes n8n via `POST ${process.env.N8N_TEST_WEBHOOK_URL}/calculate-commissions`.
|
|
2. **n8n Path Branching**:
|
|
- Within the n8n canvas, an **`IF` node** checks: `{{ $json.headers["x-nginx-original-uri"] || $json.path }}` contains `webhook-test`.
|
|
- **True**: The n8n workspace connects to the database utilizing `TEST_DATABASE_URL` credentials. It pulls test sales/goals data and pushes calculations back to the Next.js dev API.
|
|
- **False**: Connects to the main `DATABASE_URL` for production processing.
|
|
|
|
### 3.3. Manual Integration Setup
|
|
To sync and seed the testing database structure:
|
|
1. Spin up both databases.
|
|
2. Run database schema migrations on the test database:
|
|
```bash
|
|
pnpm run db:seed-test
|
|
```
|
|
3. Run the development server or test suites.
|