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

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

package/templates/apps/fullstack/packages/{{projectName}}-serv/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.servPackageName}}",
   "type": "module",
   "version": "0.1.0",
@@ -25,12 +25,19 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "clean": "rimraf dist .turbo",
-    "dev": "pnpm build && node dist/index.js",
-    "start": "node dist/index.js"
+    "dev": "pnpm build && node --env-file-if-exists=../../.env dist/index.js",
+    "start": "node --env-file-if-exists=../../.env dist/index.js"
   },
   "dependencies": {
+    "@h-ai/audit": "{{haiPackageSpecifier}}",
+    "@h-ai/cache": "{{haiPackageSpecifier}}",
     "@h-ai/core": "{{haiPackageSpecifier}}",
+    "@h-ai/crypto": "{{haiPackageSpecifier}}",
+    "@h-ai/iam": "{{haiPackageSpecifier}}",
+    "@h-ai/reldb": "{{haiPackageSpecifier}}",
     "@h-ai/serv": "{{haiPackageSpecifier}}",
+    "@h-ai/storage": "{{haiPackageSpecifier}}",
+    "zod": "{{fullstack.packageSpecifiers.zod}}",
     "{{fullstack.contractPackageName}}": "workspace:*"
   }
 }

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

@@ -1,48 +1,73 @@
-import type { ServConfigInput } from '@h-ai/serv'
-import { core } from '@h-ai/core'
+import type { CoreConfig } from '@h-ai/core'
+import type { ServHttpApp } from '@h-ai/serv'
+import { core, err, HaiCommonError, ok } from '@h-ai/core'
+import { createReldbTransportKeyStore, crypto } from '@h-ai/crypto'
+import { iam } from '@h-ai/iam'
+import { reldb } from '@h-ai/reldb'
 import { serv, ServConfigSchema } from '@h-ai/serv'
-import { ENABLED_FRONTENDS, {{fullstack.contractExportName}} } from '{{fullstack.contractPackageName}}'
+import { storage } from '@h-ai/storage'
+import { ENABLED_FRONTENDS, {{fullstack.contractExportName}}, SUPPORTED_LOCALES } from '{{fullstack.contractPackageName}}'
 import { createServerProcedures } from './server/procedures/index.js'
 
 const STARTED_AT = new Date().toISOString()
 
-/** `_core.yml` 中的应用元信息（由 core.config 加载，未初始化时回退到默认值）。 */
-interface AppCoreConfig {
-  name?: string
-  version?: string
-  env?: string
-}
-
-/** 应用侧最小 HTTP App 抽象；不把底层 Hono 类型暴露给项目代码。 */
-export interface ServerApp {
-  readonly fetch: (request: Request) => Response | Promise<Response>
-  readonly request: (input: RequestInfo | URL, init?: RequestInit) => Response | Promise<Response>
-}
-
 /** 创建后端 HTTP App；与 @h-ai/serv 的 createApp 返回语义保持一致。 */
