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

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

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

@@ -0,0 +1,94 @@
+import type { ServContext } from '@h-ai/serv'
+import { audit } from '@h-ai/audit'
+import { 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, authContract, profileContract } from '{{fullstack.contractPackageName}}'
+import {
+  createAdminUser,
+  getAdminRoles,
+  isRoleCode,
+  recordAudit,
+  toAdminUser,
+  updateAdminUser,
+  updateProfile,
+  uploadAvatar,
+  withAdminMutation,
+} from '../admin-service.js'
+import { serverM } from '../messages.js'
+
+/** 身份认证沿用框架公共契约与 refresh-cookie 传输。 */
+export function createAuthProcedures() {
+  const { currentUser, refresh } = createIamProcedures({ iam }).auth
+  const { login, logout, changePassword } = authContract
+  // 仅覆写需要业务审计的认证操作，其余直接复用框架；未选认证入口不挂载。
+  const audited = serv.implement({ login, logout, changePassword }).context<ServContext>().route('login', async ({ input, context }) => {
+    const result = await iam.auth.login(input)
+    if (!result.success)
+      return result
+    await recordAudit({ ...context, session: { userId: result.data.user.id, roles: result.data.roles, permissions: result.data.permissions } }, 'login', 'auth')
+    return result
+  }).route('logout').auth().handle(async ({ context }) => {
+    const result = await iam.auth.logout(context.accessToken ?? '')
+    if (!result.success)
+      return result
+    await recordAudit(context, 'logout', 'auth')
+    return result
+  }).route('changePassword').auth().handle(async ({ input, context }) => {
+    const result = await iam.user.changeCurrentUserPassword(context.accessToken ?? '', input.oldPassword, input.newPassword)
+    if (!result.success)
+      return result
+    await recordAudit(context, 'password-change', 'profile', context.session.userId)
+    return result
+  }).build()
+  return { ...audited, currentUser, refresh }
+}
+
+export function createAdminProcedures() {
+  return serv.implement(adminContract).context<ServContext>().route('users.list').role('admin').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.create').role('admin').handle(({ input, context }) => withAdminMutation(context, () => createAdminUser(input, context))).route('users.update').role('admin').handle(({ input, context }) => withAdminMutation(context, () => updateAdminUser(input, context))).route('users.delete').role('admin').handle(({ input, context }) => withAdminMutation(context, 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').role('admin').handle(({ input, context }) => withAdminMutation(context, () => uploadAvatar(input.id, input, context))).route('roles.list').role('admin').handle(() => getAdminRoles()).route('roles.update').role('admin').handle(({ input, context }) => withAdminMutation(context, 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 }))
+    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.list').role('admin').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
+    return ok({ ...result.data, page: input.page, pageSize: input.pageSize, 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(({ input, context }) => updateProfile(input, context)).route('avatar').auth().handle(({ input, context }) => uploadAvatar(context.session.userId, input, context)).build()
+}

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

@@ -7,6 +7,9 @@ import { appContract } from '{{fullstack.contractPackageName}}'
 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[]
 }
@@ -32,6 +35,9 @@ function createAppInfo(options: CreateAppProceduresOptions): AppInfoOutputData {
   return {
     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

@@ -1,4 +1,5 @@
 import type { CreateAppProceduresOptions } from './app-procedures.js'
+import { createAdminProcedures, createAuthProcedures, createProfileProcedures } from './admin-procedures.js'
 import { createAppProcedures } from './app-procedures.js'
 
 export interface CreateServerProceduresOptions {
@@ -9,5 +10,8 @@ export interface CreateServerProceduresOptions {
 export function createServerProcedures(options: CreateServerProceduresOptions) {
   return {
     app: createAppProcedures(options.app),
+    iam: { auth: createAuthProcedures() },
+    admin: createAdminProcedures(),
+    profile: createProfileProcedures(),
   }
-}
+}