@h-ai/cli 0.1.0-alpha.60 → 0.1.0-alpha.62

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@h-ai/cli",
   "type": "module",
-  "version": "0.1.0-alpha.60",
+  "version": "0.1.0-alpha.62",
   "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.60",
+    "@h-ai/core": "0.1.0-alpha.62",
     "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.60",
-    "@h-ai/deploy": "0.1.0-alpha.60",
-    "@h-ai/reach": "0.1.0-alpha.60",
-    "@h-ai/reldb": "0.1.0-alpha.60",
-    "@h-ai/storage": "0.1.0-alpha.60",
+    "@h-ai/cache": "0.1.0-alpha.62",
+    "@h-ai/deploy": "0.1.0-alpha.62",
+    "@h-ai/reach": "0.1.0-alpha.62",
+    "@h-ai/reldb": "0.1.0-alpha.62",
+    "@h-ai/storage": "0.1.0-alpha.62",
     "@types/fs-extra": "^11.0.4",
     "@types/node": "^26.6.5",
     "@types/prompts": "^2.4.9",

package/templates/README.md

@@ -57,7 +57,7 @@ templates/
 │       └── settings.json    # Paraglide 项目配置
 │
 └── skills/                  # AI Skill 与各 appType 桥接指引
-    └── bridges/             # admin / api / website / h5 / mobile-app / fullstack 专属 AGENTS/Copilot
+    └── bridges/             # admin / api / website / h5 / mobile-app / fullstack 专属 AGENTS
 ```
 
 ## AI Skill 模板（Single Source of Truth）
@@ -65,11 +65,12 @@ templates/
 `templates/skills/` 是 CLI 生成共享 AI 上下文时的单一来源，同时用于 `hai create` 与 `hai add`。
 
 - `hai create` 会把 `templates/skills/` 下所有 `hai-*` Skill 目录复制到 `.agents/skills/<skill>/`，再按 appType 排除互斥项（例如 fullstack 不复制 `hai-kit`；admin / website / h5 不复制 `hai-serv`、`hai-api-contract`、`hai-api-client`、`hai-capacitor`；mobile-app 不复制 `hai-core`、`hai-kit`、`hai-serv`、`hai-api-contract`）
-- `bridges/<appType>/copilot-instructions.md` 会复制到 `.github/copilot-instructions.md`；没有专属文件时回退到通用桥接文件
+- 通用 `copilot-instructions.md` 复制到 `.github/copilot-instructions.md`，只引用项目根 `AGENTS.md`，不另维护 appType 专属规则
 - `bridges/<appType>/AGENTS.md` 会复制到项目根目录，确保不同样板工程使用自己的 AI 指引；通用 `CLAUDE.md` 仅包含 `@AGENTS.md`
 - `opencode.json` 会复制到项目根目录
-- `templates/skills/AGENTS.md`、`CLAUDE.md`、`copilot-instructions.md` 与 `opencode.json` 不是多余副本：它们是 generic fallback，主要服务于缺少 appType 上下文时的桥接复制与 `hai add` 回填 AI 支持
-- `opencode.json` 使用 OpenCode 的 `instructions` 配置复用 `.github/copilot-instructions.md`；`.agents/skills/` 由 OpenCode 原生发现，不再写入过期的 `skills.paths`
+- `templates/skills/AGENTS.md` 是缺少 appType 上下文时的通用规则；`CLAUDE.md`、`copilot-instructions.md` 与 `opencode.json` 是各工具的轻量入口，用于创建项目和回填 AI 支持
+- Codex 原生读取根 `AGENTS.md` 并发现 `.agents/skills/`，支持 `$hai-app-create` 等显式调用和按任务自动选择；无需 `.codex/skills` 或工具专属配置。依据：[Codex skills](https://learn.chatgpt.com/docs/build-skills)、[AGENTS.md](https://learn.chatgpt.com/docs/agent-configuration/agents-md)
+- `opencode.json` 使用 OpenCode 的 `instructions` 配置直接引用 `AGENTS.md`；`.agents/skills/` 由 OpenCode 原生发现，不再写入过期的 `skills.paths`
 - `CLAUDE.md` 通过 `@AGENTS.md` 复用共享规范，Claude Code 按其中的任务导航读取 `.agents/skills/` 正文与参考。CLI 不生成 `.claude/` 技能副本；此模式不提供 Claude 原生技能自动发现或 `/skill` 命令。依据：[Claude Code 项目指引](https://code.claude.com/docs/en/memory)、[原生 skills](https://code.claude.com/docs/en/skills)
 - `hai add` / `hai init` 只补齐缺失的 AI 支持文件，不覆盖用户已自定义的桥接文件，也不会自动删除遗留的 `.github/skills/` 或 `.claude/`
 
@@ -104,8 +105,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

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

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

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()
+  }
+}

package/templates/apps/api/playwright.config.ts.hbs

@@ -32,6 +32,7 @@ function resolvePortFromBaseUrl(urlString: string, fallbackPort: string): string
 
 export default defineConfig({
   testDir: './e2e',
+  globalSetup: './e2e/capture-evidence.ts',
   fullyParallel: false,
   forbidOnly: !!process.env.CI,
   retries: process.env.CI ? 2 : 0,

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

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

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

@@ -18,13 +18,29 @@ const configuredEnv = process.env.HAI_CORE_ENV || 'test'
 // 测试专用的一像素 PNG；上传仍使用完整前后端加密链路。
 const avatar = Buffer.from('iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+aSxkAAAAASUVORK5CYII=', 'base64')
 
-async function login(page: Page, username: string, password: string) {
+async function capture(page: Page, name: string, fallback: string) {
+  const evidence = process.env.HAI_AUTH_EVIDENCE_DIR
+  if (evidence)
+    await mkdir(evidence, { recursive: true })
+  await expect(page.getByTestId('guide-loading')).toHaveCount(0)
+  await page.evaluate(() => document.fonts.ready)
+  await page.screenshot({ path: evidence ? path.join(evidence, name) : fallback, fullPage: true, animations: 'disabled' })
+}
+
+async function submitLogin(page: Page, username: string, password: string) {
   await expect(page.getByTestId('login-form')).toBeVisible()
   await page.locator('#login-username').fill(username)
   await page.getByTestId('login-form').locator('input[type="password"]').fill(password)
   await page.getByTestId('login-form').getByRole('button', { name: /登录|Sign in|Login|Log in/i }).click()
 }
 
+async function login(page: Page, username: string, password: string, keepGuide = false) {
+  await submitLogin(page, username, password)
+  await expect(page.getByTestId('logout')).toBeVisible()
+  if (!keepGuide && await page.getByTestId('guide-later').isVisible())
+    await page.getByTestId('guide-later').click()
+}
+
 async function userEditor(page: Page, username: string) {
   await page.getByTestId('users-search').locator('input').fill(username)
   await page.getByTestId('users-page').getByRole('button', { name: /查询|Search/ }).click()
@@ -45,6 +61,95 @@ test('service rejects plaintext business requests', async ({ request }) => {
 })
 
 {{#if fullstack.e2eFrontend}}
+test('first-use tour, help search and settings navigation work on desktop and mobile', async ({ page }, testInfo) => {
+  await page.goto('/')
+  await login(page, 'admin', adminPassword, true)
+  await expect(page.getByTestId('guide-offer')).toBeVisible()
+  await page.getByTestId('guide-start').click()
+  const popover = page.locator('.hai-guide-popover')
+  await expect(popover).toBeVisible()
+  await capture(page, '{{projectName}}-guide-desktop.png', testInfo.outputPath('guide-desktop.png'))
+  for (let step = 1; step < 3; step++) {
+    await popover.locator('.driver-popover-next-btn').click()
+    await expect(popover.locator('.driver-popover-progress-text')).toContainText(String(step + 1))
+  }
+  await popover.locator('.driver-popover-next-btn').click()
+  await expect(popover).toHaveCount(0)
+  await page.reload()
+  await expect(page.getByTestId('admin-help')).toBeVisible()
+  await expect(page.getByTestId('guide-offer')).toHaveCount(0)
+  await page.getByTestId('admin-help').click()
+  const profileTitle = (await page.getByTestId('guide-article-profile').textContent())!.trim()
+  await page.getByTestId('guide-search').locator('input').fill(profileTitle)
+  await expect(page.getByTestId('guide-article-profile')).toBeVisible()
+  await expect(page.getByTestId('guide-article-overview')).toHaveCount(0)
+  await page.getByTestId('guide-article-start').click()
+  await expect(page.getByTestId('settings-page')).toBeVisible()
+  await expect(popover).toBeVisible()
+  await page.keyboard.press('Escape')
+  await expect(popover).toHaveCount(0)
+  await page.setViewportSize({ width: 390, height: 844 })
+  await page.getByTestId('admin-help').click()
+  await expect(page.getByTestId('help-center')).toBeVisible()
+  expect(await page.evaluate(() => document.documentElement.scrollWidth <= innerWidth)).toBe(true)
+  await capture(page, '{{projectName}}-guide-help-mobile.png', testInfo.outputPath('guide-help-mobile.png'))
+  await page.getByTestId('guide-tour-overview').click()
+  await expect(popover.locator('.driver-popover-next-btn')).toBeEnabled()
+  // 下一步未渲染时仍能通过宿主提示取消，不能被引擎遮罩阻止。
+  await page.locator('[data-guide="admin-profile"]').evaluate(element => element.removeAttribute('data-guide'))
+  await popover.locator('.driver-popover-next-btn').click()
+  await expect(page.getByTestId('guide-loading')).toBeVisible()
+  await page.getByTestId('guide-cancel').click()
+  await expect(popover).toHaveCount(0)
+  await expect(page.getByTestId('guide-error')).toHaveCount(0)
+})
+
+// 所有已生成的浏览器前端都验证共享引导，不能用 Web 的成功代替 App/Desktop 预览。
+const additionalFrontends = [
+{{#each fullstack.frontendApps}}
+  {
+    target: '{{target}}',
+    url: process.env.HAI_E2E_{{target}}_URL || 'http://127.0.0.1:{{port}}',
+  },
+{{/each}}
+].filter(frontend => frontend.target !== '{{fullstack.e2eFrontend.target}}')
+
+for (const frontend of additionalFrontends) {
+  test(`${frontend.target} preview supports login, tour, help and profile navigation`, async ({ browser }, testInfo) => {
+    const page = await browser.newPage({ viewport: frontend.target === 'app' ? { width: 390, height: 844 } : { width: 1440, height: 960 } })
+    const pageErrors: string[] = []
+    page.on('pageerror', error => pageErrors.push(error.message))
+    try {
+      await page.goto(frontend.url)
+      await expect(page.getByTestId('login-form')).toBeVisible()
+      await capture(page, `{{projectName}}-${frontend.target}-login.png`, testInfo.outputPath(`${frontend.target}-login.png`))
+      await login(page, 'admin', adminPassword, true)
+      await expect(page.getByTestId('guide-offer')).toBeVisible()
+      await page.getByTestId('guide-start').click()
+      const popover = page.locator('.hai-guide-popover')
+      await expect(popover).toBeVisible()
+      await capture(page, `{{projectName}}-${frontend.target}-guide.png`, testInfo.outputPath(`${frontend.target}-guide.png`))
+      await page.keyboard.press('Escape')
+      await expect(popover).toHaveCount(0)
+      await page.getByTestId('admin-help').click()
+      await expect(page.getByTestId('help-center')).toBeVisible()
+      expect(await page.evaluate(() => document.documentElement.scrollWidth <= innerWidth)).toBe(true)
+      await capture(page, `{{projectName}}-${frontend.target}-help.png`, testInfo.outputPath(`${frontend.target}-help.png`))
+      await page.getByTestId('guide-article-profile').click()
+      await page.getByTestId('guide-article-start').click()
+      await expect(page.getByTestId('settings-page')).toBeVisible()
+      await expect(popover).toBeVisible()
+      await page.keyboard.press('Escape')
+      await expect(popover).toHaveCount(0)
+      await capture(page, `{{projectName}}-${frontend.target}-profile.png`, testInfo.outputPath(`${frontend.target}-profile.png`))
+      expect(pageErrors).toEqual([])
+    }
+    finally {
+      await page.close()
+    }
+  })
+}
+
 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')
@@ -106,7 +211,7 @@ test('shared authentication supports public registration with configuration', as
   await expect(page.getByTestId('settings-page')).toBeVisible()
 })
 
-test('frontend displays configured core metadata and restores the administrator session', async ({ page }) => {
+test('frontend displays configured core metadata and restores the administrator session', async ({ page }, testInfo) => {
   await page.goto('/')
   await expect(page.getByTestId('app-name')).toHaveText(configuredName)
   await expect(page).toHaveTitle(configuredName)
@@ -118,17 +223,24 @@ test('frontend displays configured core metadata and restores the administrator
   await expect(page.getByTestId('users-page')).toBeVisible()
   await expect(page.getByTestId('nav-roles')).toBeVisible()
   await expect(page.getByTestId('nav-audit')).toBeVisible()
+  const evidence = process.env.HAI_AUTH_EVIDENCE_DIR
+  if (evidence)
+    await mkdir(evidence, { recursive: true })
+  await page.screenshot({ path: evidence ? path.join(evidence, '{{projectName}}-users.png') : testInfo.outputPath('users.png'), fullPage: true })
   await page.getByTestId('logout').click()
   await expect(page.getByTestId('login-form')).toBeVisible()
 })
 
-test('audit filters align and fit desktop, tablet and narrow mobile screens', async ({ page }) => {
+test('audit filters align and fit desktop, tablet and narrow mobile screens', async ({ page }, testInfo) => {
   await page.goto('/')
   await login(page, 'admin', adminPassword)
   await page.getByTestId('nav-audit').click()
   await expect(page.getByTestId('audit-page')).toBeVisible()
   for (const width of [1440, 960, 390, 320]) {
     await page.setViewportSize({ width, height: 900 })
+    // 等待移动侧栏收起，避免过渡帧遮挡内容并污染截图。
+    if (width < 1024)
+      await expect.poll(() => page.locator('aside').evaluate(sidebar => sidebar.getBoundingClientRect().right)).toBeLessThanOrEqual(1)
     const controls = await page.getByTestId('audit-page').locator('form').evaluate(form => [
       form.querySelector('#audit-action')?.parentElement,
       form.querySelector('#audit-resource')?.parentElement,
@@ -152,6 +264,13 @@ test('audit filters align and fit desktop, tablet and narrow mobile screens', as
       expect(controls[2]!.top).toBeCloseTo(controls[3]!.top, 0)
     }
     expect(await page.evaluate(() => document.documentElement.scrollWidth <= innerWidth)).toBe(true)
+    if (width === 1440 || width === 390) {
+      const evidence = process.env.HAI_AUTH_EVIDENCE_DIR
+      if (evidence)
+        await mkdir(evidence, { recursive: true })
+      const file = `{{projectName}}-audit-${width}.png`
+      await page.screenshot({ path: evidence ? path.join(evidence, file) : testInfo.outputPath(file), fullPage: true, animations: 'disabled' })
+    }
   }
 })
 
@@ -252,7 +371,7 @@ test('administrator and user complete account, avatar, preference, password and
     await passwordInputs.nth(2).fill(newPassword)
     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 submitLogin(userPage, username, password)
     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}}-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`
 

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,67 +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
-
-# 注册与登录安全
-register:
-  enabled: true
-  defaultEnabled: true
-security:
-  maxLoginAttempts: 5
-  lockoutDuration: 900
-
-# LDAP 可选：安装 ldapts 后开启 login.ldap，并声明 ldap 连接配置或注入工厂。
-# OTP 需启用 login.otp，并选择 Reach 标准模板或自定义发送回调。
-otp:
-  email: true
-  sms: true
-  length: 6
-  expiresIn: 300
-  maxAttempts: 3
-  resendInterval: 60
-passwordReset:
-  enabled: true
-  mode: email # phone 使用 password_reset_sms 模板
-  tokenExpiresIn: 3600
-  maxAttempts: 3
-  # resetUrl: https://example.com/auth/reset-password
-agreements:
-  showOnRegister: true
-  showOnLogin: false
-  # Markdown 正文由公开配置传给所有客户端，在弹窗内安全渲染。
-  userAgreementMarkdown: |
-    # 用户协议示例
-
-    请妥善保管账户凭据，并按应用提供的功能使用服务。
-  privacyPolicyMarkdown: |
-    # 隐私政策示例
-
-    注册资料用于账户管理，会话信息用于身份认证。
-  # userAgreementUrl: https://example.com/terms
-  # privacyPolicyUrl: https://example.com/privacy
-ui:
-  variant: card
-  # title: Account center
-  # subtitle: Welcome back
-  # brandTitle: Your application
-  # brandText: Sign in securely
-  # logoUrl: /logo.svg
-  # illustrationUrl: /auth-illustration.svg
+{{{moduleConfig 'iam' true}}}

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

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

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

