rules/task-workflow.md

Task Workflow

Quy trình bắt buộc khi thực hiện bất kỳ task nào trong project. Áp dụng cho cả developer và AI assistant.

Phase 1: PICK UP — Nhận task

1.1 Đọc hiểu requirements

  • Đọc user story / issue description đầy đủ
  • Xác định thuộc Epic nào trong docs/product/prd.md
  • Hiểu acceptance criteria — đây là definition of done
  • Nếu chưa rõ → HỎI trước khi code. Không giả định.

1.2 Đọc context

1.3 Tạo branch

# Format: {type}/US-{number}-{short-description}
git checkout main
git pull origin main
git checkout -b feat/US-4.1-customer-online-booking

Phase 2: PLAN — Lên kế hoạch

2.1 Break down

  • List ra các files cần tạo/sửa
  • Xác định thứ tự: DTO → Service → Controller → Test
  • Ước lượng scope — nếu > 400 lines changed thì cần split task

2.2 Thiết kế trước

Với API endpoint mới, viết ra trước:

METHOD /api/{path}
Request: { field1, field2 }
Response: { success, data: { ... }, meta? }
Error cases: 400 (validation), 404 (not found), 409 (conflict)

Verify với docs/architecture/api-design.md — đúng convention chưa?

Phase 3: IMPLEMENT — Thực hiện (TDD)

3.1 Viết test TRƯỚC (RED)

# Tạo test file trước
touch src/core/booking/booking.service.spec.ts

Viết test cases cho:

  • Happy path — input hợp lệ → kết quả đúng
  • Validation — input sai → error đúng format
  • Not found — resource không tồn tại → 404
  • Business rules — conflict, permission, edge cases
  • Tenant isolation — không thấy data tenant khác
yarn test -- --watch booking.service
# Tất cả tests PHẢI FAIL (RED)

3.2 Viết implementation (GREEN)

  • DTO với class-validator + Swagger decorators
  • Service xử lý business logic
  • Controller chỉ delegate sang service
  • Follow conventions: response envelope, error codes, naming
yarn test -- --watch booking.service
# Tất cả tests PHẢI PASS (GREEN)

3.3 Refactor (CLEAN)

  • Xóa code thừa, duplicate
  • Extract helper nếu cần
  • Đảm bảo file size hợp lý (< 400 lines)
  • Tên biến/function tự giải thích
yarn test
# Vẫn PASS sau refactor

Phase 4: VERIFY — Kiểm tra

4.1 Lint (MUST PASS — 0 errors)

yarn lint

Nếu có errors → FIX. Không bỏ qua, không disable rule.

4.2 Build (MUST PASS)

yarn build

4.3 Test coverage (MUST ≥ 80%)

yarn test:cov

Kiểm tra:

  • Coverage ≥ 80% cho files đã thay đổi
  • Không có test bị skip
  • Không có test flaky (chạy lại 2-3 lần)

4.4 Manual smoke test (nếu applicable)

yarn start:dev
# Test bằng curl / Postman / Swagger UI
curl http://localhost:3010/api/docs

4.5 Self-review checklist

Trước khi commit, tự hỏi:

  • Tôi có hiểu mọi dòng code mình viết không?
  • Có console.log nào sót không?
  • Có commented-out code không?
  • Có unused import/variable không?
  • Response format đúng envelope convention không?
  • Error codes đúng UPPER_SNAKE_CASE không?
  • Tenant isolation đã test chưa?
  • Swagger decorators đầy đủ chưa?

Phase 5: COMMIT — Lưu lại

5.1 Stage chỉ files liên quan

# KHÔNG dùng git add .
# Stage từng file cụ thể
git add src/core/booking/booking.service.ts
git add src/core/booking/booking.service.spec.ts
git add src/core/booking/booking.dto.ts

5.2 Commit với message chuẩn

git commit -m "feat: add customer online booking endpoint

- POST /api/bookings with source=ONLINE
- Conflict detection for resource double-booking
- Auto-create customer if not exists
- Tests: happy path, validation, conflict, tenant isolation

Ref: US-4.1"

Rules:

  • Conventional commit format: feat:, fix:, test:, refactor:
  • Dòng đầu: ngắn (< 72 chars), mô tả what
  • Body: bullet points mô tả chi tiết
  • Ref: link user story

5.3 Pre-commit hook tự chạy

Husky + lint-staged sẽ tự:

  1. Prettier format staged files
  2. ESLint check staged files
  3. Nếu fail → commit bị block → fix rồi commit lại

KHÔNG BAO GIỜ dùng --no-verify.

Phase 6: PR — Pull Request

6.1 Push branch

git push -u origin feat/US-4.1-customer-online-booking

6.2 Tạo PR với template

## Summary
- Add customer online booking endpoint (POST /api/bookings)
- Conflict detection prevents resource double-booking
- Guest booking support (no account required)

## User Story
US-4.1: Customer đặt booking online

## Changes
- `src/core/booking/booking.dto.ts` — CreateBookingDto with validation
- `src/core/booking/booking.service.ts` — booking creation + conflict check
- `src/core/booking/booking.controller.ts` — POST endpoint
- `src/core/booking/booking.service.spec.ts` — 12 test cases

## Test Plan
- [x] Happy path: create booking → 201 + correct response
- [x] Validation: missing serviceId → 400
- [x] Conflict: overlapping time → 409
- [x] Not found: invalid serviceId → 404
- [x] Tenant isolation: can't see other tenant's bookings
- [x] Unassigned: booking without resourceId → creates with null
- [ ] Manual: tested via Swagger UI

## Checklist
- [x] Follows api-design.md conventions
- [x] Tests pass (coverage ≥ 80%)
- [x] Lint passes (0 errors)
- [x] Build passes
- [x] No console.log / dead code

6.3 Review & merge

  • Chờ ≥ 1 approval
  • Address mọi review comments
  • Tất cả CI checks pass
  • Squash merge vào main

Phase 7: CLEANUP — Dọn dẹp

7.1 Sau khi merge

git checkout main
git pull origin main
git branch -d feat/US-4.1-customer-online-booking

7.2 Verify trên main

yarn build && yarn test

7.3 Update docs (nếu cần)

  • PRD: check off completed items
  • API design: nếu có convention mới
  • Onboarding: nếu setup steps thay đổi

Quick Reference — Copy/paste checklist

## Task: [tên task]

### Pick up
- [ ] Đọc user story + acceptance criteria
- [ ] Đọc code liên quan
- [ ] Tạo branch

### Implement (TDD)
- [ ] Tests viết trước (RED)
- [ ] Implementation (GREEN)
- [ ] Refactor (CLEAN)

### Verify
- [ ] yarn lint — 0 errors
- [ ] yarn build — passes
- [ ] yarn test:cov — ≥ 80%
- [ ] Self-review checklist

### Commit & PR
- [ ] Commit atomic, message chuẩn
- [ ] PR với summary + test plan
- [ ] Review approved + CI green
- [ ] Squash merge → cleanup branch