evnict-kit 0.2.1

package/templates/content/skills/evnict-kit-coordinate/SKILL.md

@@ -0,0 +1,274 @@
+---
+name: evnict-kit-coordinate
+description: FE↔BE coordination protocol — handoff, API contract format, status sync. Đảm bảo 2 agent (BE, FE) phối hợp đúng khi cùng làm 1 feature.
+compatibility: All tech stacks
+---
+
+# evnict-kit-coordinate — FE↔BE Coordination
+
+## Khi nào dùng
+- Feature cần cả Backend và Frontend
+- BE agent xong API → FE agent cần biết để implement
+- Cần sync status giữa 2 project/agent
+
+## Input Parameters
+- `action` (bắt buộc): handoff | publish-contract | read-contract | update-status | check-status
+- `feature` (bắt buộc): Feature slug
+
+---
+
+## Workflow Steps
+
+### Action: HANDOFF — Bàn giao feature chi tiết
+Hành động đặc biệt được kích hoạt bởi lệnh `/evnict-kit:handoff`.
+
+> **CHI TIẾT:** Xem command `evnict-kit-handoff` để biết template handoff 5 sections đầy đủ.
+
+#### Bước 1: Rà soát và Publish Contract
+Chạy nội dung tương đương `PUBLISH-CONTRACT` nếu chưa chạy. Xác minh `contracts/{feature}-api.yaml` đã có đầy đủ.
+
+#### Bước 2: Append Entry vào Handoff Log (5 SECTIONS)
+**KHÔNG** tạo file riêng cho mỗi feature. Thay vào đó, APPEND entry vào `.evnict/handoff/handoff.md`.
+
+Nếu file chưa tồn tại → tạo mới với header:
+```markdown
+# Agent Handoff Log
+> File này dùng để trao đổi giữa BE Agent và FE Agent.
+> Mỗi issue ghi theo format bên dưới.
+
+---
+```
+
+Mỗi entry PHẢI có 5 sections:
+
+| Section | Nội dung |
+|---------|----------|
+| 1. Tổng quan | Tasks hoàn thành, files, tests, commits |
+| 2. API Contract | Endpoints, DTO→TypeScript interface, Validation rules sync, Request/Response format |
+| 3. Yêu cầu FE | FE tasks, UI requirements, Dropdowns cần load |
+| 4. Lưu ý | ResponseData wrapper, Auth, Date format, Audit fields |
+| 5. Hướng dẫn | Step-by-step cho FE Agent |
+
+Entry format:
+```markdown
+### [{YYYY-MM-DD}] BE→FE: {Feature Name} — Handoff
+- **Trạng thái:** 🔴 Chờ xử lý
+- **Mô tả:** {tóm tắt}
+- **API liên quan:** {endpoints}
+- **Kết quả xử lý:** _(FE Agent điền sau khi implement xong)_
+```
+
+#### Bước 3: DTO → TypeScript Interface
+Agent PHẢI đọc Java DTO file và generate TypeScript interface:
+```typescript
+// Auto-generated từ {EntityName}DTO.java
+export interface {EntityName} {
+  ID: number;
+  FIELD_NAME: string;           // @JsonProperty("FIELD_NAME")
+  NULLABLE_FIELD?: string;      // nullable → optional (?)
+  // ... map tất cả fields
+}
+```
+
+**Quy tắc mapping:**
+| Java Type | TypeScript Type | Note |
+|-----------|----------------|------|
+| Long, Integer, int | number | |
+| String | string | |
+| Date, LocalDate | string | format: yyyy-MM-dd |
+| BigDecimal | number | |
+| Boolean | boolean | |
+| Nullable field | optional (?) | thêm `?` |
+
+#### Bước 4: Validation Rules Sync Table
+Trích validation từ BE code → tạo sync table:
+```markdown
+| Field | Rule | Error Message (tiếng Việt) |
+|-------|------|---------------------------|
+| {FIELD} | Required | "Vui lòng nhập {field}" |
+| {FIELD} | MaxLength(N) | "Không quá N ký tự" |
+```
+FE PHẢI implement cùng validation rules để đảm bảo UX nhất quán.
+
+#### Bước 5: Update BE Status
+Cập nhật `.evnict/handoff/be-status.md`:
+```markdown
+# BE Status
+status: done
+feature: {feature-name}
+completed_tasks: ["task-01", "task-02", ...]
+api_contract: handoff/contracts/{feature}-api.yaml
+handoff_entry: handoff/handoff.md (entry [{date}] BE→FE: {feature})
+last_updated: {timestamp}
+```
+
+#### Khi Agent bên kia xử lý xong
+Update status entry trong `handoff.md`:
+- Đổi `🔴 Chờ xử lý` → `🟢 Đã xử lý`
+- Điền **Kết quả xử lý:** {mô tả kết quả}
+
+---
+
+### Action: PUBLISH-CONTRACT — BE agent ghi API contract
+
+#### Bước 1: Tạo contract file
+Sau khi BE hoàn thành API, tạo file:
+`.evnict/handoff/contracts/{feature}-api.yaml`
+
+```yaml
+feature: {feature-name}
+generated: {YYYY-MM-DD HH:mm}
+status: ready
+base_url: /api/{module}
+
+endpoints:
+  - method: GET
+    path: /api/{module}
+    description: Danh sách (phân trang)
+    auth: required
+    params:
+      keyword: { type: string, required: false }
+      page: { type: integer, default: 0 }
+      size: { type: integer, default: 20 }
+    response:
+      200:
+        schema: ResponseData
+        data:
+          content: [{ id: number, name: string, ... }]
+          totalElements: number
+          totalPages: number
+
+  - method: POST
+    path: /api/{module}
+    description: Tạo mới
+    auth: required
+    body:
+      name: { type: string, required: true, maxLength: 200 }
+      phone: { type: string, pattern: "^0[0-9]{9}$" }
+    response:
+      200:
+        schema: ResponseData
+        data: { id: number, name: string, ... }
+      400:
+        schema: ResponseData
+        error: { message: string }
+```
+
+#### Bước 2: Update BE status
+Cập nhật `.evnict/handoff/be-status.md`:
+```markdown
+# BE Status
+status: done
+feature: {feature-name}
+completed_tasks: ["task-01", "task-02", "task-03", "task-04"]
+api_contract: handoff/contracts/{feature}-api.yaml
+last_updated: {timestamp}
+notes: {any important notes for FE agent}
+```
+
+---
+
+### Action: READ-CONTRACT — FE agent đọc contract
+
+#### Bước 1: Check BE status
+```bash
+cat .evnict/handoff/be-status.md
+# → status: done? → Đọc contract
+# → status: in-progress? → CHƯA sẵn sàng, chờ
+```
+
+#### Bước 2: Đọc contract
+```bash
+cat .evnict/handoff/contracts/{feature}-api.yaml
+```
+
+#### Bước 3: Generate FE service từ contract
+Dựa vào contract → tạo Angular service:
+```typescript
+// Auto-generated from contract
+@Injectable({ providedIn: 'root' })
+export class {Module}Service {
+  private baseUrl = `${environment.apiUrl}/api/{module}`;
+
+  constructor(private http: HttpClient) {}
+
+  // Từ GET endpoint trong contract
+  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 });
+  }
+
+  // Từ POST endpoint trong contract
+  create(dto: {Module}DTO): Observable<ResponseData> {
+    return this.http.post<ResponseData>(this.baseUrl, dto);
+  }
+}
+```
+
+---
+
+### Action: UPDATE-STATUS — Cập nhật status
+
+#### BE Status format
+```markdown
+# BE Status
+status: idle | in-progress | done | blocked
+feature: {feature-name}
+current_task: task-{N}
+completed_tasks: ["task-01", "task-02"]
+blocked_reason: {reason if blocked}
+last_updated: {timestamp}
+```
+
+#### FE Status format
+```markdown
+# FE Status
+status: idle | waiting-be | in-progress | done | blocked
+feature: {feature-name}
+current_task: task-{N}
+completed_tasks: ["task-05", "task-06"]
+waiting_for: {what FE is waiting for}
+last_updated: {timestamp}
+```
+
+---
+
+### Action: CHECK-STATUS — Kiểm tra status
+
+Đọc cả 2 file status → tóm tắt:
+```markdown
+## 📊 Feature: {feature-name}
+
+### Backend
+- Status: {status}
+- Progress: {completed}/{total} tasks
+- API Contract: {ready/not-ready}
+
+### Frontend
+- Status: {status}
+- Progress: {completed}/{total} tasks
+- Waiting for: {if any}
+
+### Next Action
+- {Recommendation based on status}
+```
+
+---
+
+## Error Handling
+
+### DỪNG khi:
+- FE agent cố implement mà BE chưa done → Phải chờ hoặc dùng mock
+- Contract file không tồn tại → BE chưa publish
+- Contract format lỗi → Nhắc fix trước
+
+---
+
+## Tiêu chí hoàn thành
+- [ ] Contract file tạo đúng format YAML
+- [ ] Status files cập nhật đúng
+- [ ] FE agent đọc được contract
+- [ ] Status sync giữa BE ↔ FE chính xác

