​

Quy ước chung

​

Quy ước đặt tên

​

Git Workflow

​

Branch Strategy — GitHub Flow

main          # Production (protected, cần PR + 1 approval + CI pass)
staging       # Pre-production (auto-deploy khi push)
feat/*        # 1 User Story = 1 branch = 1 PR vào staging
fix/*         # Bug fixes → PR vào staging
hotfix/*      # Sửa khẩn cấp production (từ main, merge lại main)
chore/*       # Deps, config, refactor (không thay đổi business logic)

​

Đặt tên branch

feat/F01-01-generate-site
feat/F08-03-bulk-create-products
fix/F01-builder-crash
hotfix/F13-payment-timeout

​

Yêu cầu PR

• Title theo Conventional Commits
• Description điền đầy đủ theo PR template
• Ít nhất 1 approval từ team member
• Tất cả CI checks pass
• Không còn review comments chưa giải quyết

​

Commit Convention

feat(auth): add Google OAuth login
fix(api): handle null response from payment gateway
chore(deps): upgrade Next.js to 14.2
docs(readme): update local setup instructions
test(user): add unit tests for user service
refactor(db): normalize user address fields
perf(query): add index on orders.created_at
ci(actions): add staging deploy workflow

​

Types

​

Quy tắc

• Tối đa 72 ký tự trên dòng subject
• Dùng thì mệnh lệnh: “add”, “fix”, “update” (không phải “added”, “fixes”)
• Tham chiếu ticket: feat(auth): add Google OAuth login (PROJ-123)

​

API Design

​

RESTful Endpoints

GET    /api/v1/resources          # Lấy danh sách
POST   /api/v1/resources          # Tạo mới
GET    /api/v1/resources/:id      # Lấy chi tiết
PATCH  /api/v1/resources/:id      # Cập nhật một phần
DELETE /api/v1/resources/:id      # Xóa

​

Response Format (bắt buộc)

{
  "data": {},
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 100
  },
  "error": null
}

​

HTTP Status Codes

​

Pagination

GET /api/v1/products?page=1&limit=20

Response meta:
{
  "page": 1,
  "limit": 20,
  "total": 150,
  "totalPages": 8
}

​

Coding Standards

​

TypeScript / JavaScript

• Dùng const mặc định, let chỉ khi cần gán lại
• Ưu tiên async/await hơn .then() chains
• Luôn xử lý lỗi rõ ràng — không silent catch
• Dùng named exports (trừ pages/layouts)
• Co-locate types với nơi sử dụng, chỉ chuyển sang types/ khi dùng chung

​

Ví dụ

// Named export, strict types
export const getUserById = async (id: string): Promise<User | null> => {
  try {
    const user = await prisma.user.findUnique({ where: { id } });
    return user;
  } catch (error) {
    logger.error('Failed to get user', { id, error });
    throw new NotFoundException(`User ${id} not found`);
  }
};

// Default export, any type, silent catch
export default function getUser(id: any) {
  return prisma.user.findUnique({ where: { id } })
    .then(u => u)
    .catch(() => null); // Silent catch!
}

​

Môi trường

​

Security Checklist

• User input đã validate và sanitize
• Kiểm tra authorization (không chỉ authentication)
• Không có sensitive data trong logs
• SQL injection được bảo vệ (dùng ORM/parameterized queries)
• CORS cấu hình đúng cho production

​

Safety Conventions — Debug & Production Modes

/guard               # Safe debug mode
/freeze --snapshot   # Backup state
/careful --confirm   # Confirmation before delete

• /guard: Cần inspect production state mà không down service
• /freeze: Trước feature flag changes, deploy
• /careful: Before migrations, bulk deletes, major refactors