@@ -4,6 +4,30 @@ providers:
     type: console
   - name: sms
     type: console
+  # SMTP 替换 email 控制台 Provider；同名 Provider 只保留一个。
+  # - name: email
+  #   type: smtp
+  #   host: ${HAI_REACH_SMTP_HOST:smtp.example.com}
+  #   port: ${HAI_REACH_SMTP_PORT:465}
+  #   secure: true
+  #   user: ${HAI_REACH_SMTP_USER:}
+  #   pass: ${HAI_REACH_SMTP_PASS:}
+  #   from: ${HAI_REACH_SMTP_FROM:noreply@example.com}
+  # 阿里云短信替换 sms 控制台 Provider。
+  # - name: sms
+  #   type: aliyun-sms
+  #   accessKeyId: ${HAI_REACH_SMS_ACCESS_KEY}
+  #   accessKeySecret: ${HAI_REACH_SMS_SECRET_KEY}
+  #   signName: MyApp
+  #   endpoint: dysmsapi.aliyuncs.com
+  # 自有发送服务：按需将 template.provider 改为 custom。
+  # - name: custom
+  #   type: api
+  #   url: https://notify.example.com/send
+  #   method: POST # POST | PUT
+  #   headers:
+  #     Authorization: 'Bearer ${HAI_REACH_API_TOKEN}'
+  #   timeout: 10000
 templates:
   - name: otp_email
     provider: email
