evnict-kit 0.2.1

package/templates/content/rules/04-evnict-kit-frontend-conventions.md

@@ -0,0 +1,402 @@
+---
+trigger: always_on
+---
+# Frontend Conventions — EVNICT Standard
+**Activation Mode: Always On**
+**Source: QĐ-TTPM Điều 8, Mục 8.6**
+**Tech: Angular + PrimeNG**
+
+> Áp dụng cho TẤT CẢ code frontend. Mọi code mới hoặc sửa đổi PHẢI tuân thủ.
+
+---
+
+## 1. NO INLINE STYLES (RF01)
+
+### Quy tắc
+- KHÔNG sử dụng inline styles trực tiếp trong template
+- Tất cả styles PHẢI đặt trong file `.scss` hoặc `.css` riêng
+- Dùng CSS classes, KHÔNG dùng `[style]` binding
+- Exception: dynamic styles từ business logic (VD: chart colors)
+
+### Code examples
+```html
+<!-- ❌ SAI — Inline styles -->
+<div style="color: red; font-size: 14px; margin-top: 10px">
+  {{ errorMessage }}
+</div>
+<div [style.color]="isError ? 'red' : 'green'">Status</div>
+
+<!-- ✅ ĐÚNG — CSS class -->
+<div class="error-message" [class.error]="isError" [class.success]="!isError">
+  {{ errorMessage }}
+</div>
+```
+
+```scss
+// ✅ Trong component.scss
+.error-message {
+  font-size: 14px;
+  margin-top: 10px;
+  
+  &.error { color: var(--color-error); }
+  &.success { color: var(--color-success); }
+}
+```
+
+### Scan commands
+```bash
+grep -rn "style=\"" --include="*.html" src/
+grep -rn "\[style\." --include="*.html" src/
+```
+
+---
+
+## 2. COMPONENT REUSE (RF02)
+
+### Quy tắc
+- TRƯỚC KHI tạo component mới → kiểm tra đã có component tương tự chưa
+- Tìm trong: `shared/components/`, PrimeNG library, project components
+- Nếu đã có → reuse hoặc extend
+- Component mới PHẢI đặt trong `shared/` nếu dùng ≥ 2 nơi
+
+### Component categories
+```
+src/app/
+├── shared/
+│   ├── components/       ← Reusable components (dùng ≥ 2 nơi)
+│   │   ├── data-table/   ← Generic table wrapper
+│   │   ├── form-field/   ← Form field với validation
+│   │   ├── file-upload/  ← Upload component
+│   │   └── confirm-dialog/
+│   ├── pipes/            ← Shared pipes
+│   ├── directives/       ← Shared directives
+│   └── services/         ← Shared services
+├── features/
+│   └── customer/
+│       ├── components/   ← Feature-specific components
+│       ├── pages/        ← Routed pages
+│       └── services/     ← Feature services
+```
+
+### PrimeNG usage
+```typescript
+// ✅ ĐÚNG — Dùng PrimeNG components trước khi tự viết
+// Table → p-table
+// Dialog → p-dialog
+// Form elements → p-inputText, p-dropdown, p-calendar
+// Toast → p-toast (qua MessageService)
+// Confirm → p-confirmDialog (qua ConfirmationService)
+
+// ❌ SAI — Tự viết component khi PrimeNG đã có
+// Custom table → Dùng p-table
+// Custom dropdown → Dùng p-dropdown
+// Custom date picker → Dùng p-calendar
+```
+
+---
+
+## 3. NO HARDCODED TEXT / I18N (RF03)
+
+### Quy tắc
+- KHÔNG hardcode text hiển thị trong template hoặc component
+- Tất cả text PHẢI qua i18n (ngx-translate hoặc Angular i18n)
+- Labels, messages, tooltips, placeholders → đều qua translate
+
+### Code examples
+```html
+<!-- ❌ SAI — Hardcoded text -->
+<button>Tạo mới</button>
+<label>Tên khách hàng:</label>
+<p-message severity="error" text="Không tìm thấy dữ liệu"></p-message>
+
+<!-- ✅ ĐÚNG — i18n -->
+<button>{{ 'button.create' | translate }}</button>
+<label>{{ 'customer.name' | translate }}:</label>
+<p-message severity="error" [text]="'message.notFound' | translate"></p-message>
+```
+
+```json
+// vi.json
+{
+  "button": {
+    "create": "Tạo mới",
+    "save": "Lưu",
+    "cancel": "Hủy",
+    "delete": "Xóa",
+    "search": "Tìm kiếm"
+  },
+  "customer": {
+    "name": "Tên khách hàng",
+    "phone": "Số điện thoại"
+  },
+  "message": {
+    "notFound": "Không tìm thấy dữ liệu",
+    "saveSuccess": "Lưu thành công",
+    "confirmDelete": "Bạn có chắc chắn muốn xóa?"
+  }
+}
+```
+
+### Ngoại lệ
+- Technical strings (CSS class names, HTML attributes)
+- Enum labels → nên qua i18n nhưng có thể hardcode trong các dict objects
+
+---
+
+## 4. ACCESSIBILITY / A11Y (RF04)
+
+### Quy tắc
+- Mọi `<img>` PHẢI có `alt` attribute
+- Mọi form field PHẢI có `<label>` hoặc `aria-label`
+- Mọi interactive element PHẢI có `tabindex` hợp lý
+- Color contrast ratio ≥ 4.5:1 cho text
+
+### Code examples
+```html
+<!-- ❌ SAI — Thiếu a11y -->
+<img src="logo.png">
+<input type="text" placeholder="Search">
+<div (click)="doSomething()">Click me</div>
+
+<!-- ✅ ĐÚNG — a11y đầy đủ -->
+<img src="logo.png" alt="Logo EVNICT">
+<label for="search">{{ 'label.search' | translate }}</label>
+<input type="text" id="search" [placeholder]="'placeholder.search' | translate" aria-label="Search">
+<button (click)="doSomething()" tabindex="0">
+  {{ 'button.action' | translate }}
+</button>
+```
+
+### Scan commands
+```bash
+grep -rn "<img " --include="*.html" src/ | grep -v "alt="
+grep -rn "<input " --include="*.html" src/ | grep -v "aria-label\|id=" 
+```
+
+---
+
+## 5. NO DIRECT DOM MANIPULATION (RF05)
+
+### Quy tắc
+- KHÔNG dùng `document.getElementById()`, `document.querySelector()`
+- KHÔNG dùng `jQuery` hoặc truy cập DOM trực tiếp
+- Dùng Angular bindings, `@ViewChild`, hoặc `Renderer2`
+- Exception: third-party library integration (VD: chart.js) → dùng `@ViewChild`
+
+### Code examples
+```typescript
+// ❌ SAI — Direct DOM manipulation
+ngAfterViewInit() {
+  document.getElementById('myInput').focus();
+  document.querySelector('.container').classList.add('active');
+  const el = document.getElementsByClassName('item');
+}
+
+// ✅ ĐÚNG — Angular way
+@ViewChild('myInput') myInput: ElementRef;
+
+ngAfterViewInit() {
+  this.myInput.nativeElement.focus();
+}
+
+// ✅ ĐÚNG — Renderer2
+constructor(private renderer: Renderer2) {}
+
+setActive(el: ElementRef) {
+  this.renderer.addClass(el.nativeElement, 'active');
+}
+
+// ✅ ĐÚNG — Template bindings
+// <div [class.active]="isActive"></div>
+// <input #myInput (keyup)="onKeyUp()">
+```
+
+### Scan commands
+```bash
+grep -rn "document\.getElementById\|document\.querySelector\|document\.getElement" --include="*.ts" src/
+grep -rn "jQuery\|\\$(" --include="*.ts" src/
+```
+
+---
+
+## 6. RESPONSIVE DESIGN (RF06)
+
+### Quy tắc
+- Tất cả pages PHẢI responsive cho: Desktop (≥1200px), Tablet (768-1199px), Mobile (≤767px)
+- Dùng PrimeNG Grid system (p-grid, p-col) hoặc CSS Grid/Flexbox
+- Test responsive trước khi commit
+- Text KHÔNG bị cắt, table PHẢI scrollable trên mobile
+
+### Code examples
+```html
+<!-- ✅ ĐÚNG — PrimeNG responsive grid -->
+<div class="grid">
+  <div class="col-12 md:col-6 lg:col-4">
+    <!-- Card 1 -->
+  </div>
+  <div class="col-12 md:col-6 lg:col-4">
+    <!-- Card 2 -->
+  </div>
+  <div class="col-12 md:col-12 lg:col-4">
+    <!-- Card 3 -->
+  </div>
+</div>
+
+<!-- ✅ Table responsive -->
+<div class="table-responsive">
+  <p-table [value]="data" [scrollable]="true" scrollHeight="400px"
+           [responsive]="true" responsiveLayout="scroll">
+    <!-- columns -->
+  </p-table>
+</div>
+```
+
+```scss
+// ✅ SCSS responsive
+.page-container {
+  padding: 1rem;
+  
+  @media (max-width: 768px) {
+    padding: 0.5rem;
+    
+    .action-buttons {
+      flex-direction: column;
+      gap: 0.5rem;
+    }
+  }
+}
+```
+
+---
+
+## 7. ANGULAR CONVENTIONS
+
+### File naming
+| Loại | Pattern | Ví dụ |
+|------|---------|-------|
+| Component | `{name}.component.ts` | `customer-list.component.ts` |
+| Service | `{name}.service.ts` | `customer.service.ts` |
+| Module | `{name}.module.ts` | `customer.module.ts` |
+| Pipe | `{name}.pipe.ts` | `date-format.pipe.ts` |
+| Directive | `{name}.directive.ts` | `auto-focus.directive.ts` |
+| Guard | `{name}.guard.ts` | `auth.guard.ts` |
+| Interceptor | `{name}.interceptor.ts` | `auth.interceptor.ts` |
+| Model/Interface | `{name}.model.ts` | `customer.model.ts` |
+
+### Component structure
+```typescript
+// ✅ ĐÚNG — Component tiêu chuẩn
+@Component({
+  selector: 'app-customer-list',
+  templateUrl: './customer-list.component.html',
+  styleUrls: ['./customer-list.component.scss']
+})
+export class CustomerListComponent implements OnInit, OnDestroy {
+  // 1. Decorators
+  @ViewChild('dt') table: Table;
+
+  // 2. Public properties (used in template)
+  customers: CustomerDTO[] = [];
+  loading = false;
+  totalRecords = 0;
+
+  // 3. Private properties
+  private destroy$ = new Subject<void>();
+
+  // 4. Constructor (DI)
+  constructor(
+    private customerService: CustomerService,
+    private messageService: MessageService
+  ) {}
+
+  // 5. Lifecycle hooks
+  ngOnInit(): void {
+    this.loadData();
+  }
+
+  ngOnDestroy(): void {
+    this.destroy$.next();
+    this.destroy$.complete();
+  }
+
+  // 6. Public methods (used in template)
+  loadData(): void { ... }
+  onCreate(): void { ... }
+
+  // 7. Private methods
+  private handleError(err: any): void { ... }
+}
+```
+
+### Service pattern
+```typescript
+// ✅ ĐÚNG — Service tiêu chuẩn
+@Injectable({ providedIn: 'root' })
+export class CustomerService {
+  private baseUrl = `${environment.apiUrl}/api/customers`;
+
+  constructor(private http: HttpClient) {}
+
+  search(keyword: string, page: number, size: number): Observable<ResponseData> {
+    const params = new HttpParams()
+      .set('keyword', keyword)
+      .set('page', page.toString())
+      .set('size', size.toString());
+    return this.http.get<ResponseData>(this.baseUrl, { params });
+  }
+
+  getById(id: number): Observable<ResponseData> {
+    return this.http.get<ResponseData>(`${this.baseUrl}/${id}`);
+  }
+
+  create(dto: CustomerDTO): Observable<ResponseData> {
+    return this.http.post<ResponseData>(this.baseUrl, dto);
+  }
+
+  update(id: number, dto: CustomerDTO): Observable<ResponseData> {
+    return this.http.put<ResponseData>(`${this.baseUrl}/${id}`, dto);
+  }
+
+  delete(id: number): Observable<ResponseData> {
+    return this.http.delete<ResponseData>(`${this.baseUrl}/${id}`);
+  }
+}
+```
+
+### RxJS — Memory leak prevention
+```typescript
+// ❌ SAI — Không unsubscribe → memory leak
+ngOnInit() {
+  this.service.getData().subscribe(data => this.data = data);
+}
+
+// ✅ ĐÚNG — takeUntil pattern
+private destroy$ = new Subject<void>();
+
+ngOnInit() {
+  this.service.getData()
+    .pipe(takeUntil(this.destroy$))
+    .subscribe(data => this.data = data);
+}
+
+ngOnDestroy() {
+  this.destroy$.next();
+  this.destroy$.complete();
+}
+
+// ✅ ĐÚNG — async pipe (tự unsubscribe)
+// component.ts
+data$ = this.service.getData();
+// template
+<div *ngIf="data$ | async as data">{{ data.name }}</div>
+```
+
+### Scan commands
+```bash
+# Tìm subscribe không unsubscribe
+grep -rn "\.subscribe(" --include="*.ts" src/ | grep -v "takeUntil\|async\|take(1)\|first()"
+# Tìm inline styles
+grep -rn "style=\"" --include="*.html" src/
+# Tìm document access
+grep -rn "document\." --include="*.ts" src/
+```

