Cơ sở dữ liệu
PostgreSQL, Drizzle ORM và các nhóm bảng theo nghiệp vụ.
Công nghệ
| Hạng mục | Chi tiết |
|---|---|
| Hệ quản trị | PostgreSQL |
| Truy cập | pg.Pool với tối đa 8 kết nối, qua Drizzle node-postgres |
| ORM và schema | Drizzle, khai báo tập trung tại apps/api/src/schema.ts |
| Migration | drizzle-kit sinh file SQL, drizzle-orm chạy khi triển khai |
| Thư mục migration | apps/api/migrations/ |
| Số migration hiện có | 47 file SQL tại thời điểm khảo sát 13/10/2026, đánh số 0000–0047; repo vẫn đang được bổ sung |
API không tự chạy migration khi khởi động
Tiến trình API khởi động thường không tự migrate, seed hay backfill. Migration là bước riêng, có kiểm soát, nằm trong quy trình triển khai.
Các nhóm bảng theo nghiệp vụ
| Nhóm | Bảng chính |
|---|---|
| Lõi và đặt lịch | actors, sessions, otp_tokens, configuration, orders, photos, order_events, idempotency |
| Tài khoản và phân quyền | permissions, role_permissions, staff_profiles, staff_roles, password_recovery_challenges, password_recovery_limits |
| Điểm tập kết và túi rác | depots, staff_depots, bag_shops, depot_public_events |
| Xe và người thu gom | vehicle_types, vehicle_collectors |
| Khách hàng | customer_profiles, customer_events, customer_identities, customer_payment_banks |
| Vận hành | operation_settings, operation_events |
| Bảng giá | pricing_settings, price_groups, price_versions, price_lifecycle, pricing_events, pricing_images |
| Phiên thu gom | collection_sessions, collection_session_entries, collection_session_stops, collection_session_fails, collection_events, collection_inspections, collection_notifications |
| Phiên kiểm tra và sổ giá | inspection_items, inspection_invoices, inspection_payouts, pricing_accruals, pricing_ledger |
| Hoá đơn và chi trả | invoice_payout_logs, invoice_confirmation_requests |
| Tài chính | finance_settings, finance_sales, finance_sale_lines, finance_vouchers, finance_voucher_items, finance_inventory, finance_events, finance_notices, finance_requests, finance_review_records |
| Thông báo nội bộ | admin_notifications, admin_notification_reads |
| Xác thực khách | citizen_auth_profiles, citizen_otp_requests, citizen_refresh_tokens, citizen_push_subscriptions, citizen_notification_preferences, customer_addresses |
| Đơn và trang chủ khách | citizen_bonus_awards, citizen_hidden_orders, citizen_order_ratings, citizen_booking_metadata, citizen_booking_uploads |
| Thông báo khách | customer_notifications, citizen_notification_deliveries, citizen_notification_jobs |
| Tài khoản khách | citizen_personal_profiles, citizen_passwords, citizen_password_attempts, citizen_password_blocks |
Ràng buộc đáng chú ý
Số CCCD
customer_identities.num chỉ chấp nhận số CCCD 9 hoặc 12 chữ số, hoặc giá trị
đã mã hoá có tiền tố enc:v1:. Ràng buộc này được mở rộng từ 12 số để hỗ trợ
CMND 9 số.
Nhật ký chi trả
invoice_payout_logs.kind chỉ nhận một trong: issue, confirm, pause,
resume, paid. Bảng này chỉ ghi thêm, không sửa.
Trạng thái hồ sơ danh tính
Hạn chế cần biết: eKYC chưa có ở tầng cơ sở dữ liệu
Kiểu dữ liệu trong packages/contracts cho phép trạng thái hồ sơ danh tính là
review hoặc verified. Tuy nhiên ràng buộc trong cơ sở dữ liệu chỉ cho phép
review, và phương thức chỉ cho phép manual. Nghĩa là luồng eKYC tự động
chưa được mở ở tầng lưu trữ. Đây là điểm cần thống nhất giữa mã và cơ sở dữ liệu.
Cách ly cơ sở dữ liệu
Hệ thống tách dữ liệu theo môi trường bằng cả quy ước đặt tên lẫn kiểm tra trong mã:
| Môi trường | Cơ sở dữ liệu | Ghi chú |
|---|---|---|
| Local | yechai_m2_development | PostgreSQL nhúng, cổng 55432. |
| Kiểm thử tự động | yechai_m2_test_* | Mỗi lần chạy một cơ sở dữ liệu riêng. |
| vps-dev | yechai_dev | Bắt buộc đúng tên. |
| vps-test | yechai_vps_test | Môi trường đang chạy yechai.auranium.tech. |
| production | yechai_production | Bắt buộc đúng tên. |
Các chốt an toàn đã có trong mã:
- Ở chế độ local, chuỗi kết nối chỉ được trỏ tới loopback, đúng cổng và đúng mẫu tên cơ sở dữ liệu; sai sẽ báo lỗi thay vì kết nối.
- Ở môi trường VPS, việc ghi đè bằng biến kiểm thử bị cấm hoàn toàn.
- Thư mục dữ liệu runtime phải nằm ngoài thư mục mã nguồn.
- Thư mục dữ liệu có tệp đánh dấu chủ sở hữu; thiếu hoặc sai chủ sẽ bị từ chối.
Mâu thuẫn đã biết
Tài liệu kiến trúc cũ
docs/architecture/database-design.md trong repo ứng dụng mô tả cơ sở dữ liệu
chỉ có tám bảng và không có bảng phiên, kiểm tra, hoá đơn, chi trả hay tài chính.
Điều này không còn đúng: hàng chục migration hiện có tạo đầy đủ các bảng đó.
Khi cần tra cứu, hãy đọc trực tiếp thư mục apps/api/migrations/ và apps/api/src/schema.ts.