@h-ai/cli 0.1.0-alpha9 → 1.0.0-beta.2

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

@@ -0,0 +1,294 @@
+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, AdminInviteUser, 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', 'audit_admin', 'config_admin', 'business_operator', '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, operation: string, work: () => Promise<HaiResult<T>>): Promise<HaiResult<T>> {
+  // mini 的管理写入仅支持单写实例；进程内保护无租期，慢请求不会在 TTL 到期后被并发穿透。
+  if (adminMutationActive)
+    return err(HaiCommonError.CONFLICT, serverM('busy', { locale: context.locale }))
+  adminMutationActive = true
+  let owner = ''
+  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, { ttl: 300 })
+    if (!locked.success)
+      return locked
+    if (!locked.data)
+      return err(HaiCommonError.CONFLICT, serverM('busy', { locale: context.locale }))
+    owner = locked.data
+    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
+    const permitted = await iam.authz.checkPermission(actor.data.id, operation.startsWith('iam.roles.') ? 'app.roles.manage' : 'app.users.manage')
+    if (!permitted.success)
+      return permitted
+    if (actor.data.accountStatus !== 'active' || (actor.data.accountType === 'temporary' && (!actor.data.accountExpiresAt || new Date(actor.data.accountExpiresAt).getTime() <= Date.now())) || !permitted.data)
+      return err(HaiCommonError.FORBIDDEN, serverM('selfProtection', { locale: context.locale }))
+    if (leaseLost)
+      return err(HaiCommonError.CONFLICT, serverM('busy', { locale: context.locale }))
+    const sensitive = await iam.auth.checkSensitiveOperation(context.accessToken ?? '', operation, context.request.headers.get('x-hai-reauthentication') ?? undefined)
+    if (!sensitive.success)
+      return sensitive
+    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,
+    accountType: user.accountType ?? 'permanent',
+    accountStatus: user.accountStatus,
+    accountExpiresAt: user.accountExpiresAt?.toISOString() ?? null,
+    lastLoginAt: user.lastLoginAt?.toISOString() ?? null,
+    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.createUser({ ...input, accountExpiresAt: input.accountExpiresAt ? new Date(input.accountExpiresAt) : undefined })
+  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
+  }
+  await recordAudit(context, 'create', 'users', userId, { role: input.role, accountStatus: input.accountStatus })
+  return getAdminUser(userId)
+}
+
+/** 安全通知发送后发生未知结果时保留账号，不自动重试或删除已发出的邀请。 */
+export async function inviteAdminUser(input: AdminInviteUser, context: ServContext): Promise<HaiResult<AdminUser>> {
+  const role = await iam.authz.getRoleByCode(input.role)
+  if (!role.success || !role.data)
+    return role.success ? err(HaiCommonError.NOT_FOUND, serverM('notFound', { locale: context.locale })) : role
+  const created = await iam.user.inviteUser({ ...input, accountExpiresAt: input.accountExpiresAt ? new Date(input.accountExpiresAt) : undefined })
+  if (!created.success)
+    return created
+  const assigned = await iam.authz.syncRoles(created.data.user.id, [role.data.id])
+  if (!assigned.success)
+    return assigned
+  await recordAudit(context, 'invite', 'users', created.data.user.id, { role: input.role })
+  return getAdminUser(created.data.user.id)
+}
+
+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.role && input.role !== 'admin') || (input.accountStatus && input.accountStatus !== 'active') || input.accountType === 'temporary' || input.accountExpiresAt != null))
+    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, accountExpiresAt: profile.accountExpiresAt === undefined ? undefined : profile.accountExpiresAt ? new Date(profile.accountExpiresAt) : null })
+  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/audit-jobs.ts.hbs

