@thanhphi/create-360-miniapp 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 thanhphi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,80 @@
-# Temporary Holding Version
+# @thanhphi/create-360-miniapp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Khởi tạo mini app theo cấu trúc Event và Time-Management: Expo 55, React Native 0.83.6, TypeScript, React Navigation, Redux Toolkit, TanStack Query và Re.Pack 5. Template có sẵn module auth, module nghiệp vụ mẫu, kết nối token host qua `@thanhphi/miniapp-sdk`, env staging/beta/prod và pipeline Azure.
+
+## Dùng ngay từ source
+
+Từ `mysgr-shared`:
+
+```sh
+node packages/create-360-miniapp/bin/create-360-miniapp.cjs leave-management --module leave --app-code LVE --port 8085
+cd leave-management
+npm install
+npm run env:staging
+npm run start:mf
+```
+
+Lệnh chỉ tạo thư mục mới, không ghi đè app hiện có. Mặc định không install hoặc tạo Git repository. `--install` cài dependencies; `--native` cài rồi chạy Expo prebuild để tạo project `ios/` và `android/`. Native project dùng ID riêng của app mới. Chi tiết auth, cấu trúc và pipeline nằm trong README của app được sinh.
+
+## Chạy bằng npx từ tarball local
+
+Từ `mysgr-shared`, sau `npm run pack:check`:
+
+```sh
+npx --offline --yes --cache ./artifacts/.npm-cache --package ./artifacts/thanhphi-create-360-miniapp-0.2.0.tgz create-360-miniapp leave-management --module leave --app-code LVE
+```
+
+Lệnh này dùng package đã đóng gói, không cần publish registry hoặc source Event/Time-Management. Cache nằm trong `artifacts`, cùng workspace.
+
+## Qua npm sau khi publish package
+
+```sh
+npx @thanhphi/create-360-miniapp@0.2.0 leave-management --module leave --app-code LVE
+# npm create là alias npm init và ánh xạ tới @thanhphi/create-360-miniapp:
+npm create @thanhphi/360-miniapp@0.2.0 leave-management -- --module leave --app-code LVE
+```
+
+Theo [quy tắc npm initializer](https://docs.npmjs.com/cli/v11/commands/npm-init/), `npm create @thanhphi/360-miniapp` chạy package `@thanhphi/create-360-miniapp`. Package này cần được publish trước khi tên registry hoạt động.
+
+Tên package có scope `@thanhphi/create-360-miniapp` là tên đầy đủ trên npm; `create-360-miniapp` là tên executable trong `bin`. Package `create-360-miniapp` không có scope và package cùng tên dưới scope khác có thể do người khác sở hữu. Để chọn đúng generator, dùng tên có scope như ví dụ trên hoặc chỉ định tarball bằng `--package`. Scope cho phép cùng tên package dưới các namespace khác nhau; publish cần quyền trong scope tương ứng. Xem [npm scopes](https://docs.npmjs.com/about-scopes/).
+
+## Options
+
+| Option | Mặc định |
+| --- | --- |
+| `--module` | Tên app, dùng cho `src/modules/<module>` |
+| `--container` | PascalCase tên app, dùng cho federation container |
+| `--app-code` | Tối đa 12 ký tự đầu tên app, viết hoa |
+| `--bundle-id` | `com.sungroup.<tên-app-bỏ-dấu-gạch>` |
+| `--display-name` | Tên container |
+| `--port` | `8085`; chọn port khác nếu có mini app đang chạy |
+| `--env` | `staging`; hỗ trợ `beta`, `prod` |
+| `--install` | Không cài dependencies nếu bỏ option |
+| `--native` | Không prebuild nếu bỏ option |
+
+## Kiểm tra và đóng gói
+
+```sh
+npm run test:create
+npm run pack:check
+# Hoặc chỉ package generator:
+npm pack --workspace @thanhphi/create-360-miniapp --pack-destination artifacts
+```
+
+Generator không có runtime dependency: tarball chứa CLI và toàn bộ template, không cần truy cập thư mục Event/Time-Management khi người dùng chạy CLI. Bộ kiểm tra source/generator có guard cho entry hosted–standalone, capability auth, token không persist, provider chuyển tiếp token và cách dùng shared UI. Kết quả kiểm thử app sinh của bản trước là snapshot lịch sử; đợt chuẩn hóa hiện tại chưa chạy lại build/test/typecheck hoặc tạo tarball mới.
+
+Để publish sau khi kiểm tra tarball và đăng nhập đúng tài khoản:
+
+```sh
+npm publish --workspace @thanhphi/create-360-miniapp --access public
+```
+
+Không publish root workspace. Đây là hướng dẫn phát hành; việc tạo source/tarball không tự publish lên npm.
+
+Template 0.2.0 dùng contract tên màu của UI360 0.2.0, Unistyles 3.2.5/Nitro 0.36.5. Generator tạo đầy đủ mã hex trong src/themes/colors/light.ts và dark.ts để app tự quản lý. Một factory native tạo đủ màu/mode/spacing/radius/typography; ApplicationProvider chỉ chuyển tiếp token đang hoạt động, không tạo lại default hoặc scale. Màn hình/navigation dùng Unistyles color; shared UI giữ useUITheme bên trong package.
+
+Hosted không khởi tạo global, nhận toàn bộ native theme của host. Standalone cấu hình tại src/themes/standalone.ts; factory mặc định dùng DEVICE_WIDTH / 375 như host 360 và typography UI360 body 14/title 18 trước scale, không giữ body 16/title 22/scale 1 của template cũ. Scale áp dụng một lần tại factory, override số đã là dp; không qua props.uiTheme. Màn mẫu dùng Button/UIText trực tiếp và style lấy token theme, không có ActionButton chỉ để bọc shared Button.
+
+App mới bắt buộc nhận HostCapabilities khi hosted: identity/token từ auth.getSnapshot/subscribe/refreshIfNeeded và đóng app qua closeMiniApp. Không có adapter props token/callback/sessionId cũ, không suy diễn identity từ access token. Exposed App thiếu capability báo host không tương thích, không tự chuyển sang OIDC; chỉ entry standalone chọn adapter đăng nhập độc lập. Host hiện tại đã cấp capability/session ID, nhưng cần cập nhật hoặc gate catalog cho các bản host cũ trước rollout. param_supper_app vẫn phục vụ dữ liệu mở app/thông báo.
+
+Chưa tách runtime riêng. Card trắng dùng background, nền màn dùng base3; textPrimary không còn là chữ nội dung. Cần đóng gói/phát hành generator mới để npx từ registry có template này; thay source chưa tự cập nhật tarball hoặc app đã sinh. Lần thay đổi source này không chạy install, build/test, typecheck/lint hoặc publish.

package/bin/create-360-miniapp.cjs

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+const { spawnSync } = require('node:child_process');
+const { createApp } = require('../lib/create.cjs');
+
+const help = `Create a MySGR mini app (Expo 55 / React Native 0.83 / Re.Pack 5)
+
+  npx @thanhphi/create-360-miniapp my-app [options]
+  npm create @thanhphi/360-miniapp@latest my-app -- [options]
+
+Options:
+  --module <slug>       Feature module folder (default: app name)
+  --container <Name>    Federation container (default: PascalCase app name)
+  --app-code <CODE>     Backend mini-app code
+  --bundle-id <id>      Unique Android/iOS application ID
+  --display-name <name> Native display name
+  --port <number>       Re.Pack dev server port (default: 8085)
+  --env <flavor>        Initial staging, beta or prod (default: staging)
+  --install            Install dependencies and create package-lock.json
+  --native             Install if needed, then generate ios/ and android/
+  --help               Show usage
+  --version            Show generator version
+`;
+
+function main(argv) {
+  if (argv.includes('--help') || argv.includes('-h')) return process.stdout.write(help);
+  if (argv.includes('--version')) return process.stdout.write(require('../package.json').version + '\n');
+  const options = {};
+  const values = { '--module': 'module', '--container': 'container', '--app-code': 'appCode', '--bundle-id': 'bundleId', '--display-name': 'displayName', '--port': 'port', '--env': 'env' };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--') continue;
+    if (arg === '--install' || arg === '--native') options[arg.slice(2)] = true;
+    else if (values[arg]) {
+      const value = argv[++i];
+      if (!value || value.startsWith('--')) throw new Error(`Missing value for ${arg}.`);
+      options[values[arg]] = value;
+    } else if (arg.startsWith('-')) throw new Error(`Unknown option: ${arg}.`);
+    else if (options.name) throw new Error(`Unexpected argument: ${arg}.`);
+    else options.name = arg;
+  }
+  const app = createApp(options);
+  process.stdout.write(`Created ${app.appName} at ${app.destination}\n`);
+  function run(args) {
+    const result = spawnSync(process.platform === 'win32' ? 'npm.cmd' : 'npm', args, { cwd: app.destination, stdio: 'inherit', shell: process.platform === 'win32' });
+    if (result.error) throw result.error;
+    if (result.status !== 0) throw new Error(`npm ${args.join(' ')} failed. App files remain in ${app.destination}; fix the error and retry there.`);
+  }
+  if (options.install || options.native) run(['install']);
+  if (options.native) run(['exec', '--', 'expo', 'prebuild']);
+  process.stdout.write(`\nNext:\n  cd ${options.name}\n${options.install || options.native ? '' : '  npm install\n'}  npm run env:${app.environment}\n  npm run start:mf\n\nStandalone: npm run ios:${app.environment} or android:${app.environment}\nRead README.md for env, auth, host registration and pipeline setup.\n`);
+}
+
+try { main(process.argv.slice(2)); }
+catch (error) { process.stderr.write(`create-360-miniapp: ${error.message}\n`); process.exitCode = 1; }

package/lib/create.cjs

@@ -0,0 +1,56 @@
+const fs = require('node:fs');
+const path = require('node:path');
+
+const template = path.resolve(__dirname, '../template');
+const reserved = new Set(['auth', 'common', 'library', 'redux', 'navigation', 'themes']);
+
+function createApp(options, cwd = process.cwd()) {
+  const name = options.name;
+  if (!/^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/.test(name || '')) {
+    throw new Error('App name must be a lowercase slug, e.g. leave-management.');
+  }
+  const moduleName = options.module || name;
+  if (!/^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/.test(moduleName) || reserved.has(moduleName)) {
+    throw new Error('Module must be a lowercase feature name; auth and framework folders are reserved.');
+  }
+  const appName = options.container || name.split('-').map(part => part[0].toUpperCase() + part.slice(1)).join('');
+  if (!/^[A-Z][A-Za-z0-9]*$/.test(appName)) throw new Error('Container must be a PascalCase identifier.');
+  const appCode = options.appCode || name.replace(/-/g, '').slice(0, 12).toUpperCase();
+  if (!/^[A-Z][A-Z0-9_]{0,31}$/.test(appCode)) throw new Error('App code must contain uppercase letters, digits or underscore.');
+  const port = Number(options.port || 8085);
+  if (!Number.isInteger(port) || port < 1024 || port > 65535) throw new Error('Port must be an integer between 1024 and 65535.');
+  const bundleId = options.bundleId || `com.sungroup.${name.replace(/-/g, '')}`;
+  if (!/^[a-z][a-z0-9]*(?:\.[a-z][a-z0-9]*){2,}$/.test(bundleId)) throw new Error('Bundle ID must be a lowercase reverse-domain identifier without underscores.');
+  const displayName = options.displayName || appName;
+  // The same replacement is used in JS, JSON, Markdown and YAML. Keep it safe in all formats.
+  if (!/^[\p{L}\p{N} _.-]{1,80}$/u.test(displayName)) throw new Error('Display name can contain letters, numbers, spaces, dots, underscores and hyphens.');
+  const environment = options.env || 'staging';
+  if (!['staging', 'beta', 'prod'].includes(environment)) throw new Error('Environment must be staging, beta or prod.');
+  const destination = path.resolve(cwd, name);
+  if (fs.existsSync(destination)) throw new Error(`Destination already exists: ${destination}. Choose a new directory.`);
+  const replacements = {
+    __APP_NAME__: appName, __DISPLAY_NAME__: displayName, __PACKAGE_NAME__: name,
+    __APP_ID__: name, __APP_CODE__: appCode, __MODULE__: moduleName,
+    __PORT__: String(port), __BUNDLE_ID__: bundleId,
+  };
+  function render(value) {
+    return value.replace(/__(?:APP_NAME|DISPLAY_NAME|PACKAGE_NAME|APP_ID|APP_CODE|MODULE|PORT|BUNDLE_ID)__/g, key => replacements[key]);
+  }
+  function copy(directory, target) {
+    fs.mkdirSync(target, { recursive: true });
+    for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+      const source = path.join(directory, entry.name);
+      // npm strips .gitignore; keep it as a normal file inside the published template.
+      const output = path.join(target, entry.name === 'gitignore' ? '.gitignore' : render(entry.name));
+      if (entry.isDirectory()) copy(source, output);
+      else if (entry.isFile()) fs.writeFileSync(output, render(fs.readFileSync(source, 'utf8')));
+      else throw new Error(`Unsupported template entry: ${source}`);
+    }
+  }
+  copy(template, destination);
+  const { syncEnv } = require(path.join(destination, 'scripts/sync-env.js'));
+  syncEnv(environment, destination);
+  return { destination, appName, moduleName, environment, port };
+}
+
+module.exports = { createApp };

