@h-ai/cli 0.1.0-alpha.63 → 0.1.0-alpha.65

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

@@ -14,7 +14,7 @@ import {
   ProfileUpdateSchema,
 } from './admin-schemas.js'
 
-/** mini 管理业务路径统一定义；仅开放两种固定角色。 */
+/** mini 管理示例的业务路径；初始 admin/user 角色可按实际需求调整。 */
 export const adminContract = {
   users: {
     list: apiContract.route({ method: 'POST', path: '/admin/users/list', tags: ['admin'] })

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

@@ -1,36 +1,30 @@
 import { apiContract } from '@h-ai/api-contract'
 import { describe, expect, it } from 'vitest'
-import {
-  appContract,
-  AppEchoInputSchema,
-  AppInfoOutputDataSchema,
-  ENABLED_FRONTENDS,
-  {{fullstack.contractExportName}},
-} from '../src/index.js'
+import * as contracts from '../src/index.js'
 
 describe('{{fullstack.contractPackageName}}', () => {
   it('defines app contract routes', () => {
-    expect({{fullstack.contractExportName}}.app).toBeDefined()
-    expect(appContract.info).toBeDefined()
-    expect(apiContract.pathOf(appContract.info)).toBe('/app/info')
+    expect(contracts.{{fullstack.contractExportName}}.app).toBeDefined()
+    expect(contracts.appContract.info).toBeDefined()
+    expect(apiContract.pathOf(contracts.appContract.info)).toBe('/app/info')
   })
 
   it('validates app info payload', () => {
-    const result = AppInfoOutputDataSchema.safeParse({
+    const result = contracts.AppInfoOutputDataSchema.safeParse({
       name: '{{fullstack.servPackageName}}',
       version: '0.1.0',
       env: 'test',
       defaultLocale: 'zh-CN',
       supportedLocales: ['zh-CN', 'en-US'],
       startedAt: '2026-01-01T00:00:00.000Z',
-      frontends: [...ENABLED_FRONTENDS],
+      frontends: [...contracts.ENABLED_FRONTENDS],
     })
 
     expect(result.success).toBe(true)
   })
 
   it('validates echo input boundaries', () => {
-    expect(AppEchoInputSchema.safeParse({ message: 'hello' }).success).toBe(true)
-    expect(AppEchoInputSchema.safeParse({ message: '' }).success).toBe(false)
+    expect(contracts.AppEchoInputSchema.safeParse({ message: 'hello' }).success).toBe(true)
+    expect(contracts.AppEchoInputSchema.safeParse({ message: '' }).success).toBe(false)
   })
 })

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

@@ -4,6 +4,8 @@
 
 ## 默认功能与配置
 
+以下是可运行示例的初始实现，角色/权限、管理流程、头像限额、分页、审计策略及部署方案均可按用户需求调整。需求与代码或模板规则不一致时，以需求为业务基线同步实现、测试与过期说明；实际框架 API 契约和服务端安全校验仍需满足。
+
 - `config/_core.yml`：应用元信息（名称 / 版本 / 环境 / 语言），启动时由 `core.config` 加载。
 - `config/_serv.yml`：服务端运行时设置（CORS 来源等）。
 - `config/_db.yml` / `_cache.yml` / `_iam.yml` / `_storage.yml` / `_audit.yml` / `_reach.yml`：管理及开发通知配置，初始化前使用模块公开 Schema 验证。Reach 默认控制台 Provider，生产按注释替换为 SMTP/短信/API。
@@ -13,10 +15,10 @@
 - `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`，注册、登录方式、重置与协议由 `_iam.yml` 控制；登录、退出、修改密码追加业务审计。HTTP App 类型复用公开 `ServHttpApp`。
-- `src/server/admin-service.ts`：角色分配、头像上传和审计编排，全部底层操作复用 hai 模块。固定 admin/user 两种角色；锁内重新鉴权，禁止管理员自删、自禁用、自降级，并补偿用户更新失败后的角色变更。
+- `src/server/admin-service.ts`：角色分配、头像上传和审计编排，全部底层操作复用 hai 模块。初始使用 admin/user 两种角色；锁内重新鉴权，默认禁止管理员自删、自禁用、自降级，并补偿用户更新失败后的角色变更。业务规则可按需求替换，保留的不变量需验证并发与失败路径。
 - `tests/app-server.test.ts`：真实加密 HTTP 测试，覆盖 Cookie/受信原生刷新、RBAC、旧会话权限、并发管理操作、补偿、头像安全、偏好、审计及会话失效。
 
-CLI 已生成根目录 `.env`，`HAI_ADMIN_DEFAULT_PASSWORD` 为每个项目独立的随机强密码；`dev`/`start` 自动读取，首次登录使用用户名 `admin` 和该密码。仅在没有用户时创建管理员，不重设已有用户密码。密码不符合 `_iam.yml` 策略时，启动日志显示具体原因及错误码。`.env` 被 Git 和容器构建忽略，`.env.example` 不含真实密码；部署时设置目标环境自己的密码。所有业务 JSON 请求和响应强制加密；健康检查和随机路径的只读头像图片可直接访问。头像支持 PNG/JPEG/WebP，最大 512 KiB，校验内容特征和大小后由服务端生成 key，不能指定任意文件路径。
+CLI 已生成根目录 `.env.local`，`HAI_ADMIN_DEFAULT_PASSWORD` 为每个项目独立的随机强密码；`dev`/`start` 自动读取，首次登录使用用户名 `admin` 和该密码。仅在没有用户时创建管理员，不重设已有用户密码。密码不符合 `_iam.yml` 策略时，启动日志显示具体原因及错误码。`.env.local` 被 Git 和容器构建忽略，`.env.example` 不含真实密码；部署时设置目标环境自己的密码。所有业务 JSON 请求和响应强制加密；健康检查和随机路径的只读头像图片可直接访问。头像支持 PNG/JPEG/WebP，最大 512 KiB，校验内容特征和大小后由服务端生成 key，不能指定任意文件路径。
 
 默认 SQLite + 本地 storage + memory cache 适合单实例，管理写入仅支持单写实例：进程内保护无过期时间，共享 cache 锁定期续租，丢失锁或释放失败会记录错误。多实例读取可使用共享数据库、Redis cache 和 S3 storage，但管理写请求必须统一路由到同一写实例；仅更换 Redis 不提供任意多写副本的最后管理员原子保证。另需配置传输会话粘性路由：服务端私钥驻留单个进程，服务重启后客户端需重新协商。Web 使用 HttpOnly refresh Cookie + 内存 access token；仅同时满足客户端标识、body 通道头与受信原生 Origin 的 App/Desktop 请求返回 refresh token body。
 
@@ -24,9 +26,9 @@ 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 为纯函数，不提供虚构配置。
+所有配置字段以模块 Schema 为准；未使用字段和替代 Provider 用注释保留。叶子环境变量只覆盖已有 YAML 路径，先取消相应键的注释，或用 `HAI_DB` / `HAI_CACHE` 等整体对象覆盖；`connectTimeout` 对应 `HAI_CACHE_CONNECTTIMEOUT`。凭据示例在根 `.env.example`，实际密钥保存在忽略的 `.env.local` 或部署环境。`.gitignore` 的 `**/data/` 忽略所有运行数据及 `.gitkeep`；运行时会创建目录。`crypto.init()` 无配置参数，datapipe 为纯函数，不提供虚构配置。
 
-自动生成的 `.env` 只启用初始管理员密码和 `PUBLIC_API_BASE`；模块环境覆盖保留注释，以 YAML 为默认值来源。有明确环境覆盖时编辑 YAML 要同步核对。
+自动生成的 `.env` 包含已启用模块的环境参数；YAML 显式引用相同变量并保留本地回退。使用 `start:test` / `start:prod` 加载对应环境覆盖。
 
 - `pnpm --filter {{fullstack.servPackageName}} dev`
 - `pnpm --filter {{fullstack.servPackageName}} test`

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

@@ -7,17 +7,17 @@ providers:
   # SMTP 替换 email 控制台 Provider；同名 Provider 只保留一个。
   # - name: email
   #   type: smtp
-  #   host: ${HAI_REACH_SMTP_HOST:smtp.example.com}
-  #   port: ${HAI_REACH_SMTP_PORT:465}
+  #   host: ${HAI_REACH_PROVIDERS_0_HOST:smtp.example.com}
+  #   port: ${HAI_REACH_PROVIDERS_0_PORT:465}
   #   secure: true
-  #   user: ${HAI_REACH_SMTP_USER:}
-  #   pass: ${HAI_REACH_SMTP_PASS:}
-  #   from: ${HAI_REACH_SMTP_FROM:noreply@example.com}
+  #   user: ${HAI_REACH_PROVIDERS_0_USER:}
+  #   pass: ${HAI_REACH_PROVIDERS_0_PASS:}
+  #   from: ${HAI_REACH_PROVIDERS_0_FROM:noreply@example.com}
   # 阿里云短信替换 sms 控制台 Provider。
   # - name: sms
   #   type: aliyun-sms
-  #   accessKeyId: ${HAI_REACH_SMS_ACCESS_KEY}
-  #   accessKeySecret: ${HAI_REACH_SMS_SECRET_KEY}
+  #   accessKeyId: ${HAI_REACH_PROVIDERS_0_ACCESSKEYID}
+  #   accessKeySecret: ${HAI_REACH_PROVIDERS_0_ACCESSKEYSECRET}
   #   signName: MyApp
   #   endpoint: dysmsapi.aliyuncs.com
   # 自有发送服务：按需将 template.provider 改为 custom。
@@ -26,7 +26,7 @@ providers:
   #   url: https://notify.example.com/send
   #   method: POST # POST | PUT
   #   headers:
-  #     Authorization: 'Bearer ${HAI_REACH_API_TOKEN}'
+  #     Authorization: '${HAI_REACH_PROVIDERS_0_HEADERS_AUTHORIZATION}'
   #   timeout: 10000
 templates:
   - name: otp_email

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

@@ -30,9 +30,9 @@ http:
   #   gatewaySecret: ${HAI_SERV_HTTP_RPC_GATEWAYSECRET}
 
 cors:
-  origin: ${HAI_CORS_ORIGIN:*}
-  nativeOrigins: ${HAI_CORS_NATIVEORIGINS:http://localhost,https://localhost,http://tauri.localhost,https://tauri.localhost,tauri://localhost,capacitor://localhost}
-  credentials: ${HAI_CORS_CREDENTIALS:true}
+  origin: ${HAI_SERV_CORS_ORIGIN:*}
+  nativeOrigins: ${HAI_SERV_CORS_NATIVEORIGINS:http://localhost,https://localhost,http://tauri.localhost,https://tauri.localhost,tauri://localhost,capacitor://localhost}
+  credentials: ${HAI_SERV_CORS_CREDENTIALS:true}
   allowedHeaders:
     - Authorization
     - Content-Type

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

@@ -20,13 +20,20 @@
   ],
   "scripts": {
     "build": "tsup",
+    "build:prod": "pnpm build",
+    "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-if-exists=../../.env dist/index.js",
-    "start": "node --env-file-if-exists=../../.env dist/index.js"
+    "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": {
     "@h-ai/audit": "{{haiPackageSpecifier}}",

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

@@ -6,7 +6,7 @@ import { iam } from '@h-ai/iam'
 import { reldb } from '@h-ai/reldb'
 import { serv, ServConfigSchema } from '@h-ai/serv'
 import { storage } from '@h-ai/storage'
-import { ENABLED_FRONTENDS, {{fullstack.contractExportName}}, SUPPORTED_LOCALES } from '{{fullstack.contractPackageName}}'
+import * as contracts from '{{fullstack.contractPackageName}}'
 import { createServerProcedures } from './server/procedures/index.js'
 
 const STARTED_AT = new Date().toISOString()
@@ -27,16 +27,16 @@ export function createServerApp(): ServHttpApp {
   ]
 
   return serv.createApp({
-    contract: {{fullstack.contractExportName}},
+    contract: contracts.{{fullstack.contractExportName}},
     procedures: createServerProcedures({
       app: {
         name: coreConfig.name,
         version: coreConfig.version,
         env: coreConfig.env,
         defaultLocale: coreConfig.defaultLocale,
-        supportedLocales: SUPPORTED_LOCALES,
+        supportedLocales: contracts.SUPPORTED_LOCALES,
         startedAt: STARTED_AT,
-        frontends: [...ENABLED_FRONTENDS],
+        frontends: [...contracts.ENABLED_FRONTENDS],
       },
     }),
     iam,

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

@@ -2,8 +2,10 @@
 
 Shared mini administration workspace for **{{projectName}}**. Web, Capacitor App and Tauri desktop use the same `AdminWorkspace`, responsive `AppShell`, typed API client and management store.
 
+The behavior below describes the initial example. Roles, permissions, workflows, limits, preferences and audit policies can change with the user's requirements. Update conflicting implementation, tests and guidance together; preserve the applicable public API contracts and server security checks.
+
 - Administrators manage users, upload user avatars, assign the built-in administrator/user roles, edit role descriptions and query audit logs.
-- Ordinary users can only update their own profile, avatar, language, appearance and password. The server enforces access on every request.
+- By default, ordinary users update their own profile, avatar, language, appearance and password. The server enforces the actual business permissions on every request.
 - `ManagementStore` owns API calls and business state; components render the state and forward user interactions.
 - Application name, version, environment and default locale come from the backend `app.info` contract, which reads `core` configuration. Do not duplicate these values in translations or frontend constants.
 - Requests, token refresh and JSON responses use the same `@h-ai/api-client` + `@h-ai/crypto` transport. Avatar uploads use encrypted JSON and validate PNG/JPEG/WebP content, with a 512 KiB limit.
@@ -43,6 +45,8 @@ Run root `pnpm typecheck`, `pnpm lint`, `pnpm build`, `pnpm test` and `pnpm test
 
 The service's `config/_iam.yml` controls login methods, registration, password reset, agreements and `ui` branding. Email and SMS use providers/templates in `_reach.yml` or custom callbacks. `AuthPanel` uses the public configuration and framework auth actions to manage tokens, resend countdowns and errors. All service nodes must share the same database and Redis; memory cache is for a single process.
 
+Authentication defaults to a split layout. Set `ui.variant`, `title`, `subtitle`, `brandTitle`, `brandText`, `logoUrl` and `illustrationUrl` to customize login and registration. Without a `brandTitle`, the displayed application name comes from `app.info` and follows `core` configuration.
+
 LDAP and Reach are optional. Install ldapts in the IAM service workspace only when using its default LDAP client, then enable login.ldap and set connection settings. Custom onOtpSendEmail/onOtpSendSms/onPasswordResetRequest callbacks work without Reach and must reject on delivery failure. Agreements open in a Modal. LoginForm/RegisterForm support header/extraFields/footer snippets; AuthPanel forwards loginHeader/loginFields/loginFooter and registerHeader/registerFields/registerFooter. See the generated hai-iam/hai-ui skills for configuration and examples.
 
 协议支持配置中的 userAgreementMarkdown/privacyPolicyMarkdown 正文及 URL；同主题优先 Markdown，由安全渲染器在弹窗显示。
@@ -51,4 +55,4 @@ See `.agents/skills/hai-iam/reference.md` in the generated application for the c
 
 ## Form layouts
 
-The user editor uses `FormLayout columns={2} labelPosition="left"`; profile and password forms reuse the same UI options. Narrow containers automatically stack fields and labels. Field validation errors follow the current UI language. The management store syncs locale through the lightweight `@h-ai/ui/i18n` entry, without loading components or tour CSS. Configure `colSpan` on FormField to override automatic spans for textareas, uploads and multiple choices.
+The user editor uses `FormLayout columns={2} labelPosition="left"`. Personal settings use a bounded page width, stacked labels and a single avatar editor. Narrow containers automatically stack fields and labels. UI controls and CRUD forms show client validation on blur, update errors while correcting input and validate untouched fields on submit. Field errors follow the current UI language. The management store syncs locale through the lightweight `@h-ai/ui/i18n` entry, without loading components or tour CSS. Configure `colSpan` on FormField to override automatic spans for textareas, uploads and multiple choices.

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

@@ -24,8 +24,10 @@
     "paraglide:compile": "paraglide-js compile --project ./project.inlang --outdir ./src/lib/paraglide",
     "paraglide:watch": "paraglide-js compile --project ./project.inlang --outdir ./src/lib/paraglide --watch",
     "prepare": "paraglide-js compile --project ./project.inlang --outdir ./src/lib/paraglide",
+    "check": "pnpm typecheck",
     "typecheck": "pnpm paraglide:compile && svelte-check --tsconfig ./tsconfig.json",
     "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
     "test": "vitest run --passWithNoTests",
     "clean": "rimraf .turbo src/lib/paraglide"
   },

package/templates/apps/fullstack/packages/{{projectName}}-shared/src/lib/components/AdminWorkspace.svelte.hbs

@@ -1,4 +1,5 @@
 <script lang='ts'>
+  import type { Component } from 'svelte'
   import type { ManagementApiOptions } from '../api/api-client.js'
   import { Alert, Skeleton } from '@h-ai/ui/components/compounds/index'
   import { Button } from '@h-ai/ui/components/primitives/index'
@@ -6,9 +7,10 @@
   import { GuideHost } from '@h-ai/ui/guide'
   import { onMount, untrack } from 'svelte'
   import { managementAuthActions } from '../api/api-client.js'
+  import { HashRouter } from '../navigation/hash-router.svelte.js'
   import * as m from '../paraglide/messages.js'
-  import { ManagementStore } from '../stores/management-store.svelte.js'
   import { createManagementGuide } from '../stores/guide-store.js'
+  import { ManagementStore } from '../stores/management-store.svelte.js'
   import AppShell from './AppShell.svelte'
 
   interface Props {
@@ -17,10 +19,16 @@
     onLocaleChange?: (locale: string) => void
   }
   const { platform, apiOptions = {}, onLocaleChange }: Props = $props()
-  const store = new ManagementStore()
+  const pages = import.meta.glob<{ default: Component<{ store: ManagementStore }> }>('../pages/**/*.svelte')
+  const router = new HashRouter(Object.keys(pages), '/users')
+  const store = new ManagementStore(router)
   // 宿主平台在组件生命周期中固定，引导控制器只创建一次。
   const guide = untrack(() => createManagementGuide(store, platform))
   let resetToken = $state('')
+  const authConfig = $derived(store.authConfig && {
+    ...store.authConfig,
+    ui: { ...store.authConfig.ui, brandTitle: store.authConfig.ui.brandTitle || store.info?.name },
+  })
   async function authenticated() {
     await store.authenticated()
     if (resetToken) {
@@ -30,19 +38,16 @@
     }
     resetToken = ''
   }
-  const pageComponent = $derived.by(() => {
-    if (store.isAdmin && store.page === 'users')
-      return import('./UserManagement.svelte')
-    if (store.isAdmin && store.page === 'roles')
-      return import('./RoleManagement.svelte')
-    if (store.isAdmin && store.page === 'audit')
-      return import('./AuditManagement.svelte')
-    return import('./ProfileSettings.svelte')
-  })
+  const pageComponent = $derived(pages[router.file]())
   onMount(() => {
+    const stopRouting = router.start(() => {
+      if (store.user)
+        void store.navigate(router.path.slice(1))
+    })
     resetToken = new URL(location.href).searchParams.get('token') ?? ''
     void store.initialize(apiOptions, onLocaleChange)
     return () => {
+      stopRouting()
       void store.close()
     }
   })
@@ -56,6 +61,7 @@
   {#if store.initializing}
     <div class='grid min-h-dvh place-items-center bg-base-200/50'><div class='w-72 space-y-4'><Skeleton variant='title' /><Skeleton count={3} /><p class='text-center text-sm text-base-content/50'>{m.home_loading()}</p></div></div>
   {:else if !store.user || resetToken}
+    <header class='border-b border-base-content/8 bg-base-100 px-6 py-3 text-sm font-medium'>{store.info?.name}</header>
     <main data-testid='login-page'>
       {#if !store.info || !store.authConfig}
         <section class='mx-auto mt-20 max-w-md space-y-4 p-6'>
@@ -65,9 +71,9 @@
       {:else}
         <div data-testid='login-form'>
           {#if store.authConfig && store.error}<Alert variant='error' class='mx-auto max-w-lg'>{store.error}</Alert>{/if}
-          <AuthPanel config={store.authConfig} actions={managementAuthActions} {resetToken} initialMode={resetToken ? 'reset' : 'login'} error={store.authConfig ? '' : store.error} onretry={() => void store.initialize(apiOptions, onLocaleChange)} onauthenticated={authenticated} />
+          <AuthPanel config={authConfig} actions={managementAuthActions} {resetToken} initialMode={resetToken ? 'reset' : 'login'} error={store.authConfig ? '' : store.error} onretry={() => void store.initialize(apiOptions, onLocaleChange)} onauthenticated={authenticated} />
         </div>
-        <p class='fixed bottom-3 left-0 right-0 text-center text-xs text-base-content/50'><span data-testid='app-name'>{store.info.name}</span> · <span data-testid='app-version'>v{store.info.version}</span> · <span data-testid='app-environment'>{store.info.env}</span></p>
+        <footer class='border-t border-base-content/8 p-3 text-center text-xs text-base-content/50'><span data-testid='app-name'>{store.info.name}</span> · <span data-testid='app-version'>v{store.info.version}</span> · <span data-testid='app-environment'>{store.info.env}</span></footer>
       {/if}
     </main>
   {:else}

package/templates/apps/fullstack/packages/{{projectName}}-shared/src/lib/components/AppShell.svelte.hbs

@@ -22,7 +22,7 @@
 : []),
     { id: 'settings' as const, label: m.settings_title(), icon: 'icon-[tabler--settings]' },
   ])
-  const title = $derived(items.find(item => item.id === store.page)?.label ?? m.settings_title())
+  const title = $derived(items.find(item => item.id === store.page)?.label ?? store.info?.name ?? '')
 
   function navigate(page: ManagementPage) {
     menuOpen = false

package/templates/apps/fullstack/packages/{{projectName}}-shared/src/lib/pages/settings.svelte.hbs

@@ -0,0 +1,46 @@
+<script lang='ts'>
+  import type { ManagementStore } from '../stores/management-store.svelte.js'
+  import { Card, FormField, FormLayout } from '@h-ai/ui/components/compounds/index'
+  import { Badge, Select } from '@h-ai/ui/components/primitives/index'
+  import { ChangePasswordForm, UserProfile } from '@h-ai/ui/components/scenes/iam/index'
+  import { getThemeInfo } from '@h-ai/ui/theme'
+  import * as m from '../paraglide/messages.js'
+  import { locales } from '../paraglide/runtime.js'
+  import { AVAILABLE_THEMES, themeStore } from '../stores/theme-store.svelte.js'
+
+  interface Props { store: ManagementStore }
+  const { store }: Props = $props()
+  const languageOptions = $derived(locales.filter(locale => store.info?.supportedLocales.includes(locale)).map(locale => ({ value: locale, label: locale === 'zh-CN' ? '简体中文' : 'English' })))
+  const themeOptions = AVAILABLE_THEMES.map(theme => ({ value: theme, label: getThemeInfo(theme)?.name ?? theme }))
+</script>
+
+<section class='mx-auto w-full max-w-4xl space-y-6' data-testid='settings-page'>
+  <div>
+    <h1 class='text-xl font-semibold tracking-tight'>{m.settings_title()}</h1>
+    <p class='mt-1 text-sm text-base-content/50'>{m.settings_description()}</p>
+  </div>
+  {#if store.user}
+    <Card title={m.profile_title()} bordered shadow={false} data-guide='admin-profile-form'>
+      <div class='mb-5 flex flex-wrap items-center gap-3 border-b border-base-content/8 pb-4'>
+        <p class='min-w-0 break-all text-sm text-base-content/55'>@{store.user.username}</p>
+        <Badge size='sm' variant='ghost'>{store.isAdmin ? m.role_admin() : m.role_user()}</Badge>
+      </div>
+      <UserProfile columns={2} user={store.user} editable alwaysEditable fields={['avatar', 'displayName', 'email']} avatarAccept='image/png,image/jpeg,image/webp' avatarHint={m.avatar_hint()} loading={store.saving} onsubmit={data => store.saveProfile(data)} onavatarchange={file => void store.uploadAvatar(file)} data-testid='profile-form' />
+    </Card>
+    <Card title={m.preferences_title()} bordered shadow={false} data-guide='admin-preferences'>
+      <p class='mb-5 text-sm text-base-content/50'>{m.preferences_description()}</p>
+      <FormLayout columns={2}>
+        <FormField label={m.settings_language()} for='profile-language'>
+          <Select id='profile-language' value={store.locale} options={languageOptions} disabled={store.saving} onchange={locale => void store.savePreferences({ locale })} data-testid='profile-language' />
+        </FormField>
+        <FormField label={m.settings_theme()} for='profile-theme'>
+          <Select id='profile-theme' value={themeStore.current} options={themeOptions} disabled={store.saving} onchange={theme => void store.savePreferences({ theme })} data-testid='profile-theme' />
+        </FormField>
+      </FormLayout>
+    </Card>
+    <Card title={m.password_title()} bordered shadow={false} data-guide='admin-password'>
+      <p class='mb-5 text-sm text-base-content/50'>{m.password_rules()}</p>
+      <ChangePasswordForm loading={store.saving} passwordPolicy={store.authConfig?.password} minPasswordLength={store.authConfig?.password.minLength ?? 8} onsubmit={data => store.changePassword(data)} data-testid='password-form' />
+    </Card>
+  {/if}
+</section>

package/templates/apps/fullstack/packages/{{projectName}}-shared/src/lib/stores/management-store.svelte.ts.hbs

@@ -3,6 +3,7 @@ import type { HaiResult } from '@h-ai/core'
 import type { ChangePasswordFormData, UserProfileSubmitData } from '@h-ai/ui'
 import type { AdminAuditLog, AdminCreateUser, AdminRole, AdminUpdateUser, AdminUser, AvatarUpload, ProfileUpdate } from '{{fullstack.contractPackageName}}'
 import type { AppInfo, ManagementApiOptions } from '../api/api-client.js'
+import type { HashRouter } from '../navigation/hash-router.svelte.js'
 import { HaiApiClientError } from '@h-ai/api-client'
 import { setGlobalLocale } from '@h-ai/ui/i18n'
 import { SvelteDate } from 'svelte/reactivity'
@@ -13,10 +14,20 @@ import { AVAILABLE_THEMES, DEFAULT_THEME, themeStore } from './theme-store.svelt
 
 type ResultData<T> = T extends { success: true, data: infer D } ? D : never
 export type CurrentUser = ResultData<Awaited<ReturnType<typeof managementApi.iam.auth.currentUser>>>
-export type ManagementPage = 'users' | 'roles' | 'audit' | 'settings'
+/** 页面目录对应的相对路径；例如 `reports/weekly`，新增页面无需修改类型或路由表。 */
+export type ManagementPage = string
 
 /** 页面状态和业务操作在共享 store 中收敛，宿主端仅装配平台能力。 */
 export class ManagementStore {
+  /**
+   * 绑定当前工作区的页面路由；服务端继续验证各 API 的权限。
+   * @example new ManagementStore(new HashRouter(Object.keys(pages), '/users'))
+   */
+  constructor(router: HashRouter) {
+    this.router = router
+  }
+
+  private readonly router: HashRouter
   info = $state<AppInfo | null>(null)
   authConfig = $state<IamPublicConfig | null>(null)
   user = $state<CurrentUser | null>(null)
@@ -76,7 +87,7 @@ export class ManagementStore {
       const me = await managementApi.iam.auth.currentUser()
       if (me.success) {
         this.setUser(me.data)
-        await this.navigate(this.isAdmin ? 'users' : 'settings')
+        await this.navigate(this.router.path.slice(1))
       }
       else if (me.error.httpStatus !== 401) {
         this.error = m.operation_failed()
@@ -102,7 +113,7 @@ export class ManagementStore {
     if (!me?.success)
       return
     this.setUser(me.data)
-    await this.navigate(this.isAdmin ? 'users' : 'settings')
+    await this.navigate(this.router.path.slice(1))
   }
 
   async logout(): Promise<void> {
@@ -121,6 +132,9 @@ export class ManagementStore {
     this.requestVersion++
     this.loading = false
     this.page = this.isAdmin ? page : 'settings'
+    if (this.router.path !== `/${this.page}`)
+      this.router.navigate(`/${this.page}`)
+    this.page = this.router.path.slice(1)
     this.error = ''
     this.notice = ''
     if (this.page === 'users')

package/templates/apps/fullstack/packages/{{projectName}}-shared/tests/management-store.test.ts.hbs

@@ -1,4 +1,5 @@
-import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { HashRouter } from '../src/lib/navigation/hash-router.svelte.js'
 import * as m from '../src/lib/paraglide/messages.js'
 import { ManagementStore } from '../src/lib/stores/management-store.svelte.js'
 
@@ -35,15 +36,24 @@ function deferred<T>() {
 
 beforeEach(() => {
   vi.resetAllMocks()
+  vi.stubGlobal('location', { hash: '#/users' })
+  vi.stubGlobal('history', { replaceState: vi.fn(), pushState: vi.fn() })
   api.iam.auth.logout.mockResolvedValue({ success: true })
   api.iam.auth.currentUser.mockResolvedValue({ success: true, data: member })
 })
 
+afterEach(() => vi.unstubAllGlobals())
+
+/** 会话测试使用真实路由状态，浏览器历史由 E2E 验证。 */
+function createStore() {
+  return new ManagementStore(new HashRouter(['../pages/users.svelte', '../pages/settings.svelte'], '/users'))
+}
+
 describe('management session and request ownership', () => {
   it('ignores a previous administrator failure after logout and another user login', async () => {
     const oldRequest = deferred<typeof forbidden>()
     api.admin.users.list.mockReturnValueOnce(oldRequest.promise)
-    const store = new ManagementStore()
+    const store = createStore()
     store.user = administrator
     const loading = store.loadUsers()
     await store.logout()
@@ -60,7 +70,7 @@ describe('management session and request ownership', () => {
   it('ignores an obsolete page failure after opening personal settings', async () => {
     const oldRequest = deferred<typeof forbidden>()
     api.admin.users.list.mockReturnValueOnce(oldRequest.promise)
-    const store = new ManagementStore()
+    const store = createStore()
     store.user = administrator
     const loading = store.loadUsers()
     await store.navigate('settings')
@@ -75,7 +85,7 @@ describe('management session and request ownership', () => {
 
   it('refreshes revoked roles once and clears administration data', async () => {
     api.admin.users.list.mockResolvedValueOnce(forbidden)
-    const store = new ManagementStore()
+    const store = createStore()
     store.user = administrator
     store.roles = [{ id: 'role-id', code: 'admin', name: 'Administrator', userCount: 1 }]
     await store.loadUsers()
@@ -90,7 +100,7 @@ describe('management session and request ownership', () => {
 
   it('reports a connection failure when loading the authenticated user', async () => {
     api.iam.auth.currentUser.mockRejectedValueOnce(new Error('Connection unavailable'))
-    const store = new ManagementStore()
+    const store = createStore()
     await store.authenticated()
     expect(store.error).toBe(m.network_error())
     expect(store.error).not.toBe(m.login_invalid())

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

@@ -5,12 +5,17 @@ const defaultBaseURL = '{{#if fullstack.e2eFrontend}}http://127.0.0.1:{{fullstac
 const defaultServiceBaseURL = 'http://127.0.0.1:3000'
 const baseURL = process.env.BASE_URL || defaultBaseURL
 const primaryFrontend = '{{fullstack.e2eFrontend.target}}'
+const frontendUrls = {
+  web: process.env.HAI_E2E_WEB_URL,
+  app: process.env.HAI_E2E_APP_URL,
+  desktop: process.env.HAI_E2E_DESKTOP_URL,
+}
 const frontends: { target: string, name: string, url: string }[] = [
 {{#each fullstack.frontendApps}}
   {
     target: '{{target}}',
     name: '{{packageName}}',
-    url: process.env.HAI_E2E_{{target}}_URL || 'http://127.0.0.1:{{port}}',
+    url: frontendUrls.{{target}} || 'http://127.0.0.1:{{port}}',
   },
 {{/each}}
 ]

package/templates/apps/fullstack/pnpm-workspace.yaml.hbs

@@ -9,7 +9,6 @@ trustPolicyExclude:
 # pnpm 12 配置；原生依赖仅运行明确列出的安装脚本。
 nodeLinker: hoisted
 allowBuilds:
-  onnxruntime-node: true
   protobufjs: true
   vue-demi: true
   better-sqlite3: true

package/templates/apps/h5/src/routes/+layout.svelte.hbs

@@ -14,9 +14,9 @@
 {{#if hasI18n}}
   import * as m from '$lib/paraglide/messages'
   import { getLocale } from '$lib/paraglide/runtime.js'
-  import { BottomNav, setGlobalLocale } from '@h-ai/ui'
+  import { AppBar, BottomNav, setGlobalLocale } from '@h-ai/ui'
 {{else}}
-  import { BottomNav } from '@h-ai/ui'
+  import { AppBar, BottomNav } from '@h-ai/ui'
 {{/if}}
   import '../app.css'
 
@@ -39,7 +39,7 @@
   ]
 
   const activeNav = $derived(navItems.find(item => item.path === page.url.pathname)?.id)
-  // 认证页面独立显示；业务页面复用框架导航和移动端安全区域样式。
+  // 所有页面共用页头页脚；仅业务页面显示底部导航。
   const isAuthPage = $derived(page.url.pathname.startsWith('/auth'))
 
   function handleNavigation(id: string) {
@@ -60,15 +60,15 @@
   <title>{page.data.appConfig.name}</title>
 </svelte:head>
 
-{#if isAuthPage}
-  {@render children()}
-{:else}
-  <div class='hai-mobile-viewport'>
-    <div class='hai-mobile-shell max-w-lg'>
-      <main class='hai-mobile-main'>
-        {@render children()}
-      </main>
+<div class='hai-mobile-viewport'>
+  <div class='hai-mobile-shell max-w-lg'>
+    <AppBar title={page.data.appConfig.name} safeArea fixed={false} />
+    <main class='hai-mobile-main'>{@render children()}</main>
+    <footer class='border-t border-base-300 bg-base-100 p-2 text-center text-xs text-base-content/60'>
+      {page.data.appConfig.name} · {page.data.appConfig.version} · {page.data.appConfig.env}
+    </footer>
+    {#if !isAuthPage}
       <BottomNav items={navItems} active={activeNav} onchange={handleNavigation} centered maxWidth='lg' safeArea />
-    </div>
+    {/if}
   </div>
-{/if}
+</div>