Tiêu chuẩn Kỹ thuật

Tài liệu này định nghĩa "Luật của vùng đất" (Law of the Land) cho nền tảng VENI-AI. Việc tuân thủ các tiêu chuẩn này đảm bảo tính nhất quán, bảo mật và khả năng bảo trì trên toàn bộ Shell và tất cả các ứng dụng Satellite.

---

1. Quy tắc Đặt tên

Tính nhất quán trên toàn bộ stack cho phép khám phá tự động và mã nguồn sạch hơn.

Tầng	Quy tắc	Ví dụ
Bảng Cơ sở dữ liệu	snake_case (số nhiều)	organization_members
Cột Cơ sở dữ liệu	snake_case	created_at, org_id
Endpoint API	kebab-case	/api/v1/leave-requests
JSON Keys	camelCase	{ "userId": "..." }
TypeScript Classes	PascalCase	AuthService, UserController
TypeScript Types	T + PascalCase	TUserProfile
UI Components	PascalCase	DataTable, UserMenu
UI Hooks	use + PascalCase	useAuth, useLocalStorage

---

2. Git Flow & PR

Chúng tôi tuân theo mô hình Trunk-Based Development nghiêm ngặt với các nhánh tính năng ngắn hạn.

Đặt tên Nhánh

• feat/feature-name — Tính năng mới.
• fix/issue-description — Sửa lỗi.
• refactor/area-name — Dọn dẹp mã nguồn mà không thay đổi hành vi.
• docs/topic-name — Chỉ cập nhật tài liệu.

Commit Messages

Chúng tôi sử dụng tiêu chuẩn Conventional Commits:

• feat: add Google OAuth provider
• fix(ui): resolve white screen on mobile safari
• chore: update dependencies

---

3. Quy tắc Vàng về Bảo mật

Mỗi lập trình viên đều là một kỹ sư bảo mật tại VENI-AI.

1. Không lưu trữ Secret: Không bao giờ commit các tệp .env hoặc mã hóa cứng (hardcode) các khóa. Sử dụng hệ thống quản lý secret của Shell.
2. Xác thực, Không Tin tưởng: Luôn xác thực chữ ký RSA của JWT từ Shell trong Satellite API của bạn.
3. Cách ly Tổ chức (Tenant Isolation): Mọi truy vấn phải bao gồm mệnh đề where(eq(table.organizationId, user.orgId)) trừ khi đó là tài nguyên toàn cầu.
4. Xác thực Zod: Mọi đầu vào API và biến môi trường phải được xác thực bằng Zod.
5. Ghi nhật ký mọi thứ: Sử dụng AuditService để ghi lại các hành động phá hủy (Xóa, Cập nhật, Thay đổi quyền).

---

4. Pattern Thiết kế API (REST)

• Envelope: Tất cả các phản hồi phải sử dụng phong bì (envelope) tiêu chuẩn:

  {
    "code": "RS_200",
    "data": { ... },
    "messageError": null
  }

• Stateless: API phải duy trì trạng thái không lưu giữ (stateless). Sử dụng Redis cho dữ liệu phiên (session), không bao giờ dùng bộ nhớ trong.
• Idempotency: Đảm bảo rằng các lệnh gọi PUT hoặc DELETE lặp lại sẽ cho ra cùng một trạng thái.

---

5. Pattern Thiết kế UI

• Component Nguyên tử: Sử dụng các component dùng chung trong @shell/ui để đảm bảo tính nhất quán (Buttons, Inputs, Modals).
• Xử lý Lỗi mềm mại: Sử dụng các component <ErrorState /> và <Loading /> cho tất cả các thao tác bất đồng bộ.
• Mobile First: Tất cả giao diện Satellite phải phản hồi tốt (responsive) và hoạt động được bên trong menu di động của Shell.

Thực thi

Các tiêu chuẩn được thực thi thông qua ESLint, Prettier, và các bước kiểm tra (linting) trong CI/CD. Mã nguồn vi phạm các tiêu chuẩn này sẽ bị từ chối trong quá trình review PR.