package/templates/content/rules/05-evnict-kit-project-conventions.md

@@ -0,0 +1,228 @@
+---
+trigger: always_on
+---
+# Project Conventions — EVNICT Standard
+**Activation Mode: Always On**
+**Source: QĐ-TTPM Phụ lục IV — Hướng dẫn thiết lập ngữ cảnh**
+
+> **⚠️ FILE NÀY CẦN ĐƯỢC KHỞI TẠO BỞI AI AGENT**
+> Chạy `/evnict-kit:init-rules` → Agent đọc codebase → tự động điền nội dung.
+> Các section bên dưới chứa placeholder — Agent sẽ thay thế bằng conventions thực tế của dự án.
+
+---
+
+## RP01 — NAMING CONVENTION
+
+> ⚠️ **CHƯA ĐƯỢC KHỞI TẠO** — Agent cần scan codebase để xác định naming conventions.
+
+### Khi khởi tạo, Agent sẽ điền:
+- Package/namespace naming pattern
+- Class naming pattern (Controller, Service, Repository, DTO, Entity)
+- Method naming pattern (CRUD, search, business operations)
+- Variable naming pattern (fields, locals, constants)
+- File naming pattern
+- Database table/column naming pattern
+- API path naming pattern
+
+### Format mẫu (Agent sẽ điền theo dự án thực tế):
+```
+Package:    com.evn.{project}.{module}
+Class:      {Module}{Type}.java (VD: CustomerService.java)
+Method:     camelCase, prefix: find/get/create/update/delete
+Variable:   camelCase, descriptive
+Constant:   UPPER_SNAKE_CASE
+Table:      UPPER_SNAKE_CASE (VD: CUSTOMER, DON_VI)
+Column:     UPPER_SNAKE_CASE (VD: CREATED_DATE, DON_VI_ID)
+API:        /api/{module}/{action} (VD: /api/customers/search)
+```
+
+---
+
+## RP02 — ARCHITECTURE PATTERN
+
+> ⚠️ **CHƯA ĐƯỢC KHỞI TẠO** — Agent cần scan codebase để xác định kiến trúc.
+
+### Khi khởi tạo, Agent sẽ điền:
+- Overall architecture (MVC, Clean Architecture, Hexagonal...)
+- Layer structure (Controller → Service → Repository)
+- Module organization (by feature, by layer, hybrid)
+- Dependency direction rules
+- Cross-cutting concerns (logging, auth, exception handling)
+
+### Format mẫu:
+```
+Architecture: Layered MVC
+Layers:
+  1. Controller — HTTP handling, input validation
+  2. Service — Business logic, transaction management
+  3. Repository — Data access (JOOQ/JPA)
+  4. DTO/Entity — Data transfer / persistence
+
+Module Structure:
+  src/main/java/com/evn/{project}/
+  ├── config/          ← Application configuration
+  ├── common/          ← Shared utilities, base classes
+  ├── security/        ← Auth, JWT, filters
+  └── {module}/        ← Feature modules
+      ├── controller/
+      ├── service/
+      ├── repository/
+      └── dto/
+```
+
+---
+
+## RP03 — CODING CONVENTION
+
+> ⚠️ **CHƯA ĐƯỢC KHỞI TẠO** — Agent cần scan codebase để xác định coding style.
+
+### Khi khởi tạo, Agent sẽ điền:
+- Indentation (tabs vs spaces, size)
+- Import ordering
+- Method ordering within class
+- Comment style
+- Exception handling pattern
+- Logging convention
+- Null handling (Optional, null checks, annotations)
+
+### Format mẫu:
+```
+Indentation: 4 spaces (Java), 2 spaces (TypeScript/HTML/SCSS)
+Max line length: 120 characters
+Import order: java.*, javax.*, org.*, com.*, static
+Method order: public → protected → private
+Logging: SLF4J with Lombok @Slf4j
+Null: @Nullable/@NonNull annotations, Optional for return types
+```
+
+---
+
+## RP04 — API CONVENTION
+
+> ⚠️ **CHƯA ĐƯỢC KHỞI TẠO** — Agent cần scan codebase để xác định API patterns.
+
+### Khi khởi tạo, Agent sẽ điền:
+- Base URL pattern
+- HTTP method usage (GET/POST/PUT/DELETE)
+- Request/Response format (ResponseData wrapper)
+- Pagination pattern
+- Error response format
+- Authentication header format
+- API versioning (if any)
+
+### Format mẫu:
+```
+Base URL:     /api/{module}
+Response:     ResponseData { status, message, data }
+Pagination:   ?page=0&size=20&sort=name
+Auth Header:  Authorization: Bearer {token}
+Error:        ResponseData { status: 1, message: "...", data: null }
+
+Endpoints:
+  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
+```
+
+---
+
+## RP05 — DATABASE CONVENTION
+
+> ⚠️ **CHƯA ĐƯỢC KHỞI TẠO** — Agent cần scan codebase để xác định DB patterns.
+
+### Khi khởi tạo, Agent sẽ điền:
+- Database type & version
+- Schema structure (single/multi schema)
+- Table naming convention
+- Column naming convention
+- Primary key pattern (sequence, UUID, identity)
+- Foreign key naming
+- Index naming
+- Audit columns (created_by, created_date, etc.)
+- Soft delete pattern (if used)
+
+### Format mẫu:
+```
+Database:     Oracle 19c
+Schemas:      EVNTMS (system), {PROJECT} (business)
+Table:        UPPER_SNAKE (VD: CUSTOMER, HD_DIEN)
+Column:       UPPER_SNAKE (VD: TEN_KH, MA_DON_VI)
+PK:           ID (NUMBER, sequence {TABLE}_SEQ)
+FK:           {TABLE}_{REF_TABLE}_FK
+Index:        IX_{TABLE}_{COLUMNS}
+Audit:        CREATED_BY, CREATED_DATE, UPDATED_BY, UPDATED_DATE
+Soft delete:  IS_DELETED (NUMBER(1)) hoặc STATUS = 'DELETED'
+```
+
+---
+
+## RP06 — COMPONENT CONVENTION (Frontend)
+
+> ⚠️ **CHƯA ĐƯỢC KHỞI TẠO** — Agent cần scan codebase để xác định component patterns.
+
+### Khi khởi tạo, Agent sẽ điền:
+- Component file structure
+- Shared vs feature-specific components
+- Naming convention (selector prefix, file names)
+- State management pattern
+- UI library usage (PrimeNG components)
+- Form handling pattern (Reactive Forms vs Template-driven)
+- Routing pattern
+
+### Format mẫu:
+```
+Selector prefix: app-
+File structure:  {name}.component.ts/html/scss
+Shared path:     src/app/shared/components/
+Feature path:    src/app/features/{module}/components/
+State:           Service + BehaviorSubject (no NgRx)
+UI Library:      PrimeNG 16+
+Forms:           Reactive Forms (FormBuilder)
+Routing:         Lazy-loaded feature modules
+```
+
+---
+
+## RP07 — INTEGRATION MAP
+
+> ⚠️ **CHƯA ĐƯỢC KHỞI TẠO** — Agent cần scan codebase để xác định integrations.
+
+### Khi khởi tạo, Agent sẽ điền:
+- External services integrated (SSO, MinIO, CMIS, etc.)
+- Internal service dependencies
+- Message queues / event systems
+- Caching strategy
+- File storage
+- Email/notification services
+
+### Format mẫu:
+```
+Authentication:  EVN SSO → JWT (RS256)
+File Storage:    MinIO (S3-compatible)
+Document:        CMIS (Content Management)
+Cache:           Redis (session) / Caffeine (local)
+Email:           SMTP server
+Notification:    WebSocket (SockJS + STOMP)
+CI/CD:           Azure DevOps Pipelines
+Container:       Docker + Kubernetes
+```
+
+---
+
+## HƯỚNG DẪN KHỞI TẠO
+
+Khi Agent nhận `/evnict-kit:init-rules`:
+
+1. **Scan codebase** — `tree -L 3`, đọc các file cốt lõi (pom.xml, package.json, config files)
+2. **Phân tích patterns** — Tìm patterns từ code hiện có
+3. **Điền từng section** — Thay thế "⚠️ CHƯA ĐƯỢC KHỞI TẠO" bằng nội dung thực tế
+4. **Thêm code examples** — Lấy từ code thực tế của dự án (KHÔNG code mẫu generic)
+5. **Validate** — Đảm bảo conventions phù hợp với code hiện có
+
+**SAU KHI khởi tạo:**
+- Xóa tất cả placeholder "⚠️ CHƯA ĐƯỢC KHỞI TẠO"
+- Đổi mỗi section header thành `✅ ĐÃ KHỞI TẠO — {date}`
+- Commit: `chore: initialize project conventions RP01-RP07`