evnict-kit 0.2.1

package/templates/context/AGENTS.md.template

@@ -0,0 +1,462 @@
+# {{PROJECT_NAME}} — AI Agent Context
+# Generated by evnict-kit v0.1.3
+# Đây là file context chính cho AI Agent — đọc file này ĐẦU TIÊN
+
+---
+
+## 1. PROJECT OVERVIEW
+
+| Property | Value |
+|----------|-------|
+| Project Name | {{PROJECT_NAME}} |
+| Tech Stack | {{TECH_STACK}} |
+| Database | {{DATABASE}} |
+| Generated | {{DATE}} |
+| evnict-kit | v0.1.3 |
+
+### Mô tả
+<!-- CHƯA KHỞI TẠO — Agent sẽ điền khi chạy /evnict-kit:init-context -->
+{Mô tả ngắn gọn về dự án — 2-3 câu}
+
+### Mục tiêu nghiệp vụ
+<!-- CHƯA KHỞI TẠO -->
+{Mục tiêu chính của hệ thống}
+
+---
+
+## 2. ARCHITECTURE
+
+### Tổng quan
+<!-- CHƯA KHỞI TẠO — Agent sẽ điền architecture diagram -->
+```
+┌──────────────────────────────────────────────────┐
+│                   CLIENT                          │
+│           Angular + PrimeNG                       │
+└───────────────────┬──────────────────────────────┘
+                    │ HTTP/REST
+┌───────────────────▼──────────────────────────────┐
+│              API GATEWAY / NGINX                  │
+└───────────────────┬──────────────────────────────┘
+                    │
+┌───────────────────▼──────────────────────────────┐
+│              SPRING BOOT APP                      │
+│  ┌─────────┐  ┌──────────┐  ┌──────────────┐    │
+│  │Controller│→ │ Service  │→ │ Repository   │    │
+│  │ @Valid   │  │ @Transac │  │ JOOQ/JPA     │    │
+│  └─────────┘  └──────────┘  └──────┬───────┘    │
+│                                      │            │
+│  ┌──────────┐  ┌──────────┐         │            │
+│  │ Security │  │ Exception│         │            │
+│  │ JWT(RS256)│  │ Handler  │         │            │
+│  └──────────┘  └──────────┘         │            │
+└──────────────────────────────────────┤────────────┘
+                                       │
+            ┌──────────────────────────▼───────┐
+            │         ORACLE DATABASE          │
+            │    Schema: EVNTMS + {{PROJECT}}   │
+            └──────────────────────────────────┘
+                                       │
+            ┌──────────────────────────┘
+            │
+    ┌───────▼─────┐  ┌──────────┐  ┌──────────┐
+    │   MinIO     │  │ EVN SSO  │  │  Redis   │
+    │ File Storage│  │   Auth   │  │  Cache   │
+    └─────────────┘  └──────────┘  └──────────┘
+```
+
+### Layer Architecture
+```
+Controller Layer    → HTTP handling, input validation (@Valid)
+    ↓
+Service Layer       → Business logic, @Transactional
+    ↓
+Repository Layer    → Data access (JOOQ type-safe queries)
+    ↓
+Database            → Oracle/SQL Server
+```
+
+### Nguyên tắc
+- Controller KHÔNG chứa business logic
+- Service quản lý transactions
+- Repository CHỈ data access — không business logic
+- DTO cho data transfer — KHÔNG dùng Entity trực tiếp trong response
+
+---
+
+## 3. TECH STACK
+
+| Layer | Technology | Version | Notes |
+|-------|-----------|---------|-------|
+| Backend | {{TECH_STACK}} | <!-- version --> | Main API server |
+| ORM | JOOQ | <!-- version --> | Type-safe SQL |
+| Database | {{DATABASE}} | <!-- version --> | Primary data store |
+| Frontend | Angular | <!-- version --> | SPA |
+| UI Library | PrimeNG | <!-- version --> | Component library |
+| Auth | JWT (RS256) | - | Via EVN SSO |
+| File Storage | MinIO | - | S3-compatible |
+| Cache | Redis | - | Session + local cache |
+| CI/CD | Azure DevOps | - | Pipeline |
+| Container | Docker + K8s | - | Deployment |
+
+---
+
+## 4. PROJECT STRUCTURE
+
+### Backend
+<!-- CHƯA KHỞI TẠO — Agent sẽ điền từ tree output -->
+```
+src/main/java/com/evn/{{PROJECT_NAME}}/
+├── config/              ← Application configuration
+├── common/              ← Shared utilities, base classes
+│   ├── dto/             ← ResponseData, PageDTO
+│   └── exception/       ← BusinessException, GlobalExceptionHandler
+├── security/            ← JWT filter, SecurityConfig
+└── {module}/            ← Feature modules
+    ├── controller/
+    ├── service/
+    ├── repository/
+    └── dto/
+```
+
+### Frontend
+<!-- CHƯA KHỞI TẠO -->
+```
+src/app/
+├── core/                ← Guards, interceptors, core services
+├── shared/              ← Reusable components, pipes, directives
+│   ├── components/
+│   ├── pipes/
+│   └── services/
+├── features/            ← Feature modules (lazy-loaded)
+│   └── {module}/
+│       ├── pages/
+│       ├── components/
+│       ├── services/
+│       └── models/
+└── assets/              ← Static assets, i18n files
+```
+
+---
+
+## 5. DEVELOPMENT COMMANDS
+
+### Backend
+```bash
+# Build
+./mvnw clean install
+
+# Run
+./mvnw spring-boot:run
+
+# Test
+./mvnw test
+
+# Lint/Format
+./mvnw spotless:check
+./mvnw spotless:apply
+
+# Dependency check
+./mvnw versions:display-dependency-updates
+./mvnw org.owasp:dependency-check-maven:check
+```
+
+### Frontend
+```bash
+# Install
+npm install
+
+# Run
+ng serve
+
+# Test
+ng test --watch=false
+
+# Lint
+ng lint
+
+# Build
+ng build --configuration=production
+
+# Security
+npm audit
+```
+
+### Database
+```bash
+# Migration (Flyway)
+./mvnw flyway:migrate
+./mvnw flyway:info
+
+# JOOQ Code Generation
+./mvnw jooq-codegen:generate
+```
+
+---
+
+## 6. CODING CONVENTIONS
+
+> Chi tiết → `.agent/rules/03-evnict-kit-backend-conventions.md` (BE)
+> Chi tiết → `.agent/rules/04-evnict-kit-frontend-conventions.md` (FE)
+> Chi tiết → `.agent/rules/05-evnict-kit-project-conventions.md` (Project-specific)
+
+### Naming
+<!-- CHƯA KHỞI TẠO — sẽ tóm tắt từ RP01 -->
+| Loại | Convention | Ví dụ |
+|------|-----------|-------|
+| Class | PascalCase | `CustomerService` |
+| Method | camelCase | `findByStatus()` |
+| Variable | camelCase | `customerId` |
+| Constant | UPPER_SNAKE | `MAX_FILE_SIZE` |
+| Table | UPPER_SNAKE | `CUSTOMER` |
+| Column | UPPER_SNAKE | `CREATED_DATE` |
+| API path | kebab-case | `/api/customers` |
+
+### API Response Format
+```java
+// Tất cả API response dùng ResponseData
+public class ResponseData {
+    private int status;      // 0 = success, 1 = error
+    private String message;
+    private Object data;
+}
+
+// Thành công
+ResponseData.ok(data)       // { status: 0, message: "Thành công", data: {...} }
+
+// Lỗi
+ResponseData.error("msg")   // { status: 1, message: "msg", data: null }
+```
+
+### Commit Message Format
+```
+{type}({scope}): {description} [task-{N}]
+
+Types: feat, fix, refactor, test, docs, chore
+Scope: module name
+```
+
+---
+
+## 7. API CONVENTIONS
+
+<!-- CHƯA KHỞI TẠO — sẽ tóm tắt từ RP04 -->
+
+### Endpoint Pattern
+```
+GET    /api/{module}          → List (paginated)
+GET    /api/{module}/{id}     → Get by ID
+POST   /api/{module}          → Create
+PUT    /api/{module}/{id}     → Update
+DELETE /api/{module}/{id}     → Delete
+POST   /api/{module}/search   → Complex search
+```
+
+### Pagination
+```
+?page=0&size=20&sort=name
+```
+
+### Authentication
+```
+Authorization: Bearer {JWT_TOKEN}
+```
+
+### Error Codes
+| HTTP Code | Usage |
+|-----------|-------|
+| 200 | Success (kể cả business error qua ResponseData.status) |
+| 400 | Validation error |
+| 401 | Unauthorized |
+| 403 | Forbidden |
+| 500 | Server error (không trả stack trace) |
+
+---
+
+## 8. DATABASE CONVENTIONS
+
+<!-- CHƯA KHỞI TẠO — sẽ tóm tắt từ RP05 -->
+
+### Migration
+- Tool: Flyway
+- Path: `database/migrations/`
+- Naming: `V{YYYYMMDD}_{seq}__{desc}.sql`
+- BẮT BUỘC có ROLLBACK script
+
+### Audit Columns (bắt buộc mọi table)
+```sql
+CREATED_BY      VARCHAR2(50)
+CREATED_DATE    TIMESTAMP DEFAULT SYSTIMESTAMP
+UPDATED_BY      VARCHAR2(50)
+UPDATED_DATE    TIMESTAMP
+```
+
+### Soft Delete
+```sql
+IS_DELETED      NUMBER(1) DEFAULT 0
+-- Hoặc: STATUS = 'DELETED'
+```
+
+---
+
+## 9. SECURITY RULES
+
+> Chi tiết → `.agent/rules/01-evnict-kit-general-rules.md`
+> Chi tiết → `.agent/rules/02-evnict-kit-security-rules.md`
+
+### Critical Rules — LÀM SAI = DỪNG NGAY
+| # | Rule | Category |
+|---|------|----------|
+| R01 | Không hardcode secrets | General |
+| R02 | Không git push | General |
+| R03 | Không destructive ops | General |
+| R04 | Không log PII | General |
+| ATTT01 | SQL Injection prevention | Security |
+| ATTT02 | XSS prevention | Security |
+| ATTT04 | JWT RS256 only | Security |
+| ATTT07 | No data exposure | Security |
+
+### OWASP Top 10 Quick Check
+- ✅ Parameterized queries (JOOQ type-safe)
+- ✅ Response DTO (không Entity)
+- ✅ JWT RS256, key ≥ 2048
+- ✅ CSRF (JWT stateless → disabled)
+- ✅ CSP headers
+- ✅ File upload validation
+- ✅ Error handler (no stack trace)
+- ✅ Dependency scan
+
+---
+
+## 10. AGENT COMMANDS
+
+### Phase 1: Init (chạy 1 lần khi setup)
+| Command | Mô tả |
+|---------|--------|
+| `/evnict-kit:init-rules` | Agent đọc code → điền rules RP01-RP07 |
+| `/evnict-kit:init-context` | Agent sinh AGENTS.md từ rules |
+| `/evnict-kit:init-check` | Agent sinh demo code để verify |
+| `/evnict-kit:init-wiki` | Setup llm-wiki knowledge base |
+
+### Phase 2: Development (sử dụng thường xuyên)
+| Command | Mô tả |
+|---------|--------|
+| `/evnict-kit:feature-large` | Feature lớn: spec→plan→TDD→archive |
+| `/evnict-kit:feature-small` | Feature nhỏ: plan→TDD |
+| `/evnict-kit:bug-fix` | Sửa lỗi: reproduce→TDD fix |
+| `/evnict-kit:implement` | TDD implement từ plan |
+| `/evnict-kit:attt` | Scan ATTT (full hoặc module) |
+| `/evnict-kit:review` | Auto review trước merge |
+| `/evnict-kit:archive-wiki` | Archive spec + push wiki |
+| `/evnict-kit:spec-archive` | Quản lý specs |
+
+### Skills (tự động gọi bởi workflows)
+| Skill | Mô tả |
+|-------|--------|
+| evnict-kit-spec | SDD: specify + clarify + plan |
+| evnict-kit-tdd | TDD: Red→Green→Refactor |
+| evnict-kit-wiki | Push/Query wiki |
+| evnict-kit-create-api | Tạo API endpoint chuẩn |
+| evnict-kit-create-component | Tạo UI component |
+| evnict-kit-create-page | Tạo page mới |
+| evnict-kit-database-migration | Migration scripts |
+| evnict-kit-coordinate | FE↔BE coordination |
+| evnict-kit-checkpoint | Checkpoint & rollback |
+| evnict-kit-code-review | Code review (9 items) |
+| evnict-kit-merge-checklist | Pre-merge check (9 items) |
+| evnict-kit-security-audit | Security audit toàn diện |
+| evnict-kit-fix-attt | Fix lỗi ATTT |
+| evnict-kit-bug-fix | Bug fix flow |
+| evnict-kit-fix-business-logic | Fix lỗi nghiệp vụ |
+| evnict-kit-doc-postmortem | Tạo tài liệu đặc tả |
+| evnict-kit-onboard | Onboard member mới |
+| evnict-kit-prompt-standard | Chuẩn viết prompt |
+
+---
+
+## 11. SAFETY RULES (NON-NEGOTIABLE)
+
+```
+❌ KHÔNG tự động git push
+❌ KHÔNG xóa file/folder quan trọng
+❌ KHÔNG hardcode secrets, passwords, API keys
+❌ KHÔNG log PII (password, CMND, phone, token)
+❌ KHÔNG expose stack trace cho client
+❌ KHÔNG sửa code ngoài scope yêu cầu
+❌ KHÔNG tiếp tục khi test fail > 3 lần (3-strike rule)
+
+✅ Luôn tạo checkpoint trước phiên AI
+✅ Luôn chạy test trước commit
+✅ Luôn dùng DTO, không Entity trực tiếp
+✅ Luôn validate input ở Controller
+✅ Luôn transaction ở Service
+```
+
+---
+
+## 12. INTEGRATION MAP
+
+<!-- CHƯA KHỞI TẠO — sẽ tóm tắt từ RP07 -->
+
+| Service | Protocol | Usage |
+|---------|----------|-------|
+| EVN SSO | JWT (RS256) | Authentication |
+| MinIO | S3 API | File storage |
+| Redis | TCP | Session + cache |
+| CMIS | HTTP | Document management |
+| Azure DevOps | Git + Pipeline | CI/CD |
+| Docker + K8s | Container | Deployment |
+
+---
+
+## 13. WORKSPACE STRUCTURE
+
+```
+workspace/
+├── .evnict/                  ← Workspace config
+│   ├── config.yaml           ← Project configuration
+│   ├── handoff/              ← FE↔BE coordination
+│   │   ├── contracts/        ← API contracts
+│   │   ├── be-status.md
+│   │   └── fe-status.md
+│   └── specs/                ← Feature specs
+│       └── {feature}/
+│           ├── spec.md
+│           ├── plan.md
+│           ├── tasks/
+│           └── contracts/
+├── {{BE_FOLDER}}/            ← Backend project
+│   ├── .agent/
+│   │   ├── rules/            ← 5 rule files
+│   │   ├── skills/           ← 18 skills
+│   │   ├── workflows/        ← 8 workflows
+│   │   └── commands/         ← 4 commands
+│   ├── AGENTS.md             ← THIS FILE
+│   └── Instruct-Agent-AI.md
+├── {{FE_FOLDER}}/            ← Frontend project
+│   └── (same structure)
+├── docs/
+│   ├── specs/                ← Archived specs
+│   ├── attt/                 ← Security reports
+│   └── postmortem/           ← Session documents
+├── database/
+│   └── migrations/           ← DB migration scripts
+└── {{PROJECT}}-wiki/         ← LLM Wiki knowledge base
+```
+
+---
+
+## 14. REFERENCES
+
+- **QĐ-TTPM**: Quy định hướng dẫn sử dụng AI trong PTPM tại EVNICT
+  - Điều 7: Thiết lập ngữ cảnh
+  - Điều 8: Nguyên tắc sử dụng AI an toàn
+  - Phụ lục II: Quy trình theo loại công việc
+  - Phụ lục III: Cấu trúc tài liệu thiết kế
+  - Phụ lục IV: Hướng dẫn thiết lập ngữ cảnh
+- **OWASP Top 10:2021**: https://owasp.org/Top10/
+- **evnict-kit**: v0.1.3
+
+---
+
+> ⚠️ **File này chứa sections "CHƯA KHỞI TẠO"**
+> Chạy `/evnict-kit:init-context` để Agent tự động điền nội dung.