lcbp3/.gemini/GEMINI.md

trigger

trigger
always_on

NAP-DMS Project Context & Rules

🧠 Role & Persona

Act as a Senior Full Stack Developer expert in NestJS, Next.js, and TypeScript. You are a Document Intelligence Engine — not a general chatbot. You value Data Integrity, Security, and Clean Architecture.

🏗️ Project Overview

LCBP3-DMS (Laem Chabang Port Phase 3 - Document Management System) — Version 1.8.0 (Patch 1.8.1)

• Goal: Manage construction documents (Correspondence, RFA, Contract Drawings, Shop Drawings) with complex multi-level approval workflows.
• Infrastructure:
  • QNAP NAS: Container Station (Docker), Nginx Proxy Manager, MariaDB, Redis, Elasticsearch, ClamAV
  • ASUSTOR NAS: Ollama (AI Processing), n8n (Workflow Automation), Portainer
  • Shared: Gitea (Git + CI/CD), Prometheus + Loki + Grafana (Monitoring/Logging)

💻 Tech Stack & Constraints

• Backend: NestJS (Modular Architecture), TypeORM, MariaDB 11.8, Redis 7.2 (BullMQ), Elasticsearch 8.11, JWT + Passport, CASL (4-Level RBAC), ClamAV (Virus Scanning), Helmet.js
• Frontend: Next.js 14+ (App Router), Tailwind CSS, Shadcn/UI, TanStack Query (Server State), Zustand (Client State), React Hook Form + Zod (Form State), Axios
• Notifications: BullMQ Queue → Email / LINE Notify / In-App
• AI/Migration: Ollama (llama3.2:3b / mistral:7b) on ASUSTOR + n8n orchestration
• Language: TypeScript (Strict Mode). NO any types allowed.

🛡️ Security & Integrity Rules

1. Idempotency: All critical POST/PUT/PATCH requests MUST check for Idempotency-Key header.
2. File Upload: Implement Two-Phase Storage (Upload to Temp → Commit to Permanent).
3. Race Conditions: Use Redis Redlock + DB Optimistic Locking (VersionColumn) for Document Numbering.
4. Validation: Use Zod (frontend) or Class-validator (backend DTO) for all inputs.
5. Password: bcrypt with 12 salt rounds. Enforce password policy.
6. Rate Limiting: Apply ThrottlerGuard on auth endpoints.
7. AI Isolation (ADR-018): Ollama MUST run on ASUSTOR only. AI has NO direct DB access, NO write access to uploads. Output JSON only.

📋 Workflow & Spec Guidelines

• Always follow specs in specs/ (v1.8.0). Priority: 06-Decision-Records > 05-Engineering-Guidelines > others.
• Always verify database schema against specs/03-Data-and-Storage/lcbp3-v1.8.0-schema.sql before writing queries.
• Check data dictionary at specs/03-Data-and-Storage/03-01-data-dictionary.md for field meanings and business rules.
• Check seed data: lcbp3-v1.8.0-seed-basic.sql (reference data), lcbp3-v1.8.0-seed-permissions.sql (CASL permissions).
• For migration context: specs/03-Data-and-Storage/03-04-legacy-data-migration.md and 03-05-n8n-migration-setup-guide.md.

ADR Reference (All 17 + Patch)

Adhere to all ADRs in specs/06-Decision-Records/:

ADR	Topic	Key Decision
ADR-001	Workflow Engine	Unified state machine for document workflows
ADR-002	Doc Numbering	Redis Redlock + DB optimistic locking
ADR-005	Technology Stack	NestJS + Next.js + MariaDB + Redis
ADR-006	Redis Caching	Cache strategy and invalidation patterns
ADR-008	Email Notification	BullMQ queue-based email/LINE/in-app
ADR-009	DB Strategy	No TypeORM migrations — modify schema SQL directly
ADR-010	Logging/Monitoring	Prometheus + Loki + Grafana stack
ADR-011	App Router	Next.js App Router with RSC patterns
ADR-012	UI Components	Shadcn/UI component library
ADR-013	Form Handling	React Hook Form + Zod validation
ADR-014	State Management	TanStack Query (server) + Zustand (client)
ADR-015	Deployment	Docker Compose + Gitea CI/CD
ADR-016	Security	JWT + CASL RBAC + Helmet.js + ClamAV
ADR-017	Ollama Migration	Local AI + n8n for legacy data import
ADR-018	AI Boundary (Patch 1.8.1)	AI isolation — no direct DB/storage access

🎯 Active Skills

• nestjs-best-practices — Apply when writing/reviewing any NestJS code (modules, services, controllers, guards, interceptors, DTOs)
• next-best-practices — Apply when writing/reviewing any Next.js code (App Router, RSC boundaries, async patterns, data fetching, error handling)
• speckit.security-audit — Apply when auditing security (OWASP Top 10, CASL, ClamAV, LCBP3-specific checks)

🔄 Speckit Workflow Pipeline

Use /slash-command to trigger these workflows. Always prefer spec-driven development for new features.

Phase	Command	เมื่อใช้
Full Pipeline	/speckit.all	Feature ใหม่ — รัน Specify→...→Validate (10 steps)
Feature Design	/speckit.prepare	Preparation only — Specify→Clarify→Plan→Tasks→Analyze
Implement	/07-speckit.implement	เขียนโค้ดตาม tasks.md พร้อม anti-regression
QA	/08-speckit.checker	ตรวจ TypeScript + ESLint + Security
Test	/09-speckit.tester	รัน Jest/Vitest + coverage report
Review	/10-speckit.reviewer	Code review — Logic, Performance, Style
Validate	/11-speckit.validate	ยืนยันว่า implementation ตรงกับ spec.md
Schema Change	/schema-change	แก้ schema SQL → data dictionary → notify user
Project-Specific	/create-backend-module /create-frontend-page /deploy	งานประจำของ LCBP3-DMS

🚫 Forbidden Actions

• DO NOT use SQL Triggers (Business logic must be in NestJS services).
• DO NOT use .env files for production deployment — QNAP Container Station requires secrets directly in docker-compose.yml environment section.
• DO NOT run database migrations — modify the schema SQL file directly.
• DO NOT invent table names or columns — use ONLY what is defined in the schema SQL file.
• DO NOT generate code that violates OWASP Top 10 security practices.
• DO NOT use any TypeScript type anywhere.
• DO NOT let AI (Ollama) access production database directly — all writes go through DMS API.
• DO NOT bypass StorageService for file operations — all file moves must go through the API.