@@ -0,0 +1,28 @@
+/** 应用自己的定时任务装配；Scheduler 先于 IAM/Audit 关闭，不修改全局回调所属关系。 */
+import type { HaiResult } from '@h-ai/core'
+import { audit } from '@h-ai/audit'
+import { core, err, ok } from '@h-ai/core'
+import { HaiSchedulerError, scheduler, SchedulerConfigSchema } from '@h-ai/scheduler'
+import { serverM } from './messages.js'
+
+/** 仅启用自动备份时启动现有调度器；手动备份不需要启动它。 */
+export async function startAuditJobs(): Promise<HaiResult<void>> {
+  const schedule = audit.schedulerPlan
+  if (!schedule)
+    return ok(undefined)
+  const config = SchedulerConfigSchema.safeParse(core.config.get('scheduler') ?? {})
+  if (!config.success)
+    return err(HaiSchedulerError.CONFIG_ERROR, serverM('busy'), config.error)
+  const initialized = await scheduler.init({
+    ...config.data,
+    ...schedule,
+  })
+  if (!initialized.success) {
+    await scheduler.close()
+    return initialized
+  }
+  const started = scheduler.start()
+  if (!started.success)
+    await scheduler.close()
+  return started
+}

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

@@ -0,0 +1,50 @@
+/** 示例业务配置仅管理公开公告，不接触系统凭据或安全策略。 */
+import type { HaiResult } from '@h-ai/core'
+import { audit } from '@h-ai/audit'
+import { err, HaiCommonError, ok } from '@h-ai/core'
+import { reldb } from '@h-ai/reldb'
+import { z } from 'zod'
+
+export const BusinessSettingsSchema = z.object({ notice: z.string().trim().max(200) }).strict()
+
+export function initBusinessSettings(): Promise<HaiResult<void>> {
+  return reldb.ddl.createTable('app_business_settings', { id: { type: 'TEXT', primaryKey: true }, notice: { type: 'TEXT', notNull: true } })
+}
+
+export async function readBusinessSettings(): Promise<HaiResult<{ notice: string }>> {
+  const row = await reldb.sql.get<{ notice: string }>('SELECT notice FROM app_business_settings WHERE id = ?', ['public'])
+  return row.success ? ok({ notice: row.data?.notice ?? '' }) : row
+}
+
+export async function saveBusinessSettings(input: { notice: string }): Promise<HaiResult<{ notice: string }>> {
+  const parsed = BusinessSettingsSchema.safeParse(input)
+  if (!parsed.success)
+    return err(HaiCommonError.VALIDATION_ERROR)
+  const begun = await reldb.tx.begin()
+  if (!begun.success)
+    return begun
+  const tx = begun.data
+  try {
+    const sql = reldb.config?.type === 'mysql'
+      ? 'INSERT INTO app_business_settings (id, notice) VALUES (?, ?) ON DUPLICATE KEY UPDATE notice = VALUES(notice)'
+      : 'INSERT INTO app_business_settings (id, notice) VALUES (?, ?) ON CONFLICT (id) DO UPDATE SET notice = excluded.notice'
+    const saved = await tx.execute(sql, ['public', parsed.data.notice])
+    if (!saved.success) {
+      await tx.rollback()
+      return saved
+    }
+    const logged = await audit.capture({ action: 'business.configuration.update', resource: 'business-settings', category: 'business', details: { fields: ['notice'] } }, { tx })
+    if (!logged.success) {
+      await tx.rollback()
+      return logged
+    }
+    const committed = await tx.commit()
+    if (!committed.success)
+      await tx.rollback()
+    return committed.success ? ok(parsed.data) : committed
+  }
+  catch (error) {
+    await tx.rollback()
+    return err(HaiCommonError.INTERNAL_ERROR, undefined, error)
+  }
+}

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

