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

package/templates/apps/admin/src/routes/admin/settings/+page.svelte.hbs

@@ -1,11 +1,12 @@
 {{!-- 设置页面 --}}
-<script lang="ts">
+<script lang='ts'>
   /**
    * 设置页面
    */
 {{#if hasI18n}}
   import * as m from '$lib/paraglide/messages'
 {{/if}}
+  import { Card, PageHeader } from '@h-ai/ui'
 </script>
 
 <svelte:head>
@@ -17,21 +18,23 @@
 </svelte:head>
 
 {{#if hasI18n}}
-<h1 class="text-2xl font-bold mb-6">{m.page_settings_title()}</h1>
+<PageHeader title={m.page_settings_title()} description={m.page_settings_subtitle()} />
 
-<div class="card bg-base-100 shadow">
-  <div class="card-body">
-    <h2 class="card-title">{m.page_settings_basic()}</h2>
-    <p>{m.page_settings_desc()}</p>
+<Card shadow='sm' class='bg-base-100'>
+  <div class='flex items-center gap-2'>
+    <span class='icon-[tabler--adjustments] size-5 text-primary'></span>
+    <h2 class='text-base font-semibold'>{m.page_settings_basic()}</h2>
   </div>
-</div>
+  <p class='mt-2 text-sm text-base-content/60'>{m.page_settings_desc()}</p>
+</Card>
 {{else}}
-<h1 class="text-2xl font-bold mb-6">系统设置</h1>
+<PageHeader title='系统设置' description='管理系统配置项' />
 
-<div class="card bg-base-100 shadow">
-  <div class="card-body">
-    <h2 class="card-title">基本配置</h2>
-    <p>在此管理系统设置。</p>
+<Card shadow='sm' class='bg-base-100'>
+  <div class='flex items-center gap-2'>
+    <span class='icon-[tabler--adjustments] size-5 text-primary'></span>
+    <h2 class='text-base font-semibold'>基本配置</h2>
   </div>
-</div>
+  <p class='mt-2 text-sm text-base-content/60'>在此管理系统设置。</p>
+</Card>
 {{/if}}

package/templates/apps/api/.dockerignore.hbs

@@ -0,0 +1,25 @@
+**/.git
+**/node_modules
+**/.pnpm-store
+**/.cache
+**/.svelte-kit
+**/.turbo
+**/build
+**/dist
+**/coverage
+**/playwright-report
+**/test-results
+**/src-tauri/target
+**/hash-core/target
+tmp
+**/*.tar
+.github
+.agents
+.claude
+.codex
+.opencode
+**/data
+*.log
+# 仅保留公共基础 .env；分环境配置、私有覆盖及已有交付包不进入构建上下文。
+**/.env.*
+**/.hai

package/templates/apps/api/.gitignore.hbs

@@ -0,0 +1,22 @@
+node_modules
+**/data/
+.turbo
+dist
+build
+playwright-report
+test-results
+
+# 构建与部署产物（镜像 / Compose tar / 私有运行配置）
+.hai/
+*.tar
+
+# 本机私有配置；公共 .env 与 dev/test/prod 环境文件纳入版本控制。
+.env.local
+.env.*.local
+
+# 构建器生成的安装输入快照
+**/images/dependencies/
+
+# 项目本地缓存
+**/.pnpm-store/
+**/.cache/

package/templates/apps/api/.npmrc.hbs

@@ -0,0 +1 @@
+# 注册表与认证可配置在此；pnpm 专属设置统一位于 pnpm-workspace.yaml。

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

@@ -0,0 +1,39 @@
+# {{api.contractPackageName}}
+
+## 简介
+
+{{projectName}} API service 的共享 contract 包。
+
+## 核心功能清单
+
+- 共享接口路径、输入输出 Schema 和类型。
+- 客户端与服务端使用同一份 contract。
+- 不包含服务端业务实现，也不加载私有配置。
+
+## 使用入门
+
+### 包含内容
+
+- `app-contract.ts`：应用级接口定义，业务 path 与一次性输出 Schema 就近内联
+- `app-schemas.ts`：跨接口、跨层复用的输入/数据 Zod Schema
+- `{{projectName}}-contract.ts`：工程级 contract 聚合入口
+
+API 前缀、健康检查与跨端 Header 等传输配置位于 service 的 `config/_serv.yml`。
+
+### 常用命令
+
+```bash
+pnpm --filter {{api.contractPackageName}} build
+pnpm --filter {{api.contractPackageName}} test
+```
+
+## 开发测试
+
+```sh
+pnpm --filter {{api.contractPackageName}} typecheck
+pnpm --filter {{api.contractPackageName}} test
+```
+
+## 许可证
+
+Apache-2.0

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

@@ -0,0 +1,41 @@
+{
+  "engines": { "node": "^22.23.4 || ^24.22.1 || ^26.12.1" },
+  "name": "{{api.contractPackageName}}",
+  "type": "module",
+  "version": "0.1.0",
+  "private": true,
+  "license": "MIT",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "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}}",
+    "zod": "{{api.packageSpecifiers.zod}}"
+  },
+  "devDependencies": {
+    "@types/node": "{{api.packageSpecifiers.nodeTypes}}",
+    "rimraf": "{{api.packageSpecifiers.rimraf}}",
+    "tsup": "{{api.packageSpecifiers.tsup}}",
+    "typescript": "{{api.packageSpecifiers.typescript}}",
+    "vitest": "{{api.packageSpecifiers.vitest}}"
+  }
+}

package/templates/apps/api/apps/{{projectName}}-contract/src/app-contract.ts.hbs

@@ -0,0 +1,27 @@
+import { apiContract } from '@h-ai/api-contract'
+import { AppEchoInputSchema, AppEchoOutputDataSchema, AppInfoOutputDataSchema } from './app-schemas.js'
+
+/** 应用自有 app contract。 */
+export const appContract = {
+  info: apiContract
+    .route({
+      method: 'POST',
+      path: '/app/info',
+      operationId: 'app.info',
+      summary: 'Get service info',
+      tags: ['app'],
+    })
+    .output(apiContract.haiResultSchema(AppInfoOutputDataSchema)),
+  echo: apiContract
+    .route({
+      method: 'POST',
+      path: '/app/echo',
+      operationId: 'app.echo',
+      summary: '{{#if features.iam}}Echo a message (auth required){{else}}Echo a message{{/if}}',
+      tags: ['app'],
+    })
+    .input(AppEchoInputSchema)
+    .output(apiContract.haiResultSchema(AppEchoOutputDataSchema)),
+}
+
+export type AppContract = typeof appContract

package/templates/apps/api/apps/{{projectName}}-contract/src/app-schemas.ts.hbs

@@ -0,0 +1,28 @@
+import { z } from 'zod'
+
+/** 服务元信息响应数据。 */
+export const AppInfoOutputDataSchema = z.object({
+  name: z.string(),
+  version: z.string(),
+  env: z.enum(['development', 'production', 'test', 'staging']),
+  defaultLocale: z.string(),
+  uptimeMs: z.number().int().nonnegative(),
+  transportEnabled: z.boolean(),
+})
+
+/** 输入：单条文本消息（演示用，限制最大长度防止误用）。 */
+export const AppEchoInputSchema = z.object({
+  message: z.string().min(1).max(2000),
+})
+
+/** 输出：原样回显 + 调用者快照。 */
+export const AppEchoOutputDataSchema = z.object({
+  message: z.string(),
+  requestId: z.string(),
+  timestamp: z.string(),
+  userId: z.string().optional(),
+})
+
+export type AppInfoOutputData = z.infer<typeof AppInfoOutputDataSchema>
+export type AppEchoInput = z.infer<typeof AppEchoInputSchema>
+export type AppEchoOutputData = z.infer<typeof AppEchoOutputDataSchema>

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

@@ -0,0 +1,5 @@
+export * from './app-contract.js'
+export * from './app-schemas.js'
+export * from './{{projectName}}-contract.js'
+
+// @hai-generator:contracts:exports

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

@@ -0,0 +1,16 @@
+import { apiContract } from '@h-ai/api-contract'
+import { appContract } from './app-contract.js'
+
+// @hai-generator:contracts:imports
+
+/** 工程级应用 contract。 */
+export const {{api.contractExportName}} = apiContract.create({
+{{#if features.iam}}  iam: apiContract.iam,
+{{/if}}{{#if features.storage}}  storage: apiContract.storage,
+{{/if}}{{#if features.ai}}  ai: apiContract.ai,
+{{/if}}{{#if features.feedback}}  feedback: apiContract.feedback,
+{{/if}}  // @hai-generator:contracts:entries
+  app: appContract,
+})
+
+export type ApiWorkspaceContract = typeof {{api.contractExportName}}

package/templates/apps/api/apps/{{projectName}}-contract/tests/contract.test.ts.hbs

@@ -0,0 +1,18 @@
+import { describe, expect, it } from 'vitest'
+import { AppEchoInputSchema, {{api.contractExportName}} } from '../src/index.js'
+
+describe('{{api.contractPackageName}}', () => {
+  it('includes generated contract routes', () => {
+    expect({{api.contractExportName}}.app.info).toBeDefined()
+    expect({{api.contractExportName}}.app.echo).toBeDefined()
+{{#if features.iam}}    expect({{api.contractExportName}}.iam.auth.login).toBeDefined()
+{{/if}}{{#if features.storage}}    expect({{api.contractExportName}}.storage.presignedUrls.createUpload).toBeDefined()
+{{/if}}{{#if features.ai}}    expect({{api.contractExportName}}.ai.chats.createCompletion).toBeDefined()
+{{/if}}  })
+
+  it('validates app.echo input length', () => {
+    expect(AppEchoInputSchema.safeParse({ message: 'hello' }).success).toBe(true)
+    expect(AppEchoInputSchema.safeParse({ message: '' }).success).toBe(false)
+    expect(AppEchoInputSchema.safeParse({ message: 'x'.repeat(2001) }).success).toBe(false)
+  })
+})

package/templates/apps/api/apps/{{projectName}}-contract/tsconfig.json.hbs

@@ -0,0 +1,12 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {},
+  "include": [
+    "src/**/*"
+  ],
+  "exclude": [
+    "node_modules",
+    "dist",
+    "tests"
+  ]
+}

package/templates/apps/api/apps/{{projectName}}-contract/tsup.config.ts.hbs

@@ -0,0 +1,11 @@
+import { defineConfig } from 'tsup'
+
+export default defineConfig({
+  entry: { index: 'src/index.ts' },
+  format: ['esm'],
+  target: 'node22',
+  sourcemap: true,
+  clean: true,
+  dts: { compilerOptions: { ignoreDeprecations: '6.0' } },
+  external: ['@h-ai/api-contract', 'zod'],
+})

package/templates/apps/api/apps/{{projectName}}-contract/vitest.config.ts.hbs

@@ -0,0 +1,9 @@
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    include: ['tests/**/*.test.ts'],
+  },
+})

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

@@ -0,0 +1,60 @@
+# {{api.servPackageName}}
+
+## 简介
+
+{{projectName}} API service 包，负责模块初始化、procedure 装配与 HTTP 入口。
+
+## 核心功能清单
+
+- 初始化所选框架模块，装配共享接口并提供 HTTP 服务。
+- 配置、健康检查和应用 procedures 各有明确入口。
+- 从工程根构建镜像，支持自动发布与离线包。
+
+## 使用入门
+
+### 常用命令
+
+```bash
+pnpm --filter {{api.servPackageName}} dev
+pnpm --filter {{api.servPackageName}} test
+```
+
+### 容器运行
+
+
+- 配置默认打包自本目录 `config/`，可在运行时只读挂载到 `/app/config`，敏感值通过环境变量注入。
+
+
+### 关键目录
+
+{{#if features.crypto}}启用 transport 时，`serverKeyRing` 与客户端 `keyStore` 都必须显式提供。CLI 在本服务 `.env.dev/.env.test/.env.prod` 中分别生成独立 ring，提交环境文件后克隆用户可共享，变量为 `HAI_CRYPTO_TRANSPORT_SERVERKEYRING`；运行时不生成密钥。部署直接复用所选环境文件的 ring，或由 Secret Manager 向所有节点分发相同受管 ring，配合共享数据库 registry。公钥/版本参与协商，私钥不进入普通 YAML、PUBLIC_/VITE_、日志或公开响应。轮换先分发新旧版本再切 activeKeyId，过渡期后撤销旧 ID；无需会话粘性。
+{{#unless features.db}}本模板未选择 db，registry 仅在 development/test 显式使用内存；production/staging 会拒绝启动 transport。选择 db 并配置共享数据库后再部署，或显式关闭 transport。
+{{/unless}}{{/if}}
+
+- `config/`：service 配置
+- `src/app.ts`：HTTP App 装配
+- `src/lib/server/init.ts`：模块初始化与关闭
+- `src/server/procedures/`：应用级 procedures
+
+{{#if features.iam}}
+### IAM 认证配置
+
+服务端 `config/_iam.yml` 统一控制登录、注册、重置、协议与 `ui` 品牌。邮件/短信可用 `_reach.yml` 中的 Provider/标准模板或自定义发送回调。客户端可通过安全公开配置和框架认证动作接入 `AuthPanel`。Memory 仅用于本地开发和显式测试；生产环境即使只有一个实例，也须使用框架支持的共享数据库与 Redis，并按工程根 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，由安全渲染器在弹窗显示。
+
+完整契约见生成应用的 `.agents/skills/hai-iam/reference.md`。
+{{/if}}
+
+## 开发测试
+
+```sh
+pnpm --filter {{api.servPackageName}} typecheck
+pnpm --filter {{api.servPackageName}} test
+```
+
+## 许可证
+
+Apache-2.0

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

@@ -0,0 +1,17 @@
+# =============================================================================
+# {{projectName}} API Service - 应用配置
+# =============================================================================
+
+name: {{projectName}} API Service
+version: 0.1.0
+env: ${HAI_CORE_ENV:development}
+
+logging:
+  level: info
+  format: pretty
+  redact:
+    - password
+    - token
+    - secret
+
+defaultLocale: {{defaultLocale}}

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

@@ -0,0 +1,54 @@
+# =============================================================================
+# {{projectName}} API Service - Serv / HTTP 入口配置
+# =============================================================================
+
+server:
+  host: 127.0.0.1
+  port: 3000
+
+http:
+  apiPrefix: /api/v1
+  openapi:
+    path: /openapi.json
+  docs:
+    path: /docs
+  health:
+    path: /health
+    readyPath: /ready
+  rpc: false
+
+cors:
+  origin: ${HAI_SERV_CORS_ORIGIN:*}
+  nativeOrigins: ${HAI_SERV_CORS_NATIVEORIGINS:http://localhost,https://tauri.localhost,tauri://localhost,capacitor://localhost}
+{{#if features.iam}}  credentials: ${HAI_SERV_CORS_CREDENTIALS:true}
+{{else}}  credentials: ${HAI_SERV_CORS_CREDENTIALS:false}
+{{/if}}  allowedHeaders:
+    - Authorization
+    - Content-Type
+{{#if features.crypto}}    - X-Client-Id
+    - X-Encrypted
+    - X-Hai-Transport
+{{/if}}    - X-Hai-Locale
+    - X-Request-Id
+    - X-Requested-With
+  exposedHeaders:
+{{#if features.crypto}}    - X-Encrypted
+    - X-Hai-Transport
+{{/if}}    - X-Request-Id
+
+{{#if features.crypto}}transport:
+  # 双向业务明文 UTF-8 字节；默认 {{#if features.feedback}}auto（按反馈预算推导）{{else}}1 MiB{{/if}}，范围 1 KiB～64 MiB，密文容量自动推导。
+{{#if features.feedback}}
+  maxPlaintextBytes: ${HAI_SERV_TRANSPORT_MAXPLAINTEXTBYTES:auto}
+{{else}}
+  maxPlaintextBytes: ${HAI_SERV_TRANSPORT_MAXPLAINTEXTBYTES:1048576}
+{{/if}}
+  keyExchangePath: /_hai/key-exchange
+  excludePaths:
+    - /health
+    - /ready
+    - /openapi.json
+    - /docs
+    - /_hai/scalar.js
+{{else}}transport: false
+{{/if}}

package/templates/apps/api/apps/{{projectName}}-serv/data/.gitkeep.hbs

@@ -0,0 +1 @@
+

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

@@ -0,0 +1,66 @@
+{
+  "engines": { "node": "^22.23.4 || ^24.22.1 || ^26.12.1" },
+  "name": "{{api.servPackageName}}",
+  "type": "module",
+  "version": "0.1.0",
+  "private": true,
+  "license": "MIT",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "config",
+    "data",
+    "README.md"
+  ],
+  "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",
+    "dev": "pnpm build && node --env-file=.env --env-file=.env.dev --env-file-if-exists=.env.local dist/index.js",
+    "start": "node --env-file=.env --env-file=.env.prod --env-file-if-exists=.env.local dist/index.js",
+    "dev:test": "pnpm build && node --env-file=.env --env-file=.env.test --env-file-if-exists=.env.local dist/index.js",
+    "dev:prod": "pnpm build && pnpm start",
+    "start:test": "node --env-file=.env --env-file=.env.test --env-file-if-exists=.env.local dist/index.js",
+    "start:prod": "pnpm start"
+  },
+  "dependencies": {
+    "pino-pretty": "{{api.packageSpecifiers.pinoPretty}}",
+    "@h-ai/core": "{{haiPackageSpecifier}}",
+    "@h-ai/serv": "{{haiPackageSpecifier}}",
+    "{{api.contractPackageName}}": "workspace:*"{{#if features.ai}},
+    "@h-ai/ai": "{{haiPackageSpecifier}}"{{/if}}{{#if features.audit}},
+    "@h-ai/audit": "{{haiPackageSpecifier}}"{{/if}}{{#if features.cache}},
+    "@h-ai/cache": "{{haiPackageSpecifier}}"{{/if}}{{#if features.crypto}},
+    "@h-ai/crypto": "{{haiPackageSpecifier}}"{{/if}}{{#if features.datapipe}},
+    "@h-ai/datapipe": "{{haiPackageSpecifier}}"{{/if}}{{#if features.iam}},
+    "@h-ai/iam": "{{haiPackageSpecifier}}"{{/if}}{{#if features.feedback}},
+    "@h-ai/api-contract": "{{haiPackageSpecifier}}",
+    "@h-ai/feedback": "{{haiPackageSpecifier}}"{{/if}}{{#if features.payment}},
+    "@h-ai/payment": "{{haiPackageSpecifier}}"{{/if}}{{#if features.reach}},
+    "@h-ai/reach": "{{haiPackageSpecifier}}"{{/if}}{{#if features.db}},
+    "@h-ai/reldb": "{{haiPackageSpecifier}}"{{/if}}{{#if features.scheduler}},
+    "@h-ai/scheduler": "{{haiPackageSpecifier}}"{{/if}}{{#if features.storage}},
+    "@h-ai/storage": "{{haiPackageSpecifier}}"{{/if}}{{#if features.vecdb}},
+    "@h-ai/vecdb": "{{haiPackageSpecifier}}"{{/if}}
+  },
+  "devDependencies": {
+    "@h-ai/api-client": "{{haiPackageSpecifier}}",
+    "@types/node": "{{api.packageSpecifiers.nodeTypes}}",
+    "rimraf": "{{api.packageSpecifiers.rimraf}}",
+    "tsup": "{{api.packageSpecifiers.tsup}}",
+    "typescript": "{{api.packageSpecifiers.typescript}}",
+    "vitest": "{{api.packageSpecifiers.vitest}}"
+  }
+}

package/templates/apps/api/apps/{{projectName}}-serv/src/app.ts.hbs

@@ -0,0 +1,119 @@
+import type { CoreConfig } from '@h-ai/core'
+import type { {{#if features.feedback}}CreateServContext, {{/if}}ServConfig{{#if features.crypto}}, ServTransportConfig{{/if}} } from '@h-ai/serv'
+{{#if features.crypto}}import process from 'node:process'
+{{/if}}
+{{#if features.feedback}}import { resolveFeedbackBudget } from '@h-ai/api-contract/feedback'
+{{/if}}import { core } from '@h-ai/core'
+{{#if features.crypto}}import { {{#if features.db}}createReldbTransportKeyStore{{else}}createInMemoryKeyStore{{/if}}, crypto, parseTransportServerKeyRing } from '@h-ai/crypto'
+{{/if}}{{#if features.feedback}}import { FeedbackConfigSchema } from '@h-ai/feedback'
+{{/if}}{{#if features.iam}}import { iam } from '@h-ai/iam'
+{{/if}}{{#if features.crypto}}{{#if features.db}}import { reldb } from '@h-ai/reldb'
+{{/if}}{{/if}}import { serv } from '@h-ai/serv'
+import { {{api.contractExportName}} } from '{{api.contractPackageName}}'
+import { {{api.serviceProceduresFactoryName}} } from './server/procedures/index.js'
+
+const startedAt = Date.now()
+
+interface CreateApiServiceAppOptions {
+  transport?: 'config' | 'disabled'
+  refreshCookie?: 'enabled' | 'disabled'
+}
+
+/** 创建 API Service HTTP 应用。 */
+export function {{api.serviceAppFactoryName}}(_options: CreateApiServiceAppOptions = {}) {
+  const servConfig = core.config.getOrThrow<ServConfig>('serv')
+  const coreConfig = core.config.getOrThrow<CoreConfig>('core')
+  const security = serv.createRuntimeSecurityPolicy({
+    environment: coreConfig.env,
+    corsOrigin: servConfig.cors.origin,
+    nativeOrigins: servConfig.cors.nativeOrigins,
+  })
+{{#if features.crypto}}  const transportMode = _options.transport ?? 'config'
+  let transport: ServTransportConfig | undefined
+  if (transportMode !== 'disabled' && servConfig.transport !== false) {
+{{#unless features.db}}    if (coreConfig.env !== 'development' && coreConfig.env !== 'test')
+      throw new Error('Production transport requires a shared registry; enable the db feature and configure a shared database')
+{{/unless}}
+    const ring = parseTransportServerKeyRing(process.env.HAI_CRYPTO_TRANSPORT_SERVERKEYRING)
+    if (!ring.success)
+      throw new Error(`HAI_CRYPTO_TRANSPORT_SERVERKEYRING: ${ring.error.message} (${ring.error.code})`)
+{{#if features.feedback}}    // 可选反馈故障重试期间仍使用配置预算，避免缓存默认容量。
+    const feedbackSettings = FeedbackConfigSchema.safeParse(core.config.get('feedback'))
+    const feedbackBudget = resolveFeedbackBudget(feedbackSettings.success ? feedbackSettings.data : {})
+{{/if}}    transport = {
+      crypto,
+      serverKeyRing: ring.data,
+{{#if features.db}}      keyStore: createReldbTransportKeyStore({ reldb, ttlSeconds: 3600 }),
+{{else}}      keyStore: createInMemoryKeyStore(), // 无 db 的模板仅在 development/test 使用内存 registry。
+{{/if}}
+      keyExchangePath: servConfig.transport.keyExchangePath,
+      maxPlaintextBytes: servConfig.transport.maxPlaintextBytes,
+{{#if features.feedback}}      routePlaintextBytes: {
+        [`${servConfig.http.apiPrefix}/feedback/reports`]: feedbackBudget.maxTransportBytes,
+        [`${servConfig.http.apiPrefix}/feedback/reports/*/evidence`]: feedbackBudget.maxTransportBytes,
+        [`${servConfig.http.apiPrefix}/feedback/reports/*/attachments/*`]: feedbackBudget.maxTransportBytes,
+        [`${servConfig.http.apiPrefix}/feedback/reports/*/exports/*`]: feedbackBudget.maxTransportBytes,
+        ...servConfig.transport.routePlaintextBytes,
+      },
+{{else}}      routePlaintextBytes: servConfig.transport.routePlaintextBytes,
+{{/if}}
+      excludePaths: [...servConfig.transport.excludePaths],
+    }
+  }
+{{else}}  const transport = undefined
+{{/if}}
+{{#if features.iam}}
+  const refreshCookie = _options.refreshCookie === 'disabled' ? undefined : { secure: security.secureRefreshCookie }
+{{/if}}
+{{#if features.feedback}}
+  // 普通业务日志与反馈使用同一可信应用范围；身份仍由 IAM 验证。
+  const authenticatedContext = serv.buildAuthContextFactory(token => iam.auth.verifyToken(token))
+  const createContext: CreateServContext = async input => ({
+    ...await authenticatedContext(input),
+    scopeId: '{{projectName}}',
+  })
+{{/if}}
+
+  const appOptions: Parameters<typeof serv.createApp>[0] = {
+    contract: {{api.contractExportName}},
+    procedures: {{api.serviceProceduresFactoryName}}({
+      app: {
+        info: {
+          name: coreConfig.name,
+          version: coreConfig.version,
+          env: coreConfig.env,
+          defaultLocale: coreConfig.defaultLocale,
+          transportEnabled: transport !== undefined,
+        },
+        startedAt,
+      },
+    }),
+    http: {
+      ...servConfig.http,
+      openapi: security.exposeApiDocs ? servConfig.http.openapi : false,
+      docs: security.exposeApiDocs ? servConfig.http.docs : false,
+    },
+{{#if features.iam}}
+    iam,
+    refreshCookie,
+{{/if}}
+{{#if features.feedback}}
+    createContext,
+{{/if}}
+{{#if features.crypto}}
+    transport,
+{{/if}}
+    middlewares: [
+      {
+        middleware: serv.cors({
+          origin: security.allowOrigin,
+          credentials: servConfig.cors.credentials,
+          allowedHeaders: [...servConfig.cors.allowedHeaders],
+          exposedHeaders: [...servConfig.cors.exposedHeaders],
+        }),
+      },
+    ],
+  }
+
+  return serv.createApp(appOptions)
+}

package/templates/apps/api/apps/{{projectName}}-serv/src/build-metadata.ts.hbs

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