@h-ai/cli 1.0.0-beta.2 → 1.0.0-beta.21

package/templates/apps/fullstack/apps/{{projectName}}-app/src/build-metadata.ts.hbs

@@ -3,7 +3,6 @@
 {{#if features.feedback}}
 /** 当前应用编译时烘焙的产物身份；运行时配置不能覆盖。 */
 declare const __HAI_BUILD_METADATA__: { appVersion: string, buildId: string, commit: string }
-
 export const buildMetadata = __HAI_BUILD_METADATA__
 {{/if}}
 {{/if}}

package/templates/apps/fullstack/apps/{{projectName}}-app/src/lib/capacitor.ts.hbs

@@ -7,7 +7,6 @@ export async function initCapacitor(): Promise<HaiResult<void>> {
   const result = await capacitor.init()
   if (!result.success)
     return result
-
   if (capacitor.isNative()) {
     return capacitor.statusBar.configure({
       style: 'dark',

package/templates/apps/fullstack/apps/{{projectName}}-app/svelte.config.js.hbs

@@ -5,7 +5,10 @@ import { vitePreprocess } from '@sveltejs/vite-plugin-svelte'
 
 /** @type {import('@sveltejs/vite-plugin-svelte').SvelteConfig} */
 const config = {
-  preprocess: [autoImportHaiUi(), vitePreprocess()],
+  preprocess: [
+    vitePreprocess(),
+    autoImportHaiUi(),
+  ],
   compilerOptions: {
     // 使用 Svelte 5 Runes，和 @h-ai/ui 组件库保持一致。
     runes: true,

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

@@ -14,7 +14,9 @@ import { resolveBuildMetadata } from '../../scripts/build-metadata.js'
 const envDir = fileURLToPath(new URL('../../', import.meta.url))
 
 export default defineConfig(({ mode, command }) => {
-  const envResult = command === 'build' || process.env.HAI_E2E === '1' ? { 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
@@ -23,15 +25,23 @@ export default defineConfig(({ mode, command }) => {
   const metadataAsset: Plugin = {
     name: 'hai-build-metadata',
     generateBundle() {
-      this.emitFile({ type: 'asset', fileName: 'build-metadata.json', source: JSON.stringify(buildMetadata) })
+      this.emitFile({
+        type: 'asset',
+        fileName: 'build-metadata.json',
+        source: JSON.stringify(buildMetadata),
+      })
     },
   }
   const target = (env.PUBLIC_API_BASE || process.env.SERVICE_BASE_URL || 'http://127.0.0.1:3000').replace(/\/api\/v1\/?$/, '')
-  const proxy = { '/api': { target, changeOrigin: true } }
+  const proxy = {
+    '/api': { target, changeOrigin: true },
+  }
   return {
     base: './',
     envDir: false,
-    define: { __HAI_BUILD_METADATA__: JSON.stringify(buildMetadata) },
+    define: {
+      __HAI_BUILD_METADATA__: JSON.stringify(buildMetadata),
+    },
     server: { proxy },
     preview: { proxy },
     build: {
@@ -51,6 +61,8 @@ export default defineConfig(({ mode, command }) => {
       metadataAsset,
       svelte(),
       paraglideVitePlugin({
+        // 共享物理消息产物供独立 Vitest/Node 工具读取。
+        outputStructure: 'message-modules',
         project: './project.inlang',
         outdir: './src/lib/paraglide',
         strategy: ['cookie', 'baseLocale'],

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

@@ -4,7 +4,7 @@
 
 ## 简介
 
-桌面端工程，参考 `apps/desktop-app` 使用 Tauri v2 + Svelte 5 + Vite，前端通过共享 contract 调用 `{{fullstack.servPackageName}}`。
+Tauri v2 + Svelte 5 + Vite桌面工程，前端通过共享contract调用 `{{fullstack.servPackageName}}`。
 
 ## 核心功能清单
 
@@ -16,6 +16,8 @@
 
 ### i18n 与 shared 协同
 
+先从工程根安装依赖、启动Serv并配置实际API地址，再运行tauri:dev。有效账号登录后使用相同共享管理界面；输入受权限允许的管理操作，输出与Web一致。关闭并重启原生程序后内存凭据不保留，需要重新登录；外观/语言属于服务器偏好，登录后恢复。
+
 - 本端页面文案：`messages/{locale}.json` + `project.inlang/settings.json`
 - 共享 Shell/主题/语言/API：`packages/{{fullstack.sharedPackageName}}`
 - 个人设置保存语言与风格偏好到 IAM 元数据，并同步 shared 和本端 Paraglide runtime
@@ -26,6 +28,8 @@
 
 ### 编译、打包与部署
 
+产品名和主窗口初始标题统一取工程根环境文件解析后的 `packages/{{fullstack.servPackageName}}/config/_core.yml` 的 `name`，可用 `HAI_CORE_NAME` 覆盖。`tauri:dev` 默认 `dev`、打包默认 `prod`；进程 `HAI_CORE_ENV` 可指定模式。请使用下面的 `pnpm` 入口，直接 `pnpm exec tauri` / `cargo tauri` 会绕过名称解析。入口通过 `--config` 覆盖，不回写 JSON；显式追加的 `--config` 保留最终覆盖权。
+
 ```bash
 # 仅前端开发，默认端口 {{fullstack.ports.desktop}}
 pnpm --filter {{projectName}}-desktop dev
@@ -40,17 +44,15 @@ pnpm --filter {{projectName}}-desktop build
 pnpm build --target desktop --platform windows --arch x64
 ```
 
-打包前需要安装 Rust 工具链和 Tauri 平台依赖。构建不读取 .env.prod/.env.local；启动已安装程序前设置进程 PUBLIC_API_BASE（HTTP(S)，不含凭据、查询和片段）。Rust 会在页面加载前注入公开地址，仅将该 Origin 加入 CSP；不需要为 test/prod 重打安装包。缺省连接 http://localhost:3000/api/v1。
-
-### IAM 认证配置
+打包前需要安装 Rust 工具链和 Tauri 平台依赖。原生名称按 Core 规则读取环境文件，只将名称传入 Tauri 配置；前端源码编译不读取部署环境文件。启动已安装程序前设置进程 PUBLIC_API_BASE（HTTP(S)，不含凭据、查询和片段）。Rust 会在页面加载前注入公开地址，仅将该 Origin 加入 CSP；不需要为 API 地址的 test/prod 切换重打安装包，修改原生名称仍需重新打包。缺省连接 http://localhost:3000/api/v1。
 
-服务端 `config/_iam.yml` 统一控制登录、注册、重置、协议与 `ui` 品牌。邮件/短信可用 `_reach.yml` 中的 Provider/标准模板或自定义发送回调。`AuthPanel` 使用安全公开配置及框架认证动作；无需在页面适配 Token、验证码倒计时和错误提示。Memory 仅用于本地开发和显式测试；生产环境即使只有一个实例，也须使用框架支持的共享数据库与 Redis，并按工程根 README 配置写入路由和传输会话。
+加 `--debug` 生成调试安装包。成功后 CLI 打印 `.hai/build/desktop/<平台>/<构建类型>/build-{{projectName}}-desktop-<平台>-<架构>-<类型>-YYYYMMDD-HHmmss-<随机串>-<版本>/` 中的归档路径。Windows 文件名如 `{{projectName}}-windows-x64-release-<版本>-setup.exe`；使用工程标识，产品显示名仍取 Core。
 
-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，由安全渲染器在弹窗显示。
+认证方式、注册、密码策略、协议与品牌由Serv的 `_iam.yml` 控制。前端只接收安全公开配置，使用共享AuthPanel和加密typed client；服务端再次核验权限。LDAP、通知回调、用途证明和会话限制在服务端接入，不把私密配置复制到客户端。
 
-完整契约见生成应用的 `.agents/skills/hai-iam/reference.md`。
+所有前端共用的偏好、认证存储、表单、审计与帮助行为见[共享工作区](../../packages/{{fullstack.sharedPackageName}}/README.md)，详细配置见[生成应用IAM技能](../../.agents/skills/hai-iam/reference.md)。
 
 启用反馈时使用 SDK 原生保存对话框，Tauri dialog/fs 插件只允许选择路径后写入。CSP 允许图片和视频 blob 预览、沙箱回放，脚本和网络来源限制保持明确；Web 浏览器验证不代替系统 WebView/安装包验收。
 

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

@@ -23,9 +23,9 @@
     "test": "pnpm paraglide:compile && vitest run --passWithNoTests",
     "test:watch": "pnpm paraglide:compile && vitest",
     "clean": "rimraf dist .turbo src-tauri/target src/lib/paraglide",
-    "tauri": "tauri",
-    "tauri:dev": "tauri dev",
-    "tauri:build": "tauri build"
+    "tauri": "node ../../scripts/run-tauri.mjs ../.. packages/{{fullstack.servPackageName}}/config/_core.yml",
+    "tauri:dev": "pnpm tauri dev",
+    "tauri:build": "pnpm tauri build"
   },
   "dependencies": {
     "@h-ai/api-client": "{{haiPackageSpecifier}}",

package/templates/apps/fullstack/apps/{{projectName}}-desktop/src/App.svelte.hbs

@@ -12,8 +12,14 @@
   const native = '__TAURI_INTERNALS__' in globalThis
   const apiOptions: ManagementApiOptions = {
     clientName: '{{projectName}}-desktop',
-      terminalType: 'desktop',
-    ...(native ? { requireApiBase: true, tokenStorage: apiClient.tokenStorage.memory(), headers: { 'X-HAI-Token-Transport': 'body' } } : {}),
+    terminalType: 'desktop',
+    ...(native
+      ? {
+        requireApiBase: true,
+        tokenStorage: apiClient.tokenStorage.memory(),
+        headers: { 'X-HAI-Token-Transport': 'body' },
+      }
+      : {}),
   }
 
   function syncLocale(locale: string) {

package/templates/apps/fullstack/apps/{{projectName}}-desktop/src/build-metadata.ts.hbs

@@ -3,7 +3,6 @@
 {{#if features.feedback}}
 /** 当前应用编译时烘焙的产物身份；运行时配置不能覆盖。 */
 declare const __HAI_BUILD_METADATA__: { appVersion: string, buildId: string, commit: string }
-
 export const buildMetadata = __HAI_BUILD_METADATA__
 {{/if}}
 {{/if}}

package/templates/apps/fullstack/apps/{{projectName}}-desktop/src-tauri/tauri.conf.json.hbs

@@ -2,7 +2,6 @@
 {{#if fullstack.frontends.desktop}}
 {
   "$schema": "https://schema.tauri.app/config/2",
-  "productName": {{json fullstack.appName}},
   "version": "../../../package.json",
   "identifier": "com.hai.{{fullstack.nativeAppIdSegment}}.desktop",
   "build": {
@@ -14,7 +13,6 @@
   "app": {
     "windows": [
       {
-        "title": {{json fullstack.appName}},
         "width": 1280,
         "height": 800,
         "resizable": true,

package/templates/apps/fullstack/apps/{{projectName}}-desktop/svelte.config.js.hbs

@@ -5,7 +5,10 @@ import { vitePreprocess } from '@sveltejs/vite-plugin-svelte'
 
 /** @type {import('@sveltejs/vite-plugin-svelte').SvelteConfig} */
 export default {
-  preprocess: [autoImportHaiUi(), vitePreprocess()],
+  preprocess: [
+    vitePreprocess(),
+    autoImportHaiUi(),
+  ],
   compilerOptions: {
     // 使用 Svelte 5 Runes，和 @h-ai/ui 组件库保持一致。
     runes: true,

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

@@ -15,7 +15,9 @@ const host = process.env.TAURI_DEV_HOST
 const envDir = fileURLToPath(new URL('../../', import.meta.url))
 
 export default defineConfig(({ mode, command }) => {
-  const envResult = command === 'build' || process.env.HAI_E2E === '1' ? { 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
@@ -24,16 +26,24 @@ export default defineConfig(({ mode, command }) => {
   const metadataAsset: Plugin = {
     name: 'hai-build-metadata',
     generateBundle() {
-      this.emitFile({ type: 'asset', fileName: 'build-metadata.json', source: JSON.stringify(buildMetadata) })
+      this.emitFile({
+        type: 'asset',
+        fileName: 'build-metadata.json',
+        source: JSON.stringify(buildMetadata),
+      })
     },
   }
   const target = (env.PUBLIC_API_BASE || process.env.SERVICE_BASE_URL || 'http://127.0.0.1:3000').replace(/\/api\/v1\/?$/, '')
-  const proxy = { '/api': { target, changeOrigin: true } }
+  const proxy = {
+    '/api': { target, changeOrigin: true },
+  }
 
   return {
     base: './',
     envDir: false,
-    define: { __HAI_BUILD_METADATA__: JSON.stringify(buildMetadata) },
+    define: {
+      __HAI_BUILD_METADATA__: JSON.stringify(buildMetadata),
+    },
     preview: { proxy },
     build: {
       rolldownOptions: {
@@ -53,6 +63,8 @@ export default defineConfig(({ mode, command }) => {
       svelte(),
       tailwindcss(),
       paraglideVitePlugin({
+        // 共享物理消息产物供独立 Vitest/Node 工具读取。
+        outputStructure: 'message-modules',
         project: './project.inlang',
         outdir: './src/lib/paraglide',
         strategy: ['cookie', 'baseLocale'],

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

@@ -15,6 +15,8 @@
 
 选定小程序框架后再实现页面、请求适配和认证。小程序文案放本目录 `messages/`，跨端通用内容放 `packages/{{fullstack.sharedPackageName}}`；消息格式插件使用工程根已安装的依赖。
 
+例如在messages加入一条中英日文业务提示，当前输出只是可供后续接入的消息资源，不会生成页面或安装包。引用contract只获得输入输出类型，不能自动获得请求传输、登录、安全存储或平台权限。建立真正的小程序工程后再加入workspace、运行脚本和发布流程。
+
 ## 开发测试
 
 本目录不参与 workspace 构建、单元测试或 E2E。接入实际框架后增加对应命令，并在目标平台验证登录、请求、导航与发布包。

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

@@ -16,6 +16,8 @@
 
 ### i18n 与 shared 协同
 
+从根目录安装依赖并启动Serv，再执行本页dev命令。输入有效测试账号后进入共享管理界面；普通用户只能看到被授权的功能。修改个人资料成功才结束编辑，失败保留输入。个人设置的主题/语言保存后，刷新并重新登录应能恢复。
+
 - 本端页面文案：`messages/{locale}.json` + `project.inlang/settings.json`
 - 共享 Shell/主题/语言/API：`packages/{{fullstack.sharedPackageName}}`
 - 个人设置保存语言与风格偏好到 IAM 元数据，并同步 shared 和本端 Paraglide runtime
@@ -24,6 +26,8 @@
 
 ### 编译、打包与部署
 
+入口 HTML 在主应用前执行 `public/_hai/browser-check/startup.js`。Chrome/Edge 低于 111、Firefox 低于 114、Safari 或 iOS/iPadOS 低于 16.4 时，独立升级页会显示当前版本、最低要求和厂商更新入口。发布时连同该目录的 HTML 和样式一起部署。
+
 ```bash
 # 开发预览，默认端口 {{fullstack.ports.web}}
 pnpm --filter {{projectName}}-web dev
@@ -32,21 +36,17 @@ pnpm --filter {{projectName}}-web dev
 pnpm --filter {{projectName}}-web build
 ```
 
-从工程根运行 `pnpm build --target docker` 导出镜像。默认带部署工具，可运行 `pnpm run deploy --env test --build` 一次完成构建发布，或 `pnpm run deploy --env prod --bundle-only` 交付已有镜像及跨平台脚本。完整包包含自建中间件，人工部署与按服务更新见工程根 README。
-
-### IAM 认证配置
-
-服务端 `config/_iam.yml` 统一控制登录、注册、重置、协议与 `ui` 品牌。邮件/短信可用 `_reach.yml` 中的 Provider/标准模板或自定义发送回调。`AuthPanel` 使用安全公开配置及框架认证动作；无需在页面适配 Token、验证码倒计时和错误提示。Memory 仅用于本地开发和显式测试；生产环境即使只有一个实例，也须使用框架支持的共享数据库与 Redis，并按工程根 README 配置写入路由和传输会话。
+从工程根运行 `pnpm build --target image` 导出镜像。默认带部署工具，可运行 `pnpm run deploy --env test --build` 一次完成构建发布，或 `pnpm run deploy --env prod --bundle-only` 交付已有镜像及跨平台脚本。完整包包含自建中间件，人工部署与按服务更新见工程根 README。
 
-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，由安全渲染器在弹窗显示。
+认证方式、注册、密码策略、协议与品牌由Serv的 `_iam.yml` 控制。前端只接收安全公开配置，使用共享AuthPanel和加密typed client；服务端再次核验权限。LDAP、通知回调、用途证明和会话限制在服务端接入，不把私密配置复制到客户端。
 
-完整契约见生成应用的 `.agents/skills/hai-iam/reference.md`。
+所有前端共用的偏好、认证存储、表单、审计与帮助行为见[共享工作区](../../packages/{{fullstack.sharedPackageName}}/README.md)，详细配置见[生成应用IAM技能](../../.agents/skills/hai-iam/reference.md)。
 
 ## 开发测试
 
-从工程根执行 `pnpm typecheck`、`pnpm lint`、`pnpm build`、`pnpm test` 和 `pnpm test:e2e`。浏览器预览通过后，原生壳仍需在对应系统或设备单独验收。
+从工程根执行 `pnpm typecheck`、`pnpm lint`、`pnpm build`、`pnpm test` 和 `pnpm test:e2e`。浏览器通过后仍需在实际公开地址验证部署、认证与持久数据。
 
 ## 许可证
 

package/templates/apps/fullstack/apps/{{projectName}}-web/eslint.config.js.hbs

@@ -5,9 +5,17 @@ import { haiQualityConfig } from '../../eslint-rules.js'
 
 export default antfu({
   // unused-imports 使用 TS 规则，JS 同样使用 TS parser 以保持 scope 契约一致。
-  typescript: { files: [GLOB_SRC] },
+  typescript: {
+    files: [GLOB_SRC],
+  },
   formatters: true,
-  ignores: ['**/build/**', '**/dist/**', '**/*.d.ts', '**/project.inlang/**', '**/src/lib/paraglide/**'],
+  ignores: [
+    '**/build/**',
+    '**/dist/**',
+    '**/*.d.ts',
+    '**/project.inlang/**',
+    '**/src/lib/paraglide/**',
+  ],
   svelte: true,
 }, haiQualityConfig, {
   files: ['**/*.svelte'],

package/templates/apps/fullstack/apps/{{projectName}}-web/index.html.hbs

@@ -5,6 +5,7 @@
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <script id="hai-browser-startup" src="./_hai/browser-check/startup.js"></script>
     <title>{{html fullstack.appName}}</title>
     <link
       rel="icon"

package/templates/apps/fullstack/apps/{{projectName}}-web/src/build-metadata.ts.hbs

@@ -3,7 +3,6 @@
 {{#if features.feedback}}
 /** 当前应用编译时烘焙的产物身份；运行时配置不能覆盖。 */
 declare const __HAI_BUILD_METADATA__: { appVersion: string, buildId: string, commit: string }
-
 export const buildMetadata = __HAI_BUILD_METADATA__
 {{/if}}
 {{/if}}

package/templates/apps/fullstack/apps/{{projectName}}-web/src/main.ts.hbs

@@ -7,8 +7,6 @@ import './app.css'
 const target = document.getElementById('app')
 if (!target)
   throw new Error('Root element #app not found')
-
 const app = mount(App, { target })
-
 export default app
 {{/if}}

package/templates/apps/fullstack/apps/{{projectName}}-web/svelte.config.js.hbs

@@ -5,7 +5,10 @@ import { vitePreprocess } from '@sveltejs/vite-plugin-svelte'
 
 /** @type {import('@sveltejs/vite-plugin-svelte').SvelteConfig} */
 const config = {
-  preprocess: [autoImportHaiUi(), vitePreprocess()],
+  preprocess: [
+    vitePreprocess(),
+    autoImportHaiUi(),
+  ],
   compilerOptions: {
     // 使用 Svelte 5 Runes，和 @h-ai/ui 组件库保持一致。
     runes: true,

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

@@ -15,7 +15,9 @@ import { resolvePublicBasePath } from '../../scripts/public-base-path.mjs'
 const envDir = fileURLToPath(new URL('../../', import.meta.url))
 
 export default defineConfig(({ mode, command }) => {
-  const envResult = command === 'build' || process.env.HAI_E2E === '1' ? { 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
@@ -24,16 +26,26 @@ export default defineConfig(({ mode, command }) => {
   const metadataAsset: Plugin = {
     name: 'hai-build-metadata',
     generateBundle() {
-      this.emitFile({ type: 'asset', fileName: 'build-metadata.json', source: JSON.stringify(buildMetadata) })
+      this.emitFile({
+        type: 'asset',
+        fileName: 'build-metadata.json',
+        source: JSON.stringify(buildMetadata),
+      })
     },
   }
   const target = (env.PUBLIC_API_BASE || process.env.SERVICE_BASE_URL || 'http://127.0.0.1:3000').replace(/\/api\/v1\/?$/, '')
-  const proxy = { '/api': { target, changeOrigin: true } }
+  const proxy = {
+    '/api': { target, changeOrigin: true },
+  }
   const publicBase = resolvePublicBasePath()
   return {
-    base: publicBase ? `${publicBase}/` : './',
+    base: publicBase
+      ? `${publicBase}/`
+      : './',
     envDir: false,
-    define: { __HAI_BUILD_METADATA__: JSON.stringify(buildMetadata) },
+    define: {
+      __HAI_BUILD_METADATA__: JSON.stringify(buildMetadata),
+    },
     server: { proxy },
     preview: { proxy },
     build: {
@@ -53,6 +65,8 @@ export default defineConfig(({ mode, command }) => {
       metadataAsset,
       svelte(),
       paraglideVitePlugin({
+        // 共享物理消息产物供独立 Vitest/Node 工具读取。
+        outputStructure: 'message-modules',
         project: './project.inlang',
         outdir: './src/lib/paraglide',
         strategy: ['cookie', 'baseLocale'],

package/templates/apps/fullstack/docs/security-configuration.md.hbs

@@ -7,6 +7,7 @@
 | 文件                                                         | 用途                                               |
 | ------------------------------------------------------------ | -------------------------------------------------- |
 | `packages/{{projectName}}-serv/config/_iam.yml`              | 账号、密码、验证码、锁定、敏感操作、登录限制、会话 |
+| `packages/{{projectName}}-serv/config/_serv.yml`             | API 传输加密及请求时间窗口                          |
 | `packages/{{projectName}}-serv/config/_audit.yml`            | 审计采集、脱敏、保留、备份、告警                   |
 | `packages/{{projectName}}-serv/config/_reach.yml`            | 邮件、短信或通知 API 及通知模板                    |
 | `packages/{{projectName}}-serv/config/_scheduler.yml`        | 已有 Scheduler 的持久化及调度参数                  |
@@ -30,6 +31,8 @@ HAI_AUDIT_BACKUP_ENABLED=true
 
 这里列的是 fullstack 模板默认值，不是所有项目或底层 Schema 的普适限制。
 
+加密请求默认有效 300 秒，允许客户端时间领先服务器最多 30 秒。可在 `_serv.yml` 的 `transport` 下设置 `maxRequestAgeSeconds`（1～600）和 `maxFutureSkewSeconds`（0～300），单位为整数秒。超限时，前端显示校验时的服务器 UTC 时间，提示用户开启设备自动校时或手工修改时间，然后刷新。升级旧版本后，从最后一个旧节点停止处理请求起等待 12 分钟，再把请求有效期调到 300 秒以上。
+
 | 条目                         | fullstack 默认及启用入口                                        | 使用影响                                                 |
 | ---------------------------- | --------------------------------------------------------------- | -------------------------------------------------------- |
 | B03 长期/临时账号            | 用户管理中的账号类型、到期时间                                  | 临时账号必须有未来到期时间；到期后旧会话也不能继续使用   |
@@ -128,7 +131,7 @@ security:
 
 ## 独立初始凭据和安全邀请
 
-CLI 创建完成时会提示四个用户名、职责及密码变量位置；不在终端打印明文密码。新项目已在 `.env.dev/.env.test/.env.prod` 中为 admin、audit_admin、config_admin、business_operator 分别生成独立随机密码，各环境也不同。服务首次启动才创建缺失账号；缺少对应初始密码时跳过该账号，已有账号不覆盖。Admin Console 仓库示例由部署者在私有环境/进程中提供下表四个变量，不能把模板随机密码当成示例的固定通用密码。同名进程变量或 `.env.local` 可覆盖；修改这些初始变量不会重设已有账号的密码。需要首次强改时，在首次创建这些账号前开启上一节的 `requireInitialChange`。
+CLI 创建完成时会提示四个用户名、职责及密码变量位置；不在终端打印明文密码。新项目已在 `.env.dev.local/.env.test.local/.env.prod.local` 中为 admin、audit_admin、config_admin、business_operator 分别生成独立随机密码，各环境也不同。服务首次启动才创建缺失账号；缺少对应初始密码时跳过该账号，已有账号不覆盖。Admin Console 仓库示例由部署者在私有环境/进程中提供下表四个变量，不能把模板随机密码当成示例的固定通用密码。同名进程变量或 `.env.local` 可覆盖；修改这些初始变量不会重设已有账号的密码。需要首次强改时，在首次创建这些账号前开启上一节的 `requireInitialChange`。
 
 日常创建业务账号希望改为一次性邀请，先配置真实发送通道，再设置：