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

package/templates/apps/fullstack/apps/{{projectName}}-web/messages/ja-JP.json.hbs

@@ -0,0 +1,7 @@
+{{! @skipIfEmpty }}
+{{#if fullstack.frontends.web}}
+{
+  "$schema": "https://inlang.com/schema/inlang-message-format",
+  "page_title": "{name}"
+}
+{{/if}}

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
@@ -51,7 +51,7 @@ export default defineConfig(({ mode, command }) => {
     },
     envPrefix: ['VITE_', 'PUBLIC_'],
     ssr: {
-      noExternal: [/@h-ai\//, /{{fullstack.sharedPackageName}}/],
+      noExternal: ['@h-ai/ui', /{{fullstack.sharedPackageName}}/],
     },
     test: {
       environment: 'node',

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')
@@ -61,7 +61,7 @@ test('service rejects plaintext business requests', async ({ request }) => {
 })
 
 {{#if fullstack.e2eFrontend}}
-test('hash routing restores direct links, refresh and browser history', async ({ page }) => {
+test('hash routing and responsive workspace preserve usable content width', async ({ page }, testInfo) => {
   await page.goto('/#/roles?source=direct')
   await login(page, 'admin', adminPassword)
   await expect(page.getByTestId('roles-page')).toBeVisible()
@@ -70,6 +70,16 @@ test('hash routing restores direct links, refresh and browser history', async ({
   await expect(page.getByTestId('roles-page')).toBeVisible()
   await expect(page.locator('header')).toBeVisible()
   await expect(page.locator('footer')).toBeVisible()
+  for (const width of [1440, 1920, 2560, 3840, 390]) {
+    await page.setViewportSize({ width, height: 960 })
+    expect(await page.evaluate(() => document.documentElement.scrollWidth <= innerWidth)).toBe(true)
+    const main = await page.locator('main').boundingBox()
+    const content = await page.getByTestId('roles-page').boundingBox()
+    expect(content!.width).toBeGreaterThan(main!.width - 80)
+    if (width === 1920)
+      await capture(page, '{{projectName}}-wide.png', testInfo.outputPath('wide-1920.png'))
+  }
+  await page.setViewportSize({ width: 1440, height: 960 })
   await page.getByTestId('nav-settings').click()
   await expect(page).toHaveURL(/#\/settings$/)
   await page.goBack()
@@ -251,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)
@@ -448,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/hai.build.json.hbs

@@ -1,7 +1,7 @@
 {
   "images": [
-    { "name": "app", "target": "runtime", "containerPort": 3000 }{{#if fullstack.frontends.web}},
-    { "name": "web", "target": "web", "containerPort": 8080 }{{/if}}
+    { "name": "app", "dockerfile": "images/app.Dockerfile", "containerPort": 3000 }{{#if fullstack.frontends.web}},
+    { "name": "web", "dockerfile": "images/web.Dockerfile", "containerPort": 8080 }{{/if}}
   ]{{#if fullstack.frontends.desktop}},
   "desktop": ["apps/{{projectName}}-desktop"]{{/if}}
 }

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

@@ -0,0 +1,36 @@
+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
+RUN 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.Dockerfile.hbs

@@ -0,0 +1,34 @@
+{{#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
+RUN pnpm --filter {{fullstack.sharedPackageName}} paraglide:compile && 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

@@ -15,9 +15,11 @@
     "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",
+{{/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",

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

@@ -1,8 +1,18 @@
 # {{fullstack.contractPackageName}}
 
+## 简介
+
 共享 API 契约包，包含 Zod Schema、`apiContract.route()` 业务接口定义与工程级 contract。业务 schema、角色、流程及限额是模板初始方案，按用户需求修改，并同步服务端授权、调用方、测试与说明；不要求需求沿用默认业务。
 
-## 骨架说明
+## 核心功能清单
+
+- 共享接口路径、输入输出 Schema 和类型。
+- 客户端与服务端使用同一份 contract。
+- 不包含服务端业务实现，也不加载私有配置。
+
+## 使用入门
+
+### 骨架说明
 
 - `src/app-schemas.ts`：跨接口、跨层复用的输入/数据 Schema 与类型。
 - `src/app-contract.ts`：app 领域 contract；每个业务 path 直接写在对应接口定义中。
@@ -13,7 +23,18 @@
 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/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

@@ -1,8 +1,18 @@
 # {{fullstack.servPackageName}}
 
+## 简介
+
 后端 API Service，基于 `@h-ai/serv` 将共享 contract 装配为最小 HTTP App 抽象，不在应用代码中直接暴露 Hono。
 
-## 默认功能与配置
+## 核心功能清单
+
+- HTTP 服务、健康检查和共享 contract 的 procedure 实现。
+- 用户、角色、审计与个人设置的示例业务。
+- 模块配置、加密传输与服务端权限校验。
+
+## 使用入门
+
+### 默认功能与配置
 
 以下是可运行示例的初始实现，角色/权限、管理流程、头像限额、分页、审计策略及部署方案均可按用户需求调整。需求与代码或模板规则不一致时，以需求为业务基线同步实现、测试与过期说明；实际框架 API 契约和服务端安全校验仍需满足。
 
@@ -11,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')` 守卫。每个请求读取用户最新启用状态、角色和权限。
@@ -20,33 +31,46 @@
 
 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 初始化失败则停止启动。
 
-## 开发
+### 开发
 
 所有配置字段以模块 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`
 - `pnpm --filter {{fullstack.servPackageName}} test`
 
-## 容器运行
+### 容器运行
 
-从工程根运行 `pnpm build --target docker` 构建并导出镜像。启用 deploy 功能后，运行根命令 `pnpm deploy --env test`；含 Web 镜像时一并发布 API/Web，部署不重新构建。网络不通时用 `pnpm deploy --env prod --bundle-only`，按说明手工搬运 tar。
+从工程根运行 `pnpm build --target docker` 导出镜像。默认带部署工具，可运行 `pnpm run deploy --env test --build` 一次完成构建发布，或 `pnpm run deploy --env prod --bundle-only` 交付已有镜像及跨平台脚本。完整包包含自建中间件，人工部署与按服务更新见工程根 README。
 
 - 服务镜像直接由 `@h-ai/serv` 对外监听，配置挂载点为 `/app/config`，数据目录为 `/app/data`，不包含额外转发进程。
 - Web 镜像不烘焙 API 地址；启动时使用 `-e PUBLIC_API_BASE=https://api.example.com` 注入，同一镜像可部署到不同环境。未设置时 Web 默认请求自身 origin。
 - YAML 配置使用 `${ENV_NAME:default}` 接收运行时环境变量；不要把密钥写入镜像。
 
-## IAM 认证配置
+### IAM 认证配置
 
-服务端 `config/_iam.yml` 统一控制登录、注册、重置、协议与 `ui` 品牌。邮件/短信可用 `_reach.yml` 中的 Provider/标准模板或自定义发送回调。`AuthPanel` 使用安全公开配置及框架认证动作；无需在页面适配 Token、验证码倒计时和错误提示。所有节点共享同一 DB 与 Redis；Memory 仅用于单进程。
+服务端 `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，由安全渲染器在弹窗显示。
 
 完整契约见生成应用的 `.agents/skills/hai-iam/reference.md`。
+
+## 开发测试
+
+```sh
+pnpm --filter {{fullstack.servPackageName}} typecheck
+pnpm --filter {{fullstack.servPackageName}} test
+```
+
+## 许可证
+
+Apache-2.0

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(),