@@ -0,0 +1,50 @@
+import { core } from '@h-ai/core'
+
+/** 服务端业务提示与角色种子名称同步维护中英日文。 */
+export const serverM = core.i18n.createMessageGetter({
+  'zh-CN': {
+    admin: '系统管理员',
+    audit_admin: '审计管理员',
+    config_admin: '配置管理员',
+    dutyProtected: '不能通过此入口修改其他职责的权限定义。',
+    user: '普通用户',
+    business_operator: '业务操作员',
+    notFound: '用户或角色不存在',
+    unauthorized: '请提供要撤销的访问令牌',
+    selfProtection: '不能删除当前管理员或修改其职责、有效期和账号状态',
+    invalidAvatar: '请选择不超过 512 KB 的有效 PNG、JPEG 或 WebP 图片',
+    busy: '系统繁忙，请稍后重试',
+    unsupportedPreference: '不支持此语言或主题',
+    invalidDateRange: '结束时间不能早于开始时间',
+  },
+  'ja-JP': {
+    admin: 'システム管理者',
+    audit_admin: '監査管理者',
+    config_admin: '設定管理者',
+    dutyProtected: 'この操作では他の職務の権限定義を変更できません。',
+    user: '一般ユーザー',
+    business_operator: '業務担当者',
+    notFound: 'ユーザーまたはロールが存在しません',
+    unauthorized: '取り消すアクセストークンを指定してください',
+    selfProtection: '自分の管理者アカウントの削除や職務、有効期限、状態の変更はできません',
+    invalidAvatar: '512KB以下の有効なPNG、JPEG、WebP画像を選択してください',
+    busy: 'システムが混雑しています。再試行してください',
+    unsupportedPreference: 'この言語またはテーマには対応していません',
+    invalidDateRange: '終了日は開始日以降にしてください',
+  },
+  'en-US': {
+    admin: 'System administrator',
+    audit_admin: 'Audit administrator',
+    config_admin: 'Configuration administrator',
+    dutyProtected: 'This operation cannot change permission definitions for other duties.',
+    user: 'User',
+    business_operator: 'Business operator',
+    notFound: 'User or role does not exist',
+    unauthorized: 'Provide the access token to revoke',
+    selfProtection: 'Ask another administrator to change your duty, expiry or account status',
+    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',
+  },
+})

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

