Tạo ra một trải nghiệm microsite hấp dẫn nơi người dùng trả lời một loạt câu hỏi để khám phá hồ sơ "vibe" của họ, và có cơ hội giành giải thưởng thông qua vòng quay may mắn, đồng thời thu thập dữ liệu người dùng và quảng bá thương hiệu C2.

Chức năng chính

1. Quản lý Người dùng và Thông tin Cá nhân

Đăng ký thông tin người dùng:
- API để nhận và lưu trữ thông tin cá nhân (Họ tên, Nam/Nữ, Email) người dùng gửi trước khi bắt đầu quiz[cite: 2].
Quản lý chấp thuận T&C:
- API để ghi nhận việc người dùng đã đồng ý với Điều khoản và Điều kiện của chương trình[cite: 2].

2. Xử lý Logic Quiz

Cung cấp câu hỏi:
- API để trả về bộ 5 câu hỏi cho frontend[cite: 2].
- Bao gồm logic để tùy chỉnh câu hỏi dựa trên lựa chọn trước đó (ví dụ: Câu 4 tùy theo lựa chọn ở Câu 3, Câu 5 tùy theo lựa chọn ở Câu 4)[cite: 6, 7, 8, 9, 10].
Nhận và xử lý câu trả lời:
- API để nhận các câu trả lời từ người dùng cho từng câu hỏi.
Xác định Profile:
- Logic backend để phân tích các câu trả lời và xác định 1 trong 6 profile tương ứng cho người dùng.
Trả kết quả Profile:
- API để gửi kết quả profile (1 trong 6 profiles) đã xác định về cho frontend hiển thị[cite: 12].

3. Quản lý Vòng quay May mắn và Giải thưởng

Xử lý lượt quay:
- API để frontend gọi khi người dùng thực hiện "vòng quay may mắn"[cite: 12].
Logic trúng thưởng:
- Backend chứa logic để xác định ngẫu nhiên việc người dùng có trúng giải hay không trúng giải[cite: 13].
Quản lý giải thưởng:
- Phân bổ số lượng giải thưởng theo ngày[cite: 14].
- Random giá trị voucher Got it[cite: 14].
- Kiểm tra và cập nhật số lượng voucher còn lại[cite: 16].
- Tích hợp với hệ thống mã voucher/API từ brand team để cấp phát voucher (ZEE check hình voucher + mã voucher/API với brand team)[cite: 15].
Thông báo kết quả vòng quay:
- API để trả về kết quả trúng thưởng (hoặc không) cho frontend.

4. Lưu trữ và Truy xuất Dữ liệu

Lưu thông tin người chơi:
- Bao gồm thông tin cá nhân đã đăng ký (Họ tên, Nam/Nữ, Email), các câu trả lời quiz, profile kết quả[cite: 16].
Lưu danh sách người trúng giải:
- Ghi nhận thông tin người chơi đã trúng giải và chi tiết giải thưởng[cite: 16].
Thống kê:
- API để cung cấp số liệu về tổng số người tham gia[cite: 16].
- API để cung cấp thông tin về số lượng voucher còn lại[cite: 16].

5. Quản lý Trạng thái Chương trình

Kiểm tra thời gian chương trình:
- Logic để xác định chương trình còn hoạt động (trong 2 tuần) hay đã kết thúc.
Chuyển trạng thái sau chương trình:
- Tự động hoặc có cơ chế để chuyển website sang trạng thái "chương trình đã kết thúc" sau 2 tuần.
- Website sẽ được giữ lại khoảng 3 tháng, thông báo chương trình kết thúc, người dùng không thao tác được và drive traffic về fanpage C2.

6. Các Chức năng Hỗ trợ và Quản trị (Admin)

Quản lý nội dung (Tùy chọn):
- API để quản lý nội dung các câu hỏi, T&C, mô tả profile nếu cần thay đổi mà không can thiệp code.
Quản lý giải thưởng (Tùy chọn):
- Giao diện hoặc API cho admin để theo dõi, quản lý danh sách trúng thưởng, số lượng voucher.
Bảo mật:
- Đảm bảo an toàn dữ liệu người dùng và tính toàn vẹn của hệ thống.
Logging:
- Ghi lại các hoạt động quan trọng của hệ thống để theo dõi và gỡ lỗi.

