@h-ai/cli 0.1.0-alpha.59 → 0.1.0-alpha.61

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@h-ai/cli",
   "type": "module",
-  "version": "0.1.0-alpha.59",
+  "version": "0.1.0-alpha.61",
   "description": "Hai Framework CLI for project scaffolding and code generation.",
   "license": "Apache-2.0",
   "keywords": [
@@ -30,7 +30,7 @@
     "node": "^22.22.2 || ^24.15.0 || >=26.0.0"
   },
   "dependencies": {
-    "@h-ai/core": "0.1.0-alpha.59",
+    "@h-ai/core": "0.1.0-alpha.61",
     "cac": "^7.0.1",
     "chalk": "^6.0.1",
     "fast-wrap-ansi": "^0.2.2",
@@ -41,11 +41,11 @@
     "yaml": "^2.9.1"
   },
   "devDependencies": {
-    "@h-ai/cache": "0.1.0-alpha.59",
-    "@h-ai/deploy": "0.1.0-alpha.59",
-    "@h-ai/reach": "0.1.0-alpha.59",
-    "@h-ai/reldb": "0.1.0-alpha.59",
-    "@h-ai/storage": "0.1.0-alpha.59",
+    "@h-ai/cache": "0.1.0-alpha.61",
+    "@h-ai/deploy": "0.1.0-alpha.61",
+    "@h-ai/reach": "0.1.0-alpha.61",
+    "@h-ai/reldb": "0.1.0-alpha.61",
+    "@h-ai/storage": "0.1.0-alpha.61",
     "@types/fs-extra": "^11.0.4",
     "@types/node": "^26.6.5",
     "@types/prompts": "^2.4.9",

package/templates/README.md

@@ -104,8 +104,14 @@ templates/
 
 `appType` 支持 `admin` / `website` / `h5` / `api` / `mobile-app` / `fullstack`。
 
+H5 业务页面复用 `@h-ai/ui` 的 `BottomNav` 和移动端壳样式，桌面预览保持居中限宽，认证路由独立显示。
+
 `fullstack.*` 包含包名、前端选择、依赖版本、`contractExportName` 和原生壳 `nativeAppIdSegment`，用于渲染 contract / serv / 多端 UI / Capacitor / Tauri 模板。
 
+`moduleConfigs` 保留创建时指定的模块值。Fullstack 的模块 YAML 用 `{{{moduleConfig 'db' true}}}` 等 helper 复用 `cli-config-templates.ts`；可选模块传 `features.ai` 等开关，未选择时整份注释。创建流程保留已渲染的配置，不再用精简内容覆盖；core、serv、Reach 保留应用专用默认值及完整的可选字段。新增 Schema 字段同步此生成器和相应模板。
+
+所有根 `.gitignore`（base / api / fullstack）保留 `**/data/`，包括 `.gitkeep` 在内的运行数据不跟踪。Fullstack 服务端 config 始终含 core、serv、db、cache、iam、storage、audit、reach、ai、vecdb、payment、scheduler、deploy 共 13 份 YAML；不为无配置入口的 crypto/datapipe 生成 YAML。未启用块的后续接入步骤见 [CLI 配置说明](../README.md#应用配置与显示)。
+
 ### 常用条件写法
 
 ```handlebars
@@ -142,3 +148,11 @@ import { iam } from '@h-ai/iam'
 ### 新增 feature 路由
 
 在 `features/{featureId}/routes-shared/`（API 路由）或 `features/{featureId}/routes-{appType}/`（UI 页面）下创建文件，然后在 `cli-template-engine.ts` 的 `FEATURE_ROUTE_DIRS` / `FEATURE_APP_ROUTE_DIRS` 中注册该目录。
+
+## 配置驱动认证页面
+
+协议支持配置中的 userAgreementMarkdown/privacyPolicyMarkdown 正文及 URL；同主题优先 Markdown，由安全渲染器在弹窗显示。
+
+选用 IAM 的 admin/h5/website 模板提供 AuthPanel 和标准认证路由；mobile-app 与 fullstack Web/App/Desktop 使用 API 客户端共享动作。修改服务端 config/_iam.yml 即可控制登录方式、注册、重置、协议和品牌，无需改表单。配置 Reach 模板和真实发送 Provider 后启用 OTP/重置。分布式部署使用共享数据库与 Redis。
+
+LDAP/Reach 是可选 peer；IAM 不强制启用 Reach。默认 LDAP 客户端由应用选择安装 ldapts。自定义通知回调、协议弹窗、表单 snippet 用法随 hai-iam/hai-ui skills 完整复制到生成项目，不能要求应用读取本仓库私有路径。

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

@@ -1,4 +1,5 @@
 node_modules
+**/data/
 .turbo
 dist
 build

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

@@ -21,3 +21,15 @@ pnpm --filter {{api.servicePackageName}} test
 - `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`。所有节点共享同一 DB 与 Redis；Memory 仅用于单进程。
+
+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。
+
+协议支持配置中的 userAgreementMarkdown/privacyPolicyMarkdown 正文及 URL；同主题优先 Markdown，由安全渲染器在弹窗显示。
+
+完整契约见生成应用的 `.agents/skills/hai-iam/reference.md`。
+{{/if}}

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

@@ -59,6 +59,10 @@ export function {{api.serviceAppFactoryName}}(_options: CreateApiServiceAppOptio
     },
 {{#if features.iam}}
     iam,
+    refreshCookie,
+{{/if}}
+{{#if features.crypto}}
+    transport,
 {{/if}}
     middlewares: [
       {
@@ -71,13 +75,6 @@ export function {{api.serviceAppFactoryName}}(_options: CreateApiServiceAppOptio
       },
     ],
   }
-{{#if features.iam}}
-
-  appOptions.refreshCookie = refreshCookie
-{{/if}}{{#if features.crypto}}
-  if (transport)
-    appOptions.transport = transport
-{{/if}}
 
   return serv.createApp(appOptions)
 }

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

@@ -8,6 +8,7 @@
 {{/if}}import { core } from '@h-ai/core'
 {{#if features.crypto}}import { crypto } from '@h-ai/crypto'
 {{/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.storage}}import { storage, StorageConfigSchema } from '@h-ai/storage'
@@ -122,6 +123,14 @@ async function doInit(): Promise<void> {
   if (!cacheResult.success) {
     throw new Error(`Cache initialization failed: ${cacheResult.error.message}`)
   }
+{{/if}}{{#if features.reach}}
+
+  const reachConfig = core.config.get('reach')
+  if (reachConfig) {
+    const result = await reach.init(ReachConfigSchema.parse(reachConfig))
+    if (!result.success)
+      throw new Error('Reach initialization failed')
+  }
 {{/if}}{{#if features.vecdb}}
 
   const vecdbResult = await vecdb.init(vecdbConfig)
@@ -130,7 +139,7 @@ async function doInit(): Promise<void> {
   }
 {{/if}}{{#if features.iam}}
 
-  const iamResult = await iam.init(iamConfig)
+  const iamResult = await iam.init({ ...iamConfig{{#if features.reach}}, reach{{/if}} })
   if (!iamResult.success) {
     throw new Error(`IAM initialization failed: ${iamResult.error.message}`)
   }
@@ -159,6 +168,7 @@ export async function closeApp(): Promise<void> {
 {{#if features.ai}}    ['ai', () => ai.close()],
 {{/if}}{{#if features.storage}}    ['storage', () => storage.close()],
 {{/if}}{{#if features.iam}}    ['iam', () => iam.close()],
+{{/if}}{{#if features.reach}}    ['reach', () => reach.close()],
 {{/if}}{{#if features.vecdb}}    ['vecdb', () => vecdb.close()],
 {{/if}}{{#if features.cache}}    ['cache', () => cache.close()],
 {{/if}}{{#if features.db}}    ['reldb', () => reldb.close()],

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

@@ -146,7 +146,8 @@ describe('{{api.servicePackageName}}', () => {
 {{#if features.iam}}
   it('registers a user and returns authenticated echo context', async () => {
     const user = uniqueUser('svc')
-    const register = await client.iam.auth.register({
+    const authActions = apiClient.createAuthActions(client)
+    const register = await authActions.register({
       username: user.username,
       password: user.password,
       email: user.email,

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

@@ -1,8 +1,36 @@
-import { apiContract } from '@h-ai/api-contract'
+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: process.env.HAI_SERV_TRANSPORT === 'false' ? undefined : { 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')
@@ -11,14 +39,52 @@ test('service health endpoint returns ok', async ({ request }) => {
   await expect(response.json()).resolves.toEqual({ status: 'ok' })
 })
 
-test('service app.info endpoint returns HaiResult', async ({ request }) => {
-  const response = await request.post(`${API_PREFIX}${apiContract.pathOf({{api.contractExportName}}.app.info)}`)
-  const body = await response.json()
-
-  expect(response.status()).toBe(200)
+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(process.env.HAI_CORE_ENV ?? 'development')
   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}}

package/templates/apps/api/package.json.hbs

@@ -25,6 +25,10 @@
     "{{api.contractPackageName}}": "workspace:*"
   },
   "devDependencies": {
+    "@h-ai/api-client": "{{haiPackageSpecifier}}",
+{{#if features.crypto}}
+    "@h-ai/crypto": "{{haiPackageSpecifier}}",
+{{/if}}
     "@antfu/eslint-config": "{{api.packageSpecifiers.antfuEslintConfig}}",
     "@playwright/test": "{{api.packageSpecifiers.playwright}}",
     "@types/node": "{{api.packageSpecifiers.nodeTypes}}",

package/templates/apps/fullstack/.gitignore.hbs

@@ -1,4 +1,5 @@
 node_modules
+**/data/
 .turbo
 dist
 build

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

@@ -35,4 +35,14 @@ pnpm --filter {{projectName}}-app deploy
 ```
 
 部署前确认 `PUBLIC_API_BASE` 在 `.env` 中指向可访问的后端服务。Android 模拟器访问宿主机通常使用 `http://10.0.2.2:3000`。
+
+## IAM 认证配置
+
+服务端 `config/_iam.yml` 统一控制登录、注册、重置、协议与 `ui` 品牌。邮件/短信可用 `_reach.yml` 中的 Provider/标准模板或自定义发送回调。`AuthPanel` 使用安全公开配置及框架认证动作；无需在页面适配 Token、验证码倒计时和错误提示。所有节点共享同一 DB 与 Redis；Memory 仅用于单进程。
+
+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。
+
+协议支持配置中的 userAgreementMarkdown/privacyPolicyMarkdown 正文及 URL；同主题优先 Markdown，由安全渲染器在弹窗显示。
+
+完整契约见生成应用的 `.agents/skills/hai-iam/reference.md`。
 {{/if}}

package/templates/apps/fullstack/apps/{{projectName}}-app/project.inlang/settings.json.hbs

@@ -8,7 +8,7 @@
     {{/each}}
   ],
   "modules": [
-    "https://cdn.jsdelivr.net/npm/@inlang/plugin-message-format@latest/dist/index.js"
+    "../../node_modules/@inlang/plugin-message-format/dist/index.js"
   ],
   "plugin.inlang.messageFormat": {
     "pathPattern": "./messages/{locale}.json"

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

@@ -34,4 +34,14 @@ pnpm --filter {{projectName}}-desktop deploy
 ```
 
 打包前需要安装 Rust 工具链和 Tauri 平台依赖。生产环境部署时同步调整 `.env` 中的 `PUBLIC_API_BASE` 与 `src-tauri/tauri.conf.json` 的 `connect-src` 白名单。
+
+## IAM 认证配置
+
+服务端 `config/_iam.yml` 统一控制登录、注册、重置、协议与 `ui` 品牌。邮件/短信可用 `_reach.yml` 中的 Provider/标准模板或自定义发送回调。`AuthPanel` 使用安全公开配置及框架认证动作；无需在页面适配 Token、验证码倒计时和错误提示。所有节点共享同一 DB 与 Redis；Memory 仅用于单进程。
+
+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。
+
+协议支持配置中的 userAgreementMarkdown/privacyPolicyMarkdown 正文及 URL；同主题优先 Markdown，由安全渲染器在弹窗显示。
+
+完整契约见生成应用的 `.agents/skills/hai-iam/reference.md`。
 {{/if}}

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

@@ -8,7 +8,7 @@
     {{/each}}
   ],
   "modules": [
-    "https://cdn.jsdelivr.net/npm/@inlang/plugin-message-format@latest/dist/index.js"
+    "../../node_modules/@inlang/plugin-message-format/dist/index.js"
   ],
   "plugin.inlang.messageFormat": {
     "pathPattern": "./messages/{locale}.json"

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

@@ -7,6 +7,8 @@
 - `project.inlang/settings.json`：小程序端 locale 配置
 - `messages/zh-CN.json`、`messages/en-US.json`：小程序端自有文案
 
+消息格式插件复用 workspace 已安装的依赖，从根目录 `node_modules` 加载；生成后先在 workspace 根目录安装依赖，无需从 CDN 加载插件。
+
 后续实现时建议复用 `packages/{{fullstack.contractPackageName}}` 中的 Schema 与路径常量，保持接口真相源一致。
 
 协同边界：跨端通用文案/组件放 `packages/{{fullstack.sharedPackageName}}`，小程序独有页面文案放本目录 `messages/`。

package/templates/apps/fullstack/apps/{{projectName}}-miniapp/project.inlang/settings.json.hbs

@@ -8,7 +8,7 @@
     {{/each}}
   ],
   "modules": [
-    "https://cdn.jsdelivr.net/npm/@inlang/plugin-message-format@latest/dist/index.js"
+    "../../node_modules/@inlang/plugin-message-format/dist/index.js"
   ],
   "plugin.inlang.messageFormat": {
     "pathPattern": "./messages/{locale}.json"

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

@@ -27,4 +27,14 @@ pnpm --filter {{projectName}}-web package
 # 当前模板的 deploy 入口默认执行 package，可替换为 CDN / 容器发布脚本
 pnpm --filter {{projectName}}-web deploy
 ```
+
+## IAM 认证配置
+
+服务端 `config/_iam.yml` 统一控制登录、注册、重置、协议与 `ui` 品牌。邮件/短信可用 `_reach.yml` 中的 Provider/标准模板或自定义发送回调。`AuthPanel` 使用安全公开配置及框架认证动作；无需在页面适配 Token、验证码倒计时和错误提示。所有节点共享同一 DB 与 Redis；Memory 仅用于单进程。
+
+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。
+
+协议支持配置中的 userAgreementMarkdown/privacyPolicyMarkdown 正文及 URL；同主题优先 Markdown，由安全渲染器在弹窗显示。
+
+完整契约见生成应用的 `.agents/skills/hai-iam/reference.md`。
 {{/if}}

package/templates/apps/fullstack/apps/{{projectName}}-web/project.inlang/settings.json.hbs

@@ -8,7 +8,7 @@
     {{/each}}
   ],
   "modules": [
-    "https://cdn.jsdelivr.net/npm/@inlang/plugin-message-format@latest/dist/index.js"
+    "../../node_modules/@inlang/plugin-message-format/dist/index.js"
   ],
   "plugin.inlang.messageFormat": {
     "pathPattern": "./messages/{locale}.json"

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

@@ -1,6 +1,8 @@
 import type { Page } from '@playwright/test'
 import { Buffer } from 'node:buffer'
 import { randomUUID } from 'node:crypto'
+import { mkdir } from 'node:fs/promises'
+import path from 'node:path'
 import process from 'node:process'
 import { apiContract } from '@h-ai/api-contract'
 import { expect, test } from '@playwright/test'
@@ -43,6 +45,66 @@ test('service rejects plaintext business requests', async ({ request }) => {
 })
 
 {{#if fullstack.e2eFrontend}}
+test('shared authentication supports public registration with configuration', async ({ page }) => {
+  test.setTimeout(90_000)
+  const evidence = process.env.HAI_AUTH_EVIDENCE_DIR || path.resolve('test-results/auth-screenshots')
+  await mkdir(evidence, { recursive: true })
+  await page.goto('/')
+  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()
+  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()
+  await expect(page.getByTestId('settings-page')).toBeVisible()
+  expect(await page.evaluate(() => document.documentElement.scrollWidth <= innerWidth)).toBe(true)
+  if (!process.env.IAM_NOTIFICATION_URL)
+    return
+  const email = `${username}@example.com`
+  await page.getByTestId('logout').click()
+  await page.getByRole('button', { name: /邮件验证码|Email code/i, exact: true }).click()
+  await page.screenshot({ path: path.join(evidence, '{{projectName}}-email.png'), fullPage: true })
+  await page.locator('#login-username').fill(email)
+  await page.getByRole('button', { name: /发送验证码|Send code/i, exact: true }).click()
+  await expect(page.getByRole('button', { name: /秒后重发|Resend in/ })).toBeDisabled()
+  async function received(template: string) {
+    const response = await page.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
+  }
+  const otp = await received('otp_email')
+  expect(Boolean(otp?.code)).toBe(true)
+  await page.locator('#login-code').fill(otp?.code ?? '')
+  await page.locator('button[type="submit"]').click()
+  await expect(page.getByTestId('settings-page')).toBeVisible()
+  await page.getByTestId('logout').click()
+  await page.getByRole('button', { name: /忘记密码|Forgot password/i }).click()
+  await page.screenshot({ path: path.join(evidence, '{{projectName}}-forgot.png'), fullPage: true })
+  await page.locator('input[type="email"]').fill(email)
+  await page.locator('button[type="submit"]').click()
+  await expect(page.locator('.alert-success')).toBeVisible()
+  const reset = await received('password_reset')
+  expect(Boolean(reset?.token)).toBe(true)
+  await page.getByRole('button', { name: /已有重置令牌|I have a reset token/i }).click()
+  await page.screenshot({ path: path.join(evidence, '{{projectName}}-reset.png'), fullPage: true })
+  await page.goto(`/?token=${encodeURIComponent(reset?.token ?? '')}`)
+  await expect(page.locator('input[type="password"]').nth(0)).toBeVisible()
+  await page.locator('input[type="password"]').nth(0).fill('FullstackReset456')
+  await page.locator('input[type="password"]').nth(1).fill('FullstackReset456')
+  await page.locator('button[type="submit"]').click()
+  await expect(page.locator('.alert-success')).toBeVisible()
+  await page.getByRole('button', { name: /^(登录|Sign in|Login)$/i }).click()
+  await login(page, username, 'FullstackReset456')
+  await expect(page.getByTestId('settings-page')).toBeVisible()
+  expect(new URL(page.url()).searchParams.has('token')).toBe(false)
+  await page.reload()
+  await expect(page.getByTestId('settings-page')).toBeVisible()
+})
 
 test('frontend displays configured core metadata and restores the administrator session', async ({ page }) => {
   await page.goto('/')
@@ -191,7 +253,7 @@ test('administrator and user complete account, avatar, preference, password and
     await userPage.getByTestId('password-form').getByRole('button', { name: /Change password/i }).click()
     await expect(userPage.getByTestId('login-form')).toBeVisible()
     await login(userPage, username, password)
-    await expect(userPage.getByTestId('login-form')).toContainText(/不正确|incorrect/)
+    await expect(userPage.getByTestId('login-form')).toContainText(/不正确|incorrect/i)
     await login(userPage, username, newPassword)
     await expect(userPage.getByTestId('settings-page')).toBeVisible()
 

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

@@ -6,7 +6,7 @@
 
 - `src/app-schemas.ts`：跨接口、跨层复用的输入/数据 Schema 与类型。
 - `src/app-contract.ts`：app 领域 contract；每个业务 path 直接写在对应接口定义中。
-- `src/admin-schemas.ts` / `src/admin-contract.ts`：管理员用户、固定角色、分页审计、个人设置、加密 JSON 头像上传 Schema/类型/路由；认证复用框架的 IAM auth contract，未开放自助注册和其它认证方式。
+- `src/admin-schemas.ts` / `src/admin-contract.ts`：管理员用户、固定角色、分页审计、个人设置、加密 JSON 头像上传 Schema/类型/路由；认证复用框架的 IAM auth contract，通过服务端配置启用注册、密码/LDAP/验证码登录及密码重置。
 - `src/{{projectName}}-contract.ts`：工程级 contract，供 `@h-ai/serv` 与 `@h-ai/api-client` 共用。
 
 只使用一次的输出 Schema 直接内联到 `.output(...)`；同一 contract 文件内重复使用时才保留私有常量。

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

@@ -56,8 +56,15 @@ export const profileContract = {
     .output(apiContract.haiResultSchema(AvatarOutputSchema)),
 }
 
-/** 复用框架认证契约，避免额外开放自助注册和未配置的认证方式。 */
+/** 复用框架认证契约；注册、通知和登录方式由 IAM 配置控制。 */
 export const authContract = {
+  publicConfig: apiContract.iam.auth.publicConfig,
+  register: apiContract.iam.auth.register,
+  loginWithLdap: apiContract.iam.auth.loginWithLdap,
+  loginWithOtp: apiContract.iam.auth.loginWithOtp,
+  sendOtp: apiContract.iam.auth.sendOtp,
+  requestPasswordReset: apiContract.iam.auth.requestPasswordReset,
+  confirmPasswordReset: apiContract.iam.auth.confirmPasswordReset,
   login: apiContract.iam.auth.login,
   logout: apiContract.iam.auth.logout,
   currentUser: apiContract.iam.auth.currentUser,

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

@@ -28,7 +28,7 @@ export const AdminUsersSchema = z.object({
 })
 export const AdminCreateUserSchema = z.object({
   username: z.string().min(3).max(64).regex(/^[\w-]+$/),
-  password: z.string().min(8).max(128),
+  password: z.string().min(1),
   email: z.email().optional(),
   displayName: z.string().max(100).optional(),
   role: AdminRoleCodeSchema.default('user'),

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

@@ -6,12 +6,13 @@
 
 - `config/_core.yml`：应用元信息（名称 / 版本 / 环境 / 语言），启动时由 `core.config` 加载。
 - `config/_serv.yml`：服务端运行时设置（CORS 来源等）。
-- `config/_db.yml` / `_cache.yml` / `_iam.yml` / `_storage.yml` / `_audit.yml`：mini 管理所需模块配置，初始化前使用模块公开 Schema 验证。
-- `src/index.ts`：进程入口，先 `core.init({ configDir: './config' })`，再初始化 reldb → cache → crypto → storage → iam → audit；启动失败及退出反序释放。
+- `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；启动失败及退出反序释放。
 - `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')` 守卫。每个请求读取用户最新启用状态、角色和权限。
-- 当前用户与刷新 procedures 直接选用 `@h-ai/serv/features/iam` 的默认实现；仅覆写登录、退出、修改密码以追加业务审计。未选的注册/OTP/通用管理接口不挂载，HTTP App 类型直接复用公开 `ServHttpApp`。
+- 标准认证 procedures 复用 `@h-ai/serv/features/iam`，注册、登录方式、重置与协议由 `_iam.yml` 控制；登录、退出、修改密码追加业务审计。HTTP App 类型复用公开 `ServHttpApp`。
 - `src/server/admin-service.ts`：角色分配、头像上传和审计编排，全部底层操作复用 hai 模块。固定 admin/user 两种角色；锁内重新鉴权，禁止管理员自删、自禁用、自降级，并补偿用户更新失败后的角色变更。
 - `tests/app-server.test.ts`：真实加密 HTTP 测试，覆盖 Cookie/受信原生刷新、RBAC、旧会话权限、并发管理操作、补偿、头像安全、偏好、审计及会话失效。
 
@@ -23,6 +24,10 @@ CLI 已生成根目录 `.env`，`HAI_ADMIN_DEFAULT_PASSWORD` 为每个项目独
 
 ## 开发
 
+所有配置字段以模块 Schema 为准；未使用字段和替代 Provider 用注释保留。叶子环境变量只覆盖已有 YAML 路径，先取消相应键的注释，或用 `HAI_DB` / `HAI_CACHE` 等整体对象覆盖；`connectTimeout` 对应 `HAI_CACHE_CONNECTTIMEOUT`。凭据示例在根 `.env.example`，实际密钥保存在忽略的 `.env` 或部署环境。`.gitignore` 的 `**/data/` 忽略所有运行数据及 `.gitkeep`；运行时会创建目录。`crypto.init()` 无配置参数，datapipe 为纯函数，不提供虚构配置。
+
+自动生成的 `.env` 只启用初始管理员密码和 `PUBLIC_API_BASE`；模块环境覆盖保留注释，以 YAML 为默认值来源。有明确环境覆盖时编辑 YAML 要同步核对。
+
 - `pnpm --filter {{fullstack.servPackageName}} dev`
 - `pnpm --filter {{fullstack.servPackageName}} test`
 
@@ -33,3 +38,13 @@ CLI 已生成根目录 `.env`，`HAI_ADMIN_DEFAULT_PASSWORD` 为每个项目独
 - Web 镜像不烘焙 API 地址；启动时使用 `-e PUBLIC_API_BASE=https://api.example.com` 注入，同一镜像可部署到不同环境。未设置时 Web 默认请求自身 origin。
 - YAML 配置使用 `${ENV_NAME:default}` 接收运行时环境变量；不要把密钥写入镜像。
 - 将 SQLite/本地存储放入本目录 `data/` 后运行 `pnpm docker:build:data` / `pnpm podman:build:data`，可生成带初始数据的镜像，持续写入仍应使用 volume。
+
+## IAM 认证配置
+
+服务端 `config/_iam.yml` 统一控制登录、注册、重置、协议与 `ui` 品牌。邮件/短信可用 `_reach.yml` 中的 Provider/标准模板或自定义发送回调。`AuthPanel` 使用安全公开配置及框架认证动作；无需在页面适配 Token、验证码倒计时和错误提示。所有节点共享同一 DB 与 Redis；Memory 仅用于单进程。
+
+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。
+
+协议支持配置中的 userAgreementMarkdown/privacyPolicyMarkdown 正文及 URL；同主题优先 Markdown，由安全渲染器在弹窗显示。
+
+完整契约见生成应用的 `.agents/skills/hai-iam/reference.md`。

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

@@ -0,0 +1 @@
+{{{moduleConfig 'ai' features.ai}}}

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

@@ -1,3 +1 @@
-userTable: hai_iam_users
-userIdColumn: id
-userNameColumn: username
+{{{moduleConfig 'audit' true}}}

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

@@ -1,2 +1 @@
-# 多实例部署请使用共享 Redis，保障会话、管理员变更锁一致。
-type: memory
+{{{moduleConfig 'cache' true}}}

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

@@ -15,7 +15,14 @@ defaultLocale: {{fullstack.i18n.baseLocale}}
 logging:
   level: info
   format: json
+  # context:
+  #   service: api
   redact:
     - password
     - token
     - secret
+
+# 短 ID 生成配置；未设置时采用框架默认值。
+# id:
+#   prefix: app_
+#   length: 21

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

@@ -1,3 +1 @@
-# 默认单实例 SQLite；HAI_DB 可整体替换为 PostgreSQL/MySQL 配置。
-type: sqlite
-database: ./data/app.db
+{{{moduleConfig 'db' true}}}

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

@@ -0,0 +1 @@
+{{{moduleConfig 'deploy' features.deploy}}}

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

@@ -1,21 +1 @@
-login:
-  password: true
-  otp: false
-  ldap: false
-  apikey: false
-password:
-  minLength: 8
-  maxLength: 128
-  requireUppercase: false
-  requireLowercase: false
-  requireNumber: false
-  requireSpecialChar: false
-session:
-  maxAge: 86400
-  sliding: true
-  singleDevice: false
-  refreshTokenMaxAge: 604800
-rbac:
-  defaultRole: user
-# 仅由应用创建 admin/user，避免生成无业务用途的默认角色与权限。
-seedDefaultData: false
+{{{moduleConfig 'iam' true}}}

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

@@ -0,0 +1 @@
+{{{moduleConfig 'payment' features.payment}}}