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

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

@@ -0,0 +1,41 @@
+import type { CoreConfig } from '@h-ai/core'
+import type { ServConfig } from '@h-ai/serv'
+import process from 'node:process'
+import { core } from '@h-ai/core'
+import { serv } from '@h-ai/serv'
+import { {{api.serviceAppFactoryName}} } from './app.js'
+import { closeApp, initApp } from './lib/server/init.js'
+
+async function main(): Promise<void> {
+  await initApp()
+  const config = core.config.getOrThrow<CoreConfig>('core')
+  const logger = core.logger.child({ app: config.name, scope: 'entrypoint' })
+
+  // host/port 来自 config/_serv.yml 的 server（HOST/PORT 环境变量高于配置文件）。
+  const { server } = core.config.getOrThrow<ServConfig>('serv')
+  await new Promise<void>((resolve, reject) => {
+    const listener = serv.listen({{api.serviceAppFactoryName}}(), {
+      host: server.host,
+      port: server.port,
+      onListening: (info) => {
+        logger.info('API service listening', { address: info.address, port: info.port })
+        resolve()
+      },
+      onClose: closeApp,
+    })
+    listener.server.once('error', reject)
+    listener.server.once('listening', () => listener.server.off('error', reject))
+  })
+}
+
+main().catch(async (error: unknown) => {
+  core.logger.error('API service failed to start', { error })
+  process.exitCode = 1
+  try {
+    // 包括初始化后的 app/transport 创建失败，均须释放已建立的连接。
+    await closeApp()
+  }
+  catch (cleanupError) {
+    core.logger.error('API service startup cleanup failed', { error: cleanupError })
+  }
+})

package/templates/apps/api/apps/{{projectName}}-serv/src/lib/server/init.ts.hbs