Đặc điểm chính

Kiến trúc DDD (Domain Driven Development) - Customize cho phù hợp với nhu cầu dự án
U-Hierarchy - Mô hình tổ chức mã nguồn theo các cấp độ logic
Hot Reload - Phát triển nhanh với Air Tomb
Docker & Docker Compose - Containerization và orchestration
Gitea Full - CI/CD, Secret Manager, Registry Image
Postgres - Cơ sở dữ liệu quan hệ

Cài đặt

Yêu cầu hệ thống

Go 1.24.3
Docker và Docker Compose
Git

Khởi tạo dự án

# Clone repository
git clone [repo-url] my-project
cd my-project

# Cài đặt dependencies và công cụ
make init

# Cấu hình môi trường
cp .env.example .env
# Chỉnh sửa file .env theo nhu cầu

# Khởi động môi trường phát triển
make dev

Sử dụng Docker

Dự án cung cấp hai cấu hình Docker:

Môi trường phát triển (Local)

# Khởi động tất cả các dịch vụ với Docker Compose
make docker-compose-up

# Dừng tất cả các dịch vụ
make docker-compose-down

# Dọn dẹp container sau khi sử dụng
make docker-clean

Môi trường phát triển bao gồm:

API service với hot reload (Air Tomb)
PostgreSQL database
Gitea (Git Server, CI/CD, Registry)
Gitea Runner

Môi trường production

# Khởi động các dịch vụ cho production
make docker-compose-prod-up

# Dừng các dịch vụ production
make docker-compose-prod-down

Môi trường production bao gồm:

API service (optimized build)
PostgreSQL database
Nginx reverse proxy

Kiến trúc

Dự án sử dụng mô hình DDD (Domain Driven Development) với các thành phần chính:

Resource: Các Aggregate DDD
Transaction: Các Saga điều phối luồng nghiệp vụ phức tạp
Adapter: Xử lý giao tiếp với các hệ thống bên ngoài
Helper: Các thư viện, tiện ích dùng chung
UIUX: Lớp giao diện người dùng

Thành phần kiến trúc chi tiết (U-Hierarchy):

ubit: Đơn vị logic nhỏ nhất (hàm, type, hằng số)
ubrick: Tập hợp các ubit liên quan
ublock: Thành phần hoạt động độc lập tương đối
ubundle: Tính năng hoàn chỉnh cho người dùng

Các lệnh Makefile

# Xem danh sách lệnh có sẵn
make help

# Khởi tạo dự án
make init

# Chạy môi trường phát triển với Air Tomb
make dev

# Chạy tests
make test

# Kiểm tra linting
make lint

# Build ứng dụng
make build

# Dọn dẹp tệp tạm
make clean

# Docker commands
make docker-build                # Build Docker image
make docker-run                  # Run container từ image
make docker-clean                # Dọn dẹp container
make docker-prune                # Dọn dẹp tất cả tài nguyên Docker không sử dụng
make docker-compose-up           # Khởi động môi trường phát triển
make docker-compose-down         # Dừng môi trường phát triển
make docker-compose-prod-up      # Khởi động môi trường production
make docker-compose-prod-down    # Dừng môi trường production

# Cấu hình Git
make setup-git

Quy trình phát triển

Dự án sử dụng Trunk-Based Development với các quy ước đặt tên nhánh:

feat: Tạo tính năng mới
fix: Sửa lỗi
docs: Thay đổi tài liệu
style: Thay đổi không ảnh hưởng đến logic
refactor: Refactor code
test: Thêm hoặc sửa test
chore: Thay đổi cấu hình hoặc các task không liên quan đến code

Xem thêm chi tiết trong docs/workflow.md.

Tài liệu

Đóng góp

Xem hướng dẫn đóng góp trong docs/workflow.md.

Giấy phép

Dự án này được phân phối dưới Giấy phép MIT. Xem file LICENSE để biết thêm thông tin.