@@ -0,0 +1,106 @@
+import type { ServContext } from '@h-ai/serv'
+import { audit, AuditInitConfigSchema } from '@h-ai/audit'
+import { core, err, HaiCommonError, ok } from '@h-ai/core'
+import { iam } from '@h-ai/iam'
+import { serv } from '@h-ai/serv'
+import { createIamProcedures } from '@h-ai/serv/features/iam'
+import { adminContract, profileContract } from '{{fullstack.contractPackageName}}'
+import {
+  createAdminUser,
+  getAdminRoles,
+  inviteAdminUser,
+  isRoleCode,
+  recordAudit,
+  toAdminUser,
+  updateAdminUser,
+  updateProfile,
+  uploadAvatar,
+  withAdminMutation,
+} from '../admin-service.js'
+import { readBusinessSettings, saveBusinessSettings } from '../business-settings.js'
+import { serverM } from '../messages.js'
+
+/** 身份认证沿用框架公共契约与 refresh-cookie 传输。 */
+export function createAuthProcedures() {
+  return createIamProcedures({ iam }).auth
+}
+
+export function createAdminProcedures() {
+  return serv.implement(adminContract).context<ServContext>().route('permissions.list').permission('app.roles.manage').handle(async ({ input }) => {
+    const result = await iam.authz.getAllPermissions(input)
+    return result.success ? ok({ total: result.data.total, items: result.data.items.map(item => ({ id: item.id, code: item.code, name: item.name, sensitiveOperations: item.sensitiveOperations ?? [] })) }) : result
+  }).route('permissions.update').permission('app.roles.manage').handle(({ input, context }) => withAdminMutation(context, 'iam.permissions.sensitiveOperations', async () => {
+    const result = await iam.authz.setPermissionSensitiveOperations(input.id, input.sensitiveOperations)
+    return result.success ? ok({ saved: true as const }) : result
+  })).route('configuration.get').permission('app.config.manage').handle(() => readBusinessSettings()).route('configuration.update').permission('app.config.manage').handle(async ({ input, context }) => {
+    const checked = await iam.auth.checkSensitiveOperation(context.accessToken ?? '', 'business.settings.update', context.request.headers.get('x-hai-reauthentication') ?? undefined)
+    return checked.success ? saveBusinessSettings(input) : checked
+  }).route('users.list').permission('app.users.manage').handle(async ({ input }) => {
+    const users = await iam.user.listUsers(input)
+    if (!users.success)
+      return users
+    const roles = await iam.authz.getUserRolesForMany(users.data.items.map(user => user.id))
+    if (!roles.success)
+      return roles
+    return ok({ ...users.data, items: users.data.items.map(user => toAdminUser(user, roles.data.get(user.id) ?? [])) })
+  }).route('users.resetPassword').permission('app.users.manage').handle(({ input, context }) => withAdminMutation(context, 'iam.users.resetPassword', async () => {
+    const result = await iam.user.adminResetPassword(input.id, input.newPassword)
+    if (!result.success)
+      return result
+    await recordAudit(context, 'password_reset', 'users', input.id)
+    return ok({ reset: true as const })
+  })).route('users.invite').permission('app.users.manage').handle(({ input, context }) => withAdminMutation(context, 'iam.users.invite', () => inviteAdminUser(input, context))).route('users.create').permission('app.users.manage').handle(({ input, context }) => withAdminMutation(context, 'iam.users.create', () => createAdminUser(input, context))).route('users.update').permission('app.users.manage').handle(({ input, context }) => withAdminMutation(context, 'iam.users.update', () => updateAdminUser(input, context))).route('users.delete').permission('app.users.manage').handle(({ input, context }) => withAdminMutation(context, 'iam.users.delete', async () => {
+    if (context.session.userId === input.id)
+      return err(HaiCommonError.FORBIDDEN, serverM('selfProtection', { locale: context.locale }))
+    const result = await iam.user.deleteUser(input.id)
+    if (!result.success)
+      return result
+    await recordAudit(context, 'delete', 'users', input.id)
+    return ok({ deleted: true as const })
+  })).route('users.avatar').permission('app.users.manage').handle(({ input, context }) => withAdminMutation(context, 'iam.users.avatar', () => uploadAvatar(input.id, input, context))).route('roles.list').permission('app.roles.manage').handle(() => getAdminRoles()).route('roles.update').permission('app.roles.manage').handle(({ input, context }) => withAdminMutation(context, 'iam.roles.update', async () => {
+    const role = await iam.authz.getRole(input.id)
+    if (!role.success)
+      return role
+    if (!role.data || !isRoleCode(role.data.code))
+      return err(HaiCommonError.NOT_FOUND, serverM('notFound', { locale: context.locale }))
+    if (role.data.code !== 'admin' && role.data.code !== 'user')
+      return err(HaiCommonError.FORBIDDEN, serverM('dutyProtected', { locale: context.locale }))
+    const updated = await iam.authz.updateRole(input.id, { description: input.description })
+    if (!updated.success)
+      return updated
+    const roles = await getAdminRoles()
+    if (!roles.success)
+      return roles
+    const result = roles.data.items.find(item => item.id === input.id)
+    if (!result)
+      return err(HaiCommonError.NOT_FOUND, serverM('notFound', { locale: context.locale }))
+    await recordAudit(context, 'update', 'roles', input.id, { fields: ['description'] })
+    return ok(result)
+  })).route('audit.backup').permission('audit:backup').handle(async ({ input, context }) => {
+    const checked = await iam.auth.checkSensitiveOperation(context.accessToken ?? '', 'audit.backup', context.request.headers.get('x-hai-reauthentication') ?? undefined)
+    if (!checked.success)
+      return checked
+    const result = await audit.backup.run({ ...input, signal: context.request.signal })
+    return result.success ? ok({ ...result.data, createdAt: result.data.createdAt.toISOString(), cutoff: result.data.cutoff.toISOString() }) : result
+  }).route('audit.list').permission('audit:read').handle(async ({ input, context }) => {
+    if (input.startDate && input.endDate && input.startDate > input.endDate)
+      return err(HaiCommonError.VALIDATION_ERROR, serverM('invalidDateRange', { locale: context.locale }))
+    const result = await audit.list({ ...input, startDate: input.startDate ? new Date(input.startDate) : undefined, endDate: input.endDate ? new Date(input.endDate) : undefined })
+    if (!result.success)
+      return result
+    const stats = await audit.getStats(7, { category: input.category, outcome: input.outcome, severity: input.severity, resource: input.resource, scopeId: input.scopeId, userId: input.userId })
+    if (!stats.success)
+      return stats
+    return ok({ ...result.data, stats: stats.data, backupEnabled: AuditInitConfigSchema.parse(core.config.get('audit') ?? {}).backup.enabled, items: result.data.items.map(item => ({ ...item, createdAt: new Date(item.createdAt).toISOString() })) })
+  }).build()
+}
+
+export function createProfileProcedures() {
+  return serv.implement(profileContract).context<ServContext>().route('update').auth().handle(async ({ input, context }) => {
+    const checked = await iam.auth.checkSensitiveOperation(context.accessToken ?? '', 'iam.profile.update', context.request.headers.get('x-hai-reauthentication') ?? undefined)
+    return checked.success ? updateProfile(input, context) : checked
+  }).route('avatar').auth().handle(async ({ input, context }) => {
+    const checked = await iam.auth.checkSensitiveOperation(context.accessToken ?? '', 'iam.profile.avatar', context.request.headers.get('x-hai-reauthentication') ?? undefined)
+    return checked.success ? uploadAvatar(context.session.userId, input, context) : checked
+  }).build()
+}

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

