Appearance
Platform SDK và hợp đồng tích hợp Application
Version: 1.0
Date: 2026-11-12
Status: Working baseline
1. Mục đích
Platform SDK cung cấp helper tích hợp tái sử dụng và client contract để các Application dùng chung hành vi MINAP mà không buộc mọi Application dùng cùng UI framework hay server stack. UI kit trực quan thuộc platform-ui: shadcn-like web kit trên Next.js, Mobile-First, dùng cho browser và RN WebView (D-020) — không thuộc SDK này.
SDK không sở hữu dữ liệu nghiệp vụ và không được biến thành backend ẩn. ID công khai trong kiểu SDK/API theo D-017 ({prefix}_{nanoid}); không lộ integer auto-increment làm business identifier. Application đã đăng ký dùng app_{nanoid} (xem §5 và D-018).
2. Ứng viên năng lực SDK
- Helper tích hợp authentication/session (user session).
- Client Platform API có chứng thực cấu hình bằng Application credentials (
app_id+ token) cho thao tác data/platform (xem §5). - Ngữ cảnh account và Workspace hiện tại.
- Helper launch/navigation Application và deep-link.
- Xử lý lỗi có kiểu cho Platform API.
- Tích hợp localization/i18n.
- Override nhãn ở mức Workspace.
- Helper lấy schema custom field và validation.
- Helper upload/download File Service.
- Tích hợp launch/deep-link Chat.
- Helper trạng thái subscription/entitlement.
- Telemetry và ngữ cảnh correlation.
Ưu tiên lõi SDK nhỏ và ổn định. Chỉ thêm module khi ít nhất hai Application cần cùng năng lực, hoặc khi hợp đồng nền tảng yêu cầu.
3. Custom labels
Mô hình khuyến nghị:
- Application ship nhãn i18n mặc định.
- Workspace có thể override một số nhãn theo từ vựng nghiệp vụ của mình.
- Override khóa theo
application_id(app_…),workspace_id, locale và label key ổn định. - Thứ tự fallback: Workspace override → bundle locale của Application → fallback locale platform/default.
- Không cho phép label key tùy ý đổi ngữ nghĩa API hoặc ý nghĩa trường database.
- Cache kèm version/ETag và invalidate khi cấu hình Workspace đổi.
Ví dụ: nhãn mặc định “Customer” có thể hiển thị thành “Guest” hoặc thuật ngữ nghiệp vụ khác trong một Workspace cụ thể.
4. Custom fields
Tách trách nhiệm khuyến nghị:
- Application định nghĩa các điểm mở rộng custom-field được hỗ trợ cho entity cụ thể.
- Platform cung cấp năng lực schema/cấu hình custom-field tái sử dụng và helper SDK.
- Application vẫn quyết định chỗ nào được phép có custom field và chúng ảnh hưởng rule nghiệp vụ thế nào.
Mỗi định nghĩa custom field nên gồm:
- field key ổn định;
- entity/extension-point key;
- nhãn hiển thị và help text;
- kiểu dữ liệu;
- cờ bắt buộc;
- ràng buộc validation;
- options cho enum/select;
- chính sách visibility và editability;
- trạng thái và schema version.
Kiểu ban đầu cần cân nhắc: text, long text, integer, decimal, boolean, date, datetime, single select, multi-select, URL và email.
Không cho phép script validation thực thi tùy ý. Dùng schema bị ràng buộc (ví dụ subset JSON Schema) và validation phía server. Định nghĩa cách index, filter, export và migrate giá trị trước khi bật use case nâng cao.
5. Chứng thực SDK và Application credentials (D-018)
5.1 Hướng
Mọi dùng SDK truy vấn hoặc thay đổi data liên quan platform/Application phải đi qua Platform HTTP API đã authenticate. SDK là client mỏng; Platform Core (và service sở hữu) vẫn là authority authorization.
5.2 Hai lớp credential (không gộp)
| Lớp | Ai mang | Nơi giữ điển hình | Mục đích |
|---|---|---|---|
| User session | End user sau login | Browser / mobile (OIDC access + refresh qua Keycloak) | Hành động với tư cách người đó trong Workspace |
| Application credential | Application đã đăng ký | Chỉ Application backend | Nhận diện Application khi gọi Platform API (catalog, config, file helpers, entitlements, …) |
Tên làm việc cho secret của Application: Platform API credential (UX kiểu GitHub PAT về sau; kỹ thuật gần machine/client credential). Nhãn sản phẩm chính xác còn OPEN.
5.3 Cặp app_id + token
- Mỗi Application đã đăng ký có id công khai ổn định:
app_{nanoid}(D-017). - Platform Core cấp một hoặc nhiều token/secret gắn với
app_idđó. - Caller trình cặp này (hoặc binding tương đương app identity + secret) trên request API.
- Platform Core sở hữu: Application registry, issue / rotate / revoke credential, gắn scope, rate limit, và audit theo
app_id. - Chỉ lưu hash secret at rest; hiện plaintext một lần lúc tạo. Inject secret runtime qua Infisical (D-016); không commit vào git và không ship trong browser bundle.
5.4 Credential được phép nằm đâu
- Được: server Application, CI/CD, env qua Infisical của Application đó.
- Cấm: secret Application dài hạn trong bản build web/mobile SDK công khai.
- Module SDK browser/mobile có thể dùng token user session; các call data-plane cần danh tính Application đi qua backend Application (hoặc BFF) đang cầm Platform API credential.
5.5 Community / developer mode sau này (hướng, chưa đóng băng MVP)
Khi publish SDK cho cộng đồng:
- Người dùng đăng nhập MINAP Account.
- Xin bật developer mode.
- Platform admin verify yêu cầu.
- Sau kích hoạt, developer tạo/rotate Platform API credential cho Application đã đăng ký — UX tương tự GitHub personal access token, nhưng luôn gắn
app_…(và owner account), không phải key ẩn danh.
MVP có thể chỉ cấp credential cho Application do platform sở hữu (ví dụ Application A) mà chưa có portal developer tự phục vụ.
5.6 Hệ quả kiến trúc SDK
- Ưu tiên module API-first: cấu hình base URL + credentials → HTTP client có kiểu → hợp đồng OpenAPI của Platform.
- Không thêm lối tắt “offline” hay truy cập DB trực tiếp cho data platform.
- Check phía client chỉ hỗ trợ UX; server luôn re-validate authorization.
6. Quy tắc hợp đồng API
Mọi hợp đồng dùng chung phải định nghĩa:
- owner và consumer;
- authentication và authorization (user session và/hoặc Application credential);
- schema request/response;
- mã lỗi;
- idempotency và hành vi retry;
- ngữ nghĩa pagination/filter/sort;
- versioning và chính sách tương thích;
- rate limit và observability;
- phân loại dữ liệu và retention.
Dùng OpenAPI cho HTTP API và schema event tường minh cho tích hợp bất đồng bộ. Tránh chia sẻ truy cập database.
7. Chiến lược đóng gói SDK
- Giữ module SDK trung lập framework khi có thể.
- Chỉ publish package có version cho ecosystem được hỗ trợ khi thực sự cần.
- Với web/mobile, định nghĩa runtime được hỗ trợ và ma trận tương thích.
- Application backend có thể gọi Platform API trực tiếp qua client sinh ra hoặc thư viện service bằng Application credentials.
- Không giả định một JavaScript SDK đáp ứng được PHP hoặc mọi server framework.
- Authorization phía server là chuẩn; check trên client SDK chỉ hỗ trợ UX, không phải biên bảo mật.
8. Câu hỏi mở
- Cấu hình label/custom-field nằm trong Platform Core hay module cấu hình riêng.
- Entity Application nào mở điểm mở rộng custom-field.
- Custom field có nằm trong search/report/export không.
- Tên package SDK, quy trình release và semantic versioning.
- Tên sản phẩm và wire format chính xác của Platform API credential (header scheme, token prefix, độ dài).
- Scope mặc định/tối đa mỗi credential; scope gắn Workspace, Application, hay cả hai.
- Lifetime, chính sách rotate, grace sau rotate, và playbook khi lộ credential.
- Bao nhiêu credential active mỗi
app_id(ví dụ dual-key) và tách env (dev/staging/prod). - MVP: chỉ credential do platform cấp, hay sớm có portal developer mode.
- Tiêu chí và SLA verify của Platform admin cho community developer mode.
- Cách ghép Application credential với user session khi API “thay mặt user X qua app Y” (delegation / on-behalf-of) — nếu cần.