matching_app/docs/spec.md

Thông số kỹ thuật

File: Zee.md

Function:

Description:

Logic:

Input:

Output:

Error Handling:

Preconditions:

Postconditions:

Internal Dependencies:

Core Technologies

• Backend: Go
• Database: PostgreSQL
• Frontend: HTMX
• Containerization: Docker
• Cloud Hosting: VPS Storage

1. Yêu cầu hệ thống

• Quy mô dự kiến: 20,000+ người tham gia, 5,000 lượt matching
• Hiệu suất: Xử lý đồng thời 100+ request/s
• Độ trễ API: <500ms cho 95% request
• Thời gian matching: <5 phút sau khi đăng ký

2. API Endpoints

Public APIs

• GET /campaign/config - Lấy cấu hình campaign
• POST /profiles - Đăng ký profile mới
• POST /photos/upload - Upload ảnh
• POST /results/access - Truy cập kết quả bằng access code
• GET /results/{token} - Xem kết quả matching
• POST /results/select - Chọn match
• POST /results/decline - Từ chối match

Admin APIs

• POST /admin/auth/login - Đăng nhập admin
• GET /admin/reports/summary - Báo cáo tổng quan
• GET /admin/campaign/status - Trạng thái campaign
• POST /admin/campaign/actions/{action} - Thực hiện action campaign
• GET/POST/PUT/DELETE /admin/gifts - Quản lý quà tặng
• GET /admin/giveaway/allocations - Danh sách phân bổ quà
• POST /admin/giveaway/actions/run-draw - Chạy quay thưởng

3. Transaction Workflows

1. UserRegistrationTransaction: Đăng ký → Tạo Profile → Gửi email xác nhận
2. MatchingTransaction: Chạy matching → Tạo MatchOutcome
3. ResultNotificationTransaction: Gửi thông báo kết quả
4. MatchSelectionTransaction: Xử lý lựa chọn/từ chối
5. GiftAllocationTransaction: Quay thưởng → Tạo GiftAllocation
6. GiftNotificationTransaction: Gửi thông báo trúng thưởng

Error Handling Specification

Error Types:

• UserInputError: Lỗi dữ liệu đầu vào (HTTP 400)
• NotFoundError: Tài nguyên không tồn tại (HTTP 404)
• UnauthorizedError: Truy cập không được phép (HTTP 401)
• InternalServerError: Lỗi hệ thống (HTTP 500)

Logging Requirements:

• Tất cả lỗi phải được ghi lại với context đầy đủ
• Sử dụng structured logging với zap

Overall Flow:

sequenceDiagram
  

---