@h-ai/cli 0.1.0-alpha.67 → 0.1.0-alpha.68

package/templates/apps/fullstack/apps/{{projectName}}-web/vite.config.ts.hbs

@@ -12,7 +12,7 @@ import { defineConfig } from 'vitest/config'
 const envDir = fileURLToPath(new URL('../../', import.meta.url))
 
 export default defineConfig(({ mode, command }) => {
-  const envResult = command === 'build' ? { success: true as const, data: {} as Record<string, string> } : core.config.loadEnvFiles({ mode, envDir })
+  const envResult = command === 'build' || process.env.HAI_E2E === '1' ? { success: true as const, data: {} as Record<string, string> } : core.config.loadEnvFiles({ mode, envDir })
   if (!envResult.success)
     throw new Error(envResult.error.message)
   const env = envResult.data

package/templates/apps/fullstack/e2e/fullstack.spec.ts.hbs

@@ -13,7 +13,7 @@ const apiPrefix = '/api/v1'
 const adminPassword = process.env.E2E_ADMIN_PASSWORD || 'Scaffold-test-Admin123!'
 const configuredName = process.env.HAI_CORE_NAME || 'Configured scaffold'
 const configuredVersion = process.env.HAI_CORE_VERSION || '9.8.7'
-const configuredEnv = process.env.HAI_CORE_ENV || 'test'
+const configuredEnv = 'test'
 
 // 测试专用的一像素 PNG；上传仍使用完整前后端加密链路。
 const avatar = Buffer.from('iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+aSxkAAAAASUVORK5CYII=', 'base64')
@@ -261,14 +261,15 @@ test('shared authentication supports public registration with configuration', as
   await expect(page.getByTestId('login-form')).toBeVisible()
   await page.screenshot({ path: path.join(evidence, '{{projectName}}-login.png'), fullPage: true })
   await page.getByRole('button', { name: /立即注册|Register now/i }).click()
-  await expect(page.locator('input[name="username"]')).toBeVisible()
+  const registerForm = page.locator('.register-form')
+  await expect(registerForm.locator('#register-username')).toBeVisible()
   await page.screenshot({ path: path.join(evidence, '{{projectName}}-register.png'), fullPage: true })
-  const username = `signup${Date.now()}`
-  await page.locator('input[name="username"]').fill(username)
-  await page.locator('input[name="email"]').fill(`${username}@example.com`)
-  await page.locator('input[type="password"]').nth(0).fill('SignupPassword123')
-  await page.locator('input[type="password"]').nth(1).fill('SignupPassword123')
-  await page.locator('button[type="submit"]').click()
+  const username = `signup${randomUUID().replaceAll('-', '').slice(0, 12)}`
+  await registerForm.locator('#register-username').fill(username)
+  await registerForm.locator('#register-email').fill(`${username}@example.com`)
+  await registerForm.locator('#register-password').fill('SignupPassword123')
+  await registerForm.locator('#register-confirm-password').fill('SignupPassword123')
+  await registerForm.locator('button[type="submit"]').click()
   await expect(page.getByTestId('settings-page')).toBeVisible()
   expect(await page.evaluate(() => document.documentElement.scrollWidth <= innerWidth)).toBe(true)
   if (!process.env.IAM_NOTIFICATION_URL)
@@ -458,6 +459,16 @@ test('administrator and user complete account, avatar, preference, password and
     await expect(userPage.getByTestId('profile-form').locator('input[name="displayName"]')).toHaveValue('Updated member')
     await expect(userPage.getByTestId('profile-form').locator('input[name="email"]')).toHaveValue('')
     await expect.poll(() => userPage.getByTestId('profile-form').locator('img').evaluate((image: HTMLImageElement) => image.complete && image.naturalWidth > 0)).toBe(true)
+    await userPage.getByTestId('profile-language').click()
+    await userPage.getByRole('option', { name: '日本語', exact: true }).click()
+    await expect(userPage.getByTestId('nav-settings')).toHaveText('個人設定')
+    await expect(userPage.locator('html')).toHaveAttribute('lang', 'ja-JP')
+    await userPage.reload()
+    await expect(userPage.getByTestId('nav-settings')).toHaveText('個人設定')
+    await expect(userPage.locator('html')).toHaveAttribute('lang', 'ja-JP')
+    await userPage.getByTestId('profile-language').click()
+    await userPage.getByRole('option', { name: 'English', exact: true }).click()
+    await expect(userPage.getByTestId('nav-settings')).toHaveText('Personal settings')
     await userPage.setViewportSize({ width: 390, height: 844 })
     await expect.poll(() => userPage.evaluate(() => document.documentElement.scrollWidth <= window.innerWidth)).toBe(true)
     await userPage.getByTestId('mobile-menu').click()

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

@@ -15,7 +15,7 @@
     "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 --filter {{fullstack.contractPackageName}} build && pnpm i18n:compile && pnpm -r --if-present build",
+    "compile": "pnpm i18n:compile && pnpm -r --if-present build",
     "build": "hai build",
 {{#if features.deploy}}
     "deploy": "hai deploy packages/{{projectName}}-serv",

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

@@ -76,7 +76,7 @@ export const AdminAuditSchema = z.object({
 export const ProfileUpdateSchema = z.object({
   displayName: z.string().max(100).optional(),
   email: z.union([z.email(), z.literal('')]).optional(),
-  locale: z.enum(['zh-CN', 'en-US']).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 传输，上传及响应均经过统一加密。 */

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

@@ -3,3 +3,5 @@ export * from './app-schemas.js'
 export * from './admin-contract.js'
 export * from './admin-schemas.js'
 export * from './{{fullstack.contractPackageName}}.js'
+
+// @hai-generator:contracts:exports

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

@@ -2,12 +2,15 @@ import { apiContract } from '@h-ai/api-contract'
 import { adminContract, authContract, profileContract } from './admin-contract.js'
 import { appContract } from './app-contract.js'
 
+// @hai-generator:contracts:imports
+
 /** 当前工程启用的前端目标。 */
 export const ENABLED_FRONTENDS = {{{fullstack.selectedFrontendsJson}}} as const
 export const SUPPORTED_LOCALES = [{{#each fullstack.i18n.locales}}'{{this}}'{{#unless @last}}, {{/unless}}{{/each}}] as const
 
 /** 工程级 API contract，前端 typed client 与后端 service 共用。 */
 export const {{fullstack.contractExportName}} = apiContract.create({
+  // @hai-generator:contracts:entries
   app: appContract,
   iam: { auth: authContract },
   admin: adminContract,

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

@@ -21,6 +21,7 @@
 - `config/_db.yml` / `_cache.yml` / `_iam.yml` / `_storage.yml` / `_audit.yml` / `_reach.yml`：管理及开发通知配置，初始化前使用模块公开 Schema 验证。Reach 默认控制台 Provider，生产按注释替换为 SMTP/短信/API。
 - `config/_ai.yml` / `_vecdb.yml` / `_payment.yml` / `_scheduler.yml` / `_deploy.yml`：保留未启用模块的完整注释示例；配置文件存在不代表模块已接入。先在本 workspace 安装对应依赖，再在 `src/server/runtime.ts` 按公开 Schema 校验、初始化并反序关闭，接入实际业务后按需取消注释。整份注释先去掉一层外层注释，可选字段继续按需开启。
 - `src/index.ts`：进程入口，先 `core.init({ configDir: './config' })`，再初始化 reldb → cache → crypto → storage → reach（有配置时）→ iam → audit；启动失败及退出反序释放。
+- 选择 AI 时自动安装 reldb/vecdb/AI，并在 reldb/cache 之后初始化 vecdb、在其余依赖之后初始化 AI；关闭时先释放 AI，最后释放 vecdb/关系库，关闭失败会返回错误并保留重试义务。生产环境必须使用共享后端，根 `.env.prod` 默认连接 Compose `db/cache/storage/vecdb`，凭据和真实 Reach Provider JSON 私有注入。
 - `src/app-server.ts`：服务装配入口，挂载健康检查、OpenAPI、docs 与 procedures；应用名称 / 版本与 CORS 来源均取自上述配置。
 - `src/server/procedures/app-procedures.ts`：app 领域 procedures，对应 contract 中的 `app.info` / `app.echo` 路由。
 - `src/server/procedures/admin-procedures.ts`：认证、管理员用户/角色/审计管理和个人设置，使用 `.auth()` / `.role('admin')` 守卫。每个请求读取用户最新启用状态、角色和权限。
@@ -30,7 +31,7 @@
 
 CLI 已生成根目录 `.env.local`，`HAI_ADMIN_DEFAULT_PASSWORD` 为每个项目独立的随机强密码；`dev`/`start` 自动读取，首次登录使用用户名 `admin` 和该密码。仅在没有用户时创建管理员，不重设已有用户密码。密码不符合 `_iam.yml` 策略时，启动日志显示具体原因及错误码。`.env.local` 被 Git 和容器构建忽略，`.env.example` 不含真实密码；部署时设置目标环境自己的密码。所有业务 JSON 请求和响应强制加密；健康检查和随机路径的只读头像图片可直接访问。头像支持 PNG/JPEG/WebP，最大 512 KiB，校验内容特征和大小后由服务端生成 key，不能指定任意文件路径。
 
-默认 SQLite + 本地 storage + memory cache 适合单实例，管理写入仅支持单写实例：进程内保护无过期时间，共享 cache 锁定期续租，丢失锁或释放失败会记录错误。多实例读取可使用共享数据库、Redis cache 和 S3 storage，但管理写请求必须统一路由到同一写实例；仅更换 Redis 不提供任意多写副本的最后管理员原子保证。另需配置传输会话粘性路由：服务端私钥驻留单个进程，服务重启后客户端需重新协商。Web 使用 HttpOnly refresh Cookie + 内存 access token；仅同时满足客户端标识、body 通道头与受信原生 Origin 的 App/Desktop 请求返回 refresh token body。
+默认 SQLite + 本地 storage + memory cache 适合单实例，管理写入仅支持单写实例：进程内保护无过期时间，共享 cache 锁定期续租，丢失锁或释放失败会记录错误。多实例读取可使用共享数据库、Redis cache 和 S3 storage，但管理写请求必须统一路由到同一写实例；仅更换 Redis 不提供任意多写副本的最后管理员原子保证。传输在所有节点共享受管版本化密钥环与 registry，不依赖会话粘性；重启加载原 ring，轮换先分发新旧版本再切 activeKeyId。Web 使用 HttpOnly refresh Cookie + 内存 access token；仅同时满足客户端标识、body 通道头与受信原生 Origin 的 App/Desktop 请求返回 refresh token body。
 
 业务修改提交后的审计记录采用最大努力策略：写入失败输出包含操作及资源的结构化错误日志，业务仍返回原操作结果，避免将已经完成的变更误报为失败；应用启动时 audit 初始化失败则停止启动。
 
@@ -38,6 +39,8 @@ CLI 已生成根目录 `.env.local`，`HAI_ADMIN_DEFAULT_PASSWORD` 为每个项
 
 所有配置字段以模块 Schema 为准；未使用字段和替代 Provider 用注释保留。叶子环境变量只覆盖已有 YAML 路径，先取消相应键的注释，或用 `HAI_DB` / `HAI_CACHE` 等整体对象覆盖；`connectTimeout` 对应 `HAI_CACHE_CONNECTTIMEOUT`。凭据示例在根 `.env.example`，实际密钥保存在忽略的 `.env.local` 或部署环境。`.gitignore` 的 `**/data/` 忽略所有运行数据及 `.gitkeep`；运行时会创建目录。`crypto.init()` 无配置参数，datapipe 为纯函数，不提供虚构配置。
 
+CLI 同时在根 `.env.local` 一次性生成独立开发用 `HAI_CRYPTO_TRANSPORT_SERVERKEYRING`，结构为 `{activeKeyId,keys:{id:{publicKey,privateKey}}}`，运行时不隐式生成。部署由 Secret Manager 向所有节点分发相同受管 ring，客户端 registry 复用共享 reldb。私钥不进入普通 YAML、PUBLIC_/VITE_、日志或公开响应。轮换先分发含新旧版本的 ring，再切 activeKeyId 并滚动重建；过渡期后删除旧 ID，旧客户端 destroy 后重协商。没有 sticky session 依赖。
+
 自动生成的 `.env` 包含已启用模块的环境参数；YAML 显式引用相同变量并保留本地回退。使用 `start:test` / `start:prod` 加载对应环境覆盖。
 
 - `pnpm --filter {{fullstack.servPackageName}} dev`
@@ -55,7 +58,7 @@ CLI 已生成根目录 `.env.local`，`HAI_ADMIN_DEFAULT_PASSWORD` 为每个项
 
 服务端 `config/_iam.yml` 统一控制登录、注册、重置、协议与 `ui` 品牌。邮件/短信可用 `_reach.yml` 中的 Provider/标准模板或自定义发送回调。`AuthPanel` 使用安全公开配置及框架认证动作；无需在页面适配 Token、验证码倒计时和错误提示。单实例可使用 Memory；多实例需共享数据库与 Redis，并按工程根 README 配置写入路由和传输会话。
 
-LDAP/Reach 均可选：基础认证无需安装。默认 LDAP 客户端需在 IAM 服务端 workspace 安装 ldapts，再配置 login.ldap 与连接信息。自定义 onOtpSendEmail/onOtpSendSms/onPasswordResetRequest 回调可独立于 Reach 使用，投递失败须拒绝 Promise。协议在 Modal 显示；LoginForm/RegisterForm 提供 header/extraFields/footer，AuthPanel 透传 loginHeader/loginFields/loginFooter 和 registerHeader/registerFields/registerFooter。配置及例子见生成项目的 hai-iam/hai-ui skills。
+LDAP/Reach 均可选：基础认证无需安装。默认 LDAP 客户端需在 IAM 服务端 workspace 安装 ldapts，再配置 login.ldap 与连接信息。自定义 onOtpSendEmail/onOtpSendSms/onPasswordResetRequest 回调可独立于 Reach 使用，投递失败须拒绝 Promise；回调第三参数 context 提供 expiresAt/idempotencyKey，发送服务按稳定键持久化去重，异常/超时为结果未知且不自动重发。协议在 Modal 显示；LoginForm/RegisterForm 提供 header/extraFields/footer，AuthPanel 透传 loginHeader/loginFields/loginFooter 和 registerHeader/registerFields/registerFooter。配置及例子见生成项目的 hai-iam/hai-ui skills。
 
 协议支持配置中的 userAgreementMarkdown/privacyPolicyMarkdown 正文及 URL；同主题优先 Markdown，由安全渲染器在弹窗显示。
 

package/templates/apps/fullstack/packages/{{projectName}}-serv/config/_core.yml.hbs

@@ -9,7 +9,6 @@
 {{yaml 'name' fullstack.appName}}
 version: 0.1.0
 env: development
-debug: false
 
 defaultLocale: {{fullstack.i18n.baseLocale}}
 logging:
@@ -21,8 +20,3 @@ logging:
     - password
     - token
     - secret
-
-# 短 ID 生成配置；未设置时采用框架默认值。
-# id:
-#   prefix: app_
-#   length: 21

package/templates/apps/fullstack/packages/{{projectName}}-serv/config/_reach.yml.hbs

@@ -28,6 +28,7 @@ providers:
   #   headers:
   #     Authorization: '${HAI_REACH_PROVIDERS_0_HEADERS_AUTHORIZATION}'
   #   timeout: 10000
+  #   idempotent: ${HAI_REACH_PROVIDERS_0_IDEMPOTENT:false} # 仅接收端具备原子持久去重时启用；默认在途不明结果转 unknown
 templates:
   - name: otp_email
     provider: email
@@ -50,3 +51,10 @@ templates:
 #   strategy: discard # discard | delay
 #   start: '22:00'
 #   end: '08:00'
+
+# 延迟队列策略随每条消息保存；最多领取 5 次，指数退避 1 分钟至 1 小时。
+# 超限 dead 只经可信服务端人工恢复；unknown 不允许自动重发。
+queue:
+  maxAttempts: ${HAI_REACH_QUEUE_MAXATTEMPTS:5}
+  retryDelayMs: ${HAI_REACH_QUEUE_RETRYDELAYMS:60000}
+  maxRetryDelayMs: ${HAI_REACH_QUEUE_MAXRETRYDELAYMS:3600000}

package/templates/apps/fullstack/packages/{{projectName}}-serv/config/_serv.yml.hbs

@@ -42,11 +42,12 @@ cors:
     - X-HAI-Token-Transport
     - X-Client-Id
     - X-Encrypted
+    - X-Hai-Transport
   exposedHeaders:
     - X-Request-Id
     - X-Encrypted
+    - X-Hai-Transport
 
 transport:
   keyExchangePath: /_hai/key-exchange
-  maxClients: 10000
   # excludePaths: [/health, /ready]

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

@@ -35,6 +35,9 @@
     "start:prod": "pnpm start"
   },
   "dependencies": {
+{{#if features.ai}}
+    "@h-ai/ai": "{{haiPackageSpecifier}}",
+{{/if}}
     "@h-ai/audit": "{{haiPackageSpecifier}}",
     "@h-ai/cache": "{{haiPackageSpecifier}}",
     "@h-ai/core": "{{haiPackageSpecifier}}",
@@ -44,6 +47,9 @@
     "@h-ai/reldb": "{{haiPackageSpecifier}}",
     "@h-ai/serv": "{{haiPackageSpecifier}}",
     "@h-ai/storage": "{{haiPackageSpecifier}}",
+{{#if features.vecdb}}
+    "@h-ai/vecdb": "{{haiPackageSpecifier}}",
+{{/if}}
     "zod": "{{fullstack.packageSpecifiers.zod}}",
     "{{fullstack.contractPackageName}}": "workspace:*"
   }

package/templates/apps/fullstack/packages/{{projectName}}-serv/src/app-server.ts.hbs

@@ -1,7 +1,8 @@
 import type { CoreConfig } from '@h-ai/core'
 import type { ServHttpApp } from '@h-ai/serv'
+import process from 'node:process'
 import { core } from '@h-ai/core'
-import { createReldbTransportKeyStore, crypto } from '@h-ai/crypto'
+import { createReldbTransportKeyStore, crypto, parseTransportServerKeyRing } from '@h-ai/crypto'
 import { iam } from '@h-ai/iam'
 import { reldb } from '@h-ai/reldb'
 import { serv, ServConfigSchema } from '@h-ai/serv'
@@ -13,6 +14,9 @@ const STARTED_AT = new Date().toISOString()
 
 /** 创建后端 HTTP App；与 @h-ai/serv 的 createApp 返回语义保持一致。 */
 export function createServerApp(): ServHttpApp {
+  const ring = parseTransportServerKeyRing(process.env.HAI_CRYPTO_TRANSPORT_SERVERKEYRING)
+  if (!ring.success)
+    throw new Error(ring.error.message)
   const coreConfig = core.config.getOrThrow<CoreConfig>('core')
   const servConfig = ServConfigSchema.parse(core.config.getOrThrow('serv'))
   const security = serv.createRuntimeSecurityPolicy({
@@ -46,8 +50,8 @@ export function createServerApp(): ServHttpApp {
         && ['{{projectName}}-app', '{{projectName}}-desktop'].includes(request.headers.get('x-request-client') ?? '')
         && security.isNativeOrigin(request.headers.get('origin') ?? '') },
     },
-    // 管理业务默认强制双向加密；客户端公钥复用 reldb 保存，服务端密钥仅驻留进程。
-    transport: { ...(servConfig.transport || {}), excludePaths: publicPaths, crypto, keyStore: createReldbTransportKeyStore({ reldb }) },
+    // 管理业务默认强制双向加密；各节点复用受管服务端密钥环与共享 reldb 客户端 registry。
+    transport: { ...(servConfig.transport || {}), excludePaths: publicPaths, crypto, serverKeyRing: ring.data, keyStore: createReldbTransportKeyStore({ reldb, ttlSeconds: 3600 }) },
     http: {
       ...servConfig.http,
       openapi: security.exposeApiDocs ? servConfig.http.openapi : false,
@@ -57,8 +61,8 @@ export function createServerApp(): ServHttpApp {
       middleware: serv.cors({
         origin: security.allowOrigin,
         credentials: servConfig.cors.credentials,
-        allowedHeaders: [...new Set([...servConfig.cors.allowedHeaders, 'X-Client-Id', 'X-Encrypted', 'X-Request-Client', 'X-HAI-Token-Transport'])],
-        exposedHeaders: [...new Set([...servConfig.cors.exposedHeaders, 'X-Encrypted'])],
+        allowedHeaders: [...new Set([...servConfig.cors.allowedHeaders, 'X-Client-Id', 'X-Encrypted', 'X-Hai-Transport', 'X-Request-Client', 'X-HAI-Token-Transport'])],
+        exposedHeaders: [...new Set([...servConfig.cors.exposedHeaders, 'X-Encrypted', 'X-Hai-Transport'])],
       }),
     }, {
       path: `${servConfig.http.apiPrefix}/assets/*`,

package/templates/apps/fullstack/packages/{{projectName}}-serv/src/server/admin-service.ts.hbs

@@ -21,18 +21,19 @@ export async function withAdminMutation<T>(context: ServContext, work: () => Pro
   if (adminMutationActive)
     return err(HaiCommonError.CONFLICT, serverM('busy', { locale: context.locale }))
   adminMutationActive = true
-  const owner = core.id.uuid()
+  let owner = ''
   const key = 'hai:app:admin-mutation'
   let acquired = false
   let leaseLost = false
   let renewalPending = false
   let renewalTimer: ReturnType<typeof setInterval> | undefined
   try {
-    const locked = await cache.lock.acquire(key, { owner, ttl: 300 })
+    const locked = await cache.lock.acquire(key, { ttl: 300 })
     if (!locked.success)
       return locked
     if (!locked.data)
       return err(HaiCommonError.CONFLICT, serverM('busy', { locale: context.locale }))
+    owner = locked.data
     acquired = true
     renewalTimer = setInterval(() => {
       if (renewalPending || leaseLost)

package/templates/apps/fullstack/packages/{{projectName}}-serv/src/server/messages.ts.hbs

@@ -1,6 +1,6 @@
 import { core } from '@h-ai/core'
 
-/** 服务端业务提示与角色种子名称同步维护中英文。 */
+/** 服务端业务提示与角色种子名称同步维护中英日文。 */
 export const serverM = core.i18n.createMessageGetter({
   'zh-CN': {
     admin: '管理员',
@@ -8,18 +8,33 @@ export const serverM = core.i18n.createMessageGetter({
     adminDescription: '管理用户、角色和审计日志',
     userDescription: '仅可维护个人设置',
     notFound: '用户或角色不存在',
+    unauthorized: '请提供要撤销的访问令牌',
     selfProtection: '不能删除、禁用或降级当前管理员账号',
     invalidAvatar: '请选择不超过 512 KB 的有效 PNG、JPEG 或 WebP 图片',
     busy: '系统繁忙，请稍后重试',
     unsupportedPreference: '不支持此语言或主题',
     invalidDateRange: '结束时间不能早于开始时间',
   },
+  'ja-JP': {
+    admin: '管理者',
+    user: 'ユーザー',
+    adminDescription: 'ユーザー、ロール、監査ログを管理',
+    userDescription: '個人設定のみ管理',
+    notFound: 'ユーザーまたはロールが存在しません',
+    unauthorized: '取り消すアクセストークンを指定してください',
+    selfProtection: '自分の管理者アカウントは削除、無効化、降格できません',
+    invalidAvatar: '512KB以下の有効なPNG、JPEG、WebP画像を選択してください',
+    busy: 'システムが混雑しています。再試行してください',
+    unsupportedPreference: 'この言語またはテーマには対応していません',
+    invalidDateRange: '終了日は開始日以降にしてください',
+  },
   'en-US': {
     admin: 'Administrator',
     user: 'User',
     adminDescription: 'Manage users, roles and audit logs',
     userDescription: 'Manage personal settings only',
     notFound: 'User or role does not exist',
+    unauthorized: 'Provide the access token to revoke',
     selfProtection: 'You cannot delete, disable or demote your own administrator account',
     invalidAvatar: 'Choose a valid PNG, JPEG or WebP image up to 512 KB',
     busy: 'The system is busy. Please try again',

package/templates/apps/fullstack/packages/{{projectName}}-serv/src/server/procedures/admin-procedures.ts.hbs

@@ -29,11 +29,15 @@ export function createAuthProcedures() {
       return result
     await recordAudit({ ...context, session: { userId: result.data.user.id, roles: result.data.roles, permissions: result.data.permissions } }, 'login', 'auth')
     return result
-  }).route('logout').auth().handle(async ({ context }) => {
-    const result = await iam.auth.logout(context.accessToken ?? '')
+  }).route('logout', async ({ input, context }) => {
+    const token = input.accessToken ?? context.accessToken
+    if (!token)
+      return err(HaiCommonError.UNAUTHORIZED, serverM('unauthorized', { locale: context.locale }))
+    const result = await iam.auth.logout(token)
     if (!result.success)
       return result
-    await recordAudit(context, 'logout', 'auth')
+    if (context.session)
+      await recordAudit(context, 'logout', 'auth')
     return result
   }).route('changePassword').auth().handle(async ({ input, context }) => {
     const result = await iam.user.changeCurrentUserPassword(context.accessToken ?? '', input.oldPassword, input.newPassword)

package/templates/apps/fullstack/packages/{{projectName}}-serv/src/server/procedures/index.ts.hbs

@@ -2,6 +2,8 @@ import type { CreateAppProceduresOptions } from './app-procedures.js'
 import { createAdminProcedures, createAuthProcedures, createProfileProcedures } from './admin-procedures.js'
 import { createAppProcedures } from './app-procedures.js'
 
+// @hai-generator:procedures:imports
+
 export interface CreateServerProceduresOptions {
   readonly app: CreateAppProceduresOptions
 }
@@ -9,6 +11,7 @@ export interface CreateServerProceduresOptions {
 /** 工程级 procedures 聚合入口；后续增加领域时在这里追加即可。 */
 export function createServerProcedures(options: CreateServerProceduresOptions) {
   return {
+    // @hai-generator:procedures:entries
     app: createAppProcedures(options.app),
     iam: { auth: createAuthProcedures() },
     admin: createAdminProcedures(),

package/templates/apps/fullstack/packages/{{projectName}}-serv/src/server/runtime.ts.hbs

@@ -2,6 +2,9 @@ import type { CoreConfig, HaiResult } from '@h-ai/core'
 import { mkdir } from 'node:fs/promises'
 import path from 'node:path'
 import process from 'node:process'
+{{#if features.ai}}
+import { ai, AIConfigSchema } from '@h-ai/ai'
+{{/if}}
 import { audit, AuditInitConfigSchema } from '@h-ai/audit'
 import { cache, CacheConfigSchema } from '@h-ai/cache'
 import { core } from '@h-ai/core'
@@ -11,13 +14,20 @@ import { reach, ReachConfigSchema } from '@h-ai/reach'
 import { reldb, ReldbConfigSchema } from '@h-ai/reldb'
 import { ServConfigSchema } from '@h-ai/serv'
 import { storage, StorageConfigSchema } from '@h-ai/storage'
+{{#if features.vecdb}}
+import { vecdb, VecdbConfigSchema } from '@h-ai/vecdb'
+{{/if}}
 import { serverM } from './messages.js'
 
 let initialized = false
 let initializing: Promise<void> | undefined
+let closing: Promise<void> | undefined
+let cleanupPending = false
 
 /** 初始化失败停止启动并反序释放资源；不把功能缺失降级为成功。 */
 export async function initializeModules(): Promise<void> {
+  if (closing)
+    await closing
   if (initialized)
     return
   initializing ??= runInitialization().finally(() => {
@@ -27,6 +37,9 @@ export async function initializeModules(): Promise<void> {
 }
 
 async function runInitialization(): Promise<void> {
+  if (cleanupPending)
+    await cleanupModules()
+  cleanupPending = true
   try {
     requireInitialized(core.config.validate('serv', ServConfigSchema), 'serv-config')
     const db = ReldbConfigSchema.parse(core.config.getOrThrow('db'))
@@ -38,6 +51,10 @@ async function runInitialization(): Promise<void> {
       await mkdir(path.dirname(db.database), { recursive: true })
     requireInitialized(await reldb.init(db), 'reldb')
     requireInitialized(await cache.init(cacheConfig), 'cache')
+{{#if features.vecdb}}
+    const vectorConfig = VecdbConfigSchema.parse(core.config.getOrThrow('vecdb'))
+    requireInitialized(await vecdb.init(vectorConfig), 'vecdb')
+{{/if}}
     requireInitialized(await crypto.init(), 'crypto')
     requireInitialized(await storage.init(storageConfig), 'storage')
     const reachConfig = core.config.get('reach')
@@ -45,13 +62,23 @@ async function runInitialization(): Promise<void> {
       requireInitialized(await reach.init(ReachConfigSchema.parse(reachConfig)), 'reach')
     requireInitialized(await iam.init({ ...iamConfig, reach }), 'iam')
     requireInitialized(await audit.init(auditConfig), 'audit')
+{{#if features.ai}}
+    const aiConfig = AIConfigSchema.parse(core.config.getOrThrow('ai'))
+    requireInitialized(await ai.init(aiConfig), 'ai')
+{{/if}}
     await ensureRolesAndAdmin()
     initialized = true
+    cleanupPending = false
     const app = core.config.getOrThrow<CoreConfig>('core')
     core.logger.info('Application initialized', { name: app.name, version: app.version, environment: app.env })
   }
   catch (error) {
-    await closeModules()
+    try {
+      await cleanupModules()
+    }
+    catch (cleanupError) {
+      throw new AggregateError([error, cleanupError], 'Application startup and cleanup failed')
+    }
     throw error
   }
 }
@@ -91,12 +118,36 @@ async function ensureRolesAndAdmin(): Promise<void> {
 
 /** 关闭顺序与依赖初始化顺序相反，同时覆盖启动失败路径。 */
 export async function closeModules(): Promise<void> {
-  for (const [name, module] of [['audit', audit], ['iam', iam], ['reach', reach], ['storage', storage], ['crypto', crypto], ['cache', cache], ['reldb', reldb]] as const) {
-    if (!module.isInitialized)
-      continue
-    const result = await module.close()
-    if (result && !result.success)
-      core.logger.error('Failed to close application module', { module: name, error: result.error.code })
+  if (!closing) {
+    const pending = initializing
+    closing = (async () => {
+      if (pending)
+        await pending.catch(() => undefined)
+      await cleanupModules()
+    })().finally(() => {
+      closing = undefined
+    })
+  }
+  return closing
+}
+
+/** 不依赖 isInitialized 推断资源是否释放；关闭失败必须保留义务供重试。 */
+async function cleanupModules(): Promise<void> {
+  const failures: unknown[] = []
+  for (const [name, module] of [{{#if features.ai}}['ai', ai], {{/if}}['audit', audit], ['iam', iam], ['reach', reach], ['storage', storage], ['crypto', crypto], {{#if features.vecdb}}['vecdb', vecdb], {{/if}}['cache', cache], ['reldb', reldb]] as const) {
+    try {
+      const result = await module.close()
+      if (result && !result.success) {
+        core.logger.error('Failed to close application module', { module: name, error: result.error.code })
+        failures.push(result.error)
+      }
+    }
+    catch (error) {
+      failures.push(error)
+    }
   }
   initialized = false
+  cleanupPending = failures.length > 0
+  if (failures.length > 0)
+    throw new AggregateError(failures, 'Application cleanup failed; retry closeModules()')
 }

package/templates/apps/fullstack/packages/{{projectName}}-serv/tests/app-server.test.ts.hbs

@@ -46,6 +46,10 @@ beforeAll(async () => {
   vi.stubEnv('HAI_ADMIN_DEFAULT_PASSWORD', TEST_PASSWORD)
   core.init({ configDir: './config' })
   await initializeModules()
+  const key = crypto.asymmetric.generateKeyPair()
+  if (!key.success)
+    throw new Error(key.error.message)
+  vi.stubEnv('HAI_CRYPTO_TRANSPORT_SERVERKEYRING', JSON.stringify({ activeKeyId: 'test-v1', keys: { 'test-v1': key.data } }))
   app = createServerApp()
   transport = crypto.transport.createClient({
     keyExchangeUrl: `http://localhost${PREFIX}/_hai/key-exchange`,
@@ -339,7 +343,10 @@ describe('{{fullstack.servPackageName}} mini administration', () => {
   })
 
   it('rejects stale administrator snapshots and reports fresh user roles', async () => {
-    const stale = await iam.session.update(userToken, { roles: ['admin'], permissions: ['*'] })
+    const snapshot = await iam.session.get(userToken)
+    if (!snapshot.success || !snapshot.data)
+      throw new Error('Session unavailable')
+    const stale = await iam.session.update(userToken, { roles: ['admin'], permissions: ['*'] }, snapshot.data.version)
     expect(stale.success).toBe(true)
     for (const [route, input] of [['/admin/users/list', { page: 1, pageSize: 20 }], ['/admin/roles/list', undefined], ['/admin/audit/list', { page: 1, pageSize: 20 }]] as const) {
       const denied = await call(route, input, userToken)
@@ -354,8 +361,11 @@ describe('{{fullstack.servPackageName}} mini administration', () => {
   })
 
   it('returns a conflict when another administrator holds the mutation lock and resumes after release', async () => {
-    const locked = await cache.lock.acquire('hai:app:admin-mutation', { owner: 'test-owner', ttl: 10 })
+    const locked = await cache.lock.acquire('hai:app:admin-mutation', { ttl: 10 })
     expect(locked.success).toBe(true)
+    if (!locked.success || !locked.data)
+      throw new Error('Mutation lock unavailable')
+    const owner = locked.data
     try {
       const result = await call('/admin/users/update', { id: user.id, displayName: 'Locked' }, adminToken)
       expect(result.success).toBe(false)
@@ -363,7 +373,7 @@ describe('{{fullstack.servPackageName}} mini administration', () => {
         expect(result.error.httpStatus).toBe(409)
     }
     finally {
-      expect((await cache.lock.release('hai:app:admin-mutation', 'test-owner')).success).toBe(true)
+      expect((await cache.lock.release('hai:app:admin-mutation', owner)).success).toBe(true)
     }
     expect((await call('/admin/users/update', { id: user.id, displayName: 'Unlocked' }, adminToken)).success).toBe(true)
   })

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

@@ -40,11 +40,11 @@ Language and theme preferences are saved in IAM user metadata, restored after lo
 
 AdminWorkspace mounts the shared `@h-ai/ui/guide` controller and GuideHost after authentication. AppShell includes a help button; first-use invitations offer start, later and dismiss. Web stores preferences in Cookies, while App/Desktop use localStorage, scoped by the current user and tour version. Help articles link to the overview and profile tours.
 
-Extend `src/lib/stores/guide-store.ts` and the shared Chinese/English messages, then add stable data-guide attributes to existing components. Navigation uses the same ManagementStore. Keep business text as i18n callbacks and preserve the host's locale/scope binding. Browser tests cover completion, reload, replay, settings navigation and mobile help.
+Extend `src/lib/stores/guide-store.ts` and the shared Chinese/English/Japanese messages, then add stable data-guide attributes to existing components. Navigation uses the same ManagementStore. Keep business text as i18n callbacks and preserve the host's locale/scope binding. Browser tests cover completion, reload, replay, settings navigation and mobile help.
 
 ### i18n and themes
 
-Shared page copy belongs in `messages/{zh-CN,en-US}.json`. Frontend-specific copy belongs in each app's own messages directory. Keep `baseLocale` and `locales` aligned across all enabled projects, then run root `pnpm i18n:compile`; do not edit generated Paraglide files.
+Shared page copy belongs in `messages/{zh-CN,en-US,ja-JP}.json`. Frontend-specific copy belongs in each app's own messages directory. Keep `baseLocale` and `locales` aligned across all enabled projects, then run root `pnpm i18n:compile`; do not edit generated Paraglide files.
 
 All frontend and shared projects load the installed message-format plugin from the workspace root `node_modules`, matching the scaffold's hoisted dependency layout. Compilation uses the workspace dependency version and does not fetch a plugin from a CDN.
 
@@ -56,11 +56,11 @@ Run root `pnpm typecheck`, `pnpm lint`, `pnpm build`, `pnpm test` and `pnpm test
 
 ### IAM configuration
 
-The service's `config/_iam.yml` controls login methods, registration, password reset, agreements and `ui` branding. Email and SMS use providers/templates in `_reach.yml` or custom callbacks. `AuthPanel` uses the public configuration and framework auth actions to manage tokens, resend countdowns and errors. A single process can use memory cache. Multiple instances need shared database/cache, write routing and transport session affinity as described in the project README.
+The service's `config/_iam.yml` controls login methods, registration, password reset, agreements and `ui` branding. Email and SMS use providers/templates in `_reach.yml` or custom callbacks. `AuthPanel` uses the public configuration and framework auth actions to manage tokens, resend countdowns and errors. A single process can use memory cache. Multiple instances need shared database/cache, write routing and a shared managed transport key ring and registry as described in the project README.
 
 Authentication defaults to a split layout. Set `ui.variant`, `title`, `subtitle`, `brandTitle`, `brandText`, `logoUrl` and `illustrationUrl` to customize login and registration. Without a `brandTitle`, the displayed application name comes from `app.info` and follows `core` configuration.
 
-LDAP and Reach are optional. Install ldapts in the IAM service workspace only when using its default LDAP client, then enable login.ldap and set connection settings. Custom onOtpSendEmail/onOtpSendSms/onPasswordResetRequest callbacks work without Reach and must reject on delivery failure. Agreements open in a Modal. LoginForm/RegisterForm support header/extraFields/footer snippets; AuthPanel forwards loginHeader/loginFields/loginFooter and registerHeader/registerFields/registerFooter. See the generated hai-iam/hai-ui skills for configuration and examples.
+LDAP and Reach are optional. Install ldapts in the IAM service workspace only when using its default LDAP client, then enable login.ldap and set connection settings. Custom onOtpSendEmail/onOtpSendSms/onPasswordResetRequest callbacks work without Reach and must reject on delivery failure. Their third context argument supplies expiresAt/idempotencyKey; senders durably deduplicate that key, and errors/timeouts mean unknown delivery with no automatic resend. Agreements open in a Modal. LoginForm/RegisterForm support header/extraFields/footer snippets; AuthPanel forwards loginHeader/loginFields/loginFooter and registerHeader/registerFields/registerFooter. See the generated hai-iam/hai-ui skills for configuration and examples.
 
 Agreements accept Markdown text or a URL. Markdown takes precedence and opens in a safely rendered dialog.
 
@@ -74,6 +74,11 @@ The user editor uses `FormLayout columns={2} labelPosition="left"`. Personal set
 
 Run root `pnpm typecheck`, `pnpm lint`, `pnpm build`, `pnpm test` and `pnpm test:e2e`. Browser checks cover shared workflows; test native shells on their target platforms separately.
 
+## 界面设计与验收
+
+共享管理界面的 Web/App/Desktop 使用同一套 UI 组件和状态。设计、实现、审查分别参考根目录 `.agents/skills/hai-ui-design/`、`hai-ui/`、`hai-ui-review/`；正常、加载、空态、错误恢复、键盘、语言/主题和窄容器均按实际场景验收。组件的筛选、排序和分页仍由业务数据回调接入。
+
+
 ## License
 
 Apache-2.0