@@ -19,3 +43,10 @@ templates:
   - name: password_reset_sms
     provider: sms
     body: 'Reset your password: {resetUrl}. Expires at {expiresAt}.'
+
+# 免打扰可选；验证码应避免 delay，以免延迟到失效后投递。
+# dnd:
+#   enabled: false
+#   strategy: discard # discard | delay
+#   start: '22:00'
+#   end: '08:00'

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

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

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

@@ -10,15 +10,24 @@ server:
   port: 3000
 
 http:
+  # 仅列出会清洗/追加转发头的代理 IP/CIDR；空数组忽略 X-Forwarded-For/X-Real-IP。
+  trustedProxies: []
   apiPrefix: /api/v1
   openapi:
     path: /openapi.json
   docs:
     path: /docs
+    # requireAuth: true
   health:
     path: /health
     readyPath: /ready
   rpc: false
+  # 内部 RPC 可选；启用时用对象替换 false，gateway-only 必须配置网关密钥。
+  # rpc:
+  #   prefix: /api/rpc
+  #   access: gateway-only # loopback | private-network | gateway-only
+  #   gatewayHeader: X-Gateway-Key
+  #   gatewaySecret: ${HAI_SERV_HTTP_RPC_GATEWAYSECRET}
 
 cors:
   origin: ${HAI_CORS_ORIGIN:*}
