Migrate

2026-05-23 18:37:02 +07:00
parent f15d91ee29
commit 76d75c753b
3993 changed files with 403 additions and 0 deletions
--- a/microservices/.agent/skills/comment-code/SKILL.md
+++ b/microservices/.agent/skills/comment-code/SKILL.md
@@ -0,0 +1,284 @@
+---
+name: comment-code
+description: Bilingual code comments in Vietnamese and English. Use for documenting functions, classes, or adding EN/VI documentation.
+metadata:
+  author: Velik Ho
+  version: "1.0"
+---
+
+# Bilingual Code Comments / Chú Thích Code Song Ngữ
+
+Add comprehensive code comments in both Vietnamese and English to improve code readability for international and Vietnamese teams.
+
+## When to Use This Skill / Khi Nào Sử Dụng
+
+Use this skill when:
+- Adding comments to new code / Thêm chú thích cho code mới
+- Documenting existing code / Viết tài liệu cho code hiện có
+- Creating JSDoc/TSDoc documentation / Tạo JSDoc/TSDoc
+- Writing function/class descriptions / Viết mô tả hàm/lớp
+- Explaining complex logic / Giải thích logic phức tạp
+- Adding inline comments / Thêm chú thích inline
+
+## Core Concepts / Khái Niệm Cốt Lõi
+
+### Comment Format Rules / Quy Tắc Định Dạng
+
+1. **EN first, then VI**: Always put English before Vietnamese
+2. **Keep together**: Place bilingual comments on adjacent lines
+3. **Near code**: Comments should be close to what they describe
+4. **JSDoc for exports**: Use JSDoc format for public APIs
+
+### Documentation Priority / Độ Ưu Tiên
+
+| Priority | What to Document |
+|----------|------------------|
+| **High** | Public APIs, complex algorithms, security-critical code |
+| **Medium** | Helper functions, data transformations, integrations |
+| **Low** | Simple getters/setters, self-explanatory code |
+
+## Key Patterns / Mẫu Chính
+
+### Single-line Comments / Chú Thích Một Dòng
+
+```typescript
+// EN: Initialize database connection
+// VI: Khởi tạo kết nối database
+const db = await createConnection();
+```
+
+### Function Documentation / Tài Liệu Hàm
+
+```typescript
+/**
+ * EN: Calculates the total price including tax and discount
+ * VI: Tính tổng giá bao gồm thuế và giảm giá
+ * 
+ * @param basePrice - Original price / Giá gốc
+ * @param taxRate - Tax rate (0-1) / Tỷ lệ thuế (0-1)
+ * @param discount - Discount amount / Số tiền giảm giá
+ * @returns Final price / Giá cuối cùng
+ */
+function calculateTotal(
+  basePrice: number,
+  taxRate: number,
+  discount: number
+): number {
+  // EN: Apply discount first
+  // VI: Áp dụng giảm giá trước
+  const discountedPrice = basePrice - discount;
+  
+  // EN: Then calculate tax
+  // VI: Sau đó tính thuế
+  return discountedPrice * (1 + taxRate);
+}
+```
+
+### Class Documentation / Tài Liệu Lớp
+
+```typescript
+/**
+ * EN: Handles user authentication and authorization
+ * VI: Xử lý xác thực và phân quyền người dùng
+ */
+export class AuthService {
+  /**
+   * EN: JWT secret key from environment
+   * VI: Khóa bí mật JWT từ biến môi trường
+   */
+  private readonly jwtSecret: string;
+
+  /**
+   * EN: Verify JWT token and return user payload
+   * VI: Xác minh JWT token và trả về thông tin người dùng
+   * 
+   * @param token - JWT token to verify / JWT token cần xác minh
+   * @returns User payload / Thông tin người dùng
+   * @throws TokenExpiredError if token expired / Lỗi token hết hạn
+   */
+  async verifyToken(token: string): Promise<UserPayload> {
+    // Implementation
+  }
+}
+```
+
+### Interface/Type Documentation / Tài Liệu Interface/Type
+
+```typescript
+/**
+ * EN: User data transfer object
+ * VI: Đối tượng truyền dữ liệu người dùng
+ */
+interface UserDto {
+  /** EN: Unique user identifier / VI: Mã định danh duy nhất */
+  id: string;
+  
+  /** EN: User email address / VI: Địa chỉ email người dùng */
+  email: string;
+  
+  /** EN: User role for authorization / VI: Vai trò để phân quyền */
+  role: 'admin' | 'user' | 'guest';
+}
+```
+
+### React Components
+
+```typescript
+/**
+ * EN: User profile card component
+ * VI: Component thẻ hồ sơ người dùng
+ * 
+ * @param user - User data to display / Dữ liệu người dùng
+ * @param onEdit - Callback when edit clicked / Callback khi nhấn chỉnh sửa
+ */
+export function UserCard({ user, onEdit }: UserCardProps) {
+  // EN: Local state for loading status
+  // VI: State cục bộ cho trạng thái loading
+  const [isLoading, setIsLoading] = useState(false);
+
+  return (
+    <div className="user-card">
+      {/* EN: Display user avatar / VI: Hiển thị avatar */}
+      <img src={user.avatar} alt={user.name} />
+    </div>
+  );
+}
+```
+
+### Prisma Schema
+
+```prisma
+/// EN: User model for authentication and profile
+/// VI: Model người dùng cho xác thực và hồ sơ
+model User {
+  /// EN: Unique identifier / VI: Mã định danh duy nhất
+  id        String   @id @default(cuid())
+  
+  /// EN: User email (unique) / VI: Email người dùng (duy nhất)
+  email     String   @unique
+  
+  /// EN: Account creation timestamp / VI: Thời gian tạo tài khoản
+  createdAt DateTime @default(now())
+
+  @@map("users")
+}
+```
+
+### Special Comments / Chú Thích Đặc Biệt
+
+```typescript
+// TODO EN: Implement caching for better performance
+// TODO VI: Triển khai caching để cải thiện hiệu suất
+
+// FIXME EN: This causes memory leak, needs refactoring
+// FIXME VI: Đoạn này gây rò rỉ bộ nhớ, cần refactor
+
+// WARNING EN: Do not modify without updating database schema
+// WARNING VI: Không sửa đổi mà không cập nhật schema database
+```
+
+## Common Mistakes / Lỗi Thường Gặp
+
+### 1. Stating the Obvious / Nói Điều Hiển Nhiên
+
+```typescript
+// ❌ BAD: States the obvious
+// EN: Set x to 5
+// VI: Gán x bằng 5
+const x = 5;
+
+// ✅ GOOD: Explains why
+// EN: Default timeout in seconds for API calls
+// VI: Timeout mặc định (giây) cho các API call
+const x = 5;
+```
+
+### 2. Missing Translation / Thiếu Bản Dịch
+
+```typescript
+// ❌ BAD: Missing Vietnamese
+// EN: Calculate discount
+const discount = price * 0.1;
+
+// ✅ GOOD: Both languages
+// EN: Calculate 10% discount for members
+// VI: Tính giảm giá 10% cho thành viên
+const discount = price * 0.1;
+```
+
+### 3. Outdated Comments / Chú Thích Lỗi Thời
+
+```typescript
+// ❌ BAD: Comment says email, code uses phone
+// EN: Validate email format
+// VI: Xác thực định dạng email
+validatePhone(phone);
+
+// ✅ GOOD: Keep comments in sync with code
+// EN: Validate phone number format
+// VI: Xác thực định dạng số điện thoại
+validatePhone(phone);
+```
+
+### 4. No JSDoc for Public APIs
+
+```typescript
+// ❌ BAD: Exported function without JSDoc
+export function processOrder(order: Order) { ... }
+
+// ✅ GOOD: Full JSDoc for exported functions
+/**
+ * EN: Process order and update inventory
+ * VI: Xử lý đơn hàng và cập nhật kho
+ * @param order - Order to process / Đơn hàng cần xử lý
+ * @returns ProcessingResult / Kết quả xử lý
+ */
+export function processOrder(order: Order): ProcessingResult { ... }
+```
+
+## Quick Reference / Tham Chiếu Nhanh
+
+### Function Comment Template
+
+```typescript
+/**
+ * EN: [Brief description in English]
+ * VI: [Mô tả ngắn gọn bằng tiếng Việt]
+ * 
+ * @param paramName - EN description / VI mô tả
+ * @returns EN description / VI mô tả
+ * @throws ErrorType EN when / VI khi nào
+ */
+```
+
+### Inline Comment Template
+
+```typescript
+// EN: [English explanation]
+// VI: [Giải thích tiếng Việt]
+```
+
+### JSX Comment Template
+
+```tsx
+{/* EN: [Description] / VI: [Mô tả] */}
+```
+
+### Comment Prefixes
+
+| Prefix | Usage |
+|--------|-------|
+| `// EN:` + `// VI:` | Standard bilingual inline |
+| `/** */` | JSDoc for functions/classes |
+| `///` | Prisma schema comments |
+| `{/* */}` | JSX/TSX comments |
+| `// TODO` | Future improvements |
+| `// FIXME` | Known issues to fix |
+| `// WARNING` | Critical cautions |
+
+## Resources / Tài Nguyên
+
+- [Project Rules](../project-rules/SKILL.md) - Code organization standards
+- [Documentation](../documentation/SKILL.md) - Documentation patterns
+- [API Design](../api-design/SKILL.md) - API documentation standards
+- [Skill Authoring](../skill-authoring/SKILL.md) - How to write skills