Kiến trúc Dữ liệu & Lưu trữ
VENI-AI tuân thủ Kiến trúc Cơ sở dữ liệu Không chia sẻ (Shared-Nothing Database Architecture). Để duy trì tính tự chủ của các Hệ thống Tự trị (SCS), mỗi ứng dụng satellite sở hữu dữ liệu của mình từ đầu đến cuối, ngăn chặn việc phụ thuộc chéo giữa các dịch vụ ở tầng lưu trữ.
1. Triết lý Lưu trữ
Cơ sở dữ liệu Cô lập (Tuân thủ SCS)
Mọi ứng dụng trong nền tảng (Shell, Drive, HRM, v.v.) đều có cơ sở dữ liệu PostgreSQL (hoặc schema) chuyên dụng riêng.
- Không chia sẻ bảng: Các Satellite không bao giờ truy vấn trực tiếp cơ sở dữ liệu của nhau.
- Truy cập dựa trên Hợp đồng: Việc trao đổi dữ liệu giữa các dịch vụ chỉ xảy ra thông qua các API gRPC hoặc REST.
- Tiến hóa Độc lập: Một thay đổi schema trong HRM không bao giờ làm hỏng ứng dụng Drive.
Cách ly Đa người dùng (Multi-Tenant)
Nền tảng sử dụng mô hình Multitenancy dựa trên phân biệt (Discriminator-based). Hầu hết các bảng đều bao gồm cột organization_id.
- Dữ liệu Toàn cầu: Các cấu hình toàn hệ thống (ví dụ: identity providers) không có
organization_id. - Dữ liệu Tổ chức: Các thực thể nghiệp vụ (ví dụ: hồ sơ nhân viên, tệp tin) được giới hạn nghiêm ngặt trong một tổ chức.
2. Stack Kỹ thuật: Drizzle ORM
Nền tảng sử dụng Drizzle ORM vì tính an toàn kiểu (type-safety), hiệu năng cao và trải nghiệm lập trình gần với SQL thuần túy.
Các Thực thể Dữ liệu Cốt lõi (Shell)
Cơ sở dữ liệu Shell đóng vai trò là danh mục đăng ký nền tảng và bộ đệm định danh.
| Bảng | Mô tả |
|---|---|
organizations | Các thực thể gốc. Quản lý thanh toán, gói cước và tên miền. |
apps | Danh mục Đăng ký Nền tảng. Lưu trữ URL và metadata của tất cả satellite. |
users | Bộ đệm định danh local được đồng bộ từ Keycloak/Google. |
roles & permissions | Định nghĩa RBAC được quản lý bởi Casbin. |
audit_log | Nhật ký hệ thống bất biến, được phân vùng theo created_at. |
3. Migration & Seeding
Migrations Đơn định (Idempotent)
Chúng tôi sử dụng Drizzle Kit để quản lý migration. Mỗi lần triển khai đều bao gồm một initContainer chạy migration trước khi API bắt đầu.
- Postgres Types: Vì lệnh
CREATE TYPEtiêu chuẩn không có tính đơn định, chúng tôi sử dụng các khốiDO $$ ... EXCEPTION WHEN duplicate_object.
Công cụ Nạp Dữ liệu (CSV Seeding)
Shell bao gồm một công cụ mạnh mẽ để nạp dữ liệu ban đầu (vai trò, tổ chức, ứng dụng) từ các tệp CSV nằm trong scripts/seed-data/.
# Nạp dữ liệu môi trường development
bun run seed
# Sử dụng trong production (CI/CD)
# migrations chạy tự động; seeding là thủ công hoặc một phần của quy trình onboarding.4. Hiệu năng & Bộ đệm (Caching)
Lớp Trạng thái Redis
Trong khi PostgreSQL là nguồn sự thật (source of truth), Redis được sử dụng cho các trạng thái tạm thời và tối ưu hiệu năng:
- RBAC Policy Cache: Các chính sách Casbin đã biên dịch (TTL 5 phút).
- Discovery Cache: URL và trạng thái ứng dụng (TTL 30 giây).
- Token Blacklist: Mã băm SHA-256 của các JWT đã đăng xuất.
Quản lý Kết nối
Tất cả các dịch vụ sử dụng node-postgres (pg) với cơ chế connection pooling. Trong môi trường quy mô lớn, PgBouncer được khuyến nghị để quản lý hàng tá kết nối từ các satellite API.
Các bước tiếp theo
- Kiến trúc & Framework — Xem cách các lớp dữ liệu khớp vào framework Ignis.
- Định danh & Bảo mật — Hiểu cách
organization_idđược thực thi trong JWT.