package/templates/content/skills/evnict-kit-create-api/SKILL.md

@@ -0,0 +1,281 @@
+---
+name: evnict-kit-create-api
+description: Tạo API endpoint chuẩn EVNICT — DTO→Controller→Service→Repository→Test. Code examples Spring Boot + JOOQ + Oracle.
+compatibility: Java Spring Boot, JOOQ, Oracle
+---
+
+# evnict-kit-create-api — Tạo API Endpoint
+
+## Khi nào dùng
+- Tạo API endpoint mới (CRUD hoặc custom)
+- Thêm endpoint vào module có sẵn
+- Tạo module mới với đầy đủ layers
+
+## Input Parameters
+- `module` (bắt buộc): Tên module (VD: customer, order, don-vi)
+- `action` (bắt buộc): Loại endpoint (list, get, create, update, delete, search, custom)
+- `description` (bắt buộc): Mô tả API
+- `fields` (optional): Danh sách fields cho DTO
+
+---
+
+## Workflow Steps
+
+### Bước 1: Xác định cấu trúc
+Đọc conventions từ `.agent/rules/03-evnict-kit-backend-conventions.md` và `05-evnict-kit-project-conventions.md`.
+
+Xác định:
+- Package path: `com.evn.{project}.{module}`
+- Existing module? → Thêm vào module có sẵn
+- New module? → Tạo đầy đủ package structure
+
+### Bước 2: Tạo DTO
+```java
+// File: src/main/java/com/evn/{project}/{module}/dto/{Module}DTO.java
+public class CustomerDTO {
+    private Long id;
+
+    @NotBlank(message = "Tên không được trống")
+    @Size(max = 200, message = "Tên không quá 200 ký tự")
+    private String name;
+
+    @Pattern(regexp = "^0[0-9]{9}$", message = "Số điện thoại không hợp lệ")
+    private String phone;
+
+    @NotNull(message = "Mã đơn vị bắt buộc")
+    private Long donViId;
+
+    // Getters, Setters (hoặc @Data nếu dùng Lombok)
+}
+```
+
+**Quy tắc DTO:**
+- KHÔNG expose internal IDs, password hashes, audit fields (trừ khi cần hiển thị)
+- Mỗi endpoint CÓ THỂ có DTO riêng (CreateDTO, UpdateDTO, ResponseDTO)
+- Validation annotations trên DTO, KHÔNG trên Entity
+
+### Bước 3: Tạo Repository
+```java
+// File: src/main/java/com/evn/{project}/{module}/repository/{Module}Repository.java
+@Repository
+@RequiredArgsConstructor
+public class CustomerRepository {
+    private final DSLContext dsl;
+
+    // LIST — paginated
+    public Page<CustomerDTO> search(String keyword, int page, int size, String sortBy) {
+        Condition condition = DSL.trueCondition();
+        if (StringUtils.isNotBlank(keyword)) {
+            condition = condition.and(
+                CUSTOMER.NAME.containsIgnoreCase(keyword)
+                .or(CUSTOMER.PHONE.containsIgnoreCase(keyword))
+            );
+        }
+
+        int total = dsl.fetchCount(CUSTOMER, condition);
+        List<CustomerDTO> data = dsl.selectFrom(CUSTOMER)
+            .where(condition)
+            .orderBy(getSortField(sortBy))
+            .offset(page * size)
+            .limit(size)
+            .fetchInto(CustomerDTO.class);
+
+        return new Page<>(data, total, page, size);
+    }
+
+    // GET by ID
+    public CustomerDTO findById(Long id) {
+        return dsl.selectFrom(CUSTOMER)
+            .where(CUSTOMER.ID.eq(id))
+            .fetchOneInto(CustomerDTO.class);
+    }
+
+    // CREATE
+    public CustomerDTO create(CustomerDTO dto) {
+        CustomerRecord record = dsl.newRecord(CUSTOMER);
+        record.setName(dto.getName());
+        record.setPhone(dto.getPhone());
+        record.setDonViId(dto.getDonViId());
+        record.setCreatedDate(LocalDateTime.now());
+        record.store();
+        return record.into(CustomerDTO.class);
+    }
+
+    // UPDATE
+    public int update(Long id, CustomerDTO dto) {
+        return dsl.update(CUSTOMER)
+            .set(CUSTOMER.NAME, dto.getName())
+            .set(CUSTOMER.PHONE, dto.getPhone())
+            .set(CUSTOMER.UPDATED_DATE, LocalDateTime.now())
+            .where(CUSTOMER.ID.eq(id))
+            .execute();
+    }
+
+    // DELETE (soft delete)
+    public int delete(Long id) {
+        return dsl.update(CUSTOMER)
+            .set(CUSTOMER.IS_DELETED, 1)
+            .where(CUSTOMER.ID.eq(id))
+            .execute();
+    }
+
+    // Sort field whitelist
+    private SortField<?> getSortField(String sortBy) {
+        return switch (sortBy) {
+            case "name" -> CUSTOMER.NAME.asc();
+            case "createdDate" -> CUSTOMER.CREATED_DATE.desc();
+            default -> CUSTOMER.ID.desc();
+        };
+    }
+}
+```
+
+### Bước 4: Tạo Service
+```java
+// File: src/main/java/com/evn/{project}/{module}/service/{Module}Service.java
+@Service
+@RequiredArgsConstructor
+@Slf4j
+public class CustomerService {
+    private final CustomerRepository customerRepository;
+
+    public Page<CustomerDTO> search(String keyword, int page, int size, String sortBy) {
+        return customerRepository.search(keyword, page, size, sortBy);
+    }
+
+    public CustomerDTO getById(Long id) {
+        CustomerDTO dto = customerRepository.findById(id);
+        if (dto == null) {
+            throw new BusinessException("Không tìm thấy khách hàng với ID: " + id);
+        }
+        return dto;
+    }
+
+    @Transactional
+    public CustomerDTO create(CustomerDTO dto) {
+        // Business validation
+        validateBusinessRules(dto);
+        return customerRepository.create(dto);
+    }
+
+    @Transactional
+    public void update(Long id, CustomerDTO dto) {
+        // Check exists
+        getById(id);
+        // Business validation
+        validateBusinessRules(dto);
+        customerRepository.update(id, dto);
+    }
+
+    @Transactional
+    public void delete(Long id) {
+        // Check exists
+        getById(id);
+        customerRepository.delete(id);
+    }
+
+    private void validateBusinessRules(CustomerDTO dto) {
+        // Add business-specific validations here
+    }
+}
+```
+
+### Bước 5: Tạo Controller
+```java
+// File: src/main/java/com/evn/{project}/{module}/controller/{Module}Controller.java
+@RestController
+@RequestMapping("/api/{module}")
+@RequiredArgsConstructor
+@Slf4j
+public class CustomerController {
+
+    private final CustomerService customerService;
+
+    @GetMapping
+    public ResponseEntity<ResponseData> search(
+            @RequestParam(defaultValue = "") String keyword,
+            @RequestParam(defaultValue = "0") @Min(0) int page,
+            @RequestParam(defaultValue = "20") @Min(1) @Max(100) int size,
+            @RequestParam(defaultValue = "id") String sortBy) {
+        return ResponseEntity.ok(ResponseData.ok(
+            customerService.search(keyword, page, size, sortBy)
+        ));
+    }
+
+    @GetMapping("/{id}")
+    public ResponseEntity<ResponseData> getById(@PathVariable Long id) {
+        return ResponseEntity.ok(ResponseData.ok(customerService.getById(id)));
+    }
+
+    @PostMapping
+    public ResponseEntity<ResponseData> create(@Valid @RequestBody CustomerDTO dto) {
+        return ResponseEntity.ok(ResponseData.ok(customerService.create(dto)));
+    }
+
+    @PutMapping("/{id}")
+    public ResponseEntity<ResponseData> update(
+            @PathVariable Long id,
+            @Valid @RequestBody CustomerDTO dto) {
+        customerService.update(id, dto);
+        return ResponseEntity.ok(ResponseData.ok("Cập nhật thành công"));
+    }
+
+    @DeleteMapping("/{id}")
+    public ResponseEntity<ResponseData> delete(@PathVariable Long id) {
+        customerService.delete(id);
+        return ResponseEntity.ok(ResponseData.ok("Xóa thành công"));
+    }
+}
+```
+
+### Bước 6: Viết Tests (TDD)
+Dùng skill `evnict-kit-tdd` → viết test cho:
+1. Service layer: business logic, edge cases, validation
+2. Controller layer: request/response, validation errors
+3. Repository layer: query correctness (nếu có DB test)
+
+### Bước 7: Verify
+```bash
+./mvnw test                    # All tests pass
+./mvnw spotless:check          # Lint
+./mvnw compile                 # Build
+```
+
+### Bước 8: Security check
+- [ ] Endpoint có authentication filter?
+- [ ] Roles/permissions đã khai báo?
+- [ ] Input validation đầy đủ?
+- [ ] Không expose sensitive fields trong DTO?
+- [ ] SQL injection safe? (JOOQ type-safe)
+
+---
+
+## File Checklist (cho CRUD endpoint mới)
+- [ ] `{Module}DTO.java` — với validation annotations
+- [ ] `{Module}Repository.java` — JOOQ queries
+- [ ] `{Module}Service.java` — business logic + @Transactional
+- [ ] `{Module}Controller.java` — REST endpoints + @Valid
+- [ ] `{Module}ServiceTest.java` — unit tests
+- [ ] `{Module}ControllerTest.java` — MockMvc tests
+- [ ] Security config updated (nếu cần whitelist)
+- [ ] Migration script (nếu table mới)
+
+---
+
+## Error Handling
+
+### DỪNG khi:
+- Table chưa tồn tại trong DB → Tạo migration trước (dùng skill `evnict-kit-database-migration`)
+- Module structure không rõ → Đọc conventions hoặc hỏi user
+- Conflict với endpoint hiện có → Báo user
+
+---
+
+## Tiêu chí hoàn thành
+- [ ] DTO tạo đúng với validation
+- [ ] Repository dùng JOOQ type-safe
+- [ ] Service có business logic + @Transactional
+- [ ] Controller return ResponseData
+- [ ] Tests viết và PASS
+- [ ] Security check PASS
+- [ ] Build + lint PASS