@h-ai/cli 0.1.0-alpha.64 → 0.1.0-alpha.66

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

@@ -9,13 +9,16 @@
   "scripts": {
     "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",
+    "dev:test": "vite --mode test",
+    "dev:prod": "vite --mode prod",
     "dev": "vite dev --host 127.0.0.1 --port {{fullstack.ports.web}}",
     "build": "pnpm paraglide:compile && vite build",
     "package": "pnpm build",
-    "deploy": "pnpm package",
     "preview": "vite preview --host 127.0.0.1 --port {{fullstack.ports.web}} --strictPort",
+    "check": "pnpm typecheck",
     "typecheck": "pnpm paraglide:compile && svelte-check --tsconfig ./tsconfig.json",
     "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
     "test": "vitest run --passWithNoTests",
     "test:watch": "vitest",
     "clean": "rimraf dist build .turbo src/lib/paraglide"
@@ -26,6 +29,7 @@
   },
   "devDependencies": {
     "@antfu/eslint-config": "{{fullstack.packageSpecifiers.antfuEslintConfig}}",
+    "@h-ai/core": "{{haiPackageSpecifier}}",
     "@iconify-json/tabler": "{{fullstack.packageSpecifiers.iconifyJsonTabler}}",
     "@iconify/tailwind4": "{{fullstack.packageSpecifiers.iconifyTailwind}}",
     "@inlang/paraglide-js": "{{fullstack.packageSpecifiers.inlangParaglide}}",

package/templates/apps/fullstack/apps/{{projectName}}-web/vite.config.ts.hbs

@@ -2,21 +2,25 @@
 {{#if fullstack.frontends.web}}
 import process from 'node:process'
 import { fileURLToPath } from 'node:url'
+import { core } from '@h-ai/core'
 import { haiOptimizeExclude, haiPrebundledDeps } from '@h-ai/ui/vite'
 import { paraglideVitePlugin } from '@inlang/paraglide-js'
 import { svelte } from '@sveltejs/vite-plugin-svelte'
 import tailwindcss from '@tailwindcss/vite'
-import { loadEnv } from 'vite'
 import { defineConfig } from 'vitest/config'
 
 const envDir = fileURLToPath(new URL('../../', import.meta.url))
 
-export default defineConfig(({ mode }) => {
-  const env = loadEnv(mode, envDir, 'PUBLIC_')
+export default defineConfig(({ mode, command }) => {
+  const envResult = command === 'build' ? { success: true as const, data: {} as Record<string, string> } : core.config.loadEnvFiles({ mode, envDir })
+  if (!envResult.success)
+    throw new Error(envResult.error.message)
+  const env = envResult.data
+  Object.assign(process.env, env)
   const target = (env.PUBLIC_API_BASE || process.env.SERVICE_BASE_URL || 'http://127.0.0.1:3000').replace(/\/api\/v1\/?$/, '')
   const proxy = { '/api': { target, changeOrigin: true } }
   return {
-    envDir,
+    envDir: false,
     server: { proxy },
     preview: { proxy },
     build: {

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

@@ -61,11 +61,33 @@ test('service rejects plaintext business requests', async ({ request }) => {
 })
 
 {{#if fullstack.e2eFrontend}}
+test('hash routing restores direct links, refresh and browser history', async ({ page }) => {
+  await page.goto('/#/roles?source=direct')
+  await login(page, 'admin', adminPassword)
+  await expect(page.getByTestId('roles-page')).toBeVisible()
+  await expect(page).toHaveURL(/#\/roles\?source=direct$/)
+  await page.reload()
+  await expect(page.getByTestId('roles-page')).toBeVisible()
+  await expect(page.locator('header')).toBeVisible()
+  await expect(page.locator('footer')).toBeVisible()
+  await page.getByTestId('nav-settings').click()
+  await expect(page).toHaveURL(/#\/settings$/)
+  await page.goBack()
+  await expect(page.getByTestId('roles-page')).toBeVisible()
+  await page.goForward()
+  await expect(page.getByTestId('profile-form')).toBeVisible()
+  await page.goto('/#/unknown-page')
+  await expect(page).toHaveURL(/#\/users$/)
+  await expect(page.getByTestId('users-page')).toBeVisible()
+})
+
 test('branded authentication, profile layout and blur validation work across screen sizes', async ({ page }, testInfo) => {
   test.setTimeout(60_000)
   await page.setViewportSize({ width: 1440, height: 960 })
   await page.goto('/')
   await expect(page.getByRole('heading', { name: configuredName, exact: true })).toBeVisible()
+  await expect(page.locator('header')).toBeVisible()
+  await expect(page.locator('footer')).toBeVisible()
   await capture(page, '{{projectName}}-login-desktop.png', testInfo.outputPath('login-desktop.png'))
   await page.getByRole('button', { name: /立即注册|Register now/, exact: true }).click()
   await expect(page.locator('.register-form')).toBeVisible()
@@ -74,6 +96,7 @@ test('branded authentication, profile layout and blur validation work across scr
   await capture(page, '{{projectName}}-register-mobile.png', testInfo.outputPath('register-mobile.png'))
   expect(await page.evaluate(() => document.documentElement.scrollWidth <= innerWidth)).toBe(true)
   await page.reload()
+  await expect(page.getByTestId('login-form')).toBeVisible()
   await capture(page, '{{projectName}}-login-mobile.png', testInfo.outputPath('login-mobile.png'))
   await page.setViewportSize({ width: 1440, height: 960 })
   await login(page, 'admin', adminPassword)
@@ -179,7 +202,7 @@ const additionalFrontends = [
 {{#each fullstack.frontendApps}}
   {
     target: '{{target}}',
-    url: process.env.HAI_E2E_{{target}}_URL || 'http://127.0.0.1:{{port}}',
+    url: process.env['HAI_E2E_{{target}}_URL'.toUpperCase()] || 'http://127.0.0.1:{{port}}',
   },
 {{/each}}
 ].filter(frontend => frontend.target !== '{{fullstack.e2eFrontend.target}}')

package/templates/apps/fullstack/hai.build.json.hbs

@@ -0,0 +1,7 @@
+{
+  "images": [
+    { "name": "app", "target": "runtime", "containerPort": 3000 }{{#if fullstack.frontends.web}},
+    { "name": "web", "target": "web", "containerPort": 8080 }{{/if}}
+  ]{{#if fullstack.frontends.desktop}},
+  "desktop": ["apps/{{projectName}}-desktop"]{{/if}}
+}

package/templates/apps/fullstack/package.json.hbs

@@ -10,20 +10,21 @@
     "i18n:compile": "pnpm --filter {{fullstack.sharedPackageName}} paraglide:compile{{#each fullstack.frontendApps}} && pnpm --filter {{packageName}} paraglide:compile{{/each}}",
     "postinstall": "pnpm i18n:compile",
     "dev": "pnpm --filter {{fullstack.contractPackageName}} build && pnpm i18n:compile && pnpm --parallel --filter {{fullstack.servPackageName}}{{#each fullstack.frontendApps}} --filter {{packageName}}{{/each}} dev",
-    "compile": "pnpm typecheck && pnpm build",
-    "build": "pnpm --filter {{fullstack.contractPackageName}} build && pnpm i18n:compile && pnpm -r --if-present build",
-    "docker:build": "docker build --target runtime -t {{projectName}}:latest .",
-    "docker:build:data": "docker build --target runtime-with-data --build-context embedded-data=./packages/{{projectName}}-serv/data -t {{projectName}}:latest ."{{#if fullstack.frontends.web}},
-    "docker:build:web": "docker build --target web -t {{projectName}}-web:latest ."{{/if}},
-    "podman:build": "podman build --format docker --jobs=1 --target runtime -t {{projectName}}:latest .",
-    "podman:build:data": "podman build --format docker --jobs=1 --target runtime-with-data --build-context embedded-data=./packages/{{projectName}}-serv/data -t {{projectName}}:latest ."{{#if fullstack.frontends.web}},
-    "podman:build:web": "podman build --format docker --jobs=1 --target web -t {{projectName}}-web:latest ."{{/if}},
-    "package": "pnpm build{{#if fullstack.frontends.web}} && pnpm --filter {{projectName}}-web package{{/if}}{{#if fullstack.frontends.app}} && pnpm --filter {{projectName}}-app package{{/if}}{{#if fullstack.frontends.desktop}} && pnpm --filter {{projectName}}-desktop package{{/if}}",
-    "deploy": "pnpm package",
+    "start": "pnpm --filter {{fullstack.servPackageName}} start",
+    "start:test": "pnpm --filter {{fullstack.servPackageName}} start:test",
+    "start:prod": "pnpm --filter {{fullstack.servPackageName}} start:prod",
+    "dev:test": "pnpm --filter {{fullstack.contractPackageName}} build && pnpm i18n:compile && pnpm --parallel --filter {{fullstack.servPackageName}}{{#each fullstack.frontendApps}} --filter {{packageName}}{{/each}} dev:test",
+    "dev:prod": "pnpm --filter {{fullstack.contractPackageName}} build && pnpm i18n:compile && pnpm --parallel --filter {{fullstack.servPackageName}}{{#each fullstack.frontendApps}} --filter {{packageName}}{{/each}} dev:prod",
+    "compile": "pnpm --filter {{fullstack.contractPackageName}} build && pnpm i18n:compile && pnpm -r --if-present build",
+    "build": "hai build",
+    "deploy": "hai deploy packages/{{projectName}}-serv",
+    "check": "pnpm typecheck",
     "typecheck": "pnpm --filter {{fullstack.contractPackageName}} build && pnpm i18n:compile && pnpm -r --if-present typecheck",
     "lint": "eslint *.js *.ts e2e && pnpm -r --if-present lint",
+    "lint:fix": "eslint *.js *.ts e2e --fix && pnpm -r --if-present lint:fix",
     "test": "pnpm --filter {{fullstack.contractPackageName}} build && pnpm i18n:compile && pnpm -r --if-present test",
-    "test:e2e": "pnpm build && playwright test",
+    "test:watch": "pnpm -r --parallel --if-present test:watch",
+    "test:e2e": "pnpm compile && node scripts/run-e2e.mjs",
     "clean": "pnpm -r --if-present clean && rimraf node_modules .turbo"
   },
   "dependencies": {
@@ -32,6 +33,10 @@
     "{{fullstack.sharedPackageName}}": "workspace:*"
   },
   "devDependencies": {
+    "@h-ai/cli": "{{haiPackageSpecifier}}",
+{{#if features.deploy}}
+    "@h-ai/deploy": "{{haiPackageSpecifier}}",
+{{/if}}
     "@antfu/eslint-config": "{{fullstack.packageSpecifiers.antfuEslintConfig}}",
     "@playwright/test": "{{fullstack.packageSpecifiers.playwright}}",
     "@sveltejs/vite-plugin-svelte": "{{fullstack.packageSpecifiers.sveltePlugin}}",

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

@@ -1,12 +1,12 @@
 # {{fullstack.contractPackageName}}
 
-共享 API 契约包，包含 Zod Schema、`apiContract.route()` 业务接口定义与工程级 contract。
+共享 API 契约包，包含 Zod Schema、`apiContract.route()` 业务接口定义与工程级 contract。业务 schema、角色、流程及限额是模板初始方案，按用户需求修改，并同步服务端授权、调用方、测试与说明；不要求需求沿用默认业务。
 
 ## 骨架说明
 
 - `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，通过服务端配置启用注册、密码/LDAP/验证码登录及密码重置。
+- `src/admin-schemas.ts` / `src/admin-contract.ts`：示例管理员用户、初始 admin/user 角色、分页审计、个人设置、加密 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/package.json.hbs

@@ -14,8 +14,10 @@
   "types": "./dist/index.d.ts",
   "scripts": {
     "build": "tsup",
+    "check": "pnpm typecheck",
     "typecheck": "tsc --noEmit",
     "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
     "test": "vitest run",
     "test:watch": "vitest",
     "clean": "rimraf dist .turbo"

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,20 +26,20 @@ 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`
 
 ## 容器运行
 
-- 根目录 `pnpm docker:build` / `pnpm podman:build` 直接生成本服务镜像；Web 使用独立的 `docker:build:web` / `podman:build:web` 镜像。
+从工程根运行 `pnpm build --target docker` 构建并导出镜像。启用 deploy 功能后，运行根命令 `pnpm deploy --env test`；含 Web 镜像时一并发布 API/Web，部署不重新构建。网络不通时用 `pnpm deploy --env prod --bundle-only`，按说明手工搬运 tar。
+
 - 服务镜像直接由 `@h-ai/serv` 对外监听，配置挂载点为 `/app/config`，数据目录为 `/app/data`，不包含额外转发进程。
 - 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 认证配置
 

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,19 @@
   ],
   "scripts": {
     "build": "tsup",
+    "check": "pnpm typecheck",
     "typecheck": "tsc --noEmit",
     "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
     "test": "vitest run",
     "test:watch": "vitest",
     "clean": "rimraf dist .turbo",
-    "dev": "pnpm build && node --env-file-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.
@@ -37,7 +39,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. 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.
+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. Clean screenshots, reports, temporary projects, containers and helper processes in finally/teardown, including failure paths. These browser checks do not replace native-shell or miniapp device acceptance.
 
 ## IAM configuration
 

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,7 +19,9 @@
     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('')
@@ -34,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()
     }
   })
@@ -60,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'>
@@ -71,7 +73,7 @@
           {#if store.authConfig && store.error}<Alert variant='error' class='mx-auto max-w-lg'>{store.error}</Alert>{/if}
           <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/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')