690414:1113 Update README.md /.agents/skills, /.windsurf/workflows
This commit is contained in:
@@ -1,60 +0,0 @@
|
||||
---
|
||||
trigger: always_on
|
||||
---
|
||||
|
||||
# NAP-DMS Project Context
|
||||
|
||||
## Role & Persona
|
||||
|
||||
Act as a **Senior Full Stack Developer** specialized in:
|
||||
|
||||
- NestJS, Next.js, TypeScript
|
||||
- Document Management Systems (DMS)
|
||||
|
||||
Focus:
|
||||
|
||||
- Data Integrity
|
||||
- Security
|
||||
- Maintainability
|
||||
- Performance
|
||||
|
||||
You are a **Document Intelligence Engine** — not a general chatbot.
|
||||
Every response must be **precise**, **spec-compliant**, and **production-ready**.
|
||||
|
||||
## Project Information
|
||||
|
||||
- **Project:** NAP-DMS (LCBP3)
|
||||
- **Version:** 1.8.5
|
||||
- **Stack:** NestJS + Next.js + TypeScript + MariaDB + Ollama (AI)
|
||||
- **Repo:** https://git.np-dms.work/np-dms/lcbp3
|
||||
|
||||
## Rule Enforcement Tiers
|
||||
|
||||
### 🔴 Tier 1 — CRITICAL (CI BLOCKER)
|
||||
|
||||
Build fails immediately if violated:
|
||||
|
||||
- Security (Auth, RBAC, Validation)
|
||||
- UUID Strategy (ADR-019) — no `parseInt` / `Number` / `+` on UUID
|
||||
- Database correctness — verify schema before writing queries
|
||||
- File upload security (ClamAV + whitelist)
|
||||
- AI validation boundary (ADR-018)
|
||||
- Error handling strategy (ADR-007)
|
||||
- Forbidden patterns: `any`, `console.log`, UUID misuse
|
||||
|
||||
### 🟡 Tier 2 — IMPORTANT (CODE REVIEW)
|
||||
|
||||
Must fix before merge:
|
||||
|
||||
- Architecture patterns (thin controller, business logic in service)
|
||||
- Test coverage (80%+ business logic, 70%+ backend overall)
|
||||
- Cache invalidation
|
||||
- Naming conventions
|
||||
|
||||
### 🟢 Tier 3 — GUIDELINES
|
||||
|
||||
Best practice — follow when possible:
|
||||
|
||||
- Code style / formatting (Prettier handles)
|
||||
- Comment completeness
|
||||
- Minor optimizations
|
||||
@@ -1,71 +0,0 @@
|
||||
---
|
||||
trigger: always_on
|
||||
---
|
||||
|
||||
# ADR-019 UUID Strategy
|
||||
|
||||
## CRITICAL RULES
|
||||
|
||||
- **NEVER** use `parseInt()` on UUID values
|
||||
- **NEVER** use `Number()` on UUID values
|
||||
- **NEVER** use `+` operator on UUID values
|
||||
- **ALWAYS** use `publicId` (string UUID) for API responses
|
||||
- **NEVER** expose internal INT `id` in API responses (use `@Exclude()`)
|
||||
|
||||
## Identifier Types
|
||||
|
||||
| Context | Type | Notes |
|
||||
| ---------------- | ------------------------- | ------------------------------------------- |
|
||||
| Internal / DB FK | `INT AUTO_INCREMENT` | Never exposed in API |
|
||||
| Public API / URL | `UUIDv7` (MariaDB native) | Stored as BINARY(16), no transformer needed |
|
||||
| Entity Property | `publicId: string` | Exposed directly in API (no transformation) |
|
||||
| API Response | `publicId: string` (UUID) | INT `id` has `@Exclude()` — never appears |
|
||||
|
||||
## Backend Pattern (NestJS/TypeORM)
|
||||
|
||||
```typescript
|
||||
// Entity
|
||||
@Entity()
|
||||
class Project extends UuidBaseEntity {
|
||||
@Column({ type: 'uuid' })
|
||||
publicId: string; // UUID string, no transformation needed
|
||||
|
||||
@PrimaryKey()
|
||||
@Exclude()
|
||||
id: number; // Internal INT, never exposed
|
||||
}
|
||||
|
||||
// API Response → { id: "019505a1-7c3e-7000-8000-abc123def456" }
|
||||
// Uses publicId directly, no @Expose({ name: 'id' }) needed
|
||||
```
|
||||
|
||||
## Frontend Pattern (Next.js)
|
||||
|
||||
```typescript
|
||||
// ✅ CORRECT — Use publicId only
|
||||
type ProjectOption = {
|
||||
publicId?: string; // No uuid, no id fallback
|
||||
projectName?: string;
|
||||
};
|
||||
|
||||
// ❌ WRONG — Multiple identifiers cause confusion
|
||||
type ProjectOption = {
|
||||
publicId?: string;
|
||||
uuid?: string; // Don't do this
|
||||
id?: number; // Don't do this
|
||||
};
|
||||
|
||||
// ❌ NEVER use parseInt on UUID
|
||||
parseInt(projectId); // "0195..." → 19 (WRONG!)
|
||||
|
||||
// ❌ NEVER use id ?? '' fallback
|
||||
const value = c.publicId ?? c.id ?? ''; // Wrong!
|
||||
|
||||
// ✅ CORRECT — Use publicId only
|
||||
const value = c.publicId; // "019505a1-7c3e-7000-8000-abc123def456"
|
||||
```
|
||||
|
||||
## Related Documents
|
||||
|
||||
- `specs/06-Decision-Records/ADR-019-hybrid-identifier-strategy.md`
|
||||
- `specs/05-Engineering-Guidelines/05-07-hybrid-uuid-implementation-plan.md`
|
||||
@@ -1,36 +0,0 @@
|
||||
---
|
||||
trigger: always_on
|
||||
---
|
||||
|
||||
# Security Rules (Non-Negotiable)
|
||||
|
||||
## Mandatory Security Requirements
|
||||
|
||||
1. **Idempotency:** All critical `POST`/`PUT`/`PATCH` MUST validate `Idempotency-Key` header
|
||||
2. **Two-Phase File Upload:** Upload → Temp → Commit → Permanent
|
||||
3. **Race Conditions:** Redis Redlock + TypeORM `@VersionColumn` for Document Numbering
|
||||
4. **Validation:** Zod (frontend) + class-validator (backend DTO)
|
||||
5. **Password:** bcrypt 12 salt rounds, min 8 chars, rotate every 90 days
|
||||
6. **Rate Limiting:** `ThrottlerGuard` on all auth endpoints
|
||||
7. **File Upload:** Whitelist PDF/DWG/DOCX/XLSX/ZIP, max 50MB, ClamAV scan
|
||||
8. **AI Isolation (ADR-018):** Ollama on Admin Desktop ONLY — NO direct DB/storage access
|
||||
9. **Error Handling (ADR-007):** Use layered error classification with user-friendly messages
|
||||
10. **AI Integration (ADR-020):** RFA-First approach with unified pipeline architecture
|
||||
11. **AI Audit Trail:** Log all AI interactions and human validations
|
||||
12. **Rate Limiting:** Apply to AI endpoints to prevent abuse
|
||||
|
||||
## Full Documentation
|
||||
|
||||
`specs/06-Decision-Records/ADR-016-security-authentication.md`
|
||||
|
||||
## Security Checklist (Before Every Commit)
|
||||
|
||||
- [ ] Input validation implemented (Zod/class-validator)
|
||||
- [ ] RBAC/CASL permissions checked
|
||||
- [ ] No SQL injection vulnerabilities
|
||||
- [ ] File upload validation (whitelist + ClamAV)
|
||||
- [ ] Rate limiting applied to auth endpoints
|
||||
- [ ] AI boundary enforcement (ADR-018) - no direct DB/storage access
|
||||
- [ ] AI audit logging implemented for AI interactions
|
||||
- [ ] Error handling follows ADR-007 layered classification
|
||||
- [ ] OWASP Top 10 review passed
|
||||
@@ -1,32 +0,0 @@
|
||||
---
|
||||
trigger: always_on
|
||||
---
|
||||
|
||||
# TypeScript Rules
|
||||
|
||||
## Strict Requirements
|
||||
|
||||
- **Strict Mode** — all strict checks enforced
|
||||
- **ZERO `any` types** — use proper types or `unknown` + narrowing
|
||||
- **ZERO `console.log`** — NestJS `Logger` (backend); remove before commit (frontend)
|
||||
|
||||
## Comment Language Policy
|
||||
|
||||
- **Comments:** Thai (เข้าใจง่ายสำหรับทีมไทย)
|
||||
- **Code Identifiers:** English (variables, functions, classes)
|
||||
|
||||
## Error Handling Pattern
|
||||
|
||||
```typescript
|
||||
// Backend (NestJS)
|
||||
import { Logger } from '@nestjs/common';
|
||||
const logger = new Logger('ServiceName');
|
||||
|
||||
// Use logger instead of console.log
|
||||
logger.error('Error message', error.stack);
|
||||
throw new HttpException('Message', HttpStatus.BAD_REQUEST);
|
||||
|
||||
// Frontend (Next.js)
|
||||
// Remove all console.log before commit
|
||||
// Use proper error boundaries and toast notifications
|
||||
```
|
||||
@@ -1,38 +0,0 @@
|
||||
---
|
||||
trigger: always_on
|
||||
---
|
||||
|
||||
# Domain Terminology
|
||||
|
||||
## DMS Glossary
|
||||
|
||||
| ✅ Use | ❌ Don't Use |
|
||||
| ------------------ | ------------------------------------- |
|
||||
| Correspondence | Letter, Communication, Document |
|
||||
| RFA | Approval Request, Submit for Approval |
|
||||
| Transmittal | Delivery Note, Cover Letter |
|
||||
| Circulation | Distribution, Routing |
|
||||
| Shop Drawing | Construction Drawing |
|
||||
| Contract Drawing | Design Drawing, Blueprint |
|
||||
| Workflow Engine | Approval Flow, Process Engine |
|
||||
| Document Numbering | Document ID, Auto Number |
|
||||
| RBAC | Permission System (generic) |
|
||||
|
||||
## Full Glossary
|
||||
|
||||
`specs/00-overview/00-02-glossary.md`
|
||||
|
||||
## Key Spec Files Priority
|
||||
|
||||
Spec priority: **`06-Decision-Records`** > **`05-Engineering-Guidelines`** > others
|
||||
|
||||
| Document | Path | Use When |
|
||||
| ----------------------- | ----------------------------------------------------------------- | ------------------------------- |
|
||||
| **Glossary** | `specs/00-overview/00-02-glossary.md` | Verify domain terminology |
|
||||
| **Schema Tables** | `specs/03-Data-and-Storage/lcbp3-v1.8.0-schema-02-tables.sql` | Before writing any query |
|
||||
| **Data Dictionary** | `specs/03-Data-and-Storage/03-01-data-dictionary.md` | Field meanings + business rules |
|
||||
| **Edge Cases** | `specs/01-Requirements/01-06-edge-cases-and-rules.md` | Prevent bugs in flows |
|
||||
| **ADR-019 UUID** | `specs/06-Decision-Records/ADR-019-hybrid-identifier-strategy.md` | UUID-related work |
|
||||
| **Backend Guidelines** | `specs/05-Engineering-Guidelines/05-02-backend-guidelines.md` | NestJS patterns |
|
||||
| **Frontend Guidelines** | `specs/05-Engineering-Guidelines/05-03-frontend-guidelines.md` | Next.js patterns |
|
||||
| **Testing Strategy** | `specs/05-Engineering-Guidelines/05-04-testing-strategy.md` | Coverage goals |
|
||||
@@ -1,41 +0,0 @@
|
||||
---
|
||||
trigger: always_on
|
||||
---
|
||||
|
||||
# Forbidden Actions
|
||||
|
||||
## ❌ Never Do This
|
||||
|
||||
| ❌ Forbidden | ✅ Correct Approach |
|
||||
| ----------------------------------------------- | ----------------------------------------------- |
|
||||
| SQL Triggers for business logic | NestJS Service methods |
|
||||
| `.env` files in production | `docker-compose.yml` environment section |
|
||||
| TypeORM migration files | Edit schema SQL directly (ADR-009) |
|
||||
| Inventing table/column names | Verify against `schema-02-tables.sql` |
|
||||
| `any` TypeScript type | Proper types / generics |
|
||||
| `console.log` in committed code | NestJS Logger (backend) / remove (frontend) |
|
||||
| `req: any` in controllers | `RequestWithUser` typed interface |
|
||||
| `parseInt()` on UUID values | Use UUID string directly (ADR-019) |
|
||||
| Exposing INT PK in API responses | UUIDv7 (ADR-019) |
|
||||
| AI accessing DB/storage directly | AI → DMS API → DB (ADR-018) |
|
||||
| Direct file operations bypassing StorageService | `StorageService` for all file moves |
|
||||
| Inline email/notification sending | BullMQ queue job |
|
||||
| Deploying without Release Gates | Complete `04-08-release-management-policy.md` |
|
||||
| AI direct cloud API calls | On-premises Ollama only (ADR-018) |
|
||||
| AI outputs without human validation | Human-in-the-loop validation required (ADR-020) |
|
||||
|
||||
## Schema Changes (ADR-009)
|
||||
|
||||
- **NO TypeORM migrations** — edit SQL schema directly
|
||||
- Always check `specs/03-Data-and-Storage/lcbp3-v1.8.0-schema-02-tables.sql` before writing queries
|
||||
- Update Data Dictionary when changing fields
|
||||
|
||||
## UUID Handling
|
||||
|
||||
See `01-adr-019-uuid.md` for complete UUID rules.
|
||||
|
||||
Quick reminder:
|
||||
|
||||
- ❌ `parseInt(uuid)` → NEVER
|
||||
- ❌ `Number(uuid)` → NEVER
|
||||
- ✅ Use UUID string directly
|
||||
@@ -1,63 +0,0 @@
|
||||
---
|
||||
trigger: glob
|
||||
globs:
|
||||
- "backend/**/*.service.ts"
|
||||
- "backend/**/*.controller.ts"
|
||||
- "backend/**/*.dto.ts"
|
||||
- "backend/**/*.entity.ts"
|
||||
---
|
||||
|
||||
# Backend Patterns (NestJS)
|
||||
|
||||
## Architecture
|
||||
|
||||
- **Thin Controller** — business logic in Service layer
|
||||
- **DTO Validation** — class-validator + class-transformer
|
||||
- **RBAC** — CASL for authorization
|
||||
- **Error Handling** — Logger + HttpException
|
||||
|
||||
## UUID Resolution Pattern
|
||||
|
||||
```typescript
|
||||
// Controller - accept UUID in DTO
|
||||
@Post()
|
||||
async create(@Body() dto: CreateCorrespondenceDto) {
|
||||
// Resolve UUID to internal ID
|
||||
const contract = await this.contractService.findOneByUuid(dto.contractUuid);
|
||||
const contractId = contract.id; // Internal INT for DB queries
|
||||
|
||||
return this.service.create(dto, contractId);
|
||||
}
|
||||
|
||||
// Service - use internal ID for DB operations
|
||||
async create(dto: CreateCorrespondenceDto, contractId: number) {
|
||||
// Use contractId (INT) for database queries
|
||||
const correspondence = this.repo.create({
|
||||
contractId, // FK is INT
|
||||
// ... other fields
|
||||
});
|
||||
return this.repo.save(correspondence);
|
||||
}
|
||||
```
|
||||
|
||||
## API Response Pattern
|
||||
|
||||
```typescript
|
||||
// Entity
|
||||
@Entity()
|
||||
class Contract extends UuidBaseEntity {
|
||||
@Column({ type: 'uuid' })
|
||||
publicId: string;
|
||||
|
||||
@PrimaryKey()
|
||||
@Exclude()
|
||||
id: number;
|
||||
}
|
||||
|
||||
// Response automatically includes publicId as 'id'
|
||||
// { id: "019505a1-7c3e-7000-8000-abc123def456", ... }
|
||||
```
|
||||
|
||||
## Full Guidelines
|
||||
|
||||
`specs/05-Engineering-Guidelines/05-02-backend-guidelines.md`
|
||||
@@ -1,54 +0,0 @@
|
||||
---
|
||||
trigger: glob
|
||||
globs:
|
||||
- "frontend/**/*.tsx"
|
||||
- "frontend/**/*.ts"
|
||||
- "frontend/**/*.css"
|
||||
---
|
||||
|
||||
# Frontend Patterns (Next.js)
|
||||
|
||||
## Form Handling
|
||||
|
||||
- **RHF** (React Hook Form) for form management
|
||||
- **Zod** for validation schema
|
||||
- **TanStack Query** for server state
|
||||
|
||||
## UUID Handling
|
||||
|
||||
```typescript
|
||||
// ✅ CORRECT - Use publicId only
|
||||
interface ProjectOption {
|
||||
publicId?: string;
|
||||
projectName?: string;
|
||||
}
|
||||
|
||||
// Select options
|
||||
const options = contracts.map(c => ({
|
||||
label: `${c.contractName} (${c.contractCode})`,
|
||||
value: c.publicId!, // Use publicId, no fallback to id
|
||||
}));
|
||||
|
||||
// ❌ WRONG - Never use these patterns
|
||||
const value = c.publicId ?? c.id ?? ''; // Wrong!
|
||||
const id = parseInt(projectId); // Wrong - parseInt on UUID!
|
||||
```
|
||||
|
||||
## API Client Pattern
|
||||
|
||||
```typescript
|
||||
// Use publicId directly in API calls
|
||||
const contract = await contractService.getById(publicId);
|
||||
|
||||
// Form submission with UUID
|
||||
const onSubmit = async (data: FormData) => {
|
||||
await correspondenceService.create({
|
||||
contractUuid: selectedContract.publicId!, // UUID string
|
||||
// ... other fields
|
||||
});
|
||||
};
|
||||
```
|
||||
|
||||
## Full Guidelines
|
||||
|
||||
`specs/05-Engineering-Guidelines/05-03-frontend-guidelines.md`
|
||||
@@ -1,42 +0,0 @@
|
||||
---
|
||||
trigger: always_on
|
||||
---
|
||||
|
||||
# Development Flow
|
||||
|
||||
## 🔴 Critical Work — DB / API / Security / Workflow Engine
|
||||
|
||||
**MUST complete all steps:**
|
||||
|
||||
1. **Glossary check** — verify domain terms in `00-02-glossary.md`
|
||||
2. **Read the spec** — select from Key Spec Files table
|
||||
3. **Check schema** — verify table/column in `schema-02-tables.sql`
|
||||
4. **Check data dictionary** — confirm field meanings + business rules
|
||||
5. **Scan edge cases** — `01-06-edge-cases-and-rules.md`
|
||||
6. **Check ADRs** — verify decisions align (ADR-009, ADR-018, ADR-019)
|
||||
7. **Write code** — TypeScript strict, no `any`, no `console.log`
|
||||
|
||||
## 🟡 Normal Work — UI / Feature / Integration
|
||||
|
||||
- Follow existing patterns in codebase
|
||||
- Check spec for relevant module only
|
||||
- No need to read all specs
|
||||
|
||||
## 🟢 Quick Fix — Bug Fix / Typo / Style
|
||||
|
||||
- Fix directly
|
||||
- Add minimal test if logic changed
|
||||
- Check forbidden patterns before commit
|
||||
|
||||
## Context-Aware Triggers
|
||||
|
||||
| Request | Files to Check | Expected Response |
|
||||
| -------------------- | ------------------------------------------------------- | --------------------------------------------------- |
|
||||
| "สร้าง API ใหม่" | `05-02-backend-guidelines.md`, `schema-02-tables.sql` | NestJS Controller + Service + DTO + CASL Guard |
|
||||
| "แก้ฟอร์ม frontend" | `05-03-frontend-guidelines.md`, `01-06-edge-cases.md` | RHF+Zod + TanStack Query + Thai comments |
|
||||
| "เพิ่ม field ใหม่" | `ADR-009`, `data-dictionary.md`, `schema-02-tables.sql` | Edit SQL directly + update Data Dictionary + Entity |
|
||||
| "ตรวจสอบ UUID" | `ADR-019`, `05-07-hybrid-uuid-implementation-plan.md` | UUIDv7 MariaDB native UUID + TransformInterceptor |
|
||||
| "สร้าง migration" | `ADR-009`, `03-06-migration-business-scope.md` | Edit SQL schema directly + n8n workflow |
|
||||
| "ตรวจสอบ permission" | `seed-permissions.sql`, `ADR-016` | CASL 4-Level RBAC matrix |
|
||||
| "deploy production" | `04-08-release-management-policy.md`, `ADR-015` | Release Gates + Blue-Green strategy |
|
||||
| "เพิ่ม test" | `05-04-testing-strategy.md` | Coverage goals + test patterns |
|
||||
@@ -1,36 +0,0 @@
|
||||
---
|
||||
trigger: always_on
|
||||
---
|
||||
|
||||
# Commit Checklist
|
||||
|
||||
## Pre-Commit Verification
|
||||
|
||||
- [ ] UUID pattern verified (no parseInt on UUID)
|
||||
- [ ] No `any` types in TypeScript
|
||||
- [ ] No `console.log` in committed code
|
||||
- [ ] Comments in Thai
|
||||
- [ ] Code identifiers in English
|
||||
- [ ] Schema changes via SQL directly (not migration)
|
||||
- [ ] Test coverage meets targets (Backend 70%+, Business Logic 80%+)
|
||||
- [ ] Relevant ADRs checked (ADR-009, ADR-018, ADR-019)
|
||||
- [ ] Glossary terms used correctly
|
||||
- [ ] Error handling complete (Logger + HttpException)
|
||||
- [ ] i18n keys used instead of hardcode text
|
||||
- [ ] Cache invalidation when data modified
|
||||
- [ ] Security checklist passed (OWASP Top 10)
|
||||
|
||||
## Commit Message Format
|
||||
|
||||
```
|
||||
type(scope): description
|
||||
|
||||
[optional body]
|
||||
```
|
||||
|
||||
Types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`
|
||||
|
||||
Examples:
|
||||
- `feat(correspondence): add originator organization validation`
|
||||
- `fix(uuid): correct parseInt usage to string comparison`
|
||||
- `spec(agents): bump to v1.8.5 - refactor structure`
|
||||
@@ -1,78 +0,0 @@
|
||||
---
|
||||
trigger: always_on
|
||||
---
|
||||
|
||||
# ADR-007 Error Handling Strategy
|
||||
|
||||
## CRITICAL RULES
|
||||
|
||||
- **ALWAYS** use layered error classification (Validation, Business, System)
|
||||
- **NEVER** expose technical details to end users
|
||||
- **ALWAYS** provide user-friendly error messages with recovery guidance
|
||||
- **ALWAYS** log technical details for debugging
|
||||
- **NEVER** use generic error messages without context
|
||||
|
||||
## Error Classification
|
||||
|
||||
| Error Type | Description | User Message | Technical Log |
|
||||
|------------|-------------|--------------|---------------|
|
||||
| **Validation** | Input validation failures | Clear field-level errors | Full validation details |
|
||||
| **Business** | Business rule violations | Actionable guidance | Business context + user ID |
|
||||
| **System** | Infrastructure failures | Generic "try again" | Full stack trace + metrics |
|
||||
|
||||
## Backend Pattern (NestJS)
|
||||
|
||||
```typescript
|
||||
// Custom Exception Hierarchy
|
||||
export class BusinessException extends HttpException {
|
||||
constructor(
|
||||
message: string,
|
||||
userMessage: string,
|
||||
recoveryAction?: string,
|
||||
errorCode?: string
|
||||
) {
|
||||
super({ message, userMessage, recoveryAction, errorCode }, 400);
|
||||
}
|
||||
}
|
||||
|
||||
// Global Exception Filter
|
||||
@Catch()
|
||||
export class GlobalExceptionFilter implements ExceptionFilter {
|
||||
catch(exception: unknown, host: ArgumentsHost) {
|
||||
// Classify error and provide appropriate response
|
||||
// Log technical details
|
||||
// Return user-friendly message
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Frontend Pattern (Next.js)
|
||||
|
||||
```typescript
|
||||
// Error Display Component
|
||||
const ErrorDisplay = ({ error, onRetry }) => {
|
||||
const userMessage = error.userMessage || 'เกิดข้อผิดพลาด';
|
||||
const recoveryAction = error.recoveryAction;
|
||||
|
||||
return (
|
||||
<div>
|
||||
<p>{userMessage}</p>
|
||||
{recoveryAction && <p>{recoveryAction}</p>}
|
||||
{onRetry && <button onClick={onRetry}>ลองใหม่</button>}
|
||||
</div>
|
||||
);
|
||||
};
|
||||
```
|
||||
|
||||
## Required Implementation
|
||||
|
||||
- [ ] Global Exception Filter with layered classification
|
||||
- [ ] Custom exception hierarchy (Validation, Business, System)
|
||||
- [ ] Standardized error response DTOs
|
||||
- [ ] Frontend error display components
|
||||
- [ ] Error recovery mechanisms where applicable
|
||||
|
||||
## Related Documents
|
||||
|
||||
- `specs/06-Decision-Records/ADR-007-error-handling-strategy.md`
|
||||
- `specs/06-Decision-Records/ADR-010-logging-monitoring-strategy.md`
|
||||
@@ -1,100 +0,0 @@
|
||||
---
|
||||
trigger: always_on
|
||||
---
|
||||
|
||||
# ADR-020 AI Integration Architecture
|
||||
|
||||
## CRITICAL RULES
|
||||
|
||||
- **ALWAYS** follow ADR-018 AI boundary policy (isolation on Admin Desktop)
|
||||
- **ALWAYS** use RFA-First approach for AI implementation
|
||||
- **NEVER** allow AI direct database/storage access
|
||||
- **ALWAYS** implement human-in-the-loop validation
|
||||
- **NEVER** send sensitive data to cloud AI services
|
||||
|
||||
## AI Integration Patterns
|
||||
|
||||
### Architecture Overview
|
||||
|
||||
```
|
||||
Frontend → AI Gateway API → Admin Desktop (Ollama) → Backend Validation
|
||||
```
|
||||
|
||||
### Key Components
|
||||
|
||||
| Component | Location | Purpose |
|
||||
|-----------|----------|---------|
|
||||
| **AI Gateway** | Backend (NestJS) | API endpoints, validation, audit logging |
|
||||
| **Ollama Engine** | Admin Desktop (Desk-5439) | LLM inference (Gemma 4) |
|
||||
| **OCR Engine** | Admin Desktop (Desk-5439) | Thai/English text extraction |
|
||||
| **Orchestrator** | QNAP NAS (n8n) | Workflow management |
|
||||
|
||||
## Backend Implementation (NestJS)
|
||||
|
||||
```typescript
|
||||
// AI Module with boundary enforcement
|
||||
@Module({
|
||||
controllers: [AiController],
|
||||
providers: [AiService, AiGateway],
|
||||
exports: [AiService],
|
||||
})
|
||||
export class AiModule {
|
||||
constructor() {
|
||||
// Enforce ADR-018 boundaries
|
||||
}
|
||||
}
|
||||
|
||||
// AI Service with validation
|
||||
@Injectable()
|
||||
export class AiService {
|
||||
async extractMetadata(documentId: string): Promise<AIMetadata> {
|
||||
// 1. Validate permissions
|
||||
// 2. Send to Admin Desktop AI
|
||||
// 3. Validate AI response
|
||||
// 4. Log audit trail
|
||||
// 5. Return validated results
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Frontend Pattern (Next.js)
|
||||
|
||||
```typescript
|
||||
// Document Review Form (reusable component)
|
||||
const DocumentReviewForm = ({ document, aiSuggestions }) => {
|
||||
return (
|
||||
<form>
|
||||
<Field label="Document Type" suggestions={aiSuggestions.documentType} />
|
||||
<Field label="Project Code" suggestions={aiSuggestions.projectCode} />
|
||||
<Field label="Discipline" suggestions={aiSuggestions.discipline} />
|
||||
|
||||
<ConfidenceScore score={aiSuggestions.confidence} />
|
||||
<HumanValidationActions />
|
||||
</form>
|
||||
);
|
||||
};
|
||||
```
|
||||
|
||||
## Security Requirements
|
||||
|
||||
- **AI Isolation:** All AI processing on Admin Desktop only
|
||||
- **Data Privacy:** No cloud AI services, on-premises only
|
||||
- **Audit Trail:** Log all AI interactions and human validations
|
||||
- **Rate Limiting:** Prevent AI abuse and resource exhaustion
|
||||
- **Validation:** All AI outputs must be validated before use
|
||||
|
||||
## Required Implementation
|
||||
|
||||
- [ ] AiModule with ADR-018 boundary enforcement
|
||||
- [ ] AI Gateway API endpoints with validation
|
||||
- [ ] DocumentReviewForm reusable component
|
||||
- [ ] Admin Desktop Ollama + PaddleOCR setup
|
||||
- [ ] n8n workflow orchestration
|
||||
- [ ] AI audit logging and monitoring
|
||||
- [ ] Human-in-the-loop validation workflows
|
||||
|
||||
## Related Documents
|
||||
|
||||
- `specs/06-Decision-Records/ADR-018-ai-boundary.md`
|
||||
- `specs/06-Decision-Records/ADR-020-ai-intelligence-integration.md`
|
||||
- `specs/06-Decision-Records/ADR-017-ollama-data-migration.md`
|
||||
@@ -1,4 +1,5 @@
|
||||
---
|
||||
auto_execution_mode: 0
|
||||
description: Run the full speckit pipeline from specification to analysis in one command.
|
||||
---
|
||||
|
||||
|
||||
@@ -1,4 +1,5 @@
|
||||
---
|
||||
auto_execution_mode: 0
|
||||
description: Create or update the project constitution from interactive or provided principle inputs, ensuring all dependent templates stay in sync.
|
||||
---
|
||||
|
||||
|
||||
@@ -1,4 +1,5 @@
|
||||
---
|
||||
auto_execution_mode: 0
|
||||
description: Create or update the feature specification from a natural language feature description.
|
||||
---
|
||||
|
||||
|
||||
@@ -1,4 +1,5 @@
|
||||
---
|
||||
auto_execution_mode: 0
|
||||
description: Identify underspecified areas in the current feature spec by asking up to 5 highly targeted clarification questions and encoding answers back into the spec.
|
||||
---
|
||||
|
||||
|
||||
@@ -1,4 +1,5 @@
|
||||
---
|
||||
auto_execution_mode: 0
|
||||
description: Execute the implementation planning workflow using the plan template to generate design artifacts.
|
||||
---
|
||||
|
||||
|
||||
@@ -1,4 +1,5 @@
|
||||
---
|
||||
auto_execution_mode: 0
|
||||
description: Generate an actionable, dependency-ordered tasks.md for the feature based on available design artifacts.
|
||||
---
|
||||
|
||||
|
||||
@@ -1,4 +1,5 @@
|
||||
---
|
||||
auto_execution_mode: 0
|
||||
description: Perform a non-destructive cross-artifact consistency and quality analysis across spec.md, plan.md, and tasks.md after task generation.
|
||||
---
|
||||
|
||||
|
||||
@@ -1,4 +1,5 @@
|
||||
---
|
||||
auto_execution_mode: 0
|
||||
description: Execute the implementation plan by processing and executing all tasks defined in tasks.md
|
||||
---
|
||||
|
||||
|
||||
@@ -1,4 +1,5 @@
|
||||
---
|
||||
auto_execution_mode: 0
|
||||
description: Run static analysis tools and aggregate results.
|
||||
---
|
||||
|
||||
|
||||
@@ -1,4 +1,5 @@
|
||||
---
|
||||
auto_execution_mode: 0
|
||||
description: Execute tests, measure coverage, and report results.
|
||||
---
|
||||
|
||||
|
||||
@@ -1,4 +1,5 @@
|
||||
---
|
||||
auto_execution_mode: 0
|
||||
description: Perform code review with actionable feedback and suggestions.
|
||||
---
|
||||
|
||||
|
||||
@@ -1,4 +1,5 @@
|
||||
---
|
||||
auto_execution_mode: 0
|
||||
description: Validate that implementation matches specification requirements.
|
||||
---
|
||||
|
||||
|
||||
@@ -1,4 +1,5 @@
|
||||
---
|
||||
auto_execution_mode: 0
|
||||
description: Create a new NestJS backend feature module following project standards
|
||||
---
|
||||
|
||||
@@ -13,7 +14,7 @@ Follows `specs/05-Engineering-Guidelines/05-02-backend-guidelines.md` and ADR-00
|
||||
|
||||
1. **Verify requirements exist** — confirm the feature is in `specs/01-Requirements/` before starting
|
||||
|
||||
// turbo 2. **Check schema** — read `specs/03-Data-and-Storage/lcbp3-v1.7.0-schema.sql` for relevant tables
|
||||
// turbo 2. **Check schema** — read `specs/03-Data-and-Storage/lcbp3-v1.8.0-schema.sql` for relevant tables
|
||||
|
||||
3. **Scaffold module folder**
|
||||
|
||||
@@ -30,17 +31,17 @@ backend/src/modules/<module-name>/
|
||||
└── <module-name>.controller.spec.ts
|
||||
```
|
||||
|
||||
4. **Create Entity** — map ONLY columns defined in the schema SQL. Use TypeORM decorators. Add `@VersionColumn()` if the entity needs optimistic locking.
|
||||
// turbo 4. **Create Entity** — map ONLY columns defined in the schema SQL. Use TypeORM decorators. Add `@VersionColumn()` if the entity needs optimistic locking.
|
||||
|
||||
5. **Create DTOs** — use `class-validator` decorators. Never use `any`. Validate all inputs.
|
||||
// turbo 5. **Create DTOs** — use `class-validator` decorators. Never use `any`. Validate all inputs.
|
||||
|
||||
6. **Create Service** — inject repository via constructor DI. Use transactions for multi-step writes. Add `Idempotency-Key` guard for POST/PUT/PATCH operations.
|
||||
// turbo 6. **Create Service** — inject repository via constructor DI. Use transactions for multi-step writes. Add `Idempotency-Key` guard for POST/PUT/PATCH operations.
|
||||
|
||||
7. **Create Controller** — apply `@UseGuards(JwtAuthGuard, CaslAbilityGuard)`. Use proper HTTP status codes. Document with `@ApiTags` and `@ApiOperation`.
|
||||
// turbo 7. **Create Controller** — apply `@UseGuards(JwtAuthGuard, CaslAbilityGuard)`. Use proper HTTP status codes. Document with `@ApiTags` and `@ApiOperation`.
|
||||
|
||||
8. **Register in Module** — add to `imports`, `providers`, `controllers`, `exports` as needed.
|
||||
// turbo 8. **Register in Module** — add to `imports`, `providers`, `controllers`, `exports` as needed.
|
||||
|
||||
9. **Register in AppModule** — import the new module in `app.module.ts`.
|
||||
// turbo 9. **Register in AppModule** — import the new module in `app.module.ts`.
|
||||
|
||||
// turbo 10. **Write unit test** — cover service methods with Jest mocks. Run:
|
||||
|
||||
|
||||
@@ -1,4 +1,5 @@
|
||||
---
|
||||
auto_execution_mode: 0
|
||||
description: Create a new Next.js App Router page following project standards
|
||||
---
|
||||
|
||||
|
||||
@@ -1,4 +1,5 @@
|
||||
---
|
||||
auto_execution_mode: 0
|
||||
description: Deploy the application via Gitea Actions to QNAP Container Station
|
||||
---
|
||||
|
||||
|
||||
@@ -1,4 +1,5 @@
|
||||
---
|
||||
auto_execution_mode: 0
|
||||
description: Manage database schema changes following ADR-009 (no migrations, modify SQL directly)
|
||||
---
|
||||
|
||||
@@ -18,7 +19,7 @@ Follows `specs/06-Decision-Records/ADR-009-database-strategy.md` — **NO TypeOR
|
||||
1. **Read current schema** — load the full schema file:
|
||||
|
||||
```
|
||||
specs/03-Data-and-Storage/lcbp3-v1.7.0-schema.sql
|
||||
specs/03-Data-and-Storage/lcbp3-v1.8.0-schema.sql
|
||||
```
|
||||
|
||||
2. **Read data dictionary** — understand current field definitions:
|
||||
@@ -35,7 +36,7 @@ specs/03-Data-and-Storage/03-01-data-dictionary.md
|
||||
- Indexes being added/modified
|
||||
- Seed data impact (if any)
|
||||
|
||||
4. **Modify schema SQL** — edit `specs/03-Data-and-Storage/lcbp3-v1.7.0-schema.sql`:
|
||||
4. **Modify schema SQL** — edit `specs/03-Data-and-Storage/lcbp3-v1.8.0-schema.sql`:
|
||||
- Add/modify table definitions
|
||||
- Maintain consistent formatting (uppercase SQL keywords, lowercase identifiers)
|
||||
- Add inline comments for new columns explaining purpose
|
||||
@@ -52,8 +53,8 @@ specs/03-Data-and-Storage/03-01-data-dictionary.md
|
||||
- Add enum value definitions if applicable
|
||||
|
||||
6. **Update seed data** (if applicable):
|
||||
- `specs/03-Data-and-Storage/lcbp3-v1.7.0-seed-basic.sql` — for reference/lookup data
|
||||
- `specs/03-Data-and-Storage/lcbp3-v1.7.0-seed-permissions.sql` — for new CASL permissions
|
||||
- `specs/03-Data-and-Storage/lcbp3-v1.8.0-seed-basic.sql` — for reference/lookup data
|
||||
- `specs/03-Data-and-Storage/lcbp3-v1.8.0-seed-permissions.sql` — for new CASL permissions
|
||||
|
||||
7. **Update TypeORM entity** — modify corresponding `backend/src/modules/<module>/entities/*.entity.ts`:
|
||||
- Map ONLY columns defined in schema SQL
|
||||
|
||||
@@ -1,4 +1,5 @@
|
||||
---
|
||||
auto_execution_mode: 0
|
||||
description: Execute the full preparation pipeline (Specify -> Clarify -> Plan -> Tasks -> Analyze) in sequence.
|
||||
---
|
||||
|
||||
|
||||
@@ -1,4 +1,5 @@
|
||||
---
|
||||
auto_execution_mode: 0
|
||||
description: Generate a custom checklist for the current feature based on user requirements.
|
||||
---
|
||||
|
||||
|
||||
@@ -1,4 +1,5 @@
|
||||
---
|
||||
auto_execution_mode: 0
|
||||
description: Compare two versions of a spec or plan to highlight changes.
|
||||
---
|
||||
|
||||
|
||||
@@ -1,4 +1,5 @@
|
||||
---
|
||||
auto_execution_mode: 0
|
||||
description: Migrate existing projects into the speckit structure by generating spec.md, plan.md, and tasks.md from existing code.
|
||||
---
|
||||
|
||||
|
||||
@@ -1,4 +1,5 @@
|
||||
---
|
||||
auto_execution_mode: 0
|
||||
description: Challenge the specification with Socratic questioning to identify logical gaps, unhandled edge cases, and robustness issues.
|
||||
---
|
||||
|
||||
|
||||
@@ -1,4 +1,5 @@
|
||||
---
|
||||
auto_execution_mode: 0
|
||||
description: Display a dashboard showing feature status, completion percentage, and blockers.
|
||||
---
|
||||
|
||||
|
||||
@@ -1,18 +0,0 @@
|
||||
---
|
||||
description: Convert existing tasks into actionable, dependency-ordered GitHub issues for the feature based on available design artifacts.
|
||||
---
|
||||
|
||||
# Workflow: speckit.taskstoissues
|
||||
|
||||
1. **Context Analysis**:
|
||||
- The user has provided an input prompt. Treat this as the primary input for the skill.
|
||||
|
||||
2. **Load Skill**:
|
||||
- Use the `view_file` tool to read the skill file at: `.agents/skills/speckit.taskstoissues/SKILL.md`
|
||||
|
||||
3. **Execute**:
|
||||
- Follow the instructions in the `SKILL.md` exactly.
|
||||
- Apply the user's prompt as the input arguments/context for the skill's logic.
|
||||
|
||||
4. **On Error**:
|
||||
- If `tasks.md` is missing: Run `/speckit.tasks` first
|
||||
Reference in New Issue
Block a user