⚖️ Trung tâm quyết định
Nhật ký quyết định kiến trúc (ADR) — vì sao chọn, đánh đổi gì.
Thiết kế AI Platform theo mô hình BYOK + Hội đồng AI + AI Gateway
Chấp nhận- Bối cảnh
- Project OS cần một nền tảng AI dùng chung để sau này phân phối cho tới 1.000.000 Website SaaS, mà không bắt chủ hệ thống gánh chi phí AI cho toàn bộ website. Sprint chỉ THIẾT KẾ, chưa lập trình.
- Các lựa chọn
- PA1: Tài khoản AI chung của chủ hệ thống cho mọi website (bị loại — chi phí bùng nổ, rủi ro hạn mức/khóa tài khoản, khó cô lập dữ liệu). PA2 (CHỌN): BYOK — mỗi website dùng tài khoản AI của chính khách, qua AI Gateway trung gian, tổ chức theo Hội đồng AI (nhiều vai trò dùng chung một model). PA3: Chỉ 1 nhà cung cấp AI cố định (bị loại — phụ thuộc một provider, không tối ưu chi phí/năng lực).
- Quyết định
- Chốt kiến trúc AI Platform: (1) AI Gateway đứng giữa website và nhiều nhà cung cấp; (2) BYOK — khách nhập/kiểm tra/ngắt API key của họ; (3) Hội đồng AI = nhiều VAI TRÒ AI (prompt/quyền/tool khác nhau), KHÔNG bắt buộc nhiều model; (4) Năng lực AI khai báo theo Provider, tách khỏi vai trò; (5) tách lớp tri thức Prompt/Knowledge/Memory/Context/Reference làm nền RAG; (6) Workspace cô lập theo doanh nghiệp.
- Lý do
- KHÔNG dùng tài khoản AI chung của chủ hệ thống vì với 1 triệu website, chi phí và hạn mức sẽ dồn về chủ hệ thống, dễ bị khóa tài khoản và không cô lập được dữ liệu từng khách. CHỌN BYOK vì chi phí phân tán về từng khách (họ dùng tài khoản miễn phí/trả phí của họ), thêm website chỉ là thêm cấu hình. Hội đồng AI là nhiều VAI TRÒ dùng chung một model để không bùng nổ số model/tài khoản mà vẫn có 'đội ngũ AI' cho doanh nghiệp. AI Platform hiện CHỈ LÀ THIẾT KẾ (chưa triển khai) để khóa kiến trúc trước, tránh làm lại; do đó CHƯA gọi API AI, CHƯA lưu API key thật, CHƯA tích hợp Website SaaS thật — giảm rủi ro bảo mật/chi phí khi chưa chốt.
- Hệ quả
- Mở rộng tới 1.000.000 website nhờ: BYOK phân tán chi phí, Năng lực tách khỏi Provider, Gateway đứng giữa (đổi provider không ảnh hưởng website), nhiều vai trò dùng chung một model, Workspace cô lập nhân bản ngang, Gói & Chợ AI cài nhanh theo ngành. TRẠNG THÁI: Đã duyệt thiết kế · Chưa triển khai kỹ thuật · Chưa tích hợp Website SaaS · Chưa gọi API AI thật. Liên kết: /ai-platform · /ai-platform/hoi-dong · /ai-platform/lo-trinh · /trung-tam-kien-truc · /goc-nhin-kien-truc · /nghiem-thu-sprint. Tài liệu: tai-lieu-thiet-ke/22-ai-platform.md.
ADR: Mô hình hóa doanh nghiệp bằng Enum + Meta + LienKet
Chấp nhận- Bối cảnh
- Cần mở rộng sang phòng ban/nhân sự/hợp đồng mà không phá Architecture Freeze.
- Các lựa chọn
- Tạo bảng riêng / Dùng Enum+Meta+LienKet
- Quyết định
- Dùng Enum+Meta+LienKet.
- Lý do
- Không thêm bảng nền; tái dùng Reasoning/Execution/Timeline/Impact ngay.
- Hệ quả
- Truy vấn theo loai; metadata trong meta JSON.
ADR: Feature Flag & Capability lưu ở file cấu hình/catalog
Chấp nhận- Bối cảnh
- Cần bật/tắt module và quản lý năng lực.
- Quyết định
- Catalog dạng dữ liệu + file JSON cho trạng thái.
- Lý do
- Không thêm bảng nền; đổi cấu hình không sửa engine.
- Hệ quả
- Khi chạy đa tiến trình nên chuyển sang lưu DB.
Chọn PostgreSQL làm cơ sở dữ liệu
Chấp nhận- Quyết định
- Dùng PostgreSQL
- Lý do
- Chịu tải lớn.
Chuyển sang SQLite cho gọn nhẹ
Chấp nhận- Quyết định
- Dùng SQLite
- Lý do
- Triển khai đơn giản.
Đóng băng kiến trúc (Architecture Freeze)
Chấp nhận- Bối cảnh
- Sau Sprint 2.9, nền tảng đã đủ 5 tầng: Data, Semantic, Meta, Presentation, Governance.
- Các lựa chọn
- Tiếp tục mở rộng kiến trúc tự do / Đóng băng có điều kiện / Đóng băng cứng
- Quyết định
- Đóng băng có điều kiện.
- Lý do
- Ổn định nền tảng để tập trung chức năng & trải nghiệm, nhưng vẫn cho phép thay đổi nếu là thiếu sót ảnh hưởng toàn hệ thống.
- Hệ quả
- Mọi đề xuất đổi kiến trúc phải ghi ADR + phân tích tác động trước khi triển khai. Không thêm bảng nền cho 1 chức năng riêng lẻ.
Chọn Next.js cho giao diện
Chấp nhận- Bối cảnh
- Cần khung giao diện hiện đại, đồng bộ hệ sinh thái.
- Các lựa chọn
- Next.js / HTML thuần / Vue
- Quyết định
- Next.js (App Router)
- Lý do
- Định tuyến rõ ràng, render nhanh, dễ mở rộng.
- Hệ quả
- Phụ thuộc Node; cần build.
Dùng mô hình chấm điểm theo luật trước, AI sau
Chấp nhận- Bối cảnh
- Chưa đủ dữ liệu huấn luyện.
- Quyết định
- Bắt đầu bằng luật điểm.
- Lý do
- Triển khai nhanh, dễ giải thích.