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

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

@@ -1,33 +1,223 @@
+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.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 expect(page.getByRole('heading', { level: 1 })).toBeVisible()
-  await expect(page.getByTestId('service-status')).toContainText('{{fullstack.servPackageName}}')
+  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/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}}",

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,
 })

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

@@ -2,14 +2,24 @@
 
 后端 API Service，基于 `@h-ai/serv` 将共享 contract 装配为最小 HTTP App 抽象，不在应用代码中直接暴露 Hono。
 
-## 骨架说明
+## 默认功能与配置
 
 - `config/_core.yml`：应用元信息（名称 / 版本 / 环境 / 语言），启动时由 `core.config` 加载。
 - `config/_serv.yml`：服务端运行时设置（CORS 来源等）。
-- `src/index.ts`：进程入口，先 `core.init({ configDir: './config' })` 加载配置再启动监听。
+- `config/_db.yml` / `_cache.yml` / `_iam.yml` / `_storage.yml` / `_audit.yml`：mini 管理所需模块配置，初始化前使用模块公开 Schema 验证。
+- `src/index.ts`：进程入口，先 `core.init({ configDir: './config' })`，再初始化 reldb → cache → crypto → storage → iam → audit；启动失败及退出反序释放。
 - `src/app-server.ts`：服务装配入口，挂载健康检查、OpenAPI、docs 与 procedures；应用名称 / 版本与 CORS 来源均取自上述配置。
 - `src/server/procedures/app-procedures.ts`：app 领域 procedures，对应 contract 中的 `app.info` / `app.echo` 路由。
-- `tests/app-server.test.ts`：通过 `ServerApp.request()` 验证健康检查与业务路由。
+- `src/server/procedures/admin-procedures.ts`：认证、管理员用户/角色/审计管理和个人设置，使用 `.auth()` / `.role('admin')` 守卫。每个请求读取用户最新启用状态、角色和权限。
+- 当前用户与刷新 procedures 直接选用 `@h-ai/serv/features/iam` 的默认实现；仅覆写登录、退出、修改密码以追加业务审计。未选的注册/OTP/通用管理接口不挂载，HTTP App 类型直接复用公开 `ServHttpApp`。
+- `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，不能指定任意文件路径。
+
+默认 SQLite + 本地 storage + memory cache 适合单实例，管理写入仅支持单写实例：进程内保护无过期时间，共享 cache 锁定期续租，丢失锁或释放失败会记录错误。多实例读取可使用共享数据库、Redis cache 和 S3 storage，但管理写请求必须统一路由到同一写实例；仅更换 Redis 不提供任意多写副本的最后管理员原子保证。另需配置传输会话粘性路由：服务端私钥驻留单个进程，服务重启后客户端需重新协商。Web 使用 HttpOnly refresh Cookie + 内存 access token；仅同时满足客户端标识、body 通道头与受信原生 Origin 的 App/Desktop 请求返回 refresh token body。
+
+业务修改提交后的审计记录采用最大努力策略：写入失败输出包含操作及资源的结构化错误日志，业务仍返回原操作结果，避免将已经完成的变更误报为失败；应用启动时 audit 初始化失败则停止启动。
 
 ## 开发
 

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

@@ -0,0 +1,3 @@
+userTable: hai_iam_users
+userIdColumn: id
+userNameColumn: username

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

@@ -0,0 +1,2 @@
+# 多实例部署请使用共享 Redis，保障会话、管理员变更锁一致。
+type: memory

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

@@ -6,9 +6,16 @@
 # 每个叶子项都可由约定式 HAI 环境变量覆盖，敏感值不要写入文件。
 # =============================================================================
 
-name: {{fullstack.servPackageName}}
+{{yaml 'name' fullstack.appName}}
 version: 0.1.0
-env: ${HAI_ENV:development}
-debug: ${HAI_DEBUG:false}
+env: development
+debug: false
 
 defaultLocale: {{fullstack.i18n.baseLocale}}
+logging:
+  level: info
+  format: json
+  redact:
+    - password
+    - token
+    - secret

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

@@ -0,0 +1,3 @@
+# 默认单实例 SQLite；HAI_DB 可整体替换为 PostgreSQL/MySQL 配置。
+type: sqlite
+database: ./data/app.db

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

@@ -0,0 +1,21 @@
+login:
+  password: true
+  otp: false
+  ldap: false
+  apikey: false
+password:
+  minLength: 8
+  maxLength: 128
+  requireUppercase: false
+  requireLowercase: false
+  requireNumber: false
+  requireSpecialChar: false
+session:
+  maxAge: 86400
+  sliding: true
+  singleDevice: false
+  refreshTokenMaxAge: 604800
+rbac:
+  defaultRole: user
+# 仅由应用创建 admin/user，避免生成无业务用途的默认角色与权限。
+seedDefaultData: false

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

@@ -22,14 +22,21 @@ http:
 
 cors:
   origin: ${HAI_CORS_ORIGIN:*}
-  nativeOrigins: ${HAI_CORS_NATIVEORIGINS:http://localhost,https://tauri.localhost,tauri://localhost,capacitor://localhost}
-  credentials: ${HAI_CORS_CREDENTIALS:false}
+  nativeOrigins: ${HAI_CORS_NATIVEORIGINS:http://localhost,https://localhost,http://tauri.localhost,https://tauri.localhost,tauri://localhost,capacitor://localhost}
+  credentials: ${HAI_CORS_CREDENTIALS:true}
   allowedHeaders:
     - Authorization
     - Content-Type
     - X-Request-Id
     - X-Requested-With
+    - X-Request-Client
+    - X-HAI-Token-Transport
+    - X-Client-Id
+    - X-Encrypted
   exposedHeaders:
     - X-Request-Id
+    - X-Encrypted
 
-transport: false
+transport:
+  keyExchangePath: /_hai/key-exchange
+  maxClients: 10000

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

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