@@ -40,3 +49,4 @@ cors:
 transport:
   keyExchangePath: /_hai/key-exchange
   maxClients: 10000
+  # excludePaths: [/health, /ready]

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

@@ -1,3 +1 @@
-# HAI_STORAGE 可整体替换为 S3/MinIO/RustFS 配置。
-type: local
-root: ./data/uploads
+{{{moduleConfig 'storage' true}}}

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

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

package/templates/apps/fullstack/packages/{{projectName}}-serv/src/app-server.ts.hbs

@@ -1,6 +1,6 @@
 import type { CoreConfig } from '@h-ai/core'
 import type { ServHttpApp } from '@h-ai/serv'
-import { core, err, HaiCommonError, ok } from '@h-ai/core'
+import { core } from '@h-ai/core'
 import { createReldbTransportKeyStore, crypto } from '@h-ai/crypto'
 import { iam } from '@h-ai/iam'
 import { reldb } from '@h-ai/reldb'
@@ -40,26 +40,6 @@ export function createServerApp(): ServHttpApp {
       },
     }),
     iam,
-    verifyToken: async (token) => {
-      const session = await iam.session.verifyToken(token)
-      if (!session.success)
-        return session
-      const user = await iam.user.getUser(session.data.userId)
-      if (!user.success)
-        return user
-      if (!user.data?.enabled)
-        return err(HaiCommonError.UNAUTHORIZED, core.i18n.coreM('core_errorUnauthorized'))
-      // 会话中的授权同步属于最大努力，业务守卫始终读取最新持久化角色与权限。
-      const [roles, permissions] = await Promise.all([
-        iam.authz.getUserRoles(user.data.id),
-        iam.authz.getUserPermissions(user.data.id),
-      ])
-      if (!roles.success)
-        return roles
-      if (!permissions.success)
-        return permissions
-      return ok({ ...session.data, roles: roles.data.map(role => role.code), permissions: permissions.data.map(permission => permission.code) })
-    },
     refreshCookie: {
       secure: security.secureRefreshCookie,
       nativeTokenTransport: { isRequest: request => request.headers.get('x-hai-token-transport') === 'body'

package/templates/apps/fullstack/packages/{{projectName}}-serv/src/server/procedures/admin-procedures.ts.hbs

@@ -85,7 +85,7 @@ export function createAdminProcedures() {
     const result = await audit.list({ ...input, startDate: input.startDate ? new Date(input.startDate) : undefined, endDate: input.endDate ? new Date(input.endDate) : undefined })
     if (!result.success)
       return result
-    return ok({ ...result.data, page: input.page, pageSize: input.pageSize, items: result.data.items.map(item => ({ ...item, createdAt: new Date(item.createdAt).toISOString() })) })
+    return ok({ ...result.data, items: result.data.items.map(item => ({ ...item, createdAt: new Date(item.createdAt).toISOString() })) })
   }).build()
 }
 

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

