@h-ai/cli 0.1.0-alpha.56 → 0.1.0-alpha.58

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

@@ -1,32 +1,58 @@
 {{! @skipIfEmpty }}
 {{#if fullstack.frontends.web}}
+import process from 'node:process'
+import { fileURLToPath } from 'node:url'
 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'
 
-export default defineConfig({
-  plugins: [
-    svelte(),
-    paraglideVitePlugin({
-      project: './project.inlang',
-      outdir: './src/lib/paraglide',
-      strategy: ['cookie', 'baseLocale'],
-    }),
-    tailwindcss(),
-  ],
-  optimizeDeps: {
-    exclude: [...haiOptimizeExclude],
-    include: [...haiPrebundledDeps],
-  },
-  envPrefix: ['VITE_', 'PUBLIC_'],
-  ssr: {
-    noExternal: [/@h-ai\//, /{{fullstack.sharedPackageName}}/],
-  },
-  test: {
-    environment: 'node',
-    include: ['tests/**/*.test.ts'],
-  },
+const envDir = fileURLToPath(new URL('../../', import.meta.url))
+
+export default defineConfig(({ mode }) => {
+  const env = loadEnv(mode, envDir, 'PUBLIC_')
+  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,
+    server: { proxy },
+    preview: { proxy },
+    build: {
+      rolldownOptions: {
+        output: {
+          codeSplitting: {
+            groups: [
+              { name: 'vendor-ui', test: /node_modules\/(?:@h-ai\/ui|bits-ui|svelte)\// },
+              { name: 'vendor-crypto', test: /node_modules\/(?:@h-ai\/(?:core|crypto)|sm-crypto(?:-v2)?)\// },
+              { name: 'vendor-api', test: /node_modules\/(?:@orpc\/|zod\/)/ },
+            ],
+          },
+        },
+      },
+    },
+    plugins: [
+      svelte(),
+      paraglideVitePlugin({
+        project: './project.inlang',
+        outdir: './src/lib/paraglide',
+        strategy: ['cookie', 'baseLocale'],
+      }),
+      tailwindcss(),
+    ],
+    optimizeDeps: {
+      exclude: [...haiOptimizeExclude],
+      include: [...haiPrebundledDeps],
+    },
+    envPrefix: ['VITE_', 'PUBLIC_'],
+    ssr: {
+      noExternal: [/@h-ai\//, /{{fullstack.sharedPackageName}}/],
+    },
+    test: {
+      environment: 'node',
+      include: ['tests/**/*.test.ts'],
+    },
+  }
 })
 {{/if}}

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

@@ -1,33 +1,223 @@
-import { expect, test } from '@playwright/test'
+import type { Page } from '@playwright/test'
+import { Buffer } from 'node:buffer'
+import { randomUUID } from 'node:crypto'
+import process from 'node:process'
 import { apiContract } from '@h-ai/api-contract'
+import { expect, test } from '@playwright/test'
 import { {{fullstack.contractExportName}} } from '{{fullstack.contractPackageName}}'
 
-const DEFAULT_SERVICE_BASE_URL = 'http://127.0.0.1:3000'
-const apiBaseUrl = process.env.SERVICE_BASE_URL || DEFAULT_SERVICE_BASE_URL
+const apiBaseUrl = process.env.SERVICE_BASE_URL || 'http://127.0.0.1:3000'
 const apiPrefix = '/api/v1'
+const adminPassword = process.env.E2E_ADMIN_PASSWORD || 'Scaffold-test-Admin123!'
+const configuredName = process.env.HAI_CORE_NAME || 'Configured scaffold'
+const configuredVersion = process.env.HAI_CORE_VERSION || '9.8.7'
+const configuredEnv = process.env.HAI_CORE_ENV || 'test'
+
+// 测试专用的一像素 PNG；上传仍使用完整前后端加密链路。
+const avatar = Buffer.from('iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+aSxkAAAAASUVORK5CYII=', 'base64')
+
+async function login(page: Page, username: string, password: string) {
+  await expect(page.getByTestId('login-form')).toBeVisible()
+  await page.locator('#login-username').fill(username)
+  await page.getByTestId('login-form').locator('input[type="password"]').fill(password)
+  await page.getByTestId('login-form').getByRole('button', { name: /登录|Sign in|Login|Log in/i }).click()
+}
+
+async function userEditor(page: Page, username: string) {
+  await page.getByTestId('users-search').locator('input').fill(username)
+  await page.getByTestId('users-page').getByRole('button', { name: /查询|Search/ }).click()
+  const row = page.getByRole('row').filter({ hasText: username })
+  await expect(row).toBeVisible()
+  await row.getByRole('button', { name: /编辑|Edit/, exact: true }).click()
+  return row
+}
 
 test('service health endpoint is ready', async ({ request }) => {
   const response = await request.get(`${apiBaseUrl}/health`)
-  expect(response.ok()).toBe(true)
   await expect(response).toBeOK()
 })
 
-test('service echo endpoint returns HaiResult', async ({ request }) => {
-  const response = await request.post(`${apiBaseUrl}${apiPrefix}${apiContract.pathOf({{fullstack.contractExportName}}.app.echo)}`, {
-    data: { message: 'hello e2e' },
-  })
-  expect(response.ok()).toBe(true)
-
-  const body = await response.json()
-  expect(body.success).toBe(true)
-  expect(body.data.message).toBe('hello e2e')
-  expect(body.data.requestId).toBeTruthy()
+test('service rejects plaintext business requests', async ({ request }) => {
+  const response = await request.post(`${apiBaseUrl}${apiPrefix}${apiContract.pathOf({{fullstack.contractExportName}}.app.echo)}`, { data: { message: 'hello e2e' } })
+  expect(response.status()).toBe(400)
 })
+
 {{#if fullstack.e2eFrontend}}
 
-test('frontend loads service status from page', async ({ page }) => {
+test('frontend displays configured core metadata and restores the administrator session', async ({ page }) => {
   await page.goto('/')
-  await expect(page.getByRole('heading', { level: 1 })).toBeVisible()
-  await expect(page.getByTestId('service-status')).toContainText('{{fullstack.servPackageName}}')
+  await expect(page.getByTestId('app-name')).toHaveText(configuredName)
+  await expect(page).toHaveTitle(configuredName)
+  await expect(page.getByTestId('app-version')).toHaveText(`v${configuredVersion}`)
+  await expect(page.getByTestId('app-environment')).toHaveText(configuredEnv)
+  await login(page, 'admin', adminPassword)
+  await expect(page.getByTestId('users-page')).toBeVisible()
+  await page.reload()
+  await expect(page.getByTestId('users-page')).toBeVisible()
+  await expect(page.getByTestId('nav-roles')).toBeVisible()
+  await expect(page.getByTestId('nav-audit')).toBeVisible()
+  await page.getByTestId('logout').click()
+  await expect(page.getByTestId('login-form')).toBeVisible()
+})
+
+test('audit filters align and fit desktop, tablet and narrow mobile screens', async ({ page }) => {
+  await page.goto('/')
+  await login(page, 'admin', adminPassword)
+  await page.getByTestId('nav-audit').click()
+  await expect(page.getByTestId('audit-page')).toBeVisible()
+  for (const width of [1440, 960, 390, 320]) {
+    await page.setViewportSize({ width, height: 900 })
+    const controls = await page.getByTestId('audit-page').locator('form').evaluate(form => [
+      form.querySelector('#audit-action')?.parentElement,
+      form.querySelector('#audit-resource')?.parentElement,
+      form.querySelector('#audit-start'),
+      form.querySelector('#audit-end'),
+      form.querySelector('button[type="submit"]'),
+    ].map((element) => {
+      if (!element)
+        throw new Error('Audit filter control is missing')
+      const rect = element.getBoundingClientRect()
+      return { top: rect.top, bottom: rect.bottom, height: rect.height }
+    }))
+    for (const control of controls)
+      expect(control.height).toBeCloseTo(40, 0)
+    if (width >= 1280) {
+      expect(Math.max(...controls.map(control => control.top)) - Math.min(...controls.map(control => control.top))).toBeLessThan(1)
+      expect(Math.max(...controls.map(control => control.bottom)) - Math.min(...controls.map(control => control.bottom))).toBeLessThan(1)
+    }
+    else if (width >= 640) {
+      expect(controls[0]!.top).toBeCloseTo(controls[1]!.top, 0)
+      expect(controls[2]!.top).toBeCloseTo(controls[3]!.top, 0)
+    }
+    expect(await page.evaluate(() => document.documentElement.scrollWidth <= innerWidth)).toBe(true)
+  }
+})
+
+test('administrator and user complete account, avatar, preference, password and audit workflows', async ({ page, browser }) => {
+  test.setTimeout(120_000)
+  const username = `member-${randomUUID().slice(0, 8)}`
+  const password = 'User-test-Pass123!'
+  const newPassword = 'Changed-test-Pass123!'
+  const encryptedRequests: string[] = []
+  const encryptedResponses: string[] = []
+  page.on('request', (request) => {
+    if (request.url().includes(`${apiPrefix}/`) && !request.url().includes('/_hai/') && request.postData()) {
+      expect(request.headers()['x-encrypted']).toBe('true')
+      expect(request.postData()).not.toContain('"password"')
+      expect(request.postData()).not.toContain(adminPassword)
+      encryptedRequests.push(request.url())
+    }
+  })
+  page.on('response', (response) => {
+    if (response.request().method() !== 'OPTIONS' && response.url().includes(`${apiPrefix}/`) && !response.url().includes('/_hai/') && !response.url().includes('/assets/')) {
+      expect(response.headers()['x-encrypted']).toBe('true')
+      encryptedResponses.push(response.url())
+    }
+  })
+  await page.goto('/')
+  await login(page, 'admin', adminPassword)
+  await expect(page.getByTestId('users-page')).toBeVisible()
+  await page.getByTestId('create-user').click()
+  await expect(page.getByRole('dialog', { name: /新增用户|New user|Create user|Add user/ })).toBeVisible()
+  await expect(page.getByTestId('user-username').locator('input')).toBeFocused()
+  await page.getByTestId('user-username').locator('input').fill(username)
+  await page.getByTestId('user-display-name').locator('input').fill('Test member')
+  await page.getByTestId('user-email').locator('input').fill(`${username}@example.com`)
+  await page.getByTestId('user-password').locator('input').fill(password)
+  await page.getByTestId('user-save').click()
+  await expect(page.getByTestId('user-editor')).not.toBeVisible()
+  const userRow = page.getByRole('row').filter({ hasText: username })
+  await expect(userRow).toBeVisible()
+  await userRow.getByTestId('user-avatar-input').setInputFiles({ name: 'avatar.png', mimeType: 'image/png', buffer: avatar })
+  await expect(userRow.locator('img')).toHaveAttribute('src', /\/assets\/avatars\//)
+  await expect.poll(() => userRow.locator('img').evaluate((image: HTMLImageElement) => image.complete && image.naturalWidth > 0)).toBe(true)
+  await page.getByTestId('nav-roles').click()
+  await expect(page.getByTestId('roles-page')).toBeVisible()
+  await page.getByTestId('roles-page').getByRole('button', { name: /编辑说明|Edit description/ }).first().click()
+  await page.getByTestId('role-description').locator('textarea').fill('Workspace administration')
+  await page.getByRole('dialog').getByRole('button', { name: /保存|Save/, exact: true }).focus()
+  await page.keyboard.press('Tab')
+  await expect(page.getByRole('dialog').getByRole('button', { name: /关闭|Close/, exact: true })).toBeFocused()
+  await page.keyboard.press('Shift+Tab')
+  await expect(page.getByRole('dialog').getByRole('button', { name: /保存|Save/, exact: true })).toBeFocused()
+  await page.getByRole('dialog').getByRole('button', { name: /保存|Save/, exact: true }).click()
+  await expect(page.getByTestId('roles-page')).toContainText('Workspace administration')
+
+  const userContext = await browser.newContext()
+  const userPage = await userContext.newPage()
+  try {
+    await userPage.goto('/')
+    await login(userPage, username, password)
+    await expect(userPage.getByTestId('settings-page')).toBeVisible()
+    await expect(userPage.getByTestId('nav-users')).toHaveCount(0)
+    await expect(userPage.getByTestId('nav-roles')).toHaveCount(0)
+    await expect(userPage.getByTestId('nav-audit')).toHaveCount(0)
+    await userPage.getByTestId('profile-form').locator('input[name="displayName"]').fill('Updated member')
+    await userPage.getByTestId('profile-form').locator('input[name="email"]').fill('')
+    await userPage.getByTestId('profile-form').getByRole('button', { name: /保存|Save/, exact: true }).click()
+    await expect(userPage.getByTestId('notice')).toBeVisible()
+    await userPage.getByTestId('profile-form').locator('input[type="file"]').setInputFiles({ name: 'personal.png', mimeType: 'image/png', buffer: avatar })
+    await expect(userPage.getByTestId('notice')).toHaveText(/头像已更新|Avatar updated/)
+    await userPage.getByTestId('profile-language').click()
+    await userPage.getByRole('option', { name: 'English', exact: true }).click()
+    await expect(userPage.getByTestId('nav-settings')).toHaveText('Personal settings')
+    await expect(userPage.locator('html')).toHaveAttribute('lang', 'en-US')
+    const themes = [{{#each fullstack.theme.themes}}'{{this}}'{{#unless @last}}, {{/unless}}{{/each}}]
+    const selectedTheme = themes.find(theme => theme !== '{{fullstack.theme.defaultTheme}}') ?? themes[0]
+    await userPage.getByTestId('profile-theme').click()
+    await userPage.getByRole('option').nth(themes.indexOf(selectedTheme)).click()
+    await expect(userPage.locator('html')).toHaveAttribute('data-theme', selectedTheme)
+    await userPage.reload()
+    await expect(userPage.getByTestId('settings-page')).toBeVisible()
+    await expect(userPage.getByTestId('nav-settings')).toHaveText('Personal settings')
+    await expect(userPage.locator('html')).toHaveAttribute('data-theme', selectedTheme)
+    await expect(userPage.getByTestId('profile-form').locator('input[name="displayName"]')).toHaveValue('Updated member')
+    await expect(userPage.getByTestId('profile-form').locator('input[name="email"]')).toHaveValue('')
+    await expect.poll(() => userPage.getByTestId('profile-form').locator('img').evaluate((image: HTMLImageElement) => image.complete && image.naturalWidth > 0)).toBe(true)
+    await userPage.setViewportSize({ width: 390, height: 844 })
+    await expect.poll(() => userPage.evaluate(() => document.documentElement.scrollWidth <= window.innerWidth)).toBe(true)
+    await userPage.getByTestId('mobile-menu').click()
+    await expect(userPage.getByTestId('nav-settings')).toBeVisible()
+    await userPage.getByTestId('nav-settings').click()
+    const passwordInputs = userPage.getByTestId('password-form').locator('input[type="password"]')
+    await passwordInputs.nth(0).fill(password)
+    await passwordInputs.nth(1).fill(password)
+    await passwordInputs.nth(2).fill(password)
+    await userPage.getByTestId('password-form').getByRole('button', { name: /Change password/i }).click()
+    await expect(userPage.getByTestId('settings-page')).toBeVisible()
+    await expect(userPage.getByTestId('error')).toContainText(/检查|check/i)
+    await passwordInputs.nth(1).fill(newPassword)
+    await passwordInputs.nth(2).fill(newPassword)
+    await userPage.getByTestId('password-form').getByRole('button', { name: /Change password/i }).click()
+    await expect(userPage.getByTestId('login-form')).toBeVisible()
+    await login(userPage, username, password)
+    await expect(userPage.getByTestId('login-form')).toContainText(/不正确|incorrect/)
+    await login(userPage, username, newPassword)
+    await expect(userPage.getByTestId('settings-page')).toBeVisible()
+
+    await page.getByTestId('nav-users').click()
+    await userEditor(page, username)
+    await page.getByTestId('user-editor').locator('input[type="checkbox"]').uncheck()
+    await page.getByTestId('user-save').click()
+    await expect(page.getByTestId('user-editor')).not.toBeVisible()
+    await userPage.getByTestId('profile-form').getByRole('button', { name: 'Save', exact: true }).click()
+    await expect(userPage.getByTestId('login-form')).toBeVisible()
+    await expect(userPage.getByTestId('login-form')).toContainText(/expired|过期/)
+  }
+  finally {
+    await userContext.close()
+  }
+
+  await page.getByRole('row').filter({ hasText: username }).getByRole('button', { name: /删除|Delete/, exact: true }).click()
+  await page.getByTestId('confirm-delete-user').click()
+  await expect(page.getByRole('row').filter({ hasText: username })).toHaveCount(0)
+  await page.getByTestId('nav-audit').click()
+  await page.getByTestId('audit-resource').locator('input').fill('users')
+  await page.getByTestId('audit-page').getByRole('button', { name: /查询|Search/ }).click()
+  await expect(page.getByTestId('audit-page')).toContainText('delete')
+  await page.getByTestId('audit-page').getByRole('button', { name: /详情|Details/ }).first().click()
+  await expect(page.getByRole('dialog')).toContainText(/users/)
+  expect(encryptedRequests.length).toBeGreaterThan(5)
+  expect(encryptedResponses.length).toBeGreaterThan(5)
 })
 {{/if}}

package/templates/apps/fullstack/{eslint.config.js → eslint.config.js.hbs}

@@ -1,6 +1,9 @@
-import antfu from '@antfu/eslint-config'
+import antfu, { GLOB_SRC } from '@antfu/eslint-config'
+import { haiQualityConfig } from './eslint-rules.js'
 
 export default antfu({
+  // unused-imports 使用 TS 规则，JS 同样使用 TS parser 以保持 scope 契约一致。
+  typescript: { files: [GLOB_SRC] },
   formatters: true,
   ignores: [
     '**/build/**',
@@ -9,6 +12,7 @@ export default antfu({
     '**/project.inlang/**',
     '**/*.d.ts',
     '**/.agents/**',
+    '**/.claude/**',
     '**/.github/**',
     '**/AGENTS.md',
     '**/CLAUDE.md',
@@ -17,13 +21,7 @@ export default antfu({
     '**/package.json',
   ],
   svelte: true,
-}, {
-  files: ['**/*.ts', '**/*.svelte'],
-  rules: {
-    'no-console': 'error',
-    'ts/no-explicit-any': 'error',
-  },
-}, {
+}, haiQualityConfig, {
   files: ['**/*.svelte'],
   rules: {
     'svelte/html-quotes': 'off',

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

@@ -1,10 +1,10 @@
 {
-  "engines": { "node": ">=22.12.0" },
+  "engines": { "node": "^22.22.2 || ^24.15.0 || >=26.0.0" },
   "name": "{{projectName}}",
   "type": "module",
   "version": "0.1.0",
   "private": true,
-  "packageManager": "pnpm@9.15.0",
+  "packageManager": "pnpm@12.11.2",
   "description": "Full-stack hai workspace with separated contract, service and frontends.",
   "scripts": {
     "i18n:compile": "pnpm --filter {{fullstack.sharedPackageName}} paraglide:compile{{#each fullstack.frontendApps}} && pnpm --filter {{packageName}} paraglide:compile{{/each}}",
@@ -21,7 +21,7 @@
     "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",
     "typecheck": "pnpm --filter {{fullstack.contractPackageName}} build && pnpm i18n:compile && pnpm -r --if-present typecheck",
-    "lint": "pnpm -r --if-present lint",
+    "lint": "eslint *.js *.ts e2e && pnpm -r --if-present lint",
     "test": "pnpm --filter {{fullstack.contractPackageName}} build && pnpm i18n:compile && pnpm -r --if-present test",
     "test:e2e": "pnpm build && playwright test",
     "clean": "pnpm -r --if-present clean && rimraf node_modules .turbo"

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

@@ -6,10 +6,12 @@
 
 - `src/app-schemas.ts`：跨接口、跨层复用的输入/数据 Schema 与类型。
 - `src/app-contract.ts`：app 领域 contract；每个业务 path 直接写在对应接口定义中。
+- `src/admin-schemas.ts` / `src/admin-contract.ts`：管理员用户、固定角色、分页审计、个人设置、加密 JSON 头像上传 Schema/类型/路由；认证复用框架的 IAM auth contract，未开放自助注册和其它认证方式。
 - `src/{{projectName}}-contract.ts`：工程级 contract，供 `@h-ai/serv` 与 `@h-ai/api-client` 共用。
 
 只使用一次的输出 Schema 直接内联到 `.output(...)`；同一 contract 文件内重复使用时才保留私有常量。
 API 前缀、健康检查与跨端 Header 等传输配置位于 serv 包的 `config/_serv.yml`。
+`SUPPORTED_LOCALES` 为生成时实际编译的语言列表；`app.info` 中名称、版本、环境、默认语言来自后端 core 配置。更新公开契约时同时更新 serv、shared typed API client、各端 UI 与测试。
 
 ## 开发
 

package/templates/apps/fullstack/packages/{{projectName}}-contract/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.contractPackageName}}",
   "type": "module",
   "version": "0.1.0",

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

@@ -0,0 +1,66 @@
+import { apiContract } from '@h-ai/api-contract'
+import { z } from 'zod'
+import {
+  AdminAuditInputSchema,
+  AdminAuditSchema,
+  AdminCreateUserSchema,
+  AdminRoleSchema,
+  AdminUpdateUserSchema,
+  AdminUserSchema,
+  AdminUsersInputSchema,
+  AdminUsersSchema,
+  AvatarOutputSchema,
+  AvatarUploadSchema,
+  ProfileUpdateSchema,
+} from './admin-schemas.js'
+
+/** mini 管理业务路径统一定义；仅开放两种固定角色。 */
+export const adminContract = {
+  users: {
+    list: apiContract.route({ method: 'POST', path: '/admin/users/list', tags: ['admin'] })
+      .input(AdminUsersInputSchema)
+      .output(apiContract.haiResultSchema(AdminUsersSchema)),
+    create: apiContract.route({ method: 'POST', path: '/admin/users/create', tags: ['admin'] })
+      .input(AdminCreateUserSchema)
+      .output(apiContract.haiResultSchema(AdminUserSchema)),
+    update: apiContract.route({ method: 'POST', path: '/admin/users/update', tags: ['admin'] })
+      .input(AdminUpdateUserSchema)
+      .output(apiContract.haiResultSchema(AdminUserSchema)),
+    delete: apiContract.route({ method: 'POST', path: '/admin/users/delete', tags: ['admin'] })
+      .input(z.object({ id: z.string().min(1) }).strict())
+      .output(apiContract.haiResultSchema(z.object({ deleted: z.literal(true) }))),
+    avatar: apiContract.route({ method: 'POST', path: '/admin/users/avatar', tags: ['admin'] })
+      .input(AvatarUploadSchema.extend({ id: z.string().min(1) }))
+      .output(apiContract.haiResultSchema(AvatarOutputSchema)),
+  },
+  roles: {
+    list: apiContract.route({ method: 'POST', path: '/admin/roles/list', tags: ['admin'] })
+      .output(apiContract.haiResultSchema(z.object({ items: z.array(AdminRoleSchema) }))),
+    update: apiContract.route({ method: 'POST', path: '/admin/roles/update', tags: ['admin'] })
+      .input(z.object({ id: z.string().min(1), description: z.string().max(300) }).strict())
+      .output(apiContract.haiResultSchema(AdminRoleSchema)),
+  },
+  audit: {
+    list: apiContract.route({ method: 'POST', path: '/admin/audit/list', tags: ['admin'] })
+      .input(AdminAuditInputSchema)
+      .output(apiContract.haiResultSchema(AdminAuditSchema)),
+  },
+}
+
+export const profileContract = {
+  update: apiContract.route({ method: 'POST', path: '/profile/update', tags: ['profile'] })
+    .input(ProfileUpdateSchema)
+    .output(apiContract.haiResultSchema(AdminUserSchema)),
+  avatar: apiContract.route({ method: 'POST', path: '/profile/avatar', tags: ['profile'] })
+    .input(AvatarUploadSchema)
+    .output(apiContract.haiResultSchema(AvatarOutputSchema)),
+}
+
+/** 复用框架认证契约，避免额外开放自助注册和未配置的认证方式。 */
+export const authContract = {
+  login: apiContract.iam.auth.login,
+  logout: apiContract.iam.auth.logout,
+  currentUser: apiContract.iam.auth.currentUser,
+  refresh: apiContract.iam.auth.refresh,
+  changePassword: apiContract.iam.auth.changePassword,
+}

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

@@ -0,0 +1,96 @@
+import { z } from 'zod'
+
+export const AdminRoleCodeSchema = z.enum(['admin', 'user'])
+export const AdminPageInputSchema = z.object({
+  page: z.number().int().min(1).default(1),
+  pageSize: z.number().int().min(1).max(100).default(20),
+})
+export const AdminUserSchema = z.object({
+  id: z.string(),
+  username: z.string(),
+  email: z.string().optional(),
+  displayName: z.string().optional(),
+  avatarUrl: z.string().optional(),
+  enabled: z.boolean(),
+  roles: z.array(AdminRoleCodeSchema),
+  createdAt: z.string().datetime(),
+  updatedAt: z.string().datetime(),
+})
+export const AdminUsersInputSchema = AdminPageInputSchema.extend({
+  search: z.string().max(100).optional(),
+  enabled: z.boolean().optional(),
+})
+export const AdminUsersSchema = z.object({
+  items: z.array(AdminUserSchema),
+  total: z.number(),
+  page: z.number(),
+  pageSize: z.number(),
+})
+export const AdminCreateUserSchema = z.object({
+  username: z.string().min(3).max(64).regex(/^[\w-]+$/),
+  password: z.string().min(8).max(128),
+  email: z.email().optional(),
+  displayName: z.string().max(100).optional(),
+  role: AdminRoleCodeSchema.default('user'),
+  enabled: z.boolean().default(true),
+}).strict()
+export const AdminUpdateUserSchema = z.object({
+  id: z.string().min(1),
+  email: z.union([z.email(), z.literal('')]).optional(),
+  displayName: z.string().max(100).optional(),
+  enabled: z.boolean().optional(),
+  role: AdminRoleCodeSchema.optional(),
+}).strict()
+export const AdminRoleSchema = z.object({
+  id: z.string(),
+  code: AdminRoleCodeSchema,
+  name: z.string(),
+  description: z.string().optional(),
+  userCount: z.number(),
+})
+export const AdminAuditInputSchema = AdminPageInputSchema.extend({
+  userId: z.string().max(100).optional(),
+  action: z.string().max(50).optional(),
+  resource: z.string().max(50).optional(),
+  startDate: z.string().datetime().optional(),
+  endDate: z.string().datetime().optional(),
+})
+export const AdminAuditLogSchema = z.object({
+  id: z.string(),
+  userId: z.string().nullable(),
+  username: z.string().nullable(),
+  action: z.string(),
+  resource: z.string(),
+  resourceId: z.string().nullable(),
+  details: z.string().nullable(),
+  ipAddress: z.string().nullable(),
+  userAgent: z.string().nullable(),
+  createdAt: z.string().datetime(),
+})
+export const AdminAuditSchema = z.object({
+  items: z.array(AdminAuditLogSchema),
+  total: z.number(),
+  page: z.number(),
+  pageSize: z.number(),
+})
+export const ProfileUpdateSchema = z.object({
+  displayName: z.string().max(100).optional(),
+  email: z.union([z.email(), z.literal('')]).optional(),
+  locale: z.enum(['zh-CN', 'en-US']).optional(),
+  theme: z.string().min(1).max(40).regex(/^[\w-]+$/).optional(),
+}).strict()
+/** 512 KiB 头像以 JSON 传输，上传及响应均经过统一加密。 */
+export const AvatarUploadSchema = z.object({
+  contentType: z.enum(['image/png', 'image/jpeg', 'image/webp']),
+  base64: z.string().min(1).max(699052).regex(/^[A-Z\d+/]+={0,2}$/i),
+}).strict()
+export const AvatarOutputSchema = z.object({ avatarUrl: z.string().describe('Generated relative asset path') })
+
+export type AdminUser = z.infer<typeof AdminUserSchema>
+export type AdminRole = z.infer<typeof AdminRoleSchema>
+export type AdminRoleCode = z.infer<typeof AdminRoleCodeSchema>
+export type AdminAuditLog = z.infer<typeof AdminAuditLogSchema>
+export type AdminCreateUser = z.infer<typeof AdminCreateUserSchema>
+export type AdminUpdateUser = z.infer<typeof AdminUpdateUserSchema>
+export type ProfileUpdate = z.infer<typeof ProfileUpdateSchema>
+export type AvatarUpload = z.infer<typeof AvatarUploadSchema>

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

@@ -7,6 +7,9 @@ export const AppFrontendTargetSchema = z.enum(['web', 'app', 'miniapp', 'desktop
 export const AppInfoOutputDataSchema = z.object({
   name: z.string(),
   version: z.string(),
+  env: z.string(),
+  defaultLocale: z.string(),
+  supportedLocales: z.array(z.string()),
   startedAt: z.string().datetime(),
   frontends: z.array(AppFrontendTargetSchema),
 })

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

@@ -1,3 +1,5 @@
 export * from './app-contract.js'
 export * from './app-schemas.js'
-export * from './{{projectName}}-contract.js'
+export * from './admin-contract.js'
+export * from './admin-schemas.js'
+export * from './{{fullstack.contractPackageName}}.js'

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

@@ -1,12 +1,17 @@
 import { apiContract } from '@h-ai/api-contract'
+import { adminContract, authContract, profileContract } from './admin-contract.js'
 import { appContract } from './app-contract.js'
 
 /** 当前工程启用的前端目标。 */
 export const ENABLED_FRONTENDS = {{{fullstack.selectedFrontendsJson}}} as const
+export const SUPPORTED_LOCALES = [{{#each fullstack.i18n.locales}}'{{this}}'{{#unless @last}}, {{/unless}}{{/each}}] as const
 
 /** 工程级 API contract，前端 typed client 与后端 service 共用。 */
 export const {{fullstack.contractExportName}} = apiContract.create({
   app: appContract,
+  iam: { auth: authContract },
+  admin: adminContract,
+  profile: profileContract,
 })
 
 export type FullstackContract = typeof {{fullstack.contractExportName}}

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

@@ -19,6 +19,9 @@ describe('{{fullstack.contractPackageName}}', () => {
     const result = 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],
     })

package/templates/apps/fullstack/packages/{{projectName}}-contract/tsup.config.ts.hbs

@@ -3,7 +3,7 @@ import { defineConfig } from 'tsup'
 export default defineConfig({
   entry: ['src/index.ts'],
   format: ['esm'],
-  dts: true,
+  dts: { compilerOptions: { ignoreDeprecations: '6.0' } },
   sourcemap: true,
   clean: true,
 })