Appearance
Hướng dẫn sử dụng Platform Core
Version: 1.1
Date: 2026-11-16
Status: Working baseline
Mô hình tích hợp: Chỉ import thư viện (Owner quyết định 2026-11-16)
1. Đây là gì?
platform-core là SoT chung của Platform Core: hàm TypeScript domain + PostgreSQL cho Account / Workspace / Membership (sau này: catalog, entitlement, credential app_…).
| Dùng như | Không dùng như |
|---|---|
Thư viện in-process cho platform-web BE, platform-admin BE, platform-api | REST / HTTP server trong repo này |
| SoT logic + DB dùng chung | SDK browser / mobile |
| Thứ Application import trực tiếp |
text
platform-web FE → platform-web BE → import @minap/platform-core
platform-admin FE → platform-admin BE → import @minap/platform-core
application-* → platform-sdk → platform-api → import @minap/platform-coreKhông còn /internal/v1 trong package này. Nếu cần HTTP, caller (portal BE hoặc platform-api) tự sở hữu tầng HTTP và map sang hàm domain.
2. Phụ thuộc và build
json
{
"dependencies": {
"@minap/platform-core": "file:../platform-core"
}
}bash
cd platform-core
npm ci
npm run prisma:generate
npm run buildts
import {
getPrisma,
ensureAccountFromIdp,
listMyWorkspaces,
createOrganizationWorkspace,
checkWorkspaceAction,
DomainError,
} from "@minap/platform-core";Ưu tiên barrel công khai (src/index.ts). Không deep-import persistence nội bộ trừ khi đã export.
3. Ai validate token IdP?
Caller (portal BE / platform-api) validate JWT Keycloak, rồi truyền keycloak_subject / email đã tin cậy vào hàm domain. Helper tùy chọn: createTokenValidator, mapClaimsToEnsureInput, MockTokenValidator / encodeMockToken (test).
4. Ví dụ tối thiểu (sau login)
ts
const db = getPrisma(process.env.DATABASE_URL);
try {
const ensured = await ensureAccountFromIdp(db, {
keycloak_subject: claims.sub,
email: claims.email,
display_name: claims.name ?? null,
});
const workspaces = await listMyWorkspaces(db, ensured.account.id);
return { ensured, workspaces };
} catch (err) {
if (err instanceof DomainError) {
// map err.code / err.statusCode sang HTTP response của bạn
}
throw err;
}5. Bản đồ hàm
| Hàm | Mục đích |
|---|---|
ensureAccountFromIdp | Provision/resume Account + Personal Workspace |
findByKeycloakSubject / findAccountById | Lookup |
listMyWorkspaces | Danh sách + default workspace |
createOrganizationWorkspace | Tạo Organization Workspace |
switchWorkspaceContext | Lưu last workspace |
createInvitation / acceptInvitation / declineInvitation / listMyPendingInvitations | Invite |
removeMember | Gỡ membership |
requireActiveMembership | Gate membership |
checkWorkspaceAction | Quyết định authz |
expireInvitations | Hết hạn invite pending |
getPrisma / disconnectPrisma | DB client |
generatePrefixedId | ID theo D-017 |
Chi tiết: specs/.../contracts/library-api.md
6. Chạy local (thư viện + test)
bash
cd platform-core
cd deploy && docker compose up -d postgres && cd ..
cp .env.example .env # không commit
npm ci
npm run prisma:generate
npm run prisma:migrate
npm run test:unit
export DATABASE_URL=postgresql://minap:minap@localhost:5432/platform_core
export IDP_MODE=test
npm test
npm run buildKhông có script dev:http.
7. Quy tắc
- Truyền
acc_…/ws_…— không dùng Keycloaksublàmaccount_id. - Resolve Account một lần, tái dùng
account.id. - Bắt
DomainError; không lộ lỗi Prisma ra client. - Migration thuộc repo này; secrets qua Infisical (D-016).
- Application không được cài package này.
8. Tài liệu liên quan
| Tài liệu | Vai trò |
|---|---|
platform-core/README.md | Ranh giới repo |
| 01. Platform Core DB | Schema + provenance (gói database) |
contracts/library-api.md | Contract hàm |
Feature quickstart.md | Validate AC qua import |