@@ -21,6 +21,12 @@ Capacitor native uses `createCapacitorTokenStorage()` and the trusted native tok
 
 Language and theme preferences are saved in IAM user metadata, restored after login and synchronized with the shared/host Paraglide runtimes and `core.i18n`. The small reactive theme store delegates DOM updates and safe appearance caching to `@h-ai/ui/theme` (`applyTheme` / `getSavedTheme`); the framework uses the `theme` localStorage key. Appearance selectors live in personal settings and save through the authenticated profile contract.
 
+## Onboarding and help
+
+AdminWorkspace mounts the shared `@h-ai/ui/guide` controller and GuideHost after authentication. AppShell includes a help button; first-use invitations offer start, later and dismiss. Web stores preferences in Cookies, while App/Desktop use localStorage, scoped by the current user and tour version. Help articles link to the overview and profile tours.
+
+Extend `src/lib/stores/guide-store.ts` and the shared Chinese/English messages, then add stable data-guide attributes to existing components. Navigation uses the same ManagementStore. Keep business text as i18n callbacks and preserve the host's locale/scope binding. Browser tests cover completion, reload, replay, settings navigation and mobile help.
+
 ## i18n and themes
 
 Shared page copy belongs in `messages/{zh-CN,en-US}.json`. Frontend-specific copy belongs in each app's own messages directory. Keep `baseLocale` and `locales` aligned across all enabled projects, then run root `pnpm i18n:compile`; do not edit generated Paraglide files.