@@ -0,0 +1,165 @@
+/** 应用声明真实模块顺序；并发、失败回滚与关闭重试由 core 处理。 */
+{{#if features.ai}}
+import { ai, AIConfigSchema } from '@h-ai/ai'
+{{/if}}
+{{#if features.audit}}
+import { audit, AuditInitConfigSchema } from '@h-ai/audit'
+{{/if}}
+{{#if features.cache}}
+import { cache, CacheConfigSchema } from '@h-ai/cache'
+{{/if}}
+import { core } from '@h-ai/core'
+{{#if features.crypto}}
+import { crypto } from '@h-ai/crypto'
+{{/if}}
+{{#if features.feedback}}
+import { feedback } from '@h-ai/feedback'
+{{/if}}
+{{#if features.iam}}
+import { iam, IamConfigSchema } from '@h-ai/iam'
+{{/if}}
+{{#if features.reach}}
+import { reach, ReachConfigSchema } from '@h-ai/reach'
+{{/if}}
+{{#if features.db}}
+import { reldb, ReldbConfigSchema } from '@h-ai/reldb'
+{{/if}}
+import { ServConfigSchema } from '@h-ai/serv'
+{{#if features.audit}}
+{{#if features.scheduler}}
+import { scheduler, SchedulerConfigSchema } from '@h-ai/scheduler'
+{{/if}}
+{{/if}}
+{{#if features.storage}}
+import { storage, StorageConfigSchema } from '@h-ai/storage'
+{{/if}}
+{{#if features.vecdb}}
+import { vecdb, VecdbConfigSchema } from '@h-ai/vecdb'
+{{/if}}
+{{#if features.feedback}}
+import { buildMetadata } from '../../build-metadata.js'
+{{/if}}
+
+{{#if features.feedback}}
+let feedbackRetry: ReturnType<typeof setTimeout> | undefined
+let feedbackStarting: Promise<void> | undefined
+let feedbackClosing = false
+let feedbackFailure: string | number | undefined
+
+/** 可选辅助能力独立重试；不能回滚已经就绪的 IAM 与业务模块。 */
+function startFeedback(): Promise<void> {
+  if (feedbackStarting)
+    return feedbackStarting
+  feedbackClosing = false
+  feedbackStarting = (async () => {
+    try {
+      const result = await feedback.init({ ...core.config.getOrThrow<import('@h-ai/feedback').FeedbackConfigInput>('feedback'), ...buildMetadata })
+      if (!result.success) {
+        if (feedbackFailure !== result.error.code)
+          core.logger.warn('Optional feedback unavailable; business runtime remains ready', { module: 'feedback', code: result.error.code })
+        feedbackFailure = result.error.code
+      }
+      else {
+        feedbackFailure = undefined
+      }
+    }
+    catch {
+      if (feedbackFailure !== 'configuration')
+        core.logger.warn('Optional feedback configuration unavailable; business runtime remains ready', { module: 'feedback' })
+      feedbackFailure = 'configuration'
+    }
+    if (feedbackFailure && !feedbackClosing) {
+      feedbackRetry = setTimeout(() => {
+        feedbackRetry = undefined
+        void startFeedback()
+      }, 30000)
+      feedbackRetry.unref()
+    }
+  })().finally(() => { feedbackStarting = undefined })
+  return feedbackStarting
+}
+
+async function closeFeedback() {
+  feedbackClosing = true
+  if (feedbackRetry)
+    clearTimeout(feedbackRetry)
+  feedbackRetry = undefined
+  await feedbackStarting
+  return feedback.close()
+}
+
+{{/if}}
+
+const runtime = core.module.createRuntime([
+  { name: 'configuration', start: () => { core.init({ configDir: './config' }) }, close: () => {} },
+  { name: 'serv-config', start: () => core.config.validate('serv', ServConfigSchema), close: () => {} },
+{{#if features.db}}
+  { name: 'reldb', start: async () => {
+    const config = ReldbConfigSchema.parse(core.config.getOrThrow('db'))
+    if (config.type === 'sqlite' && config.database !== ':memory:') {
+      const { mkdir } = await import('node:fs/promises')
+      const { dirname } = await import('node:path')
+      await mkdir(dirname(config.database), { recursive: true })
+    }
+    return reldb.init(config)
+  }, close: () => reldb.close() },
+{{/if}}
+{{#if features.cache}}
+  { name: 'cache', start: () => cache.init(CacheConfigSchema.parse(core.config.getOrThrow('cache'))), close: () => cache.close() },
+{{/if}}
+{{#if features.vecdb}}
+  { name: 'vecdb', start: () => vecdb.init(VecdbConfigSchema.parse(core.config.getOrThrow('vecdb'))), close: () => vecdb.close() },
+{{/if}}
+{{#if features.crypto}}
+  { name: 'crypto', start: () => crypto.init(), close: () => crypto.close() },
+{{/if}}
+{{#if features.storage}}
+  { name: 'storage', start: () => storage.init(StorageConfigSchema.parse(core.config.getOrThrow('storage'))), close: () => storage.close() },
+{{/if}}
+{{#if features.reach}}
+  { name: 'reach', enabled: () => Boolean(core.config.get('reach')), start: () => reach.init(ReachConfigSchema.parse(core.config.getOrThrow('reach'))), close: () => reach.close() },
+{{/if}}
+{{#if features.audit}}
+  { name: 'audit', start: () => audit.init({ ...AuditInitConfigSchema.parse(core.config.get('audit') ?? {}){{#if features.storage}}, storage{{/if}}{{#if features.reach}}, reach{{/if}} }), close: () => audit.close() },
+{{/if}}
+{{#if features.iam}}
+  { name: 'iam', start: () => iam.init({ ...IamConfigSchema.parse(core.config.getOrThrow('iam')){{#if features.reach}}, reach{{/if}} }), close: () => iam.close() },
+{{/if}}
+{{#if features.audit}}
+{{#if features.scheduler}}
+  { name: 'audit-jobs', enabled: () => Boolean(audit.schedulerPlan), start: async () => {
+    const schedule = audit.schedulerPlan
+    if (!schedule)
+      return
+    const initialized = await scheduler.init({ ...SchedulerConfigSchema.parse(core.config.get('scheduler') ?? {}), ...schedule })
+    if (!initialized.success)
+      return initialized
+    const started = scheduler.start()
+    if (!started.success)
+      await scheduler.close()
+    return started
+  }, close: () => scheduler.close() },
+{{/if}}
+{{/if}}
+{{#if features.feedback}}
+  { name: 'feedback', enabled: () => Boolean(core.config.get('feedback')), start: startFeedback, close: closeFeedback },
+{{/if}}
+{{#if features.ai}}
+  { name: 'ai', start: () => ai.init(AIConfigSchema.parse(core.config.getOrThrow('ai'))), close: () => ai.close() },
+{{/if}}
+  { name: 'bootstrap', start: () => { core.logger.info('API service initialized') }, close: () => {} },
+])
+
+/** 启动失败只报告模块、错误码和配置路径，私密值不进入错误上下文。 */
+export async function initApp(): Promise<void> {
+  const result = await runtime.start()
+  if (!result.success)
+    throw new Error(result.error.message, { cause: result.error })
+}
+
+/** 清理失败时保留依赖和清理义务，可再次调用。 */
+export async function closeApp(): Promise<void> {
+  const result = await runtime.close()
+  if (!result.success)
+    throw new Error(result.error.message, { cause: result.error })
+}

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

@@ -0,0 +1,57 @@
+import type { ServContext } from '@h-ai/serv'
+import type { AppEchoOutputData, AppInfoOutputData } from '{{api.contractPackageName}}'
+import { ok } from '@h-ai/core'
+import { serv } from '@h-ai/serv'
+import { appContract } from '{{api.contractPackageName}}'
+
+export interface AppProcedureDeps {
+  readonly info: {
+    readonly name: string
+    readonly version: string
+    readonly env: AppInfoOutputData['env']
+    readonly defaultLocale: string
+    readonly transportEnabled: boolean
+  }
+  readonly startedAt: number
+}
+
+/** 创建应用自有 procedures。 */
+export function createAppProcedures(deps: AppProcedureDeps) {
+  return serv
+    .implement(appContract)
+    .context<ServContext>()
+    .route('info', () => {
+      const data: AppInfoOutputData = {
+        name: deps.info.name,
+        version: deps.info.version,
+        env: deps.info.env,
+        defaultLocale: deps.info.defaultLocale,
+        transportEnabled: deps.info.transportEnabled,
+        uptimeMs: Math.max(0, Date.now() - deps.startedAt),
+      }
+      return ok(data)
+    })
+{{#if features.iam}}
+    .route('echo')
+    .auth()
+    .handle(({ input, context }) => {
+      const data: AppEchoOutputData = {
+        message: input.message,
+        userId: context.session.userId,
+        requestId: context.requestId,
+        timestamp: new Date().toISOString(),
+      }
+      return ok(data)
+    })
+{{else}}
+    .route('echo', ({ input, context }) => {
+      const data: AppEchoOutputData = {
+        message: input.message,
+        requestId: context.requestId,
+        timestamp: new Date().toISOString(),
+      }
+      return ok(data)
+    })
+{{/if}}
+    .build()
+}

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

@@ -0,0 +1,41 @@
+import type { AppProcedureDeps } from './app-procedures.js'
+{{#if features.ai}}import { ai } from '@h-ai/ai'
+{{/if}}{{#if features.feedback}}import { feedback } from '@h-ai/feedback'
+{{/if}}{{#if features.iam}}import { iam } from '@h-ai/iam'
+{{/if}}{{#if features.ai}}import { createAiProcedures } from '@h-ai/serv/features/ai'
+{{/if}}{{#if features.feedback}}import { createFeedbackProcedures } from '@h-ai/serv/features/feedback'
+{{/if}}{{#if features.iam}}import { createIamProcedures } from '@h-ai/serv/features/iam'
+{{/if}}{{#if features.storage}}import { createStorageProcedures } from '@h-ai/serv/features/storage'
+import { storage } from '@h-ai/storage'
+{{/if}}import { createAppProcedures } from './app-procedures.js'
+
+// @hai-generator:procedures:imports
+
+/** 创建应用级 procedures 聚合。 */
+export function {{api.serviceProceduresFactoryName}}(deps: { app: AppProcedureDeps }) {
+  return {
+    // @hai-generator:procedures:entries
+{{#if features.iam}}    iam: createIamProcedures({ iam }),
+{{/if}}{{#if features.storage}}    storage: createStorageProcedures({
+      storage,
+      authorize: ({ context, keys }) => keys.every(key =>
+        key.startsWith(`users/${encodeURIComponent(context.session.userId)}/`)),
+    }),
+{{/if}}{{#if features.ai}}    // AI 默认绑定可信 session.userId，跨主体访问需另行提供 authorizeObject 策略。
+    ai: createAiProcedures({ ai }),
+{{/if}}{{#if features.feedback}}
+    feedback: createFeedbackProcedures({
+      feedback,
+      resolveContext: ({ session }) => ({
+        scopeId: '{{projectName}}',
+        userId: session.userId,
+        // 示例角色映射；实际产品应从可信租户与资源权限确定范围。
+        permissions: session.roles.includes('admin')
+          ? ['feedback:create', 'feedback:read', 'feedback:process', 'feedback:reopen', 'feedback:export']
+          : ['feedback:create'],
+      }),
+    }),
+{{/if}}
+    app: createAppProcedures(deps.app),
+  }
+}

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

@@ -0,0 +1,176 @@
+import type { CoreConfig } from '@h-ai/core'
+import type { ServConfig } from '@h-ai/serv'
+import type { AddressInfo } from 'node:net'
+import { mkdtempSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+{{#if features.ai}}import { ai } from '@h-ai/ai'
+{{/if}}import { apiClient } from '@h-ai/api-client'
+{{#if features.cache}}import { cache } from '@h-ai/cache'
+{{/if}}import { core } from '@h-ai/core'
+{{#if features.iam}}import { iam } from '@h-ai/iam'
+{{/if}}{{#if features.db}}import { reldb } from '@h-ai/reldb'
+{{/if}}import { serv } from '@h-ai/serv'
+{{#if features.storage}}import { storage } from '@h-ai/storage'
+{{/if}}{{#if features.vecdb}}import { vecdb } from '@h-ai/vecdb'
+{{/if}}import { {{api.contractExportName}} } from '{{api.contractPackageName}}'
+import { afterAll, beforeAll, describe, expect, it } from 'vitest'
+
+import { {{api.serviceAppFactoryName}} } from '../src/app.js'
+
+let tempRoot = ''
+let baseUrl = ''
+let client: ReturnType<typeof apiClient.create<typeof {{api.contractExportName}}>>
+let server: ReturnType<typeof serv.listen>
+let servConfig: ServConfig
+{{#if features.storage}}let storageRoot = ''
+{{/if}}{{#if features.vecdb}}let vecdbRoot = ''
+{{/if}}
+
+{{#if features.iam}}
+function uniqueUser(prefix = 'api') {
+  const suffix = `${Date.now().toString(36)}${Math.random().toString(36).slice(2, 6)}`.slice(-8)
+  return {
+    username: `${prefix}_${suffix}`,
+    password: 'TestPass123',
+    email: `${prefix}_${suffix}@test.local`,
+  }
+}
+{{/if}}
+
+beforeAll(async () => {
+  tempRoot = mkdtempSync(join(tmpdir(), '{{projectName}}-service-test-'))
+{{#if features.storage}}  storageRoot = join(tempRoot, 'storage')
+{{/if}}{{#if features.vecdb}}  vecdbRoot = join(tempRoot, 'vecdb')
+{{/if}}
+
+  core.init({
+    configDir: './config',
+    logging: { level: 'warn' },
+  })
+  servConfig = core.config.getOrThrow<ServConfig>('serv')
+{{#if features.db}}
+
+  const dbResult = await reldb.init({ type: 'sqlite', database: ':memory:' })
+  if (!dbResult.success)
+    throw new Error(`reldb: ${dbResult.error.message}`)
+{{/if}}{{#if features.cache}}
+
+  const cacheResult = await cache.init({ type: 'memory' })
+  if (!cacheResult.success)
+    throw new Error(`cache: ${cacheResult.error.message}`)
+{{/if}}{{#if features.vecdb}}
+
+  const vecdbResult = await vecdb.init({ type: 'lancedb', path: vecdbRoot })
+  if (!vecdbResult.success)
+    throw new Error(`vecdb: ${vecdbResult.error.message}`)
+{{/if}}{{#if features.iam}}
+
+  const iamResult = await iam.init({})
+  if (!iamResult.success)
+    throw new Error(`iam: ${iamResult.error.message}`)
+{{/if}}{{#if features.storage}}
+
+  const storageResult = await storage.init({ type: 'local', root: storageRoot })
+  if (!storageResult.success)
+    throw new Error(`storage: ${storageResult.error.message}`)
+{{/if}}{{#if features.ai}}
+
+  const aiResult = await ai.init({})
+  if (!aiResult.success)
+    throw new Error(`ai: ${aiResult.error.message}`)
+{{/if}}
+
+  const app = {{api.serviceAppFactoryName}}({
+    transport: 'disabled',{{#if features.iam}}
+    refreshCookie: 'disabled',{{/if}}
+  })
+  const listening = new Promise<AddressInfo>((resolve) => {
+    server = serv.listen(app, {
+      host: '127.0.0.1',
+      port: 0,
+      onListening: info => resolve(info as AddressInfo),
+    })
+  })
+  const address = await listening
+  baseUrl = `http://127.0.0.1:${address.port}`
+
+  client = apiClient.create({{api.contractExportName}})
+  const initResult = await client.init({
+    baseUrl: `${baseUrl}${servConfig.http.apiPrefix}`,
+    auth: { storage: apiClient.tokenStorage.memory() },
+  })
+  if (!initResult.success)
+    throw new Error(`client.init: ${initResult.error.message}`)
+}, 30_000)
+
+afterAll(async () => {
+  await client?.close()
+  await server?.close()
+{{#if features.ai}}  await ai.close()
+{{/if}}{{#if features.storage}}  await storage.close()
+{{/if}}{{#if features.iam}}  await iam.close()
+{{/if}}{{#if features.vecdb}}  await vecdb.close()
+{{/if}}{{#if features.cache}}  await cache.close()
+{{/if}}{{#if features.db}}  await reldb.close()
+{{/if}}  rmSync(tempRoot, { recursive: true, force: true })
+})
+
+describe('{{api.servPackageName}}', () => {
+  it('returns health status', async () => {
+    if (servConfig.http.health === false)
+      throw new Error('service test requires health endpoint')
+    const response = await fetch(`${baseUrl}${servConfig.http.health.path}`)
+
+    expect(response.status).toBe(200)
+    await expect(response.json()).resolves.toEqual({ status: 'ok' })
+  })
+
+  it('returns app info as HaiResult', async () => {
+    const result = await client.app.info()
+
+    expect(result.success).toBe(true)
+    if (result.success) {
+      const config = core.config.getOrThrow<CoreConfig>('core')
+      expect(result.data).toMatchObject({ name: config.name, version: config.version, env: config.env, defaultLocale: config.defaultLocale })
+      expect(typeof result.data.transportEnabled).toBe('boolean')
+    }
+  })
+
+  it('validates echo input', async () => {
+    const result = await client.app.echo({ message: '' })
+
+    expect(result.success).toBe(false)
+  })
+
+{{#if features.iam}}
+  it('registers a user and returns authenticated echo context', async () => {
+    const user = uniqueUser('svc')
+    const authActions = apiClient.createAuthActions(client)
+    const register = await authActions.register({
+      username: user.username,
+      password: user.password,
+      email: user.email,
+    })
+
+    expect(register.success).toBe(true)
+
+    const result = await client.app.echo({ message: 'hello unit' })
+    expect(result.success).toBe(true)
+    if (result.success) {
+      expect(result.data.message).toBe('hello unit')
+      expect(result.data.userId).toBeTruthy()
+    }
+  })
+{{else}}
+  it('returns echo result as HaiResult', async () => {
+    const result = await client.app.echo({ message: 'hello unit' })
+
+    expect(result.success).toBe(true)
+    if (result.success) {
+      expect(result.data.message).toBe('hello unit')
+      expect(result.data.userId).toBeUndefined()
+    }
+  })
+{{/if}}
+})

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

@@ -0,0 +1,16 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "moduleResolution": "bundler",
+    "types": ["node"],
+    "verbatimModuleSyntax": true,
+    "skipLibCheck": true
+  },
+  "include": [
+    "src/**/*.ts"
+  ],
+  "exclude": [
+    "node_modules",
+    "dist"
+  ]
+}

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

@@ -0,0 +1,20 @@
+import { writeFile } from 'node:fs/promises'
+import { fileURLToPath } from 'node:url'
+import { defineConfig } from 'tsup'
+import { resolveBuildMetadata } from '../../scripts/build-metadata.js'
+
+const buildMetadata = resolveBuildMetadata(fileURLToPath(new URL('.', import.meta.url)))
+
+export default defineConfig({
+  define: { __HAI_BUILD_METADATA__: JSON.stringify(buildMetadata) },
+  async onSuccess() {
+    await writeFile(new URL('./dist/build-metadata.json', import.meta.url), JSON.stringify(buildMetadata))
+  },
+  entry: ['src/index.ts'],
+  format: ['esm'],
+  target: 'node22',
+  sourcemap: true,
+  clean: true,
+  dts: false,
+  external: ['@lancedb/lancedb'],
+})

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

@@ -0,0 +1,12 @@
+import { fileURLToPath } from 'node:url'
+import { defineConfig } from 'vitest/config'
+import { resolveBuildMetadata } from '../../scripts/build-metadata.js'
+
+export default defineConfig({
+  define: { __HAI_BUILD_METADATA__: JSON.stringify(resolveBuildMetadata(fileURLToPath(new URL('.', import.meta.url)))) },
+  test: {
+    globals: true,
+    environment: 'node',
+    include: ['tests/**/*.test.ts'],
+  },
+})

package/templates/apps/api/e2e/api-serv.spec.ts.hbs

@@ -0,0 +1,113 @@
+import process from 'node:process'
+import { apiClient } from '@h-ai/api-client'
+{{#if features.crypto}}
+import { crypto } from '@h-ai/crypto'
+{{/if}}
+import { expect, test } from '@playwright/test'
+import { {{api.contractExportName}} } from '{{api.contractPackageName}}'
+
+const API_PREFIX = '/api/v1'
+const client = apiClient.create({{api.contractExportName}})
+
+test.beforeAll(async () => {
+{{#if features.crypto}}
+  expect((await crypto.init()).success).toBe(true)
+{{/if}}
+  const result = await client.init({
+    baseUrl: `${process.env.BASE_URL || 'http://127.0.0.1:3000'}${API_PREFIX}`,
+{{#if features.iam}}
+    auth: { storage: apiClient.tokenStorage.memory() },
+{{/if}}
+{{#if features.crypto}}
+    transport: { crypto },
+{{/if}}
+  })
+  expect(result.success).toBe(true)
+})
+
+test.afterAll(async () => {
+  await client.close()
+{{#if features.crypto}}
+  await crypto.close()
+{{/if}}
+})
+
+test('service health endpoint returns ok', async ({ request }) => {
+  const response = await request.get('/health')
+
+  expect(response.status()).toBe(200)
+  await expect(response.json()).resolves.toEqual({ status: 'ok' })
+})
+
+test('service app.info endpoint returns HaiResult', async () => {
+  const body = await client.app.info()
+  expect(body.success).toBe(true)
+  if (!body.success)
+    return
+  expect(body.data.name).toBe(process.env.HAI_CORE_NAME ?? '{{projectName}} API Service')
+  expect(body.data.version).toBe(process.env.HAI_CORE_VERSION ?? '0.1.0')
+  expect(body.data.env).toBe('test')
+  expect(typeof body.data.transportEnabled).toBe('boolean')
+})
+{{#if features.iam}}
+
+/** 通过真实 API 验证 IAM 开关、登录、通知和重置，不需要页面适配。 */
+test('configured IAM supports registration, OTP and reset', async ({ request }) => {
+  test.setTimeout(60_000)
+  const actions = apiClient.createAuthActions(client)
+  const publicConfig = await actions.publicConfig()
+  expect(publicConfig.success).toBe(true)
+  if (!publicConfig.success)
+    return
+  expect(publicConfig.data?.register.enabled).toBe(true)
+  const username = `api${Date.now()}`
+  const email = `${username}@example.com`
+  const password = 'ApiPassword123'
+  expect((await actions.register({ username, email, password })).success).toBe(true)
+  expect((await actions.login({ identifier: username, password })).success).toBe(true)
+  if (!publicConfig.data?.login.email) {
+    // 无 Reach/发送回调时，基础认证仍可用，未就绪的通知入口保持关闭。
+    expect((await actions.sendOtp(email)).success).toBe(false)
+    return
+  }
+  if (!process.env.IAM_NOTIFICATION_URL)
+    return
+  async function received(template: string) {
+    const response = await request.get(`${process.env.IAM_NOTIFICATION_URL}/messages?to=${encodeURIComponent(email)}`)
+    const messages = await response.json() as { template: string, vars: Record<string, string> }[]
+    return messages.findLast(item => item.template === template)?.vars
+  }
+  expect((await actions.sendOtp(email)).success).toBe(true)
+  const otp = await received('otp_email')
+  expect(Boolean(otp?.code)).toBe(true)
+  expect((await actions.login({ identifier: email, method: 'email', code: otp?.code })).success).toBe(true)
+  expect((await actions.requestPasswordReset(email)).success).toBe(true)
+  const reset = await received('password_reset')
+  expect(Boolean(reset?.token)).toBe(true)
+  expect((await actions.confirmPasswordReset(reset?.token ?? '', 'ApiResetPassword456')).success).toBe(true)
+  expect((await actions.login({ identifier: username, password: 'ApiResetPassword456' })).success).toBe(true)
+})
+{{/if}}
+{{#if features.feedback}}
+
+test('feedback intake is idempotent and creator can append evidence without administrator access', async () => {
+  const actions = apiClient.createAuthActions(client)
+  const username = `feedback${Date.now()}`
+  const password = 'Feedback-test-Password123!'
+  expect((await actions.register({ username, password, email: `${username}@example.test` })).success).toBe(true)
+  expect((await actions.login({ identifier: username, password })).success).toBe(true)
+  const submissionId = `submission-${Date.now()}`
+  const created = await client.feedback.reports.submit({ appId: '{{projectName}}', submissionId })
+  expect(created.success).toBe(true)
+  if (!created.success)
+    return
+  const duplicate = await client.feedback.reports.submit({ appId: '{{projectName}}', submissionId })
+  expect(duplicate.success).toBe(true)
+  if (duplicate.success)
+    expect(duplicate.data.id).toBe(created.data.id)
+  const evidence = await client.feedback.reports.appendEvidence({ id: created.data.id, evidence: [{ id: 'event-1', source: 'api-test', sequence: 1, kind: 'business', timestamp: Date.now(), data: { action: 'api-feedback' } }] })
+  expect(evidence.success).toBe(true)
+  expect((await client.feedback.reports.completeCollection({ id: created.data.id, missing: ['browser-not-applicable'] })).success).toBe(true)
+  expect((await client.feedback.reports.list({})).success).toBe(false)
+})
+{{/if}}

package/templates/apps/api/e2e/capture-evidence.ts.hbs

@@ -0,0 +1,23 @@
+import { mkdir } from 'node:fs/promises'
+import path from 'node:path'
+import process from 'node:process'
+import { chromium, expect } from '@playwright/test'
+
+/** 仅在指定证据目录时采集健康端点截图，常规 API 测试通过 HTTP 请求完成。 */
+export default async function captureEvidence() {
+  const evidence = process.env.HAI_AUTH_EVIDENCE_DIR
+  if (!evidence)
+    return
+  const browser = await chromium.launch({ channel: 'chrome' })
+  try {
+    const page = await browser.newPage()
+    const response = await page.goto(new URL('/health', process.env.BASE_URL || 'http://127.0.0.1:3000').href)
+    expect(response?.status()).toBe(200)
+    await expect(page.locator('body')).toContainText('ok')
+    await mkdir(evidence, { recursive: true })
+    await page.screenshot({ path: path.join(evidence, '{{projectName}}-health.png'), fullPage: true })
+  }
+  finally {
+    await browser.close()
+  }
+}