Skip to content

PHASE_DEVELOPMENT_GUIDE.md

Latest commit

 

History

History
298 lines (227 loc) · 6.9 KB

PHASE_DEVELOPMENT_GUIDE.md

File metadata and controls

298 lines (227 loc) · 6.9 KB
Raw

📋 HƯỚNG DẪN PHÁT TRIỂN CHERRY THEO 4 GIAI ĐOẠN

📊 TỔNG QUAN

Dự án Cherry được chia thành 4 giai đoạn phát triển (phases) để quản lý tốt hơn quá trình phát triển, kiểm thử và triển khai.

🎯 Mục tiêu

  • Phát triển từng bước, dễ kiểm soát
  • Mỗi phase có thể build và deploy độc lập
  • Dễ dàng kiểm thử và demo
  • Phù hợp cho môn Kiểm thử phần mềm

📊 BẢNG TÓM TẮT 4 GIAI ĐOẠN

Giai đoạn Mục tiêu Services Docker Tag Git Branch
Phase 1 Quản lý sản phẩm ProductAPI + Database v1.x-phase1 phase1-product-management
Phase 2 Giỏ hàng & Mã giảm giá Phase 1 + CouponAPI + ShoppingCartAPI v2.x-phase2 phase2-cart-coupons
Phase 3 Xác thực & Đặt hàng Phase 2 + AuthAPI + OrderAPI v3.x-phase3 phase3-auth-orders
Phase 4 Hệ thống hoàn chỉnh All services + Gateway + Web v4.x-phase4 phase4-complete-system

🏗️ CẤU TRÚC DỰ ÁN

FastFoodOrder/
├── Cherry.Services.AuthAPI/
├── Cherry.Services.ProductAPI/
├── Cherry.Services.CouponAPI/
├── Cherry.Services.ShoppingCartAPI/
├── Cherry.Services.OrderAPI/
├── Cherry.Services.EmailAPI/
├── Cherry.Services.RewardAPI/
├── Cherry.GatewaySolution/
├── Cherry.Web/
├── docker/
│   └── phases/
│       ├── docker-compose.phase1.yml
│       ├── docker-compose.phase2.yml
│       ├── docker-compose.phase3.yml
│       └── docker-compose.phase4.yml
├── scripts/
│   ├── build-phase.sh
│   ├── run-phase.sh
│   ├── stop-phase.sh
│   ├── run-tests.sh
│   └── deploy-phase.sh
├── .github/
│   └── workflows/
│       ├── phase1-ci.yml
│       ├── phase2-ci.yml
│       ├── phase3-ci.yml
│       └── phase4-ci.yml
└── docs/
    └── phases/
        ├── phase1/
        ├── phase2/
        ├── phase3/
        └── phase4/

🚀 HƯỚNG DẪN SỬ DỤNG

1️⃣ Build một phase

./scripts/build-phase.sh <phase_number> <version>

# Ví dụ:
./scripts/build-phase.sh 1 v1.0

2️⃣ Chạy một phase

./scripts/run-phase.sh <phase_number>

# Ví dụ:
./scripts/run-phase.sh 1

3️⃣ Chạy tests

./scripts/run-tests.sh <phase_number> [test_type]

# Ví dụ:
./scripts/run-tests.sh 1 unit
./scripts/run-tests.sh 2 all

4️⃣ Dừng một phase

./scripts/stop-phase.sh <phase_number>

# Ví dụ:
./scripts/stop-phase.sh 1

5️⃣ Deploy

./scripts/deploy-phase.sh <phase_number> <version> [environment]

# Ví dụ:
./scripts/deploy-phase.sh 1 v1.0 production

📝 QUY TRÌNH PHÁT TRIỂN

Workflow cho mỗi phase

  1. Tạo branch mới

    git checkout -b phase1-product-management

  2. Phát triển features

    • Viết code
    • Viết tests
    • Commit thường xuyên

  3. Build và test local

    ./scripts/build-phase.sh 1 v1.0-beta
./scripts/run-tests.sh 1 all
./scripts/run-phase.sh 1

  4. Push lên GitHub

    git push origin phase1-product-management

  5. CI/CD tự động chạy

    • GitHub Actions sẽ build
    • Chạy tests
    • Build Docker images

  6. Merge vào main và tag

    git checkout main
git merge phase1-product-management
git tag -a v1.0-phase1 -m "Phase 1: Product Management completed"
git push origin main
git push origin v1.0-phase1

🧪 KẾ HOẠCH KIỂM THỬ

Phase 1: Product Management

  • Unit Tests: ProductService CRUD operations
  • Integration Tests: Product API endpoints + Database
  • Coverage Target: ≥ 70%

Phase 2: Cart & Coupons

  • Unit Tests: Cart logic, Coupon validation
  • Integration Tests: Cart + Coupon workflow
  • Coverage Target: ≥ 75%

Phase 3: Auth & Orders

  • Unit Tests: JWT, Password hashing, Order creation
  • Integration Tests: Auth flow, Order processing
  • Security Tests: SQL injection, XSS, CSRF
  • Coverage Target: ≥ 80%

Phase 4: Complete System

  • Unit Tests: All services
  • Integration Tests: Service-to-service communication
  • E2E Tests: Complete user journeys
  • Performance Tests: Load testing
  • Coverage Target: ≥ 80%

🐳 DOCKER COMMANDS

Build toàn bộ một phase

docker-compose -f docker/phases/docker-compose.phase1.yml build

Chạy một phase

docker-compose -f docker/phases/docker-compose.phase1.yml up -d

Xem logs

docker-compose -f docker/phases/docker-compose.phase1.yml logs -f

Dừng và xóa

docker-compose -f docker/phases/docker-compose.phase1.yml down
docker-compose -f docker/phases/docker-compose.phase1.yml down -v  # Xóa cả volumes

📦 GIT WORKFLOW

Branch naming convention

  • phase1-product-management
  • phase2-cart-coupons
  • phase3-auth-orders
  • phase4-complete-system

Tag naming convention

  • v1.0-phase1, v1.1-phase1
  • v2.0-phase2, v2.1-phase2
  • v3.0-phase3, v3.1-phase3
  • v4.0-phase4, v4.1-phase4

Commit message convention

feat: add Product CRUD API
test: add unit tests for ProductService
docker: update Dockerfile for Phase 1
docs: add Phase 1 documentation
fix: resolve Product API bug

🔧 TROUBLESHOOTING

Lỗi: Port đã được sử dụng

# Kiểm tra process đang dùng port
lsof -i :5002

# Dừng tất cả containers
docker-compose -f docker/phases/docker-compose.phase1.yml down

Lỗi: Database connection failed

# Kiểm tra database đã chạy chưa
docker ps | grep cherry-db

# Restart database
docker-compose -f docker/phases/docker-compose.phase1.yml restart cherry-db

Lỗi: Build failed

# Xóa build cache
docker builder prune

# Build lại từ đầu
docker-compose -f docker/phases/docker-compose.phase1.yml build --no-cache

📚 TÀI LIỆU THAM KHẢO

💡 TIPS

  1. Luôn chạy tests trước khi commit
  2. Sử dụng Docker volumes cho development để tránh mất data
  3. Commit nhỏ, commit thường xuyên
  4. Viết commit message rõ ràng
  5. Document mọi thứ trong code comments
  6. Review code trước khi merge

📞 HỖ TRỢ

Nếu gặp vấn đề, vui lòng:

  1. Kiểm tra logs: docker-compose logs
  2. Kiểm tra GitHub Issues
  3. Liên hệ team lead

Happy Coding! 🚀