@@ -31,7 +37,7 @@ The scaffold theme configuration determines the themes compiled into frontend CS
 
 ## Validation
 
-Run root `pnpm typecheck`, `pnpm lint`, `pnpm build`, `pnpm test` and `pnpm test:e2e`. Shared API tests exercise real transport key exchange, encrypted request/response handling, configured core metadata and credential forwarding. Root browser tests cover administrator and ordinary-user workflows, avatar rendering, persisted preferences, password/session invalidation and narrow-screen layout.
+Run root `pnpm typecheck`, `pnpm lint`, `pnpm build`, `pnpm test` and `pnpm test:e2e`. Shared API tests exercise real transport key exchange, encrypted request/response handling, configured core metadata and credential forwarding. Root browser tests cover administrator and ordinary-user workflows, avatar rendering, persisted preferences, password/session invalidation and narrow-screen layout. All selected Web/App/Desktop previews also exercise login, tours, help and profile navigation. Set `HAI_AUTH_EVIDENCE_DIR` to keep screenshots outside the test output directory. These browser checks do not replace native-shell or miniapp device acceptance.
 
 ## IAM configuration
 

package/templates/apps/fullstack/packages/{{projectName}}-shared/messages/en-US.json.hbs

@@ -83,5 +83,23 @@
   "audit_system": "System",
   "audit_details": "Audit log details",
   "audit_date_invalid": "The end date must be on or after the start date.",
