Quy trình Git

Mô hình Nhánh: GitLab Flow

main                    ← sẵn sàng production, được bảo vệ
  └── develop           ← nhánh phát triển chính
        ├── feature/*   ← tính năng mới
        ├── bugfix/*    ← sửa lỗi
        └── hotfix/*    ← sửa lỗi production khẩn cấp

• Nhánh feature/bugfix → develop qua squash merge
• develop → main qua merge commit (giữ ranh giới release)
• Hotfix tách từ main, merge vào cả main LẪN develop

Đặt tên nhánh

<type>/<author>/<short-description>

Loại	Mục đích
feature	Chức năng mới
bugfix	Sửa lỗi
hotfix	Sửa lỗi production khẩn cấp
chore	Bảo trì, phụ thuộc
docs	Chỉ tài liệu
refactor	Tái cấu trúc code
test	Thêm/cập nhật test

Quy tắc: chữ thường + dấu gạch nối, bao gồm tên tác giả, mô tả 3-5 từ, tách từ develop.

Ví dụ:

• feature/ducbach/role-permission-crud
• bugfix/phat/pagination-reset-on-filter
• hotfix/phat/payment-webhook-timeout

Quy ước Commit: Conventional Commits

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Loại

Loại	Mô tả	SemVer
feat	Tính năng mới	MINOR
fix	Sửa lỗi	PATCH
refactor	Tái cấu trúc code (không thay đổi hành vi)	—
perf	Cải thiện hiệu năng	PATCH
test	Thêm/cập nhật test	—
docs	Chỉ tài liệu	—
style	Định dạng, khoảng trắng	—
build	Hệ thống build, phụ thuộc	—
ci	Thay đổi pipeline CI/CD	—
chore	Tác vụ bảo trì	—

Scope

Dùng tên package hoặc app: core, identity, commerce, sale, finance, payment, inventory, signal, client, bo, mq-pay, iiapi, t-van, ledger, pricing, licensing, taxation, outreach

Ví dụ

feat(identity): add role-based access control with Casbin policies
fix(sale): prevent race condition in concurrent checkout
refactor(core): extract auth middleware into reusable component
perf(commerce): add Redis caching for product catalog queries
test(licensing): add license lifecycle integration tests
docs(identity): update API endpoint documentation
build: upgrade Bun to 1.3.x and update lockfile
feat(identity)!: change authentication to JWKS-based verification

BREAKING CHANGE: All services must update their auth configuration.

Quy tắc

1. Thể mệnh lệnh — "add feature" không phải "added feature"
2. Không có dấu chấm ở cuối mô tả
3. Tối đa 72 ký tự cho dòng đầu tiên
4. Body giải thích "tại sao" không phải "cái gì"
5. Breaking change dùng ! trước dấu hai chấm HOẶC footer BREAKING CHANGE:
6. Tham chiếu issue trong footer: Closes #123 hoặc Refs NXET-456

Quy ước Merge Request

Định dạng tiêu đề

Giống Conventional Commits: <type>[scope]: <description>

Quy tắc

1. MR nhỏ — nhắm đến ~200 dòng. Nếu > 500 dòng, hãy cân nhắc tách ra.
2. Tự review trước — review diff của bạn trước khi yêu cầu review.
3. MR draft — dùng trạng thái draft cho công việc đang tiến hành.
4. Một MR = một mối quan tâm — đừng trộn tính năng với refactoring.
5. Bao gồm test — chức năng mới phải có test.
6. Không được build hỏng — CI phải pass trước khi yêu cầu review.
7. Xóa nhánh nguồn — luôn xóa nhánh sau khi merge.
8. Squash commit — squash trước khi merge để có lịch sử sạch.

Chiến lược Merge

Hướng merge	Chiến lược
Nhánh feature → develop	Squash merge (lịch sử tuyến tính sạch)
develop → main	Merge commit (giữ ranh giới release)
Hotfix → main	Merge commit với --no-ff

Quy tắc vàng: Đừng bao giờ rebase các commit đã được push lên một nhánh chia sẻ.

Code Review: Conventional Comments

Dùng comment có nhãn để rõ ràng:

Nhãn	Ý nghĩa	Có chặn?
praise:	Khen điều gì đó tốt	Không
nitpick:	Style/sở thích nhỏ nhặt	Không
suggestion:	Đề xuất một cải tiến	Không
issue:	Vấn đề cụ thể được phát hiện	Có
question:	Cần làm rõ	Không
thought:	Ý tưởng nảy ra từ code	Không
todo:	Thay đổi nhỏ cần thiết	Có
chore:	Tác vụ đơn giản bắt buộc	Có

Ví dụ:

praise: Clean abstraction — this makes the DI pattern much clearer.

issue: This query runs inside a loop, creating an N+1 problem.
Consider using a bulk fetch with `inArray()`.

suggestion (non-blocking): Could extract this validation into a
shared Zod schema since it's duplicated in 3 controllers.

question: Is this timeout intentional? 30s seems high for a
health check endpoint.

Cần review gì (theo thứ tự ưu tiên)

1. Thiết kế — kiến trúc có phù hợp với pattern IGNIS không?
2. Tính đúng đắn — lỗi logic, trường hợp biên, xử lý lỗi
3. Bảo mật — auth, validate input, lộ credential
4. Hiệu năng — query N+1, thiếu cache, thao tác chặn
5. Test — độ phủ, trường hợp biên, assertion có ý nghĩa
6. Đặt tên & dễ đọc — tên rõ ràng, comment phù hợp
7. Style & nhất quán — TypeScript strict, path alias, object i18n

Tốc độ Review

• Phản hồi trong vòng 1 ngày làm việc (lý tưởng là trong vài giờ)
• Đối với MR lớn, đưa phản hồi thiết kế trước khi review chi tiết
• Nếu review sẽ mất thời gian, hãy xác nhận: "Sẽ review trước cuối ngày"

Tham khảo glab CLI

Cài đặt

glab auth login --hostname git.nexpando.com    # cài đặt ban đầu
glab auth status                                # xác minh kết nối

Merge Request

# Liệt kê
glab mr list                           # các MR mở trong project hiện tại
glab mr list --assignee=@me            # MR của tôi
glab mr list --reviewer=@me            # MR tôi cần review
glab mr list --merged --per-page=50    # các MR mới merge

# Xem & review
glab mr view <id>                      # xem chi tiết MR
glab mr view <id> --comments           # với chuỗi thảo luận
glab mr diff <id>                      # xem diff đầy đủ
glab mr checkout <id>                  # checkout nhánh MR cục bộ

# Tạo
glab mr create --fill                  # tự điền từ commit
glab mr create --fill --draft          # tạo dạng draft
glab mr create -t "title" -d "desc" --assignee user --reviewer reviewer
glab mr create --fill --target-branch develop --assignee @me

# Hành động
glab mr approve <id>                   # phê duyệt
glab mr merge <id> -s -d               # squash merge + xóa nhánh nguồn
glab mr note <id> -m "comment"         # thêm comment
glab mr update <id> --ready            # đánh dấu sẵn sàng (bỏ draft)
glab mr close <id>                     # đóng mà không merge

Issue

glab issue list                        # tất cả issue mở
glab issue list --assignee=@me         # issue của tôi
glab issue create -t "title" -d "desc" -l bug
glab issue view <id>
glab issue close <id>

CI/CD

glab ci list                           # liệt kê pipeline
glab ci status                         # pipeline của nhánh hiện tại
glab ci status --live                  # giám sát thời gian thực
glab ci view --web                     # mở trên trình duyệt

Pattern Hữu ích

# Phê duyệt nhanh + squash merge
glab mr approve <id> && glab mr merge <id> -s -d

# Tạo MR từ nhánh hiện tại
glab mr create --fill --target-branch develop --assignee @me

Git Hook

Project dùng .githooks/ được cấu hình qua make setup-tools:

Hook	Làm gì
pre-commit	Chạy make pre-commit → lint tất cả các package

make setup-tools    # bật hook (chạy một lần sau khi clone)

Checklist Review Bảo mật

Đối với mọi MR, hãy xác minh:

• [ ] Áp dụng strategy auth ở những nơi cần (jwt/basic)
• [ ] Không có credential hay secret hard-code
• [ ] Kiểm tra vai trò đúng cho các endpoint được bảo vệ
• [ ] Cập nhật chính sách Casbin nếu quy tắc truy cập thay đổi
• [ ] Tất cả input người dùng được validate bằng Zod schema
• [ ] Không có raw SQL (Drizzle ORM tự parameterize query)
• [ ] Dữ liệu nhạy cảm không được log (mật khẩu, token, PII)
• [ ] Phản hồi API không lộ stack trace
• [ ] JWT token có thời gian hết hạn phù hợp

Khắc phục Sự cố

Xung đột merge:

git checkout develop && git pull
git checkout <your-branch>
git rebase develop
# giải quyết xung đột, sau đó: git add <files> && git rebase --continue

Hoàn tác commit cuối (chưa push):

git reset --soft HEAD~1

Build sạch sau khi chuyển nhánh:

bun run rebuild    # trong package bị ảnh hưởng

Trang Liên quan

Trang	Mô tả
Bắt đầu	Cài đặt ban đầu
Hệ thống Build	Target Make và thứ tự build
IGNIS Patterns	Pattern framework cần tuân theo