-export function createServerApp(): ServerApp {
-  // 配置来自 config/_core.yml 与 config/_serv.yml。
-  // 单元测试可不初始化 core，此时回退到内置默认值。
-  const coreConfig = core.config.get<AppCoreConfig>('core')
-  const servConfig = ServConfigSchema.parse(core.config.get<ServConfigInput>('serv') ?? {})
-  const appName = coreConfig?.name ?? '{{fullstack.servPackageName}}'
-  const appVersion = coreConfig?.version ?? '0.1.0'
+export function createServerApp(): ServHttpApp {
+  const coreConfig = core.config.getOrThrow<CoreConfig>('core')
+  const servConfig = ServConfigSchema.parse(core.config.getOrThrow('serv'))
   const security = serv.createRuntimeSecurityPolicy({
-    environment: coreConfig?.env,
+    environment: coreConfig.env,
     corsOrigin: servConfig.cors.origin,
     nativeOrigins: servConfig.cors.nativeOrigins,
   })
+  const publicPaths = [
+    ...(servConfig.http.health ? [servConfig.http.health.path, servConfig.http.health.readyPath].filter((path): path is `/${string}` => Boolean(path)) : []),
+    ...(servConfig.http.openapi && security.exposeApiDocs ? [servConfig.http.openapi.path] : []),
+    ...(servConfig.http.docs && security.exposeApiDocs ? [servConfig.http.docs.path] : []),
+  ]
 
   return serv.createApp({
     contract: {{fullstack.contractExportName}},
     procedures: createServerProcedures({
       app: {
-        name: appName,
-        version: appVersion,
+        name: coreConfig.name,
+        version: coreConfig.version,
+        env: coreConfig.env,
+        defaultLocale: coreConfig.defaultLocale,
+        supportedLocales: SUPPORTED_LOCALES,
         startedAt: STARTED_AT,
         frontends: [...ENABLED_FRONTENDS],
       },
     }),
+    iam,
+    verifyToken: async (token) => {
+      const session = await iam.session.verifyToken(token)
+      if (!session.success)
+        return session
+      const user = await iam.user.getUser(session.data.userId)
+      if (!user.success)
+        return user
+      if (!user.data?.enabled)
+        return err(HaiCommonError.UNAUTHORIZED, core.i18n.coreM('core_errorUnauthorized'))
+      // 会话中的授权同步属于最大努力，业务守卫始终读取最新持久化角色与权限。
+      const [roles, permissions] = await Promise.all([
+        iam.authz.getUserRoles(user.data.id),
+        iam.authz.getUserPermissions(user.data.id),
+      ])
+      if (!roles.success)
+        return roles
+      if (!permissions.success)
+        return permissions
+      return ok({ ...session.data, roles: roles.data.map(role => role.code), permissions: permissions.data.map(permission => permission.code) })
+    },
+    refreshCookie: {
+      secure: security.secureRefreshCookie,
+      nativeTokenTransport: { isRequest: request => request.headers.get('x-hai-token-transport') === 'body'
+        && ['{{projectName}}-app', '{{projectName}}-desktop'].includes(request.headers.get('x-request-client') ?? '')
+        && security.isNativeOrigin(request.headers.get('origin') ?? '') },
+    },
+    // 管理业务默认强制双向加密；客户端公钥复用 reldb 保存，服务端密钥仅驻留进程。
+    transport: { ...(servConfig.transport || {}), excludePaths: publicPaths, crypto, keyStore: createReldbTransportKeyStore({ reldb }) },
     http: {
       ...servConfig.http,
       openapi: security.exposeApiDocs ? servConfig.http.openapi : false,
@@ -52,8 +77,18 @@ export function createServerApp(): ServerApp {
       middleware: serv.cors({
         origin: security.allowOrigin,
         credentials: servConfig.cors.credentials,
-        allowedHeaders: [...servConfig.cors.allowedHeaders],
-        exposedHeaders: [...servConfig.cors.exposedHeaders],
+        allowedHeaders: [...new Set([...servConfig.cors.allowedHeaders, 'X-Client-Id', 'X-Encrypted', 'X-Request-Client', 'X-HAI-Token-Transport'])],
+        exposedHeaders: [...new Set([...servConfig.cors.exposedHeaders, 'X-Encrypted'])],
+      }),
+    }, {
+      path: `${servConfig.http.apiPrefix}/assets/*`,
+      middleware: serv.storageAssets({
+        storage,
+        pathPrefix: `${servConfig.http.apiPrefix}/assets/`,
+        keyPattern: /^avatars\/[\w-]+\/[\w-]+\.(png|jpg|webp)$/,
+        allowedContentTypes: ['image/png', 'image/jpeg', 'image/webp'],
+        cacheControl: 'public, max-age=31536000, immutable',
+        crossOriginResourcePolicy: 'cross-origin',
       }),
     }],
   })

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

@@ -1,18 +1,33 @@
+import type { CoreConfig } from '@h-ai/core'
 import type { ServConfigInput } from '@h-ai/serv'
+import process from 'node:process'
 import { core } from '@h-ai/core'
 import { serv, ServConfigSchema } from '@h-ai/serv'
 import { createServerApp } from './app-server.js'
+import { closeModules, initializeModules } from './server/runtime.js'
 
-// 加载 config/ 下的 _core.yml / _serv.yml 等配置文件（约定优于配置）
-core.init({ configDir: './config', logging: { level: 'info' } })
+async function startServer(): Promise<void> {
+  // 加载配置后按依赖顺序初始化；日志设置沿用 _core.yml。
+  core.init({ configDir: './config' })
+  await initializeModules()
+  try {
+    // HOST/PORT 环境变量优先于 config/_serv.yml。
+    const { server } = ServConfigSchema.parse(core.config.getOrThrow<ServConfigInput>('serv'))
+    const app = createServerApp()
+    serv.listen(app, {
+      host: server.host,
+      port: server.port,
+      onListening: info => core.logger.info('Application listening', { name: core.config.getOrThrow<CoreConfig>('core').name, host: server.host, port: info.port }),
+      onClose: closeModules,
+    })
+  }
+  catch (error) {
+    await closeModules()
+    throw error
+  }
+}
 
-// host/port 来自 config/_serv.yml 的 server（HOST/PORT 环境变量高于配置文件）。
-const { server } = ServConfigSchema.parse(core.config.get<ServConfigInput>('serv') ?? {})
-const app = createServerApp()
-const listenApp = app as Parameters<typeof serv.listen>[0]
-
-serv.listen(listenApp, {
-  host: server.host,
-  port: server.port,
-  onListening: info => core.logger.info('{{fullstack.servPackageName}} listening', { host: server.host, port: info.port }),
+void startServer().catch((error: unknown) => {
+  core.logger.fatal('Application startup failed', { error: error instanceof Error ? error.message : 'Unknown startup failure' })
+  process.exitCode = 1
 })

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

@@ -0,0 +1,276 @@
+import type { HaiResult } from '@h-ai/core'
+import type { Role, User } from '@h-ai/iam'
+import type { ServConfig, ServContext } from '@h-ai/serv'
+import type { AdminCreateUser, AdminRole, AdminRoleCode, AdminUpdateUser, AdminUser, AvatarUpload, ProfileUpdate } from '{{fullstack.contractPackageName}}'
+import { Buffer } from 'node:buffer'
+import { audit } from '@h-ai/audit'
+import { cache } from '@h-ai/cache'
+import { core, err, HaiCommonError, ok } from '@h-ai/core'
+import { iam } from '@h-ai/iam'
+import { storage } from '@h-ai/storage'
+import { SUPPORTED_LOCALES } from '{{fullstack.contractPackageName}}'
+import { serverM } from './messages.js'
+
+const ROLE_CODES = new Set<AdminRoleCode>(['admin', 'user'])
+const SUPPORTED_THEMES = [{{#each fullstack.theme.themes}}'{{this}}'{{#unless @last}}, {{/unless}}{{/each}}] as readonly string[]
+let adminMutationActive = false
+
+/** 管理写操作串行化，锁内重新鉴权，防止两个管理员同时互相删除或降级。 */
+export async function withAdminMutation<T>(context: ServContext, work: () => Promise<HaiResult<T>>): Promise<HaiResult<T>> {
+  // mini 的管理写入仅支持单写实例；进程内保护无租期，慢请求不会在 TTL 到期后被并发穿透。
+  if (adminMutationActive)
+    return err(HaiCommonError.CONFLICT, serverM('busy', { locale: context.locale }))
+  adminMutationActive = true
+  const owner = core.id.uuid()
+  const key = 'hai:app:admin-mutation'
+  let acquired = false
+  let leaseLost = false
+  let renewalPending = false
+  let renewalTimer: ReturnType<typeof setInterval> | undefined
+  try {
+    const locked = await cache.lock.acquire(key, { owner, ttl: 300 })
+    if (!locked.success)
+      return locked
+    if (!locked.data)
+      return err(HaiCommonError.CONFLICT, serverM('busy', { locale: context.locale }))
+    acquired = true
+    renewalTimer = setInterval(() => {
+      if (renewalPending || leaseLost)
+        return
+      renewalPending = true
+      void cache.lock.extend(key, 300, owner).then((renewed) => {
+        if (!renewed.success || !renewed.data) {
+          leaseLost = true
+          core.logger.error('Admin mutation lease renewal failed', { owner, error: renewed.success ? 'lease_not_owned' : renewed.error.code })
+        }
+      }).catch(() => {
+        leaseLost = true
+        core.logger.error('Admin mutation lease renewal failed', { owner, error: 'unexpected_renewal_failure' })
+      }).finally(() => {
+        renewalPending = false
+      })
+    }, 100_000)
+    renewalTimer.unref()
+    const actor = await getAdminUser(context.session?.userId ?? '')
+    if (!actor.success)
+      return actor
+    if (!actor.data.enabled || !actor.data.roles.includes('admin'))
+      return err(HaiCommonError.FORBIDDEN, serverM('selfProtection', { locale: context.locale }))
+    if (leaseLost)
+      return err(HaiCommonError.CONFLICT, serverM('busy', { locale: context.locale }))
+    return await work()
+  }
+  finally {
+    if (renewalTimer)
+      clearInterval(renewalTimer)
+    try {
+      if (acquired) {
+        const released = await cache.lock.release(key, owner)
+        if (!released.success || !released.data)
+          core.logger.error('Failed to release admin mutation lock', { owner, error: released.success ? 'lease_not_owned' : released.error.code })
+      }
+    }
+    finally {
+      adminMutationActive = false
+    }
+  }
+}
+
+/** 用户与角色读取失败直接透传，不能把角色查询失败当作普通用户。 */
+export async function getAdminUser(id: string): Promise<HaiResult<AdminUser>> {
+  const user = await iam.user.getUser(id)
+  if (!user.success)
+    return user
+  if (!user.data)
+    return err(HaiCommonError.NOT_FOUND, serverM('notFound'))
+  const roles = await iam.authz.getUserRoles(id)
+  if (!roles.success)
+    return roles
+  return ok(toAdminUser(user.data, roles.data))
+}
+
+export function toAdminUser(user: User, roles: Role[]): AdminUser {
+  return {
+    id: user.id,
+    username: user.username,
+    email: user.email,
+    displayName: user.displayName,
+    avatarUrl: user.avatarUrl,
+    enabled: user.enabled,
+    roles: roles.map(role => role.code).filter(isRoleCode),
+    createdAt: user.createdAt.toISOString(),
+    updatedAt: user.updatedAt.toISOString(),
+  }
+}
+
+export function isRoleCode(code: string): code is AdminRoleCode {
+  return ROLE_CODES.has(code as AdminRoleCode)
+}
+
+export async function createAdminUser(input: AdminCreateUser, context: ServContext): Promise<HaiResult<AdminUser>> {
+  const role = await iam.authz.getRoleByCode(input.role)
+  if (!role.success)
+    return role
+  if (!role.data)
+    return err(HaiCommonError.NOT_FOUND, serverM('notFound', { locale: context.locale }))
+  const registered = await iam.user.register(input)
+  if (!registered.success)
+    return registered
+  const userId = registered.data.user.id
+  const assigned = await iam.authz.syncRoles(userId, [role.data.id])
+  if (!assigned.success) {
+    await rollbackCreatedUser(userId)
+    return assigned
+  }
+  if (!input.enabled) {
+    const disabled = await iam.user.updateUser(userId, { enabled: false })
+    if (!disabled.success) {
+      await rollbackCreatedUser(userId)
+      return disabled
+    }
+  }
+  await recordAudit(context, 'create', 'users', userId, { role: input.role, enabled: input.enabled })
+  return getAdminUser(userId)
+}
+
+async function rollbackCreatedUser(id: string): Promise<void> {
+  const removed = await iam.user.deleteUser(id)
+  if (!removed.success)
+    core.logger.error('Failed to roll back user creation', { userId: id, error: removed.error.code })
+}
+
+export async function updateAdminUser(input: AdminUpdateUser, context: ServContext): Promise<HaiResult<AdminUser>> {
+  if (input.id === context.session?.userId && (input.enabled === false || input.role === 'user'))
+    return err(HaiCommonError.FORBIDDEN, serverM('selfProtection', { locale: context.locale }))
+  const existing = await iam.user.getUser(input.id)
+  if (!existing.success)
+    return existing
+  if (!existing.data)
+    return err(HaiCommonError.NOT_FOUND, serverM('notFound', { locale: context.locale }))
+  const role = input.role ? await iam.authz.getRoleByCode(input.role) : undefined
+  if (role && !role.success)
+    return role
+  if (role?.success && !role.data)
+    return err(HaiCommonError.NOT_FOUND, serverM('notFound', { locale: context.locale }))
+  const { id, role: _role, ...profile } = input
+  const previousRoles = await iam.authz.getUserRoles(id)
+  if (!previousRoles.success)
+    return previousRoles
+  if (role?.success && role.data) {
+    const assigned = await iam.authz.syncRoles(id, [role.data.id])
+    if (!assigned.success)
+      return assigned
+  }
+  const updated = await iam.user.updateUser(id, profile)
+  if (!updated.success) {
+    // 角色 ID 可精确还原，避免 undefined 资料字段被 updateUser 忽略后无法补偿。
+    if (role?.success && role.data) {
+      const restored = await iam.authz.syncRoles(id, previousRoles.data.map(item => item.id))
+      if (!restored.success)
+        core.logger.error('Failed to restore roles after user update failure', { userId: id, error: restored.error.code })
+    }
+    return updated
+  }
+  await recordAudit(context, 'update', 'users', id, { fields: Object.keys(profile), role: input.role })
+  return getAdminUser(id)
+}
+
+export async function getAdminRoles(): Promise<HaiResult<{ items: AdminRole[] }>> {
+  const roles = await iam.authz.getAllRoles({ page: 1, pageSize: 100 })
+  if (!roles.success)
+    return roles
+  const items = roles.data.items.filter(role => isRoleCode(role.code))
+  const counts = await iam.authz.getRoleUserCounts(items.map(role => role.id))
+  if (!counts.success)
+    return counts
+  return ok({ items: items.map(role => ({
+    id: role.id,
+    code: role.code as AdminRoleCode,
+    name: role.name,
+    description: role.description,
+    userCount: counts.data.get(role.id) ?? 0,
+  })) })
+}
+
+export async function updateProfile(input: ProfileUpdate, context: ServContext): Promise<HaiResult<AdminUser>> {
+  const token = context.accessToken ?? ''
+  const current = await iam.user.getCurrentUser(token)
+  if (!current.success)
+    return current
+  if ((input.locale && !(SUPPORTED_LOCALES as readonly string[]).includes(input.locale)) || (input.theme && !SUPPORTED_THEMES.includes(input.theme)))
+    return err(HaiCommonError.VALIDATION_ERROR, serverM('unsupportedPreference', { locale: context.locale }))
+  const metadata = { ...current.data.metadata }
+  if (input.locale)
+    metadata.locale = input.locale
+  if (input.theme)
+    metadata.theme = input.theme
+  const updated = await iam.user.updateCurrentUser(token, { displayName: input.displayName, email: input.email, metadata })
+  if (!updated.success)
+    return updated
+  await recordAudit(context, 'update', 'profile', current.data.id, { fields: Object.keys(input) })
+  return getAdminUser(current.data.id)
+}
+
+/** 上传路径由服务端生成，禁止客户端写入任意 storage key。 */
+export async function uploadAvatar(userId: string, input: AvatarUpload, context: ServContext): Promise<HaiResult<{ avatarUrl: string }>> {
+  const current = await iam.user.getUser(userId)
+  if (!current.success)
+    return current
+  if (!current.data)
+    return err(HaiCommonError.NOT_FOUND, serverM('notFound', { locale: context.locale }))
+  const bytes = Buffer.from(input.base64, 'base64')
+  if (bytes.length === 0 || bytes.length > 512 * 1024 || bytes.toString('base64') !== input.base64 || !matchesImage(bytes, input.contentType))
+    return err(HaiCommonError.VALIDATION_ERROR, serverM('invalidAvatar', { locale: context.locale }))
+  const extension = { 'image/png': 'png', 'image/jpeg': 'jpg', 'image/webp': 'webp' }[input.contentType]
+  const key = `avatars/${userId}/${core.id.uuid()}.${extension}`
+  const stored = await storage.file.put(key, bytes, { contentType: input.contentType })
+  if (!stored.success)
+    return stored
+  const apiPrefix = core.config.getOrThrow<ServConfig>('serv').http.apiPrefix
+  // 只保存生成资源路径，公开 Origin 由客户端已配置的 API 地址决定，禁止信任 Host。
+  const avatarUrl = `${apiPrefix}/assets/${key}`
+  const updated = await iam.user.updateUser(userId, { avatarUrl })
+  if (!updated.success) {
+    const cleaned = await storage.file.delete(key)
+    if (!cleaned.success)
+      core.logger.warn('Failed to clean up rejected avatar', { error: cleaned.error.code })
+    return updated
+  }
+  // 更新成功后删除旧头像；只清理此用户且符合服务端生成规则的资源。
+  const oldKey = current.data.avatarUrl?.split('/assets/')[1]
+  if (oldKey && oldKey.startsWith(`avatars/${userId}/`) && /^avatars\/[\w-]+\/[\w-]+\.(?:png|jpg|webp)$/.test(oldKey)) {
+    const cleaned = await storage.file.delete(oldKey)
+    if (!cleaned.success)
+      core.logger.warn('Failed to clean up previous avatar', { error: cleaned.error.code })
+  }
+  await recordAudit(context, 'update', 'avatars', userId)
+  return ok({ avatarUrl })
+}
+
+function matchesImage(bytes: Buffer, contentType: AvatarUpload['contentType']): boolean {
+  if (contentType === 'image/png') {
+    if (bytes.length < 33 || bytes.subarray(0, 8).toString('hex') !== '89504e470d0a1a0a' || bytes.toString('ascii', 12, 16) !== 'IHDR')
+      return false
+    const width = bytes.readUInt32BE(16)
+    const height = bytes.readUInt32BE(20)
+    return width > 0 && height > 0 && width <= 4096 && height <= 4096
+  }
+  if (contentType === 'image/jpeg')
+    return bytes.length >= 4 && bytes.subarray(0, 3).toString('hex') === 'ffd8ff' && bytes.subarray(-2).toString('hex') === 'ffd9'
+  return bytes.length >= 20 && bytes.toString('ascii', 0, 4) === 'RIFF' && bytes.toString('ascii', 8, 12) === 'WEBP' && bytes.readUInt32LE(4) + 8 === bytes.length
+}
+
+/** 审计记录仅含操作字段与资源标识，不记录密码、token、头像内容或联系信息。 */
+export async function recordAudit(context: ServContext, action: string, resource: string, resourceId?: string, details?: Record<string, unknown>): Promise<void> {
+  const result = await audit.log({
+    userId: context.session?.userId,
+    action,
+    resource,
+    resourceId,
+    details,
+    ipAddress: context.ip,
+    userAgent: context.userAgent,
+  })
+  if (!result.success)
+    core.logger.error('Failed to record audit event', { action, resource, error: result.error.code })
+}

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

@@ -0,0 +1,29 @@
+import { core } from '@h-ai/core'
+
+/** 服务端业务提示与角色种子名称同步维护中英文。 */
+export const serverM = core.i18n.createMessageGetter({
+  'zh-CN': {
+    admin: '管理员',
+    user: '普通用户',
+    adminDescription: '管理用户、角色和审计日志',
+    userDescription: '仅可维护个人设置',
+    notFound: '用户或角色不存在',
+    selfProtection: '不能删除、禁用或降级当前管理员账号',
+    invalidAvatar: '请选择不超过 512 KB 的有效 PNG、JPEG 或 WebP 图片',
+    busy: '系统繁忙，请稍后重试',
+    unsupportedPreference: '不支持此语言或主题',
+    invalidDateRange: '结束时间不能早于开始时间',
+  },
+  'en-US': {
+    admin: 'Administrator',
+    user: 'User',
+    adminDescription: 'Manage users, roles and audit logs',
+    userDescription: 'Manage personal settings only',
+    notFound: 'User or role does not exist',
+    selfProtection: 'You cannot delete, disable or demote your own administrator account',
+    invalidAvatar: 'Choose a valid PNG, JPEG or WebP image up to 512 KB',
+    busy: 'The system is busy. Please try again',
+    unsupportedPreference: 'This language or theme is not supported',
+    invalidDateRange: 'End date must not precede start date',
+  },
+})