Skip to content

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-apiREST / HTTP server trong repo này
SoT logic + DB dùng chungSDK 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-core

Khô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 build
ts
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àmMục đích
ensureAccountFromIdpProvision/resume Account + Personal Workspace
findByKeycloakSubject / findAccountByIdLookup
listMyWorkspacesDanh sách + default workspace
createOrganizationWorkspaceTạo Organization Workspace
switchWorkspaceContextLưu last workspace
createInvitation / acceptInvitation / declineInvitation / listMyPendingInvitationsInvite
removeMemberGỡ membership
requireActiveMembershipGate membership
checkWorkspaceActionQuyết định authz
expireInvitationsHết hạn invite pending
getPrisma / disconnectPrismaDB client
generatePrefixedIdID 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 build

Không có script dev:http.

7. Quy tắc ​

  1. Truyền acc_… / ws_… — không dùng Keycloak sub làm account_id.
  2. Resolve Account một lần, tái dùng account.id.
  3. Bắt DomainError; không lộ lỗi Prisma ra client.
  4. Migration thuộc repo này; secrets qua Infisical (D-016).
  5. Application không được cài package này.

8. Tài liệu liên quan ​

Tài liệuVai trò
platform-core/README.mdRanh giới repo
01. Platform Core DBSchema + provenance (gói database)
contracts/library-api.mdContract hàm
Feature quickstart.mdValidate AC qua import

docs/ = SoT duy nhất · văn xuôi tiếng Việt + thuật ngữ chuyên ngành English