@@ -0,0 +1,49 @@
+import type { ServContext } from '@h-ai/serv'
+import type { AppEchoOutputData, AppFrontendTarget, AppInfoOutputData } from '{{fullstack.contractPackageName}}'
+import { ok } from '@h-ai/core'
+import { serv } from '@h-ai/serv'
+import { appContract } from '{{fullstack.contractPackageName}}'
+import { readBusinessSettings } from '../business-settings.js'
+
+export interface CreateAppProceduresOptions {
+  readonly name: string
+  readonly version: string
+  readonly env: string
+  readonly defaultLocale: string
+  readonly supportedLocales: readonly string[]
+  readonly startedAt: string
+  readonly frontends: readonly AppFrontendTarget[]
+}
+
+/** app 领域 procedures：把共享 contract 绑定到真实业务处理函数。 */
+export function createAppProcedures(options: CreateAppProceduresOptions) {
+  return serv
+    .implement(appContract)
+    .context<ServContext>()
+    .route('info', async () => {
+      const settings = await readBusinessSettings()
+      return settings.success ? ok({ ...createAppInfo(options), notice: settings.data.notice }) : settings
+    })
+    .route('echo', ({ input, context }) => {
+      const data: AppEchoOutputData = {
+        message: input.message,
+        echoedAt: new Date().toISOString(),
+        requestId: context.requestId,
+      }
+      return ok(data)
+    })
+    .build()
+}
+
+function createAppInfo(options: CreateAppProceduresOptions): AppInfoOutputData {
+  return {
+    notice: '',
+    name: options.name,
+    version: options.version,
+    env: options.env,
+    defaultLocale: options.defaultLocale,
+    supportedLocales: [...options.supportedLocales],
+    startedAt: options.startedAt,
+    frontends: [...options.frontends],
+  }
+}

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

@@ -0,0 +1,34 @@
+import type { CreateAppProceduresOptions } from './app-procedures.js'
+{{#if features.feedback}}
+import { feedback } from '@h-ai/feedback'
+import { createFeedbackProcedures } from '@h-ai/serv/features/feedback'
+{{/if}}
+import { createAdminProcedures, createAuthProcedures, createProfileProcedures } from './admin-procedures.js'
+import { createAppProcedures } from './app-procedures.js'
+
+// @hai-generator:procedures:imports
+
+export interface CreateServerProceduresOptions {
+  readonly app: CreateAppProceduresOptions
+}
+
+/** 工程级 procedures 聚合入口；后续增加领域时在这里追加即可。 */
+export function createServerProcedures(options: CreateServerProceduresOptions) {
+  return {
+    // @hai-generator:procedures:entries
+    app: createAppProcedures(options.app),
+    iam: { auth: createAuthProcedures() },
+    admin: createAdminProcedures(),
+    profile: createProfileProcedures(),
+{{#if features.feedback}}
+    feedback: createFeedbackProcedures({
+      feedback,
+      resolveContext: ({ session }) => ({
+        scopeId: '{{projectName}}',
+        userId: session.userId,
+        permissions: session.permissions,
+      }),
+    }),
+{{/if}}
+  }
+}