package/package.json

@@ -1,6 +1,11 @@
 {
   "name": "@thanhphi/create-360-miniapp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Create a MySGR Expo and Re.Pack mini app with modules, host auth and Azure pipelines",
+  "license": "MIT",
+  "bin": { "create-360-miniapp": "bin/create-360-miniapp.cjs" },
+  "files": ["bin", "lib", "template", "README.md", "LICENSE"],
+  "scripts": { "test": "node --test tests/*.test.cjs" },
+  "publishConfig": { "access": "public", "registry": "https://registry.npmjs.org/" },
+  "engines": { "node": ">=20" }
+}

package/template/.eslintrc.cjs

@@ -0,0 +1 @@
+module.exports = { root: true, extends: '@react-native', ignorePatterns: ['build/', 'env/env-config.ts'] };

package/template/.prettierrc.cjs

@@ -0,0 +1 @@
+module.exports = { singleQuote: true, trailingComma: 'all', arrowParens: 'avoid' };

package/template/.watchmanconfig

@@ -0,0 +1 @@
+{}

package/template/App.tsx

@@ -0,0 +1,2 @@
+import 'react-native-gesture-handler';
+export { default } from './src/StandaloneApp';

package/template/README.md

@@ -0,0 +1,234 @@
+# __DISPLAY_NAME__
+
+Base TypeScript lấy Event làm nền, giữ thêm `constants`, `hooks`, `services` quen thuộc của Time Management; expose `__APP_NAME__/MiniApp` để MySGR tải qua Re.Pack, chạy độc lập bằng Expo là tùy chọn phục vụ dev. Đây là chuẩn cho app mới, không mang adapter host cũ hoặc quy tắc giao diện legacy của các app nguồn.
+
+## Theme 360 / UI360 0.2.0
+
+- Mã hex nằm ngay trong src/themes/colors/light.ts và dark.ts của app. @thanhphi/ui360 chỉ chia sẻ contract tên màu/component/factory, không sở hữu palette thương hiệu.
+- src/themes/index.ts có một factory tạo đủ màu/mode, spacing, radius và typography; chỉ khai báo giá trị/hàm khi import, không tự cấu hình runtime. Hosted src/App.tsx không import setup global.
+- src/themes/standalone.ts chọn mode/override phục vụ dev và gọi configureStandaloneTheme từ factory đó. StandaloneApp và bootstrap standalone import file này sau ranh giới federation bootstrap.
+- ApplicationProvider đọc đầy đủ token đang hoạt động từ Unistyles rồi chuyển tiếp type → mode, color → colors cùng spacing/radius/typography vào UIThemeProvider. Không tạo bộ default thứ hai hoặc scale lại ở provider; không dùng props.uiTheme để override riêng shared UI.
+- Navigation và màn hình thuộc app dùng useUnistyles để lấy color/spacing/typography; style riêng tiếp tục StyleSheet.create(({ color }) => (...)), xem ProfileCard. useUITheme nằm bên trong thư viện shared.
+- Factory mặc định dùng scale DEVICE_WIDTH / 375 như host 360, với typography chuẩn UI360 (body 14/title 18 trước scale). Scale chỉ áp dụng một lần lúc dựng default geometry; override số trong standaloneThemeOptions đã là dp. Hosted nhận đầy đủ token của host, không ép default standalone lên host hoặc scale lại ở provider/màn hình.
+- Màn mẫu dùng Button/UIText từ shared, spacing/radius/typography từ theme. Không tạo ActionButton chỉ để bọc Button hoặc ép một chuẩn chiều cao khác.
+- Chưa tách runtime riêng. Palette local phục vụ khởi tạo mặc định/standalone, không tự cô lập global Unistyles. Muốn đổi màu riêng toàn mini app khi hosted cần áp dụng theme đồng bộ cho native và shared theo phạm vi app.
+- content1 là chữ nội dung; textPrimary là chữ trên nút primary. base3 là nền màn, base2 là nền hồng có chủ ý; card trắng dùng background.
+- Native host cần Unistyles 3.2.5/Nitro 0.36.5 và UI360 0.2.0. Base khai báo expo-image vì đây là peer của UI360. Cài đặt lại dependencies sau khi publisher phát hành package tương ứng.
+
+| Cấu hình | Giá trị |
+| --- | --- |
+| Package | `__PACKAGE_NAME__` |
+| Federation container | `__APP_NAME__` |
+| App ID / code trong catalog | `__APP_ID__` / `__APP_CODE__` |
+| Module nghiệp vụ | `__MODULE__` |
+| Re.Pack port | `__PORT__` |
+| Native bundle ID | `__BUNDLE_ID__` |
+
+## Tạo project khác từ base
+
+Sau khi `@thanhphi/create-360-miniapp` được publish lên registry:
+
+```sh
+npx @thanhphi/create-360-miniapp@latest demo --module sample --port 8085 --bundle-id com.sungroup.demo
+npm create @thanhphi/360-miniapp@latest demo -- --module sample --port 8085 --bundle-id com.sungroup.demo
+```
+
+`npm create @thanhphi/360-miniapp` ánh xạ tới `@thanhphi/create-360-miniapp` theo [npm init/create](https://docs.npmjs.com/cli/v11/commands/npm-init/). Khi chưa publish, chạy từ thư mục `mysgr-shared`:
+
+```sh
+node packages/create-360-miniapp/bin/create-360-miniapp.cjs demo --module sample --port 8085 --bundle-id com.sungroup.demo
+```
+
+CLI mặc định chỉ sinh file. Thêm `--install` để chạy npm install, thêm `--native` để cài dependencies rồi prebuild native. CLI không khởi tạo git repository.
+
+## Chạy lần đầu
+
+Dùng Node/npm theo `package.json`, Xcode/CocoaPods để chạy iOS, Android SDK/JDK để chạy Android. Cấu hình env trước khi tạo native build.
+
+```sh
+npm install
+npm run env:staging
+npx expo prebuild
+npm run ios:staging
+# hoặc
+npm run android:staging
+```
+
+`npx expo prebuild` tạo project `ios/` và `android/` theo `__BUNDLE_ID__`; source/env/pipeline giữ nguyên. AppAuth và các native dependencies cần development build. Xem [Expo SDK 55](https://docs.expo.dev/versions/v55.0.0/) và [Expo prebuild](https://docs.expo.dev/workflow/continuous-native-generation/).
+
+Commit lockfile được sinh sau `npm install` để CI có thể dùng `npm ci`. Lần sau dùng:
+
+```sh
+npm run start:staging
+npm run start:beta
+npm run start:prod
+npm run typecheck
+npm run lint
+npm test
+```
+
+## Thư mục và nơi thêm code
+
+```text
+assets/                         # static assets cấp app
+declare/                        # ambient declarations cho assets
+env/                            # JSON các flavor và env-config.ts sinh ra
+pipelines/templates/            # Azure build/ZIP, upload/register
+scripts/                        # sync env và build remote
+src/
+  assets/                       # assets nhập từ source
+  common/                       # mini-app runtime và host adapter
+  config/                       # cấu hình dùng trong app
+  constants/                    # hằng số cấp app
+  hooks/                        # hook dùng chung
+  library/
+    components/                 # UI dùng lại trong app
+    networking/                 # SDK HTTP client
+    utils/                      # helper không thuộc nghiệp vụ
+  modules/
+    auth/                       # màn/login service/redux/navigation auth
+    __MODULE__/                 # screens/navigation/redux/services/types nghiệp vụ
+  navigation/                   # root navigator
+  redux/                        # store factory, reducers và typed hooks
+  services/                     # application composition, runtime/store/cache/client
+  themes/                       # theme của app
+  types/                        # contract app, assets và kiểu dùng chung
+  App.tsx
+  bootstrap.tsx
+```
+
+Thêm màn/service/state trong `src/modules/__MODULE__`; endpoint thuộc service của module. `src/services/application.ts` chỉ nối các thành phần cấp app. `ios/`/`android/` được Expo prebuild sinh khi chạy độc lập. Không cần native build riêng để chỉ tạo remote bundle.
+
+## Env
+
+Sửa `env/staging.json`, `env/beta.json`, `env/prod.json`. Script sinh `env/env-config.ts`; không sửa file sinh trực tiếp. Các lệnh có hậu tố môi trường sync JSON trước khi start/build.
+
+```json
+{
+  "ENV": "staging",
+  "BASE_URL": "https://api.example.com",
+  "API_TIMEOUT_MS": 15000,
+  "AUTH": {
+    "issuer": "https://identity.example.com",
+    "clientId": "your-native-client-id",
+    "redirectUrl": "__BUNDLE_ID__.auth://oauth/redirect",
+    "scopes": ["openid", "profile", "offline_access"]
+  }
+}
+```
+
+Issuer, client ID, scope và URL là placeholder; thay bằng cấu hình public của provider/API. Mọi giá trị env này được đưa vào bundle. Không đặt client secret, private key, mật khẩu hay token trong JSON. Secret CI dùng secret variables/service connections.
+
+Các script gọi trực tiếp Expo/Re.Pack như Event và Time Management. Chọn môi trường bằng `env:staging`, `env:beta` hoặc `env:prod` trước khi chạy Re.Pack hoặc bundle. Các lệnh `start:<flavor>`, `ios:<flavor>` và `android:<flavor>` chọn env rồi gọi Expo trực tiếp. Đổi env cần restart Metro/Re.Pack.
+
+Khi đổi redirect URL, cập nhật cấu hình provider và chạy lại prebuild/build để native redirect được áp dụng. App config đọc redirect cho AppAuth plugin. Xem [AppAuth Expo config plugin](https://github.com/FormidableLabs/react-native-app-auth/blob/main/docs/docs/usage/expo-setup.md).
+
+## Auth và token khi chạy trong MySGR
+
+Hosted bắt buộc dùng `HostCapabilities`. Host hiện tại đã cấp capability/session ID chung; template không nhận các prop token/callback/session ID legacy và không có adapter tự suy diễn identity từ access token.
+
+```tsx
+import MiniApp from './src/App';
+import type { HostCapabilities } from '@thanhphi/miniapp-sdk';
+
+const capabilities: HostCapabilities = {
+  auth: {
+    getSnapshot: () => hostAuth.getSnapshot(),
+    refreshIfNeeded: input => hostAuth.refreshIfNeeded(input),
+    subscribe: listener => hostAuth.subscribe(listener),
+  },
+  closeMiniApp: () => navigation.goBack(),
+};
+
+// Phía host: `hostAuth` và `navigation` là service/navigation thật.
+// Giữ object capabilities ổn định (ví dụ useMemo trong component host).
+<MiniApp
+  hostCapabilities={capabilities}
+  param_supper_app={{ notifications: notification }}
+/>;
+```
+
+Host cấp session ID mới khi login/logout/đổi tài khoản, giữ session ID khi refresh token; cập nhật snapshot trước khi phát subscription. Host sở hữu refresh token, persistence và coordinator refresh chung. Không đưa refresh token vào props mini app.
+
+Mini app đọc identity/token bằng `auth.getSnapshot()`, theo dõi thay đổi bằng `auth.subscribe()` và nhờ host refresh qua `auth.refreshIfNeeded()`; đóng app qua `closeMiniApp()`. `param_supper_app` vẫn là dữ liệu mở app/thông báo, không dùng để cấp token hay nhận diện phiên. Một lần refresh chỉ đổi access token không được reset dữ liệu nghiệp vụ nếu session ID không đổi.
+
+Exposed `App` luôn là hosted: thiếu capability thì báo cấu hình host không tương thích, không tự chuyển sang màn OIDC standalone. Chỉ entry standalone chủ động chọn adapter OIDC. Host đã phát hành nhưng chưa có capability không tương thích template mới; phải cập nhật binary/host hoặc chặn phiên bản qua catalog trước khi deploy remote này. Base không thay host registry; thêm app ID `__APP_ID__`, container `__APP_NAME__`, import `__APP_NAME__/MiniApp` và URL/port `__PORT__` trong registry/resolver của MySGR theo môi trường triển khai.
+
+HTTP dùng `@thanhphi/miniapp-sdk`: tự gắn `Authorization: Bearer <accessToken>`, refresh và retry tối đa một lần sau HTTP 401. Client nhận route tương đối theo `BASE_URL`; service module tự unwrap response envelope. Demo gọi đường dẫn `/me`; chỉnh `PROFILE_PATH` trong service của module cho backend thật. Nếu backend báo token hết hạn trong HTTP 200 envelope, cấu hình `isAuthExpired` trong `src/library/networking/client.ts` theo response contract của API.
+
+Service dùng client được tạo theo runtime, chẳng hạn:
+
+```ts
+import type { ApiClient } from './src/library/networking/client';
+
+export async function loadItem(api: ApiClient, itemId: string) {
+  return api.get<{ id: string; name: string }>(
+    `/items/${encodeURIComponent(itemId)}`,
+  );
+}
+```
+
+Runtime/store/client/QueryClient có vòng đời theo mount. Identity đổi reset auth/state và cancel/clear queries của phiên cũ; unmount hủy subscriptions, cancel/clear cache và dispose client/runtime. `AuthError.kind` phân biệt `expired`, `session-changed`, `unavailable`; lỗi mạng tạm thời không được coi như logout.
+
+## Auth standalone
+
+Chỉ khi chạy entry standalone, app dùng adapter riêng và có màn đăng nhập OIDC qua `react-native-app-auth`. Không phát hiện standalone bằng việc thiếu props host. Adapter standalone đóng vai host, giữ access/refresh token trong bộ nhớ, dùng coordinator để chia sẻ refresh và kiểm tra identity trước khi lưu kết quả. Đóng app hoặc reset runtime sẽ mất phiên này; muốn lưu phiên cần thêm secure native storage. Không persist token do host cấp vào Redux/storage của mini app.
+
+Đăng ký native OAuth client và redirect `__BUNDLE_ID__.auth://oauth/redirect` với provider; chọn scopes cho API audience, rồi thay env của từng flavor. `openid/profile/offline_access` không tự cấp quyền gọi API của bạn. Backend MySGR có thể yêu cầu đổi Azure token sang token riêng: thêm flow exchange trong service auth, với endpoint/body đúng backend. Base không giả định endpoint exchange, không dùng ID token làm API access token. Login và profile demo chỉ có dữ liệu thật sau khi provider/API được cấu hình.
+
+## Re.Pack và build remote
+
+```sh
+npm run env:staging
+# hoặc env:beta / env:prod
+npm run start:mf
+
+# Thiết bị thật hoặc reset cache
+npm run start:mf:device
+npm run start:mf:reset
+
+# Bundle dùng env đã chọn
+npm run bundle:mf:android
+npm run bundle:mf:ios
+```
+
+Dev server chạy port `__PORT__`; resolver của host phải trỏ đúng server đó. Với thiết bị thật, dùng IP LAN của máy và bảo đảm thiết bị truy cập được dev server. Host phải có native modules và singleton versions tương thích với dependencies remote; thêm native package vào mini app cần cập nhật binary host trước khi sử dụng.
+
+Output deploy:
+
+```text
+build/outputs/android/remotes/__APP_NAME__.container.js.bundle
+build/outputs/ios/remotes/__APP_NAME__.container.js.bundle
+build/outputs/<platform>/remotes/*.chunk.bundle
+```
+
+ZIP toàn bộ nội dung `remotes`, bỏ `*.map`; container cần các chunk đi kèm. `build/generated/<platform>/index.bundle` là entry standalone và không upload cho host. Script clean output từng platform trước bundle để không đưa chunk cũ vào archive. Pipeline giữ SHA-1 vì catalog/host hiện dùng checksum này.
+
+## Pipeline Azure DevOps
+
+Các YAML trong `pipelines/` chọn flavor/branch và dùng chung `pipelines/templates`. Mặc định chỉ build, đóng ZIP và publish artifacts. Bật deployment sau khi cấu hình Azure/DB thật; xem các parameters/variables trong YAML, không đưa secret vào git.
+
+Pipeline có `parameters.deploy: false`, `parameters.agentPool` mặc định Ubuntu và `parameters.nodeVersion`. Các flavor là `pipelines/staging.yml`, `beta.yml`, `production.yml`. Khi `deploy: true`, cấu hình các biến sau trong Azure Pipeline/variable group:
+
+| Biến | Mục đích |
+| --- | --- |
+| `MINIAPP_AZURE_SUBSCRIPTION` | Azure service connection có quyền upload Blob |
+| `MINIAPP_STORAGE_ACCOUNT` | Tên Storage Account |
+| `MINIAPP_STORAGE_CONTAINER` | Blob container chứa ZIP |
+| `DB_HOST`, `DB_LOGIN`, `DB_DATABASE` | PostgreSQL host/user/database của mini app catalog |
+| `DB_PASSWORD` | Mật khẩu PostgreSQL, đánh dấu secret |
+| `appName`, `appId`, `appCode` | Container `__APP_NAME__`, catalog ID `__APP_ID__`, code `__APP_CODE__` |
+| `envBuild`, `envFolder` | Flavor env và folder Blob của môi trường |
+| `miniAppVersion` | Version artifact, mặc định `$(Build.BuildNumber)` |
+
+Pipeline cần agent có Node/npm, `zip`, `sha1sum`; deployment cần Azure CLI và `psql`, truy cập mạng đến PostgreSQL. DB kết nối SSL (`PGSSLMODE=require`); schema cần bảng `mini_app` và `mini_app_version` phù hợp host. ZIP nằm ở `appId/envFolder/platform/version.zip` trong Blob. Metadata được ghi sau upload thành công. Version nên duy nhất vì upload không ghi đè archive đã có. Cài lần đầu có thể dùng npm install khi chưa có lockfile; các lần sau dùng npm ci từ lockfile đã commit.
+
+Build cả Android/iOS remote chỉ tạo JavaScript artifacts, không tạo IPA/APK. Có thể chạy build-only CI trước khi cấu hình deployment.
+
+Base chưa tự đăng ký app trên hạ tầng và không tự publish npm package. Provider login/native redirect, native binary, tích hợp host và deployment vào Azure thật cần được kiểm chứng trong môi trường của app.
+
+## Kiểm tra trước khi phát hành
+
+Source generator có guard kiểm tra entry hosted không kéo standalone setup, chỉ nhận capability auth, không persist token hosted, provider không tạo bộ token thứ hai và màn mẫu dùng shared UI/theme token thay vì wrapper/alias legacy. Chạy `npm run test:create` từ workspace để kiểm tra source generator; các guard này không thay thế thử runtime/native trên host.
+
+Đợt chuẩn hóa source này không chạy build/test, install, typecheck/lint, đóng gói hoặc publish. App đã sinh, tarball cũ và package trên registry không tự cập nhật theo template nguồn.