@h-ai/cli 0.1.0-alpha9 → 1.0.0-beta.2

package/templates/apps/fullstack/e2e/session-close.spec.ts.hbs

@@ -0,0 +1,119 @@
+{{! @skipIfEmpty }}
+{{#if fullstack.e2eFrontend}}
+import type { Page } from '@playwright/test'
+import process from 'node:process'
+import { expect, test } from '@playwright/test'
+
+const configAdminPassword = process.env.E2E_CONFIG_ADMIN_PASSWORD || 'Scaffold-test-Config123!'
+
+async function dismissToasts(page: Page) {
+  const dismiss = page.locator('.hai-toast-layer').getByRole('button', { name: /^(关闭|Dismiss|閉じる)$/ })
+  for (let count = 0; count < 10 && await dismiss.count(); count++)
+    await dismiss.click()
+}
+
+async function login(page: Page, username = 'admin', initialPassword = process.env.E2E_ADMIN_PASSWORD || 'Scaffold-test-Admin123!') {
+  await page.goto('/')
+  await page.locator('#login-username').fill(username)
+  await page.getByTestId('login-form').locator('input[type=password]').fill(initialPassword)
+  await page.getByTestId('login-form').locator('button[type=submit]').click()
+  // 每例使用独立初始账号，真实完成服务端限制下的首次改密后才能建立普通会话。
+  await expect(page.locator('#old-password')).toBeVisible()
+  await expect(page.getByTestId('logout')).toHaveCount(0)
+  await page.screenshot({ path: test.info().outputPath('initial-password-renewal.png'), fullPage: true })
+  const form = page.locator('form').filter({ has: page.locator('#old-password') })
+  const error = page.locator('.hai-toast-item[data-variant=error]')
+  await dismissToasts(page)
+  // 同密码仍由服务端拒绝，显示安全原因与关联编号；本地确认不一致则直接提示字段。
+  await page.locator('#old-password').fill(initialPassword)
+  await page.locator('#new-password').fill(initialPassword)
+  await page.locator('#confirm-password').fill(initialPassword)
+  await form.locator('button[type=submit]').click()
+  await expect(error).toContainText(/新密码不能与当前密码相同|different from your current password/)
+  await expect(error).not.toContainText('traceId:')
+  await error.getByRole('button', { name: /^(查看排查信息|View diagnostic details|調査情報を表示)$/ }).click()
+  await expect(error.locator('code')).toHaveText(/^[\w.:-]{1,128}$/)
+  await expect(page.getByTestId('logout')).toHaveCount(0)
+  await page.screenshot({ path: test.info().outputPath('initial-password-same.png'), fullPage: true })
+  await expect(form.locator('.alert-error')).toHaveCount(0)
+  await dismissToasts(page)
+  const password = `${initialPassword}-Renewed!`
+  await page.locator('#old-password').fill('Incorrect-test-password!')
+  await page.locator('#new-password').fill(password)
+  await page.locator('#confirm-password').fill(password)
+  await form.locator('button[type=submit]').click()
+  await expect(error).toContainText(/用户名或密码不正确|Username or password is incorrect/)
+  await expect(error).not.toContainText(/原密码错误|Original password/)
+  await dismissToasts(page)
+  await page.locator('#old-password').fill(initialPassword)
+  await page.locator('#confirm-password').fill(`${password}-mismatch`)
+  await expect(form).toContainText(/两次密码输入不一致|do not match/)
+  await expect(form.locator('button[type=submit]')).toBeDisabled()
+  await page.locator('#confirm-password').fill(password)
+  await form.locator('button[type=submit]').click()
+  await expect(page.locator('#login-username')).toBeVisible()
+  await page.locator('#login-username').fill(username)
+  await page.getByTestId('login-form').locator('input[type=password]').fill(password)
+  await page.getByTestId('login-form').locator('button[type=submit]').click()
+  await expect(page.getByTestId('logout')).toBeVisible()
+  if (await page.getByTestId('guide-later').isVisible())
+    await page.getByTestId('guide-later').click()
+  return password
+}
+
+test('configured page exit revokes the actual server session, while BFCache keeps it', async ({ page, context }) => {
+  await login(page)
+  let closes = 0
+  page.on('request', (request) => {
+    if (new URL(request.url()).pathname.endsWith('/auth/session/close'))
+      closes++
+  })
+  await page.evaluate(() => window.dispatchEvent(new PageTransitionEvent('pagehide', { persisted: true })))
+  expect(closes).toBe(0)
+  const revoked = page.waitForResponse(response => new URL(response.url()).pathname.endsWith('/auth/session/close'))
+  // 浏览器关闭事件本身不保证送达；明确触发同一原生事件，验证已送达的请求确实撤销。
+  await page.evaluate(() => window.dispatchEvent(new PageTransitionEvent('pagehide', { persisted: false })))
+  const response = await revoked
+  expect(response.status()).toBe(200)
+  await response.body()
+  expect(closes).toBe(1)
+  await page.close()
+  const reopened = await context.newPage()
+  await reopened.goto('/')
+  await expect(reopened.getByTestId('login-form')).toBeVisible()
+  await expect(reopened.getByTestId('logout')).toHaveCount(0)
+})
+
+test('server idle expiry opens normal login in place and resumes one rejected save without losing the draft', async ({ page }) => {
+  const password = await login(page, 'config_admin', configAdminPassword)
+  await page.getByTestId('nav-configuration').click()
+  const draft = 'Draft preserved across server idle expiry'
+  await page.getByTestId('business-notice-input').locator('textarea').fill(draft)
+  // 此等待是被测的真实服务端闲置期限；期间不发业务保活请求。
+  await page.waitForTimeout(6500)
+  const statuses: number[] = []
+  page.on('response', (response) => {
+    if (new URL(response.url()).pathname.endsWith('/admin/configuration/update'))
+      statuses.push(response.status())
+  })
+  await page.getByTestId('configuration-page').locator('button[type=submit]').click()
+  const dialog = page.getByTestId('session-recovery-dialog')
+  await expect(dialog).toBeVisible()
+  await expect(page.getByTestId('business-notice-input').locator('textarea')).toHaveValue(draft)
+  await page.screenshot({ path: test.info().outputPath('idle-session-recovery.png'), fullPage: true })
+  const form = dialog.locator('form.login-form')
+  await form.locator('input[type=password]').fill('Incorrect-test-password!')
+  await form.locator('button[type=submit]').click()
+  await expect(page.locator('.hai-toast-item[data-variant=error]')).toBeVisible()
+  await expect(page.locator('.hai-toast-item[data-variant=error]')).toBeInViewport({ ratio: 1 })
+  await page.screenshot({ path: test.info().outputPath('idle-session-recovery-error-toast.png'), fullPage: true })
+  expect(statuses).toHaveLength(1)
+  await form.locator('input[type=password]').fill(password)
+  await form.locator('button[type=submit]').click()
+  await expect(dialog).toHaveCount(0)
+  await expect.poll(() => statuses.length).toBe(2)
+  await expect(page.getByTestId('notice')).toBeVisible()
+  await expect(page.getByTestId('business-notice-input').locator('textarea')).toHaveValue(draft)
+  await expect(page.getByTestId('logout')).toBeVisible()
+})
+{{/if~}}

package/templates/apps/fullstack/eslint.config.js.hbs

@@ -0,0 +1,41 @@
+import antfu, { GLOB_SRC } from '@antfu/eslint-config'
+import { haiQualityConfig } from './eslint-rules.js'
+
+export default antfu({
+  // unused-imports 使用 TS 规则，JS 同样使用 TS parser 以保持 scope 契约一致。
+  typescript: { files: [GLOB_SRC] },
+  formatters: true,
+  ignores: [
+    '**/build/**',
+    '**/dist/**',
+    '**/src/lib/paraglide/**',
+    '**/project.inlang/**',
+    '**/*.d.ts',
+    '**/.agents/**',
+    '**/.claude/**',
+    '**/.github/**',
+    '**/AGENTS.md',
+    '**/CLAUDE.md',
+    '**/README.md',
+    '**/opencode.json',
+    '**/package.json',
+  ],
+  svelte: true,
+}, haiQualityConfig, {
+  files: ['**/*.svelte'],
+  rules: {
+    'svelte/html-quotes': 'off',
+    'svelte/indent': 'off',
+    'perfectionist/sort-imports': 'off',
+  },
+}, {
+  files: ['**/tsconfig.json', '**/tsconfig.*.json'],
+  rules: {
+    'jsonc/sort-keys': 'off',
+  },
+}, {
+  files: ['**/index.ts'],
+  rules: {
+    'perfectionist/sort-exports': 'off',
+  },
+})

package/templates/apps/fullstack/hai.json.hbs

@@ -0,0 +1,11 @@
+{
+  "build": {
+  "images": [
+    { "name": "serv", "dockerfile": "images/serv.Dockerfile", "containerPort": 3000 }{{#if fullstack.frontends.web}},
+    { "name": "web", "dockerfile": "images/web.Dockerfile", "containerPort": 8080 }{{/if}}
+  ]{{#if fullstack.frontends.app}},
+  "app": ["apps/{{projectName}}-app"]{{/if}}{{#if fullstack.frontends.desktop}},
+  "desktop": ["apps/{{projectName}}-desktop"]{{/if}}
+}{{#if features.deploy}},
+  "deploy": {{{deploymentConfig}}}{{/if}}
+}

package/templates/apps/fullstack/images/serv.Dockerfile.hbs

@@ -0,0 +1,38 @@
+FROM node:24.22.1-bookworm-slim AS build
+ARG SQLITE_PREBUILD_MIRROR=
+ENV npm_config_better_sqlite3_binary_host_mirror=$SQLITE_PREBUILD_MIRROR
+
+ENV PNPM_HOME=/pnpm
+ENV PATH=$PNPM_HOME:$PATH
+ENV CI=true
+ENV ONNXRUNTIME_NODE_INSTALL_CUDA=skip
+WORKDIR /workspace
+
+RUN corepack enable && corepack prepare pnpm@12.11.2 --activate && pnpm config set store-dir /pnpm/store
+COPY pnpm-lock.yaml pnpm-workspace.yaml ./
+COPY images/dependencies/ ./
+RUN --mount=type=cache,id={{projectName}}-pnpm,target=/pnpm/store pnpm fetch --ignore-scripts
+COPY . .
+RUN --mount=type=cache,id={{projectName}}-pnpm,target=/pnpm/store pnpm install --offline --frozen-lockfile --ignore-scripts
+ARG HAI_BUILD_ID=
+ARG HAI_BUILD_COMMIT=unknown
+RUN HAI_BUILD_ID="$HAI_BUILD_ID" HAI_BUILD_COMMIT="$HAI_BUILD_COMMIT" pnpm --filter {{fullstack.servPackageName}}... --if-present build
+
+RUN --mount=type=cache,id={{projectName}}-sqlite,target=/root/.npm/_prebuilds if [ -d node_modules/better-sqlite3 ]; then cd node_modules/better-sqlite3; for attempt in 1 2 3; do node -e "require('node:child_process').execFileSync(process.execPath,[require.resolve('prebuild-install/bin.js'),'--verbose'],{stdio:'inherit'})" && break; [ "$attempt" = 3 ] && exit 1; sleep 3; done; fi
+RUN --mount=type=cache,id={{projectName}}-pnpm,target=/pnpm/store --mount=type=cache,id={{projectName}}-sqlite,target=/root/.npm/_prebuilds pnpm pm deploy --filter {{fullstack.servPackageName}} --prod /prod/service
+
+FROM node:24.22.1-bookworm-slim AS service
+
+ENV NODE_ENV=production
+ENV HOST=0.0.0.0
+ENV PORT=3000
+WORKDIR /app
+
+COPY --from=build --chown=node:node /prod/service ./
+RUN mkdir -p /app/data && chown node:node /app/data
+
+USER node
+EXPOSE 3000
+HEALTHCHECK --interval=30s --timeout=5s --start-period=15s --retries=3 \
+  CMD node -e "fetch('http://127.0.0.1:'+process.env.PORT+'/health').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"
+CMD ["node", "dist/index.js"]

package/templates/apps/fullstack/images/web/19-runtime-config.envsh.hbs

@@ -0,0 +1,5 @@
+#!/bin/sh
+
+# 使用 Base64 跨越 shell、envsubst 与 JavaScript 字符串边界，避免 URL 字符改变脚本语义。
+PUBLIC_API_BASE_BASE64="$(printf '%s' "${PUBLIC_API_BASE:-}" | base64 | tr -d '\n')"
+export PUBLIC_API_BASE_BASE64

package/templates/apps/fullstack/images/web/nginx.conf.hbs

@@ -0,0 +1,24 @@
+{{! @skipIfEmpty }}
+{{#if fullstack.frontends.web}}
+server {
+  listen 8080;
+  server_name _;
+  root /usr/share/nginx/html;
+
+  location / {
+    try_files $uri $uri/ /index.html;
+  }
+
+  location = /runtime-config.js {
+    alias /tmp/hai-runtime-config/runtime-config.js;
+    add_header Cache-Control "no-store";
+    default_type application/javascript;
+  }
+
+  location = /health {
+    access_log off;
+    add_header Content-Type text/plain;
+    return 200 'ok';
+  }
+}
+{{/if}}

package/templates/apps/fullstack/images/web/runtime-config.js.template.hbs

@@ -0,0 +1,3 @@
+globalThis.__HAI_PUBLIC_CONFIG__ = {
+  apiBase: new TextDecoder().decode(Uint8Array.from(atob('${PUBLIC_API_BASE_BASE64}'), value => value.charCodeAt(0))),
+}

package/templates/apps/fullstack/images/web.Dockerfile.hbs

@@ -0,0 +1,37 @@
+{{#if fullstack.frontends.web}}
+FROM node:24.22.1-bookworm-slim AS build
+ARG SQLITE_PREBUILD_MIRROR=
+ENV npm_config_better_sqlite3_binary_host_mirror=$SQLITE_PREBUILD_MIRROR
+
+ENV PNPM_HOME=/pnpm
+ENV PATH=$PNPM_HOME:$PATH
+ENV CI=true
+WORKDIR /workspace
+
+RUN corepack enable && corepack prepare pnpm@12.11.2 --activate && pnpm config set store-dir /pnpm/store
+COPY pnpm-lock.yaml pnpm-workspace.yaml ./
+COPY images/dependencies/ ./
+RUN --mount=type=cache,id={{projectName}}-pnpm,target=/pnpm/store pnpm fetch --ignore-scripts
+COPY . .
+RUN --mount=type=cache,id={{projectName}}-pnpm,target=/pnpm/store pnpm install --offline --frozen-lockfile --ignore-scripts
+ARG HAI_BUILD_ID=
+ARG HAI_BUILD_COMMIT=unknown
+ARG PUBLIC_BASE_PATH=
+RUN pnpm --filter {{fullstack.sharedPackageName}} paraglide:compile && HAI_BUILD_ID="$HAI_BUILD_ID" HAI_BUILD_COMMIT="$HAI_BUILD_COMMIT" PUBLIC_BASE_PATH="$PUBLIC_BASE_PATH" pnpm --filter {{projectName}}-web... --if-present build
+
+FROM nginxinc/nginx-unprivileged:1.29.8-alpine AS web
+
+ENV PUBLIC_API_BASE=
+ENV NGINX_ENVSUBST_FILTER=PUBLIC_API_BASE_BASE64
+ENV NGINX_ENVSUBST_OUTPUT_DIR=/tmp/hai-runtime-config
+
+RUN mkdir -p /tmp/hai-runtime-config
+COPY images/web/nginx.conf /etc/nginx/conf.d/default.conf
+COPY --chmod=755 images/web/19-runtime-config.envsh /docker-entrypoint.d/19-runtime-config.envsh
+COPY images/web/runtime-config.js.template /etc/nginx/templates/runtime-config.js.template
+COPY --from=build /workspace/apps/{{projectName}}-web/dist /usr/share/nginx/html
+
+EXPOSE 8080
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
+  CMD wget -Y off -q -O /dev/null http://127.0.0.1:8080/health || exit 1
+{{/if}}

package/templates/apps/fullstack/package.json.hbs

@@ -0,0 +1,61 @@
+{
+  "engines": { "node": "^22.23.4 || ^24.22.1 || ^26.12.1" },
+  "name": "{{projectName}}",
+  "type": "module",
+  "version": "0.1.0",
+  "private": true,
+  "packageManager": "pnpm@12.11.2",
+  "description": "Full-stack hai workspace with separated contract, service and frontends.",
+  "scripts": {
+    "i18n:compile": "pnpm --filter {{fullstack.sharedPackageName}} paraglide:compile{{#each fullstack.frontendApps}} && pnpm --filter {{packageName}} paraglide:compile{{/each}}",
+    "postinstall": "pnpm i18n:compile",
+    "dev": "pnpm --filter {{fullstack.contractPackageName}} build && pnpm i18n:compile && pnpm --parallel --filter {{fullstack.servPackageName}}{{#each fullstack.frontendApps}} --filter {{packageName}}{{/each}} dev",
+    "start": "pnpm --filter {{fullstack.servPackageName}} start",
+    "start:test": "pnpm --filter {{fullstack.servPackageName}} start:test",
+    "start:prod": "pnpm --filter {{fullstack.servPackageName}} start:prod",
+    "dev:test": "pnpm --filter {{fullstack.contractPackageName}} build && pnpm i18n:compile && pnpm --parallel --filter {{fullstack.servPackageName}}{{#each fullstack.frontendApps}} --filter {{packageName}}{{/each}} dev:test",
+    "dev:prod": "pnpm --filter {{fullstack.contractPackageName}} build && pnpm i18n:compile && pnpm --parallel --filter {{fullstack.servPackageName}}{{#each fullstack.frontendApps}} --filter {{packageName}}{{/each}} dev:prod",
+    "compile": "pnpm i18n:compile && pnpm -r --if-present build",
+    "build": "hai build",
+{{#if features.deploy}}
+    "deploy": "hai deploy packages/{{projectName}}-serv",
+{{/if}}
+    "check": "pnpm typecheck",
+    "typecheck": "pnpm --filter {{fullstack.contractPackageName}} build && pnpm i18n:compile && pnpm -r --if-present typecheck",
+    "lint": "eslint *.js *.ts e2e && pnpm -r --if-present lint",
+    "lint:fix": "eslint *.js *.ts e2e --fix && pnpm -r --if-present lint:fix",
+    "test": "pnpm --filter {{fullstack.contractPackageName}} build && pnpm i18n:compile && pnpm -r --if-present test",
+    "test:watch": "pnpm -r --parallel --if-present test:watch",
+    "test:e2e": "pnpm compile && node scripts/run-e2e.mjs --config playwright.config.ts{{#if fullstack.e2eFrontend}} --next --config playwright.session-close.config.ts{{/if}}",
+    "clean": "pnpm -r --if-present clean && rimraf node_modules .turbo"
+  },
+  "dependencies": {
+    "@h-ai/api-contract": "{{haiPackageSpecifier}}",
+    "{{fullstack.contractPackageName}}": "workspace:*",
+    "{{fullstack.sharedPackageName}}": "workspace:*"
+  },
+  "devDependencies": {
+    "@h-ai/cli": "{{haiPackageSpecifier}}",
+{{#if features.feedback}}
+    "@h-ai/feedback": "{{haiPackageSpecifier}}",
+{{/if}}
+{{#if features.deploy}}
+    "@h-ai/deploy": "{{haiPackageSpecifier}}",
+{{/if}}
+    "@antfu/eslint-config": "{{fullstack.packageSpecifiers.antfuEslintConfig}}",
+    "@playwright/test": "{{fullstack.packageSpecifiers.playwright}}",
+    "@sveltejs/vite-plugin-svelte": "{{fullstack.packageSpecifiers.sveltePlugin}}",
+    "@types/node": "{{fullstack.packageSpecifiers.nodeTypes}}",
+    "eslint": "{{fullstack.packageSpecifiers.eslint}}",
+    "eslint-plugin-format": "{{fullstack.packageSpecifiers.eslintPluginFormat}}",
+    "eslint-plugin-svelte": "{{fullstack.packageSpecifiers.eslintPluginSvelte}}",
+    "rimraf": "{{fullstack.packageSpecifiers.rimraf}}",
+    "svelte": "{{fullstack.packageSpecifiers.svelte}}",
+    "svelte-check": "{{fullstack.packageSpecifiers.svelteCheck}}",
+    "svelte-eslint-parser": "{{fullstack.packageSpecifiers.svelteEslintParser}}",
+    "tsup": "{{fullstack.packageSpecifiers.tsup}}",
+    "typescript": "{{fullstack.packageSpecifiers.typescript}}",
+    "vite": "{{fullstack.packageSpecifiers.vite}}",
+    "vitest": "{{fullstack.packageSpecifiers.vitest}}"
+  }
+}

package/templates/apps/fullstack/packages/{{projectName}}-contract/README.md.hbs

@@ -0,0 +1,40 @@
+# {{fullstack.contractPackageName}}
+
+## 简介
+
+共享 API 契约包，包含 Zod Schema、`apiContract.route()` 业务接口定义与工程级 contract。业务 schema、角色、流程及限额是模板初始方案，按用户需求修改，并同步服务端授权、调用方、测试与说明；不要求需求沿用默认业务。
+
+## 核心功能清单
+
+- 共享接口路径、输入输出 Schema 和类型。
+- 客户端与服务端使用同一份 contract。
+- 不包含服务端业务实现，也不加载私有配置。
+
+## 使用入门
+
+### 骨架说明
+
+- `src/app-schemas.ts`：跨接口、跨层复用的输入/数据 Schema 与类型。
+- `src/app-contract.ts`：app 领域 contract；每个业务 path 直接写在对应接口定义中。
+- `src/admin-schemas.ts` / `src/admin-contract.ts`：示例管理员用户、系统/审计/配置/业务操作员及基础成员角色、账号生命周期、邀请、用户列表服务端排序、审计分类/列头排序/统计/备份、业务公告和个人设置、加密 JSON 头像上传 Schema/类型/路由；认证复用框架的 IAM auth contract，通过服务端配置启用注册、密码/LDAP/验证码登录及密码重置。
+- `src/{{projectName}}-contract.ts`：工程级 contract，供 `@h-ai/serv` 与 `@h-ai/api-client` 共用。
+
+只使用一次的输出 Schema 直接内联到 `.output(...)`；同一 contract 文件内重复使用时才保留私有常量。
+API 前缀、健康检查与跨端 Header 等传输配置位于 serv 包的 `config/_serv.yml`。
+`SUPPORTED_LOCALES` 为生成时实际编译的语言列表；`app.info` 中名称、版本、环境、默认语言来自后端 core 配置。更新公开契约时同时更新 serv、shared typed API client、各端 UI 与测试。
+
+### 开发
+
+- `pnpm --filter {{fullstack.contractPackageName}} typecheck`
+- `pnpm --filter {{fullstack.contractPackageName}} test`
+
+## 开发测试
+
+```sh
+pnpm --filter {{fullstack.contractPackageName}} typecheck
+pnpm --filter {{fullstack.contractPackageName}} test
+```
+
+## 许可证
+
+Apache-2.0

package/templates/apps/fullstack/packages/{{projectName}}-contract/package.json.hbs

@@ -0,0 +1,30 @@
+{
+  "engines": { "node": "^22.23.4 || ^24.22.1 || ^26.12.1" },
+  "name": "{{fullstack.contractPackageName}}",
+  "type": "module",
+  "version": "0.1.0",
+  "private": true,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "tsup",
+    "check": "pnpm typecheck",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "clean": "rimraf dist .turbo"
+  },
+  "dependencies": {
+    "@h-ai/api-contract": "{{haiPackageSpecifier}}",
+    "@h-ai/core": "{{haiPackageSpecifier}}",
+    "zod": "{{fullstack.packageSpecifiers.zod}}"
+  }
+}

package/templates/apps/fullstack/packages/{{projectName}}-contract/src/admin-contract.ts.hbs

@@ -0,0 +1,78 @@
+import { apiContract, IamAdminResetPasswordInputSchema } from '@h-ai/api-contract'
+import { z } from 'zod'
+import {
+  AdminAuditInputSchema,
+  AdminAuditSchema,
+  AdminCreateUserSchema,
+  AdminInviteUserSchema,
+  AdminPermissionPolicyInputSchema,
+  AdminPermissionPolicySchema,
+  AdminRoleSchema,
+  AdminUpdateUserSchema,
+  AdminUserSchema,
+  AdminUsersInputSchema,
+  AdminUsersSchema,
+  AuditBackupReceiptSchema,
+  AvatarOutputSchema,
+  AvatarUploadSchema,
+  BusinessSettingsSchema,
+  ProfileUpdateSchema,
+} from './admin-schemas.js'
+
+/** mini 管理示例的业务路径；四类职责与权限由应用配置，可按项目需求调整。 */
+export const adminContract = {
+  permissions: {
+    list: apiContract.route({ method: 'POST', path: '/admin/permissions/list', tags: ['admin'] }).input(z.object({ page: z.number().int().min(1).default(1), pageSize: z.number().int().min(1).max(100).default(20) })).output(apiContract.haiResultSchema(z.object({ items: z.array(AdminPermissionPolicySchema), total: z.number() }))),
+    update: apiContract.route({ method: 'POST', path: '/admin/permissions/update', tags: ['admin'] }).input(AdminPermissionPolicyInputSchema).output(apiContract.haiResultSchema(z.object({ saved: z.literal(true) }))),
+  },
+  configuration: {
+    get: apiContract.route({ method: 'POST', path: '/admin/configuration/get', tags: ['admin'] }).output(apiContract.haiResultSchema(BusinessSettingsSchema)),
+    update: apiContract.route({ method: 'POST', path: '/admin/configuration/update', tags: ['admin'] }).input(BusinessSettingsSchema).output(apiContract.haiResultSchema(BusinessSettingsSchema)),
+  },
+  users: {
+    resetPassword: apiContract.route({ method: 'POST', path: '/admin/users/reset-password', tags: ['admin'] })
+      .input(IamAdminResetPasswordInputSchema.strict())
+      .output(apiContract.haiResultSchema(z.object({ reset: z.literal(true) }))),
+    invite: apiContract.route({ method: 'POST', path: '/admin/users/invite', tags: ['admin'] }).input(AdminInviteUserSchema).output(apiContract.haiResultSchema(AdminUserSchema)),
+    list: apiContract.route({ method: 'POST', path: '/admin/users/list', tags: ['admin'] })
+      .input(AdminUsersInputSchema)
+      .output(apiContract.haiResultSchema(AdminUsersSchema)),
+    create: apiContract.route({ method: 'POST', path: '/admin/users/create', tags: ['admin'] })
+      .input(AdminCreateUserSchema)
+      .output(apiContract.haiResultSchema(AdminUserSchema)),
+    update: apiContract.route({ method: 'POST', path: '/admin/users/update', tags: ['admin'] })
+      .input(AdminUpdateUserSchema)
+      .output(apiContract.haiResultSchema(AdminUserSchema)),
+    delete: apiContract.route({ method: 'POST', path: '/admin/users/delete', tags: ['admin'] })
+      .input(z.object({ id: z.string().min(1) }).strict())
+      .output(apiContract.haiResultSchema(z.object({ deleted: z.literal(true) }))),
+    avatar: apiContract.route({ method: 'POST', path: '/admin/users/avatar', tags: ['admin'] })
+      .input(AvatarUploadSchema.extend({ id: z.string().min(1) }))
+      .output(apiContract.haiResultSchema(AvatarOutputSchema)),
+  },
+  roles: {
+    list: apiContract.route({ method: 'POST', path: '/admin/roles/list', tags: ['admin'] })
+      .output(apiContract.haiResultSchema(z.object({ items: z.array(AdminRoleSchema) }))),
+    update: apiContract.route({ method: 'POST', path: '/admin/roles/update', tags: ['admin'] })
+      .input(z.object({ id: z.string().min(1), description: z.string().max(300) }).strict())
+      .output(apiContract.haiResultSchema(AdminRoleSchema)),
+  },
+  audit: {
+    backup: apiContract.route({ method: 'POST', path: '/admin/audit/backup', tags: ['admin'] }).input(z.object({ id: z.uuid() }).strict()).output(apiContract.haiResultSchema(AuditBackupReceiptSchema)),
+    list: apiContract.route({ method: 'POST', path: '/admin/audit/list', tags: ['admin'] })
+      .input(AdminAuditInputSchema)
+      .output(apiContract.haiResultSchema(AdminAuditSchema)),
+  },
+}
+
+export const profileContract = {
+  update: apiContract.route({ method: 'POST', path: '/profile/update', tags: ['profile'] })
+    .input(ProfileUpdateSchema)
+    .output(apiContract.haiResultSchema(AdminUserSchema)),
+  avatar: apiContract.route({ method: 'POST', path: '/profile/avatar', tags: ['profile'] })
+    .input(AvatarUploadSchema)
+    .output(apiContract.haiResultSchema(AvatarOutputSchema)),
+}
+
+/** 复用框架认证契约；注册、通知和登录方式由 IAM 配置控制。 */
+export const authContract = apiContract.iam.auth

package/templates/apps/fullstack/packages/{{projectName}}-contract/src/admin-schemas.ts.hbs

@@ -0,0 +1,134 @@
+import { IamListUsersInputSchema, IamPermissionSchema } from '@h-ai/api-contract'
+import { z } from 'zod'
+
+/** 权限的敏感操作配置复用框架字段；职责授权仍由应用控制。 */
+export const AdminPermissionPolicySchema = IamPermissionSchema.pick({ id: true, code: true, name: true, sensitiveOperations: true })
+export const AdminPermissionPolicyInputSchema = AdminPermissionPolicySchema.pick({ id: true, sensitiveOperations: true })
+export type AdminPermissionPolicy = z.infer<typeof AdminPermissionPolicySchema>
+
+export const BusinessSettingsSchema = z.object({ notice: z.string().trim().max(200) }).strict()
+
+export const AdminRoleCodeSchema = z.enum(['admin', 'audit_admin', 'config_admin', 'business_operator', 'user'])
+export const AdminPageInputSchema = z.object({
+  page: z.number().int().min(1).default(1),
+  pageSize: z.number().int().min(1).max(100).default(20),
+})
+export const AdminUserSchema = z.object({
+  id: z.string(),
+  username: z.string(),
+  email: z.string().optional(),
+  displayName: z.string().optional(),
+  avatarUrl: z.string().optional(),
+  accountType: z.enum(['permanent', 'temporary']),
+  accountStatus: z.enum(['active', 'dormant', 'closed']),
+  accountExpiresAt: z.string().datetime().nullable(),
+  lastLoginAt: z.string().datetime().nullable(),
+  roles: z.array(AdminRoleCodeSchema),
+  createdAt: z.string().datetime(),
+  updatedAt: z.string().datetime(),
+})
+export const AdminUsersInputSchema = AdminPageInputSchema.extend({
+  sortBy: IamListUsersInputSchema.shape.sortBy,
+  sortDirection: IamListUsersInputSchema.shape.sortDirection,
+  search: z.string().max(100).optional(),
+  accountStatus: IamListUsersInputSchema.shape.accountStatus,
+})
+export const AdminUsersSchema = z.object({
+  items: z.array(AdminUserSchema),
+  total: z.number(),
+  page: z.number(),
+  pageSize: z.number(),
+})
+export const AdminCreateUserSchema = z.object({
+  username: z.string().min(3).max(64).regex(/^[\w-]+$/),
+  password: z.string().min(1),
+  email: z.email().optional(),
+  displayName: z.string().max(100).optional(),
+  role: AdminRoleCodeSchema.default('user'),
+  accountType: z.enum(['permanent', 'temporary']).default('permanent'),
+  accountStatus: z.enum(['active', 'dormant', 'closed']).default('active'),
+  accountExpiresAt: z.string().datetime().nullable().optional(),
+}).strict()
+export const AdminInviteUserSchema = AdminCreateUserSchema.omit({ password: true }).extend({ phone: z.string().trim().min(1).max(32).optional(), accountStatus: z.literal('active').default('active') })
+export const AdminUpdateUserSchema = z.object({
+  id: z.string().min(1),
+  email: z.union([z.email(), z.literal('')]).optional(),
+  displayName: z.string().max(100).optional(),
+  accountType: z.enum(['permanent', 'temporary']).optional(),
+  accountStatus: z.enum(['active', 'dormant', 'closed']).optional(),
+  accountExpiresAt: z.string().datetime().nullable().optional(),
+  role: AdminRoleCodeSchema.optional(),
+}).strict()
+export const AdminRoleSchema = z.object({
+  id: z.string(),
+  code: AdminRoleCodeSchema,
+  name: z.string(),
+  description: z.string().optional(),
+  userCount: z.number(),
+})
+export const AdminAuditInputSchema = AdminPageInputSchema.extend({
+  category: z.enum(['system', 'business']).optional(),
+  outcome: z.enum(['success', 'failure', 'denied']).optional(),
+  severity: z.enum(['info', 'warning', 'error', 'critical']).optional(),
+  scopeId: z.string().max(256).optional(),
+  requestId: z.string().max(256).optional(),
+  traceId: z.string().max(256).optional(),
+  sortBy: z.enum(['createdAt', 'action', 'resource', 'category', 'outcome', 'severity']).optional(),
+  sortDirection: z.enum(['asc', 'desc']).optional(),
+  userId: z.string().max(100).optional(),
+  action: z.string().max(50).optional(),
+  resource: z.string().max(50).optional(),
+  startDate: z.string().datetime().optional(),
+  endDate: z.string().datetime().optional(),
+})
+export const AdminAuditLogSchema = z.object({
+  category: z.enum(['system', 'business']).nullish(),
+  outcome: z.enum(['success', 'failure', 'denied']).nullish(),
+  severity: z.enum(['info', 'warning', 'error', 'critical']).nullish(),
+  scopeId: z.string().nullish(),
+  requestId: z.string().nullish(),
+  traceId: z.string().nullish(),
+  actorSnapshot: z.object({ id: z.string(), username: z.string().optional(), displayName: z.string().optional(), roles: z.array(z.string()).optional() }).nullish(),
+  id: z.string(),
+  userId: z.string().nullable(),
+  username: z.string().nullable(),
+  action: z.string(),
+  resource: z.string(),
+  resourceId: z.string().nullable(),
+  details: z.string().nullable(),
+  ipAddress: z.string().nullable(),
+  userAgent: z.string().nullable(),
+  createdAt: z.string().datetime(),
+})
+export const AuditBackupReceiptSchema = z.object({ id: z.string(), key: z.string(), recordCount: z.number(), sha256: z.string(), createdAt: z.string().datetime(), cutoff: z.string().datetime() })
+export const AdminAuditSchema = z.object({
+  backupEnabled: z.boolean(),
+  stats: z.array(z.object({ action: z.string(), count: z.number() })),
+  items: z.array(AdminAuditLogSchema),
+  total: z.number(),
+  page: z.number(),
+  pageSize: z.number(),
+})
+export const ProfileUpdateSchema = z.object({
+  displayName: z.string().max(100).optional(),
+  email: z.union([z.email(), z.literal('')]).optional(),
+  locale: z.enum([{{#each fullstack.i18n.locales}}'{{this}}'{{#unless @last}}, {{/unless}}{{/each}}]).optional(),
+  theme: z.string().min(1).max(40).regex(/^[\w-]+$/).optional(),
+}).strict()
+/** 512 KiB 头像以 JSON 传输，上传及响应均经过统一加密。 */
+export const AvatarUploadSchema = z.object({
+  contentType: z.enum(['image/png', 'image/jpeg', 'image/webp']),
+  base64: z.string().min(1).max(699052).regex(/^[A-Z\d+/]+={0,2}$/i),
+}).strict()
+export const AvatarOutputSchema = z.object({ avatarUrl: z.string().describe('Generated relative asset path') })
+
+export type AdminUser = z.infer<typeof AdminUserSchema>
+export type AdminRole = z.infer<typeof AdminRoleSchema>
+export type AdminRoleCode = z.infer<typeof AdminRoleCodeSchema>
+export type AuditBackupReceipt = z.infer<typeof AuditBackupReceiptSchema>
+export type AdminAuditLog = z.infer<typeof AdminAuditLogSchema>
+export type AdminInviteUser = z.infer<typeof AdminInviteUserSchema>
+export type AdminCreateUser = z.infer<typeof AdminCreateUserSchema>
+export type AdminUpdateUser = z.infer<typeof AdminUpdateUserSchema>
+export type ProfileUpdate = z.infer<typeof ProfileUpdateSchema>
+export type AvatarUpload = z.infer<typeof AvatarUploadSchema>