-  "api_not_configured": "The service connection is not configured. Please contact your administrator."
+  "api_not_configured": "The service connection is not configured. Please contact your administrator.",
+  "guide_overview_title": "Explore your admin workspace",
+  "guide_overview_description": "A few short steps introduce the workspace, personal settings and help. Leave at any time and replay tours from the help center.",
+  "guide_content_title": "Workspace",
+  "guide_content_description": "The current page appears here. Use navigation to switch features. Available actions depend on your permissions.",
+  "guide_theme_title": "Appearance",
+  "guide_theme_description": "Switch between light and dark appearances here. More themes are available in settings.",
+  "guide_profile_title": "Your profile",
+  "guide_profile_description": "Use your avatar to access your profile and settings, including personal information and passwords.",
+  "guide_help_title": "Help center",
+  "guide_help_description": "Search instructions here whenever you need help, or replay a product tour.",
+  "guide_profile_tour_title": "Set up your profile",
+  "guide_profile_tour_description": "Find your personal information, preferences and password settings. This tour explains actions without submitting changes.",
+  "guide_profile_form_description": "View or edit your profile, choose an avatar and save your changes. Uploaded files must meet the format and size requirements shown on the page.",
+  "guide_preferences_description": "Save your preferred language and theme. The interface and help content follow your selection.",
+  "guide_password_title": "Change password",
+  "guide_password_description": "Enter your current password, new password and confirmation. Check the password rules before submitting.",
+  "guide_overview_article": "## Getting started\n\n- Open features through navigation. Menus and actions depend on your current permissions.\n- The workspace contains lists, details or settings. Follow the page instructions and check information before submitting.\n- Use your avatar to access your profile and settings.\n- Search instructions or replay tours through the help button.\n\n## First-use tour\n\n“Remind me later” pauses reminders for one day. “Do not remind me” saves your preference. Completed tours no longer prompt automatically and remain available for manual replay.",
+  "guide_profile_article": "## Profile and preferences\n\nOpen your profile to view or update personal information and your avatar. Check the file requirements, save changes and read the result message. Appearance and language can be adjusted in settings.\n\n## Password\n\nChanging a password requires the current password, new password and confirmation. Follow the displayed password rules and check the result after submitting.\n\n“Start tour” opens the relevant page. Tours never save forms or change your account automatically."
 }