# Core `sdk` — Module SDK & CLI

> 07/7/2026 · Repo: **ws_suns** · Đánh giá: **✅ DX tốt · ⚠ thiếu template create** · Bản HTML: [sdk.html](sdk.html) · [Review tổng core](core-review-2026-07-07.md)

## 1. Vai trò
Bộ phát triển module: **defineApp** (backend models/associate/mountRoutes · frontend render/nav), **manifest schema + validator**, CLI **dev / build / publish / deploy / create / seed**, Module Federation dev-mode tự đăng ký với host.

## 2. Thành phần chính

| Thành phần | Vai trò |
|---|---|
| **@opengate/module-sdk/node · /react** | defineApp 2 phía · useHostApi (hasPermission, navigate, getCurrentUser) |
| **manifest schema + test** | Validate key/version/permissions/engines — có test (manifest-schema.test.js) |
| **CLI** | dev (env riêng, migrations tự chạy, federation) · build (.ogapp) · publish (registry) · deploy (host trực tiếp) |
| **@opengate/ui · types** | UI kit dùng chung (AppLayout…) + type defs |

## 3. Hiện trạng (đọc từ code)
- DX vòng lặp dev → build → publish → install trọn vẹn, có tài liệu HUONG_DAN.md chi tiết
- Convention chặt: tableName prefix key, permission 4 cấp, migration idempotent — checklist trước publish rõ ràng
- ⚠ `opengate-module create` hỏng: template `opengate-app-base` **chưa tồn tại** (ghi chú 06/10) — dev phải scaffold tay theo warehouse
- ⚠ Manifest chưa có chỗ khai `fields`/`scopeVars` cho data scope (P1 của plan)

## 4. Khuyến nghị — tham chiếu hệ phổ biến

| Tham chiếu | Khuyến nghị |
|---|---|
| **Shopify CLI / create-vite** | **Ưu tiên cao & rẻ:** làm template create từ chính module student/warehouse tinh gọn — GĐ1 sắp scaffold 3 module mới (tuition/report/notify), mỗi lần scaffold tay là một lần lệch convention |
| **VS Code extension API** | Bổ sung manifest v1.1: fields/scopeVars (plan data-scope P1) + bump minor moduleSdk — không breaking |
| **npm workspaces** | Thêm lệnh `opengate-module lint`: check tableName prefix, permission format, migration idempotent — tự động hóa checklist publish |

## 5. Liên kết trong core
- **rt-host** — tiêu thụ .ogapp
- **registry** — đích publish
- **rt-authz** — manifest permissions đổ vào catalog


## Ma trận tác nhân × năng lực

Core không phải module nghiệp vụ — ma trận theo **tác nhân**, kèm cơ chế/quyền gate. R đọc · W thực hiện · A duyệt.

| Năng lực | Cơ chế / quyền gate | SUPER | OWNER/QTHT | DEV | SVC | USER |
|---|---|:--:|:--:|:--:|:--:|:--:|
| dev / build / lint (đích P5) | local, .env module | — | — | W | — | — |
| publish lên registry | token registry (đích P1) | — | — | W | — | — |
| deploy trực tiếp vào host | OPENGATE_TOKEN của host | — | — | W | — | — |
| create từ template (đích P5) | local | — | — | W | — | — |

SUPER = super admin CP · OWNER/QTHT = quản trị WS · DEV = developer/publisher · SVC = service-to-service · USER = người dùng cuối. Mục **(đích)** = theo khuyến nghị P1–P5.