🏗️ Kiến trúc Level 7: Pattern Chuẩn cho Domain Module

Luồng dữ liệu chỉ đi một chiều gốc rễ. Thiết kế Feature-Based & Domain-Driven loại bỏ tuyệt đối Circular Dependencies (import chéo) giữa các tính năng.

1. Data Contract (Hạt nhân Dữ Liệu)

src/features/[feature]/types.ts

Quy tụ toàn bộ Interface ánh xạ Database. Bắt buộc dùng TableRow<"table"> và TableInsert làm gốc.
Là Single Source of Truth. Đảm bảo toàn bộ dự án cập nhật tự động khi Schema thay đổi, xóa sạch kỹ thuật ép kiểu lỏng lẻo.

2. Validation Schema (Rào chắn Input)

src/schema/[feature].schema.ts

Dùng Zod làm ranh giới phòng thủ. Bắt mọi lỗi logic người dùng trước khi chạm vào Store hoặc API.
Tách bạch FormValues khỏi DbModel để Frontend tuỳ biến thả ga (định dạng ngày tháng, tiền tệ) mà không phá vỡ DB.

3. Pure Domain Logic (Bộ não Nghiệp vụ)

src/domain/[module]/[Module]Domain.ts

Chứa 100% Pure TypeScript — Nơi các thuật toán tính hao hụt, parse mã Barcode, hoặc map dữ liệu Form ra DTO được thực thi.
Cách ly tuyệt đối: Không dùng React Hook, không gọi Supabase API. Chỉ Input -> Xử lý tính toán -> Output (Dễ dàng Unit Testing).

4. Infrastructure Layer (Tầng Hạ Tầng)

src/api/[feature].api.ts

Chế tác các Function Async tương tác trực tiếp với tầng Backend (Supabase RPC, Postgres Select/Insert).
Tuyệt đối không nhúng Code UI hay tính toán rườm rà. Thông lượng truyền nhận phải là Entity chuẩn (types.ts).

5. Use-Cases Orchestrator (Kẻ Điều Phối)

src/features/[feature]/use[Feature].ts

Wrappers bằng React Query (useQuery, useMutation). Quản lý triệt để Caching, Polling, Invalidate.
Đóng vai trò "Giám đốc vận hành" - lấy Data từ UI -> Kêu gọi Domain xử lý -> Gọi API Layer lưu DB -> Báo UI render.

6. Presentational Views & Plugins

src/features/[feature]/[feature].module.ts (và Components)

Giao diện thuần hiển thị (View Layer) như AdaptiveSheet, Grid Data, Modals.
File Module dùng sinh MetaData (Route, Icon, Breadcrumbs) cho kiến trúc cắm thả Feature Plugin Registry mở rộng vĩnh viễn không giới hạn.

⚡ Sơ đồ vận hành dòng dữ liệu (Unidirectional)

01 UI Component (Thu thập Input từ Form)

↳ 02 Use-Case Hook (Điều phối Mutations & Trạng thái Loading)

↳ 03 Domain Logic (Tính toán siêu dữ liệu & Mapping Payload DB)

↳ 04 API Layer (Thực thi gửi lên máy chủ Supabase)

↳ 05 Data Contract (Trả về kết quả khít 100% với types.ts)

Kiến trúc Level 7 - Domain Pattern