Đặc tả Tính năng: Thanh toán & Hạn mức

1. Tổng quan & Tầm nhìn

Thanh toán & Hạn mức là lớp quản trị tài chính và tài nguyên của nền tảng. Nó thu hẹp khoảng cách giữa các gói thương mại và các giới hạn kỹ thuật, đảm bảo các tổ chức được lập hóa đơn chính xác cho việc sử dụng của họ, đồng thời cung cấp một cách liền mạch để nâng cấp hoặc quản lý đăng ký.

2. Các Vai trò & Bên liên quan

Vai trò	Mục tiêu
Chủ sở hữu (Owner)	Nâng cấp gói cước, quản lý phương thức thanh toán và xem hóa đơn.
Quản trị viên	Theo dõi việc sử dụng của tổ chức so với hạn mức gói cước.
Quản trị viên Hệ thống	Định nghĩa các cấp độ sản phẩm toàn cầu và giám sát doanh thu.

3. Câu chuyện Người dùng (User Stories)

• Với tư cách là chủ sở hữu, tôi muốn nâng cấp lên gói "Pro" để có thể thêm nhiều hơn 5 thành viên.
• Với tư cách là quản trị viên, tôi muốn xem dung lượng lưu trữ còn lại trong Drive trước khi tải lên các tệp lớn.

4. Yêu cầu Chức năng (FR)

• REQ-BILL-001: Hỗ trợ các cấp độ gói đăng ký (Hobby, Pro, Enterprise).
• REQ-BILL-002: Tích hợp Stripe Checkout để nâng cấp gói cước.
• REQ-BILL-003: Stripe Customer Portal để quản lý hóa đơn và thanh toán.
• REQ-BILL-004: Theo dõi hạn mức thời gian thực (Lưu trữ, Người dùng, Yêu cầu AI).

5. Yêu cầu Phi chức năng (NFR)

• Độ chính xác: Việc theo dõi sử dụng phải có tính nguyên tử (atomic) và nhất quán cuối cùng trong vòng 1 phút.
• Bảo mật: Không lưu trữ dữ liệu thẻ tín dụng thô (tuân thủ PCI qua Stripe).

6. Logic & Quy tắc Nghiệp vụ

• Hạn mức Cứng vs. Mềm: Lưu trữ là hạn mức cứng (dừng tải lên); Các yêu cầu AI là hạn mức mềm (tính phí vượt mức).
• Thời gian ân hạn: Thời gian ân hạn 3 ngày cho các khoản thanh toán thất bại trước khi khóa tài khoản.
• Thanh toán theo tỷ lệ: Stripe tự động xử lý tính phí theo tỷ lệ cho các nâng cấp giữa chu kỳ.

7. Giao diện Người dùng (UI/UX)

• Ma trận so sánh "Gói cước & Giá cả".
• "Bảng điều khiển Sử dụng" với các thanh tiến trình cho từng hạn mức.
• Banner trong ứng dụng cho các trạng thái "Sắp hết hạn mức" hoặc "Thanh toán thất bại".

8. Kiến trúc Thông tin

• Phần "Thanh toán" trong Cài đặt Tổ chức.
• Thống kê sử dụng nhanh trong thanh bên Shell (tùy chọn).

9. Mô hình Dữ liệu & Lưu trữ

• Các bảng: subscription_plans, plan_limits, plan_usage.
• Bên ngoài: Sản phẩm, Giá và Khách hàng trên Stripe.

10. Lớp API & Dịch vụ

• GET /api/subscriptions/usage
• POST /api/subscriptions/upgrade
• POST /api/subscriptions/webhook

11. Các Mẫu Tích hợp

• Stripe Webhooks: Để đồng bộ trạng thái thanh toán và các sự kiện vòng đời.
• Quota Hooks: Các module satellite tăng bộ đếm sử dụng trong Shell qua các lệnh gọi API nội bộ.

12. Bảo mật & Quyền hạn

• Chỉ Chủ sở hữu tổ chức mới có thể truy cập cài đặt thanh toán và checkout.
• Việc thực thi hạn mức được kiểm tra tại lớp API của mỗi module satellite.

13. Xử lý Lỗi & Khả năng Phục hồi

• Phục hồi mượt mà từ các lỗi timeout API của Stripe.
• "Chế độ Khẩn cấp" (Chỉ đọc) khi một tài khoản bị khóa do không thanh toán.

14. Hiệu năng & Khả năng Mở rộng

• Bộ đếm hạn mức được cache trong Redis cho các lần kiểm tra tần suất cao.
• Việc tổng hợp sử dụng được thực hiện không đồng bộ.

15. Toàn cầu hóa & Bản địa hóa

• Hỗ trợ nhiều loại tiền tệ (USD, VND).
• Tính toán thuế theo khu vực (ủy thác cho Stripe).

16. Khả năng Tiếp cận (a11y)

• Các bảng giá có thể tiếp cận (aria-describedby cho các tính năng của gói).

17. Khả năng Quan sát & Phân tích

• Theo dõi các chỉ số "Tỷ lệ rời bỏ" và "Chuyển đổi nâng cấp".
• Giám sát các tổ chức có mức sử dụng cao cho các cơ hội bán hàng tiềm năng.

18. Kiểm thử & Chất lượng

• Kiểm thử tích hợp sử dụng Stripe CLI để mô phỏng webhook.
• Kiểm thử đơn vị cho logic tính phí theo tỷ lệ và hạn mức.

19. Các Ràng buộc & Giả định

• Giả định rằng một tài khoản Stripe hợp lệ đã được cấu hình trong môi trường.

20. Các Cải tiến Tương lai

• Thanh toán dựa trên mức độ sử dụng (metered) cho các token AI.
• Các gói tài nguyên bổ sung (ví dụ: "+10GB Lưu trữ").