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

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

@@ -1,39 +1,32 @@
 # {{fullstack.sharedPackageName}}
 
-Frontend shared package for **{{projectName}}**. Provides:
+Shared mini administration workspace for **{{projectName}}**. Web, Capacitor App and Tauri desktop use the same `AdminWorkspace`, responsive `AppShell`, typed API client and management store.
 
-- `AppShell` — common layout (header / footer / theme + language switchers)
-- `ThemeSwitcher`, `LanguageSwitcher`
-- `themeStore` — daisyUI theme persistence
-- `fetchAppInfo` — typed API client wrapping `@h-ai/api-client`
-- Shared Inlang Paraglide messages compiled from this package's `project.inlang/` + `messages/`
+- 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.
+- `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.
+- Read metadata through the same initialized `managementApi.app.info()` client; inspect `success` before using `data`.
 
-Consumed by `{{projectName}}-web`, `{{projectName}}-app`, `{{projectName}}-desktop`, and the reserved `{{projectName}}-miniapp` guidance.
+All three Vite apps read the workspace root .env. Development and preview servers proxy /api to the local backend when no explicit API base is configured, so browser clients can use a single origin. In deployments, configure PUBLIC_API_BASE or the Web container runtime API origin for the actual service.
 
-## i18n collaboration
+An origin-only API base uses `/api/v1`. For a custom service `http.apiPrefix`, include that path in `PUBLIC_API_BASE` or the runtime API base; the client preserves the configured path and restricts avatar URLs to its matching resource prefix.
 
-- `packages/{{fullstack.sharedPackageName}}/messages/` stores **shared UI copy** used by reusable components such as `AppShell`, `ThemeSwitcher`, and `LanguageSwitcher`.
-- `apps/{{projectName}}-web/messages/`, `apps/{{projectName}}-app/messages/`, and `apps/{{projectName}}-desktop/messages/` store **frontend-specific product copy**.
-- `apps/{{projectName}}-miniapp/messages/` is prepared for mini-app-specific copy even though the mini target is currently a placeholder.
-- Keep `baseLocale` and `locales` aligned across shared and every frontend `project.inlang/settings.json`. The language switcher updates shared and the host app runtime together.
+## Authentication and preferences
 
-Rule of thumb: if a string appears inside reusable shared components, put it here; if it belongs to one product surface, put it in that frontend's `messages/` directory.
+Web and browser previews keep access tokens in memory and refresh tokens in the server's httpOnly Cookie. Requests include credentials; reload restores the session through the encrypted refresh flow. Never store authentication tokens in localStorage.
 
-## Scripts
+Capacitor native uses `createCapacitorTokenStorage()` and the trusted native token channel. Tauri native uses memory token storage and requires a new login after restarting the application. Native builds require a reachable `PUBLIC_API_BASE` in the workspace root `.env`; missing configuration produces a connection configuration error. Both send their frontend `clientName` and `X-HAI-Token-Transport: body`; the service verifies the allowed native origin before returning a refresh token in JSON.
 
-- `pnpm paraglide:compile` — compile messages → `src/lib/paraglide/`
-- `pnpm paraglide:watch` — watch + recompile on message edits
-- `pnpm typecheck`, `pnpm lint`, `pnpm test`
+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.
 
-## Adding a locale
+## i18n and themes
 
-1. Add the locale to `project.inlang/settings.json` `locales` array.
-2. Add the same locale to every enabled frontend `project.inlang/settings.json`.
-3. Create `messages/{locale}.json` in shared and each enabled frontend.
-4. Run root `pnpm i18n:compile` to compile shared and every enabled frontend Paraglide output. You can also run `pnpm paraglide:compile` inside one package when editing that package only.
+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.
 
-## Customizing theme and shell
+The scaffold theme configuration determines the themes compiled into frontend CSS. Personal settings offer only those available themes. Customize the common layout in `src/lib/components/AppShell.svelte`, the management pages in adjacent components, and business behavior in `src/lib/stores/management-store.svelte.ts`.
 
-- Theme names come from the scaffold `fullstack.theme` config and are rendered into each frontend `src/app.css` daisyUI plugin block.
-- `themeStore` persists the selected theme in local storage under `{{projectName}}:theme`.
-- To customize the global chrome, edit `src/lib/components/AppShell.svelte`; to customize a single frontend page, edit that frontend's route and messages.
+## 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.

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

@@ -1,24 +1,87 @@
 {{! @skipIfEmpty }}
 {
   "$schema": "https://inlang.com/schema/inlang-message-format",
-  "app_name": "{{projectName}}",
-  "nav_home": "Home",
-  "nav_settings": "Settings",
-  "settings_title": "Settings",
+  "settings_title": "Personal settings",
   "settings_language": "Language",
   "settings_theme": "Theme",
-  "shell_footer": "Hai Framework · {platform}",
-  "shell_tagline": "Shared shell · Theme · Locale",
-  "home_welcome": "Welcome to {name}",
-  "home_subtitle": "Hai Framework fullstack starter for web / app / desktop / mini collaboration",
-  "home_status_title": "Service status",
   "home_refresh": "Refresh",
   "home_loading": "Loading…",
   "home_error": "Unable to reach the API service",
-  "home_started_at": "Started at: {time}",
-  "home_frontends": "Enabled frontends: {list}",
-  "platform_web": "Web",
-  "platform_app": "App",
-  "platform_desktop": "Desktop",
-  "platform_miniapp": "Mini"
+  "nav_users": "Users",
+  "nav_roles": "Roles",
+  "nav_audit": "Audit logs",
+  "navigation": "Main navigation",
+  "open_menu": "Open navigation",
+  "close_menu": "Close navigation",
+  "logout": "Sign out",
+  "login_title": "Sign in",
+  "login_description": "Sign in to manage your account and workspace",
+  "login_invalid": "The account or password is incorrect. Please try again.",
+  "session_expired": "Your session has expired. Please sign in again.",
+  "saved": "Changes saved",
+  "save": "Save",
+  "edit": "Edit",
+  "delete": "Delete",
+  "cancel": "Cancel",
+  "search": "Search",
+  "details": "Details",
+  "created_at": "Created at",
+  "enabled": "Active",
+  "disabled": "Disabled",
+  "all_statuses": "All statuses",
+  "operation_failed": "The operation could not be completed. Please try again.",
+  "network_error": "Connection failed. Check your network and try again.",
+  "forbidden": "You do not have permission to perform this operation.",
+  "conflict": "This account already exists or the change conflicts with the current data.",
+  "validation_failed": "Check the information entered and try again.",
+  "settings_description": "Manage your profile, preferences and account security",
+  "profile_title": "Profile",
+  "preferences_title": "Preferences",
+  "preferences_description": "Your language and appearance preferences follow your account across devices.",
+  "password_title": "Change password",
+  "password_rules": "Use at least 8 characters. Choose a different password. You will need to sign in again after changing it.",
+  "password_changed": "Password updated. Please sign in with your new password.",
+  "avatar_hint": "Upload a PNG, JPEG or WebP image, up to 512 KB.",
+  "avatar_invalid": "Choose a PNG, JPEG or WebP image no larger than 512 KB.",
+  "avatar_saved": "Avatar updated",
+  "avatar_upload": "Upload avatar",
+  "users_description": "Create accounts, assign roles and manage access",
+  "users_search": "Search username, name or email",
+  "user_account": "Account",
+  "user_username": "Username",
+  "user_display_name": "Display name",
+  "user_email": "Email",
+  "user_password": "Initial password",
+  "user_role": "Role",
+  "user_status": "Status",
+  "user_create": "Add user",
+  "initial_password_rules": "Use at least 8 characters.",
+  "account_enabled": "Allow sign-in",
+  "users_empty": "No matching accounts. Try another search or create a user.",
+  "user_edit": "Edit user",
+  "user_deleted": "User deleted",
+  "user_delete_title": "Delete user",
+  "user_delete_confirm": "Delete {name}? This permanently removes the account and its access.",
+  "roles_description": "Two roles keep access simple. Assign roles from user management.",
+  "role_admin": "Administrator",
+  "role_user": "User",
+  "role_admin_capabilities": "Manage users, role descriptions and audit logs, and update personal settings.",
+  "role_user_capabilities": "Update personal profile, avatar, language, appearance and password.",
+  "role_members": "{count} members",
+  "role_edit": "Edit description",
+  "role_description": "Description",
+  "audit_description": "Review account and administration activity",
+  "audit_actor": "Actor",
+  "audit_action": "Action",
+  "audit_resource": "Resource",
+  "audit_resource_id": "Resource ID",
+  "audit_ip": "IP address",
+  "audit_start": "From",
+  "audit_end": "To",
+  "audit_action_placeholder": "All actions",
+  "audit_resource_placeholder": "All resources",
+  "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."
 }

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

@@ -1,24 +1,87 @@
 {{! @skipIfEmpty }}
 {
   "$schema": "https://inlang.com/schema/inlang-message-format",
-  "app_name": "{{projectName}}",
-  "nav_home": "首页",
-  "nav_settings": "设置",
-  "settings_title": "设置",
+  "settings_title": "个人设置",
   "settings_language": "语言",
   "settings_theme": "主题",
-  "shell_footer": "Hai Framework · {platform}",
-  "shell_tagline": "共享 Shell · 主题 · 语言",
-  "home_welcome": "欢迎使用 {name}",
-  "home_subtitle": "Hai Framework 全栈样板（web / app / desktop / mini 协同）",
-  "home_status_title": "服务状态",
   "home_refresh": "刷新",
   "home_loading": "加载中…",
   "home_error": "无法连接到 API 服务",
-  "home_started_at": "启动时间：{time}",
-  "home_frontends": "已启用前端：{list}",
-  "platform_web": "Web",
-  "platform_app": "App",
-  "platform_desktop": "Desktop",
-  "platform_miniapp": "Mini"
+  "nav_users": "用户管理",
+  "nav_roles": "角色管理",
+  "nav_audit": "审计日志",
+  "navigation": "主导航",
+  "open_menu": "打开导航",
+  "close_menu": "关闭导航",
+  "logout": "退出登录",
+  "login_title": "登录",
+  "login_description": "登录后管理个人账户与工作空间",
+  "login_invalid": "账号或密码不正确，请重试。",
+  "session_expired": "登录已过期，请重新登录。",
+  "saved": "已保存修改",
+  "save": "保存",
+  "edit": "编辑",
+  "delete": "删除",
+  "cancel": "取消",
+  "search": "查询",
+  "details": "详情",
+  "created_at": "创建时间",
+  "enabled": "正常",
+  "disabled": "已禁用",
+  "all_statuses": "全部状态",
+  "operation_failed": "操作未完成，请重试。",
+  "network_error": "连接失败，请检查网络后重试。",
+  "forbidden": "没有执行此操作的权限。",
+  "conflict": "账户已存在，或修改与当前数据冲突。",
+  "validation_failed": "请检查填写的信息后重试。",
+  "settings_description": "管理个人资料、偏好与账户安全",
+  "profile_title": "个人资料",
+  "preferences_title": "偏好设置",
+  "preferences_description": "语言与界面风格保存到个人账户，在不同设备上保持一致。",
+  "password_title": "修改密码",
+  "password_rules": "密码至少 8 个字符，请使用与旧密码不同的新密码。修改后需要重新登录。",
+  "password_changed": "密码已修改，请使用新密码重新登录。",
+  "avatar_hint": "支持 PNG、JPEG 和 WebP 图片，大小不超过 512 KB。",
+  "avatar_invalid": "请选择不超过 512 KB 的 PNG、JPEG 或 WebP 图片。",
+  "avatar_saved": "头像已更新",
+  "avatar_upload": "上传头像",
+  "users_description": "创建账户、分配角色并管理访问权限",
+  "users_search": "搜索用户名、姓名或邮箱",
+  "user_account": "账户",
+  "user_username": "用户名",
+  "user_display_name": "显示名称",
+  "user_email": "邮箱",
+  "user_password": "初始密码",
+  "user_role": "角色",
+  "user_status": "状态",
+  "user_create": "新增用户",
+  "initial_password_rules": "密码至少 8 个字符。",
+  "account_enabled": "启用账户",
+  "users_empty": "没有匹配的账户，请调整查询条件或新增用户。",
+  "user_edit": "编辑用户",
+  "user_deleted": "用户已删除",
+  "user_delete_title": "删除用户",
+  "user_delete_confirm": "确认删除 {name}？此操作将永久删除账户及其访问权限。",
+  "roles_description": "以两种角色简化权限管理，在用户管理中分配角色。",
+  "role_admin": "管理员",
+  "role_user": "普通用户",
+  "role_admin_capabilities": "管理用户、角色说明和审计日志，并修改个人设置。",
+  "role_user_capabilities": "修改个人资料、头像、语言、界面风格与密码。",
+  "role_members": "{count} 名成员",
+  "role_edit": "编辑说明",
+  "role_description": "角色说明",
+  "audit_description": "查看账户与管理操作的审计记录",
+  "audit_actor": "操作用户",
+  "audit_action": "操作",
+  "audit_resource": "资源",
+  "audit_resource_id": "资源 ID",
+  "audit_ip": "IP 地址",
+  "audit_start": "开始日期",
+  "audit_end": "结束日期",
+  "audit_action_placeholder": "全部操作",
+  "audit_resource_placeholder": "全部资源",
+  "audit_system": "系统",
+  "audit_details": "审计日志详情",
+  "audit_date_invalid": "结束日期不能早于开始日期。",
+  "api_not_configured": "尚未配置服务连接，请联系应用管理员。"
 }

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

@@ -1,5 +1,5 @@
 {
-  "engines": { "node": ">=22.12.0" },
+  "engines": { "node": "^22.22.2 || ^24.15.0 || >=26.0.0" },
   "name": "{{fullstack.sharedPackageName}}",
   "type": "module",
   "version": "0.1.0",
@@ -31,10 +31,13 @@
   },
   "dependencies": {
     "@h-ai/api-client": "{{haiPackageSpecifier}}",
+    "@h-ai/core": "{{haiPackageSpecifier}}",
+    "@h-ai/crypto": "{{haiPackageSpecifier}}",
     "@h-ai/ui": "{{haiPackageSpecifier}}",
     "{{fullstack.contractPackageName}}": "workspace:*"
   },
   "devDependencies": {
+    "@sveltejs/vite-plugin-svelte": "{{fullstack.packageSpecifiers.sveltePlugin}}",
     "@inlang/paraglide-js": "{{fullstack.packageSpecifiers.inlangParaglide}}",
     "@inlang/plugin-message-format": "{{fullstack.packageSpecifiers.inlangMessageFormat}}",
     "svelte": "{{fullstack.packageSpecifiers.svelte}}",

package/templates/apps/fullstack/packages/{{projectName}}-shared/src/index.ts.hbs

@@ -1,8 +1,7 @@
 export { default as AppShell } from './lib/components/AppShell.svelte'
-export { default as LanguageSwitcher } from './lib/components/LanguageSwitcher.svelte'
-export { default as ThemeSwitcher } from './lib/components/ThemeSwitcher.svelte'
+export { default as AdminWorkspace } from './lib/components/AdminWorkspace.svelte'
 export { AVAILABLE_THEMES, themeStore } from './lib/stores/theme-store.svelte.js'
-export type { AppInfo, FetchAppInfoOptions } from './lib/api/api-client.js'
-export { fetchAppInfo } from './lib/api/api-client.js'
+export type { AppInfo, ManagementApiOptions } from './lib/api/api-client.js'
+export { initializeManagementApi, managementApi } from './lib/api/api-client.js'
 export * as messages from './lib/paraglide/messages.js'
 export { getLocale, locales, setLocale } from './lib/paraglide/runtime.js'

package/templates/apps/fullstack/packages/{{projectName}}-shared/src/lib/api/api-client.ts.hbs

@@ -1,39 +1,61 @@
+import type { TokenStorage } from '@h-ai/api-client'
 import type { AppInfoOutputData } from '{{fullstack.contractPackageName}}'
-import { apiClient } from '@h-ai/api-client'
+import { apiClient, HaiApiClientError } from '@h-ai/api-client'
+import { err } from '@h-ai/core'
+import { crypto } from '@h-ai/crypto'
 import { {{fullstack.contractExportName}} } from '{{fullstack.contractPackageName}}'
 
 export type AppInfo = AppInfoOutputData
+export const managementApi = apiClient.create({{fullstack.contractExportName}})
 
 const DEFAULT_API_ORIGIN = 'http://127.0.0.1:3000'
 
-export interface FetchAppInfoOptions {
+export interface ManagementApiOptions {
   fetchFn?: typeof fetch
   baseUrl?: string
   clientName?: string
+  tokenStorage?: TokenStorage
+  headers?: Record<string, string>
+  requireApiBase?: boolean
+  onSessionExpired?: () => void
 }
 
-export async function fetchAppInfo(options: FetchAppInfoOptions = {}): Promise<AppInfo> {
-  const fetchFn = options.fetchFn ?? fetch
-  const baseUrl = options.baseUrl ?? resolveDefaultApiOrigin()
-  const clientName = options.clientName ?? '{{projectName}}-shared'
+/** 所有业务请求由 api-client 统一完成 Token 注入、刷新和双向加密。 */
+export async function initializeManagementApi(options: ManagementApiOptions = {}) {
+  if (options.requireApiBase && !options.baseUrl && !resolveRuntimeApiOrigin() && !import.meta.env.PUBLIC_API_BASE)
+    return err(HaiApiClientError.CONFIG_ERROR, 'Native applications require a configured API origin')
+  if (managementApi.isInitialized)
+    await managementApi.close()
+  if (!crypto.isInitialized) {
+    const result = await crypto.init()
+    if (!result.success)
+      return result
+  }
 
-  const client = apiClient.create({{fullstack.contractExportName}})
-  const init = await client.init({
-    baseUrl: normalizeApiBaseUrl(baseUrl),
-    clientName,
-    fetch: fetchFn,
+  return managementApi.init({
+    baseUrl: normalizeApiBaseUrl(options.baseUrl ?? resolveDefaultApiOrigin()),
+    clientName: options.clientName ?? '{{fullstack.sharedPackageName}}',
+    fetch: createCredentialedFetch(options.fetchFn),
+    headers: options.headers,
+    auth: { storage: options.tokenStorage, onRefreshFailed: options.onSessionExpired },
+    transport: { crypto },
   })
-  if (!init.success)
-    throw new Error(init.error?.message ?? 'Failed to initialize API client')
+}
 
+/** 头像仅允许服务端约定资源路径，并统一指向当前可信 API origin。 */
+export function resolveAvatarUrl(value: string | undefined): string | undefined {
+  if (!value)
+    return undefined
   try {
-    const result = await client.app.info()
-    if (!result.success)
-      throw new Error(result.error?.message ?? 'Failed to fetch app info')
-    return result.data
+    const origin = managementApi.config?.baseUrl ?? normalizeApiBaseUrl(resolveDefaultApiOrigin())
+    const parsed = new URL(value, origin)
+    const prefix = `${new URL(origin).pathname.replace(/\/+$/, '')}/assets/avatars/`
+    if (!parsed.pathname.startsWith(prefix) || !/^[\w-]+\/[\w-]+\.(?:png|jpg|webp)$/.test(parsed.pathname.slice(prefix.length)))
+      return undefined
+    return new URL(parsed.pathname, origin).toString()
   }
-  finally {
-    await client.close()
+  catch {
+    return undefined
   }
 }
 
@@ -43,6 +65,14 @@ function resolveDefaultApiOrigin(): string {
     || (typeof globalThis.location === 'undefined' ? DEFAULT_API_ORIGIN : globalThis.location.origin)
 }
 
+/** 跨端浏览器请求携带服务端管理的 httpOnly refresh Cookie。 */
+function createCredentialedFetch(fetchFn: typeof fetch = globalThis.fetch.bind(globalThis)): typeof fetch {
+  return (input, init) => {
+    const request = new Request(input, init)
+    return fetchFn(new Request(request, { credentials: 'include' }))
+  }
+}
+
 function resolveRuntimeApiOrigin(): string | undefined {
   const runtimeConfig = (globalThis as typeof globalThis & {
     __HAI_PUBLIC_CONFIG__?: { apiBase?: string }
@@ -51,12 +81,8 @@ function resolveRuntimeApiOrigin(): string | undefined {
 }
 
 function normalizeApiBaseUrl(value: string): string {
-  const trimmed = trimTrailingSlash(value)
-  return trimmed.endsWith('/api/v1')
-    ? trimmed
-    : `${trimmed}/api/v1`
-}
-
-function trimTrailingSlash(value: string): string {
-  return value.replace(/\/+$/, '')
+  const url = new URL(value.trim())
+  if (url.pathname === '/')
+    url.pathname = '/api/v1'
+  return url.toString().replace(/\/+$/, '')
 }

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

@@ -0,0 +1,73 @@
+<script lang="ts">
+  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'
+  import { LoginForm } from '@h-ai/ui/components/scenes/iam/index'
+  import { onMount } from 'svelte'
+  import * as m from '../paraglide/messages.js'
+  import { ManagementStore } from '../stores/management-store.svelte.js'
+  import AppShell from './AppShell.svelte'
+
+  interface Props {
+    platform: 'web' | 'app' | 'desktop'
+    apiOptions?: ManagementApiOptions
+    onLocaleChange?: (locale: string) => void
+  }
+  const { platform, apiOptions = {}, onLocaleChange }: Props = $props()
+  const store = new ManagementStore()
+  const loginErrors = $derived({ general: store.error })
+  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')
+  })
+  onMount(() => {
+    void store.initialize(apiOptions, onLocaleChange)
+    return () => {
+      void store.close()
+    }
+  })
+  $effect(() => {
+    if (store.info)
+      document.title = store.info.name
+  })
+</script>
+
+{#key store.locale}
+  {#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}
+    <main class="grid min-h-dvh place-items-center bg-base-200/50 px-4 py-10">
+      <section class="w-full max-w-md rounded-2xl border border-base-content/8 bg-base-100 p-7 shadow-xl shadow-base-content/3 sm:p-9" data-testid="login-page">
+        <div class="mb-7 flex items-center gap-3">
+          <span class="grid size-11 place-items-center rounded-xl bg-primary text-primary-content"><span class="icon-[tabler--hexagon-letter-h] size-6"></span></span>
+          <div><h1 class="text-lg font-semibold" data-testid="app-name">{store.info?.name || m.login_title()}</h1><p class="mt-1 text-xs text-base-content/45">{m.login_description()}</p></div>
+        </div>
+        {#if store.notice}<Alert variant="success" class="mb-5" data-testid="notice">{store.notice}</Alert>{/if}
+        {#if !store.info}
+          <Alert variant="error">{store.error || m.home_error()}</Alert>
+          <Button class="mt-5 w-full" variant="primary" onclick={() => void store.initialize(apiOptions, onLocaleChange)}>{m.home_refresh()}</Button>
+        {:else}
+          <LoginForm loading={store.saving} showRememberMe={false} showForgotPassword={false} errors={loginErrors} onsubmit={data => store.login(data)} data-testid="login-form" />
+          <p class="mt-6 text-center text-xs text-base-content/40"><span data-testid="app-version">v{store.info.version}</span> · <span data-testid="app-environment">{store.info.env}</span></p>
+        {/if}
+      </section>
+    </main>
+  {:else}
+    <AppShell {platform} {store}>
+      <div class="space-y-5">
+        {#if store.error}<Alert variant="error" data-testid="error">{store.error}</Alert>{/if}
+        {#if store.notice}<Alert variant="success" data-testid="notice">{store.notice}</Alert>{/if}
+        {#await pageComponent}
+          <div class="space-y-4"><Skeleton variant="title" /><Skeleton count={3} /></div>
+        {:then { default: Page }}
+          <Page {store} />
+        {/await}
+      </div>
+    </AppShell>
+  {/if}
+{/key}

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

@@ -1,60 +1,70 @@
 <script lang="ts">
   import type { Snippet } from 'svelte'
+  import type { ManagementPage, ManagementStore } from '../stores/management-store.svelte.js'
+  import { Avatar, Badge, BareButton, Button } from '@h-ai/ui/components/primitives/index'
   import * as m from '../paraglide/messages.js'
-  import LanguageSwitcher from './LanguageSwitcher.svelte'
-  import ThemeSwitcher from './ThemeSwitcher.svelte'
 
   interface Props {
-    /** 当前运行的前端平台 */
     platform: 'web' | 'app' | 'desktop' | 'miniapp'
-    /** 宿主应用本地 Paraglide runtime 的同步回调 */
-    onLocaleChange?: (locale: string) => void
-    /** 主内容 */
+    store: ManagementStore
     children: Snippet
   }
+  const { platform, store, children }: Props = $props()
+  let menuOpen = $state(false)
+  const items = $derived([
+    ...(store.isAdmin
+? [
+      { id: 'users' as const, label: m.nav_users(), icon: 'icon-[tabler--users]' },
+      { id: 'roles' as const, label: m.nav_roles(), icon: 'icon-[tabler--shield-lock]' },
+      { id: 'audit' as const, label: m.nav_audit(), icon: 'icon-[tabler--file-text]' },
+    ]
+: []),
+    { 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 { platform, onLocaleChange, children }: Props = $props()
-
-  function getPlatformLabel(value: Props['platform']): string {
-    if (value === 'web')
-      return m.platform_web()
-    if (value === 'app')
-      return m.platform_app()
-    if (value === 'desktop')
-      return m.platform_desktop()
-    return m.platform_miniapp()
+  function navigate(page: ManagementPage) {
+    menuOpen = false
+    void store.navigate(page)
   }
-
-  const platformLabel = $derived(getPlatformLabel(platform))
 </script>
 
-<div class="min-h-screen flex flex-col overflow-hidden bg-base-100 text-base-content">
-  <div class="pointer-events-none fixed inset-0 -z-10 bg-[radial-gradient(circle_at_top_left,var(--color-primary)_0,transparent_34%),radial-gradient(circle_at_bottom_right,var(--color-secondary)_0,transparent_30%)] opacity-10"></div>
-
-  <header class="navbar sticky top-0 z-20 border-b border-base-300/70 bg-base-100/80 px-4 shadow-sm backdrop-blur-xl lg:px-8">
-    <div class="flex-1 flex items-center gap-3">
-      <div class="grid size-10 place-items-center rounded-2xl bg-primary text-primary-content shadow-lg shadow-primary/20">
-        <span class="icon-[tabler--sparkles] size-5"></span>
+<div class="flex min-h-dvh bg-base-200/50 text-base-content" class:hai-safe-area={platform === 'app'}>
+  {#if menuOpen}
+    <BareButton class="fixed inset-0 z-30 bg-black/30 lg:hidden" ariaLabel={m.close_menu()} onclick={() => { menuOpen = false }} />
+  {/if}
+  <aside class="fixed inset-y-0 left-0 z-40 flex w-60 flex-col border-r border-base-content/8 bg-base-100 transition-transform duration-200 lg:sticky lg:top-0 lg:h-dvh lg:translate-x-0 {menuOpen ? 'translate-x-0' : '-translate-x-full'}">
+    <div class="flex h-16 items-center gap-3 border-b border-base-content/8 px-5">
+      <span class="grid size-8 shrink-0 place-items-center rounded-lg bg-primary text-primary-content"><span class="icon-[tabler--hexagon-letter-h] size-5"></span></span>
+      <span class="truncate text-sm font-semibold" data-testid="app-name">{store.info?.name}</span>
+    </div>
+    <nav class="flex-1 space-y-1 p-3" aria-label={m.navigation()}>
+      {#each items as item (item.id)}
+        <BareButton class="flex w-full items-center gap-3 rounded-lg px-3 py-2.5 text-left text-sm transition-colors {store.page === item.id ? 'bg-primary/10 font-medium text-primary' : 'text-base-content/60 hover:bg-base-content/4'}" onclick={() => navigate(item.id)} data-testid="nav-{item.id}">
+          <span class="{item.icon} size-4.5"></span>{item.label}
+        </BareButton>
+      {/each}
+    </nav>
+    <div class="border-t border-base-content/8 p-4 text-xs text-base-content/40"><span data-testid="app-version">v{store.info?.version}</span></div>
+  </aside>
+  <div class="flex min-w-0 flex-1 flex-col">
+    <header class="sticky top-0 z-20 flex h-16 items-center justify-between gap-2 border-b border-base-content/8 bg-base-100/95 px-3 backdrop-blur sm:px-4 lg:px-6">
+      <div class="flex min-w-0 flex-1 items-center gap-2 sm:gap-3">
+        <BareButton class="rounded-lg p-2 hover:bg-base-content/5 lg:hidden" ariaLabel={m.open_menu()} onclick={() => { menuOpen = !menuOpen }} data-testid="mobile-menu"><span class="icon-[tabler--menu-2] size-5"></span></BareButton>
+        <span class="truncate text-sm font-medium">{title}</span>
       </div>
-      <div>
-        <span class="block text-lg font-semibold leading-tight">{m.app_name()}</span>
-        <span class="text-xs text-base-content/55">{m.shell_tagline()}</span>
+      <div class="flex shrink-0 items-center gap-1.5 sm:gap-3">
+        <Badge variant="ghost" size="sm" data-testid="app-environment">{store.info?.env}</Badge>
+        {#if store.user}
+          <BareButton class="flex items-center gap-2 rounded-lg px-1 py-1 hover:bg-base-content/5 sm:px-2" ariaLabel={m.settings_title()} onclick={() => navigate('settings')}>
+            <Avatar name={store.user.displayName || store.user.username} src={store.user.avatarUrl} size="sm" />
+            <span class="hidden max-w-36 truncate text-sm sm:block">{store.user.displayName || store.user.username}</span>
+          </BareButton>
+        {/if}
+        <Button variant="ghost" size="sm" loading={store.saving} onclick={() => void store.logout()} data-testid="logout">{m.logout()}</Button>
       </div>
-      <span class="badge badge-primary badge-outline ml-1 hidden sm:inline-flex">{platformLabel}</span>
-    </div>
-    <div class="flex-none flex items-end gap-2">
-      <ThemeSwitcher />
-      <LanguageSwitcher {onLocaleChange} />
-    </div>
-  </header>
-
-  <main class="flex-1 px-4 py-8 lg:px-8 lg:py-10">
-    <div class="mx-auto w-full max-w-6xl">
-      {@render children()}
-    </div>
-  </main>
-
-  <footer class="footer footer-center border-t border-base-300/70 bg-base-100/70 p-4 text-sm text-base-content/60 backdrop-blur-xl">
-    <span>{m.shell_footer({ platform: platformLabel })}</span>
-  </footer>
+    </header>
+    <main class="mx-auto w-full max-w-7xl flex-1 p-4 pb-8 sm:p-6 lg:p-8">{@render children()}</main>
+    <footer class="border-t border-base-content/8 px-6 py-3 text-center text-xs text-base-content/35">{store.info?.name} · v{store.info?.version}</footer>
+  </div>
 </div>