create-bubbles 0.1.25 → 0.1.27

package/template-vp-monorepo-react-nestjs/apps/server/src/modules/access/roles/roles.service.ts

@@ -0,0 +1,249 @@
+import { Injectable } from '@nestjs/common'
+import { and, count, desc, eq, sql } from 'drizzle-orm'
+import { rolePermissions, roles, userRoles } from '@/database/schema'
+import type {
+  AccessScope,
+  CreateRoleRequest,
+  PageQuery,
+  PermissionTreeResult,
+  RoleRecord,
+  SetRolePermissionsRequest,
+  UpdateRoleRequest,
+} from 'shared/types'
+import { ACCESS_CATALOG_VERSION, ACCESS_PERMISSION_CATALOG } from 'shared/utils'
+import { AppException } from '@/common/exceptions/app.exception'
+import { AccessService, type AccessActor, type VerifiedAccess } from '../access.service'
+import { ACCESS_ERRORS } from '../access.errors'
+import {
+  checkVersion,
+  pageWindow,
+  requireFound,
+  scopeColumns,
+  scopeFilter,
+  searchSql,
+  toScope,
+  type AccessDb,
+  type AccessTx,
+} from '../access.store'
+
+@Injectable()
+export class RolesService {
+  constructor(private readonly access: AccessService) {}
+  /** 返回角色读取允许的权限集合，同时支持角色管理和成员角色分配界面读取角色。 */
+  readPermissions(scope: AccessScope) {
+    return [
+      `${scope.type}.roles.read`,
+      scope.type === 'platform' ? 'platform.accounts.roles' : `${scope.type}.members.roles`,
+    ]
+  }
+  /**
+   * 读取当前作用域的角色详情，聚合权限、成员数量并计算操作者是否可以分配该角色。
+   *
+   * 管理员角色仅允许管理员分配，其他角色的权限不得超出操作者有效权限。
+   */
+  async record(db: AccessDb, access: VerifiedAccess, id: string): Promise<RoleRecord> {
+    const [row] = await db
+      .select()
+      .from(roles)
+      .where(and(scopeFilter(access.scope), eq(roles.id, id)))
+    const role = requireFound(row)
+    const grants = await db
+      .select()
+      .from(rolePermissions)
+      .where(eq(rolePermissions.roleId, role.id))
+    const members = await db.select().from(userRoles).where(eq(userRoles.roleId, role.id))
+    const permissionKeys = grants.map((p) => p.permissionKey)
+    return {
+      id: role.id,
+      name: role.name,
+      description: role.description,
+      scope: toScope(role),
+      builtin: role.builtin,
+      permissionKeys,
+      version: role.version,
+      memberCount: members.length,
+      assignable:
+        role.builtin === 'administrator'
+          ? !!access.administrator
+          : permissionKeys.every((p) => access.permissionKeys.includes(p)),
+      createdAt: role.createdAt.toISOString(),
+      updatedAt: role.updatedAt.toISOString(),
+    }
+  }
+  /**
+   * 校验角色权限属于当前作用域且可授权，并确保页面依赖完整、未超过操作者权限。
+   *
+   * 管理员专属或已废弃权限不可写入自定义角色。
+   */
+  validatePermissions(access: VerifiedAccess, keys: string[]) {
+    for (const key of keys) {
+      const p = ACCESS_PERMISSION_CATALOG.find((p) => p.key === key)
+      if (
+        !p ||
+        p.scopeType !== access.scope.type ||
+        p.adminOnly ||
+        p.deprecated ||
+        (p.pagePermissionKey && !keys.includes(p.pagePermissionKey))
+      )
+        throw new AppException(ACCESS_ERRORS.INVALID_PERMISSION_SET)
+      if (!access.permissionKeys.includes(key)) throw new AppException(ACCESS_ERRORS.FORBIDDEN)
+    }
+  }
+  /** 在当前事务内全量替换角色权限；调用方负责校验权限集合并维护角色版本。 */
+  async replacePermissions(tx: AccessTx, roleId: string, permissionKeys: string[]) {
+    await tx.delete(rolePermissions).where(eq(rolePermissions.roleId, roleId))
+    if (permissionKeys.length)
+      await tx
+        .insert(rolePermissions)
+        .values(permissionKeys.map((permissionKey) => ({ roleId, permissionKey })))
+  }
+  /** 校验角色读取权限后，按名称分页查询当前作用域角色及其可分配状态。 */
+  list(input: { actor: AccessActor; scope: AccessScope; query: PageQuery }) {
+    return this.access.read(
+      { ...input, permission: this.readPermissions(input.scope) },
+      /** 在同一快照内计算角色总数、读取当前页并聚合角色授权详情。 */
+      async (tx, access) => {
+        const { page, pageSize, offset } = pageWindow(input.query)
+        const condition = and(scopeFilter(input.scope), searchSql([roles.name], input.query.query))
+        const [total] = await tx.select({ value: count() }).from(roles).where(condition)
+        const selected = await tx
+          .select()
+          .from(roles)
+          .where(condition)
+          .orderBy(desc(roles.createdAt), desc(roles.id))
+          .limit(pageSize)
+          .offset(offset)
+        return {
+          page,
+          pageSize,
+          total: total!.value,
+          items: await Promise.all(selected.map((r) => this.record(tx, access, r.id))),
+        }
+      },
+    )
+  }
+  /** 校验角色读取权限后，返回当前作用域内指定角色的完整记录。 */
+  get(input: { actor: AccessActor; scope: AccessScope; roleId: string }) {
+    return this.access.read(
+      { ...input, permission: this.readPermissions(input.scope) },
+      (tx, access) => this.record(tx, access, input.roleId),
+    )
+  }
+  /** 返回作用域的菜单树、权限目录及操作者可授予的权限键，供角色授权界面使用。 */
+  permissions(input: { actor: AccessActor; scope: AccessScope }) {
+    return this.access.read(
+      { ...input, permission: this.readPermissions(input.scope) },
+      async (_tx, access): Promise<PermissionTreeResult> => ({
+        catalogVersion: ACCESS_CATALOG_VERSION,
+        items: access.allMenus,
+        permissions: ACCESS_PERMISSION_CATALOG.filter((p) => p.scopeType === input.scope.type).map(
+          (p) => ({ ...p }),
+        ),
+        grantablePermissionKeys: ACCESS_PERMISSION_CATALOG.filter(
+          (p) =>
+            p.scopeType === input.scope.type &&
+            !p.adminOnly &&
+            !p.deprecated &&
+            access.permissionKeys.includes(p.key),
+        ).map((p) => p.key),
+      }),
+    )
+  }
+  /** 验证权限集合与名称唯一性后创建自定义角色，写入权限和审计记录并返回角色详情。 */
+  create(input: { actor: AccessActor; scope: AccessScope; body: CreateRoleRequest }) {
+    return this.access.write(
+      { ...input, permission: `${input.scope.type}.roles.create` },
+      /** 将名称检查、角色创建、权限绑定和审计写入作为一个原子操作。 */
+      async (tx, access) => {
+        this.validatePermissions(access, input.body.permissionKeys ?? [])
+        const [existing] = await tx
+          .select()
+          .from(roles)
+          .where(and(scopeFilter(input.scope), eq(roles.name, input.body.name)))
+        if (existing) throw new AppException(ACCESS_ERRORS.DUPLICATE_RESOURCE)
+        const [role] = await tx
+          .insert(roles)
+          .values({
+            ...scopeColumns(input.scope),
+            name: input.body.name,
+            description: input.body.description ?? '',
+          })
+          .returning()
+        await this.replacePermissions(tx, role!.id, input.body.permissionKeys ?? [])
+        await this.access.audit(tx, {
+          ...input,
+          access,
+          action: 'role.create',
+          objectType: 'role',
+          objectId: role!.id,
+          summary: { permissionKeys: input.body.permissionKeys ?? [] },
+        })
+        return this.record(tx, access, role!.id)
+      },
+    )
+  }
+  /**
+   * 按操作类型修改、替换权限或删除自定义角色，并校验权限、版本与资源引用。
+   *
+   * 内置角色不可修改；已分配给成员的角色不可删除。成功后记录审计，修改时递增版本。
+   * @returns 删除标记或变更后的角色详情。
+   */
+  change(input: {
+    actor: AccessActor
+    scope: AccessScope
+    roleId: string
+    body: UpdateRoleRequest | SetRolePermissionsRequest | { expectedVersion: number }
+    action: 'update' | 'permissions' | 'delete'
+  }) {
+    return this.access.write(
+      { ...input, permission: `${input.scope.type}.roles.${input.action}` },
+      /** 基于锁内角色版本执行目标变更，保证角色资料、权限和审计一起提交。 */
+      async (tx, access) => {
+        const role = await this.record(tx, access, input.roleId)
+        if (role.builtin) throw new AppException(ACCESS_ERRORS.BUILTIN_ROLE_IMMUTABLE)
+        checkVersion(role.version, input.body.expectedVersion)
+        if (input.action === 'delete') {
+          if (role.memberCount) throw new AppException(ACCESS_ERRORS.RESOURCE_IN_USE)
+          await tx.delete(rolePermissions).where(eq(rolePermissions.roleId, role.id))
+          await tx.delete(roles).where(and(scopeFilter(input.scope), eq(roles.id, role.id)))
+        } else {
+          if ('permissionKeys' in input.body) {
+            this.validatePermissions(access, input.body.permissionKeys)
+            await this.replacePermissions(tx, role.id, input.body.permissionKeys)
+          }
+          if ('name' in input.body && input.body.name !== undefined) {
+            const [existing] = await tx
+              .select()
+              .from(roles)
+              .where(and(scopeFilter(input.scope), eq(roles.name, input.body.name)))
+            if (existing && existing.id !== role.id)
+              throw new AppException(ACCESS_ERRORS.DUPLICATE_RESOURCE)
+          }
+          const body = input.body as UpdateRoleRequest
+          await tx
+            .update(roles)
+            .set({
+              ...(body.name !== undefined ? { name: body.name } : {}),
+              ...(body.description !== undefined ? { description: body.description } : {}),
+              version: sql`${roles.version} + 1`,
+              updatedAt: new Date(),
+            })
+            .where(and(scopeFilter(input.scope), eq(roles.id, role.id)))
+        }
+        await this.access.audit(tx, {
+          ...input,
+          access,
+          action: `role.${input.action}`,
+          objectType: 'role',
+          objectId: role.id,
+          summary: {
+            changedFields: Object.keys(input.body).filter((k) => k !== 'expectedVersion'),
+          },
+        })
+        return input.action === 'delete'
+          ? { deleted: true as const }
+          : this.record(tx, access, role.id)
+      },
+    )
+  }
+}

package/template-vp-monorepo-react-nestjs/apps/server/src/modules/access/roles/roles.validation.ts

@@ -0,0 +1,24 @@
+import { z } from 'zod'
+import {
+  descriptionSchema,
+  nameSchema,
+  permissionKeysSchema,
+  versionSchema,
+} from '../access.validation'
+
+export const createRoleSchema = z.strictObject({
+  name: nameSchema,
+  description: descriptionSchema.optional(),
+  permissionKeys: permissionKeysSchema.optional(),
+})
+export const updateRoleSchema = z
+  .strictObject({
+    expectedVersion: versionSchema,
+    name: nameSchema.optional(),
+    description: descriptionSchema.optional(),
+  })
+  .refine((v) => v.name !== undefined || v.description !== undefined)
+export const permissionsSchema = z.strictObject({
+  expectedVersion: versionSchema,
+  permissionKeys: permissionKeysSchema,
+})

package/template-vp-monorepo-react-nestjs/apps/server/src/modules/access/seed/access-seed.service.ts

@@ -0,0 +1,183 @@
+import { Inject, Injectable, type OnModuleInit } from '@nestjs/common'
+import { DRIZZLE, type DrizzleDB } from '@/database/db.module'
+import {
+  accessBootstrap,
+  auditLogs,
+  cleanupTombstones,
+  companies,
+  menus,
+  menuVersions,
+  permissions,
+  projects,
+  rolePermissions,
+  roles,
+  userRoles,
+  users,
+} from '@/database/schema'
+import { and, eq, sql } from 'drizzle-orm'
+import type { AccessScope } from 'shared/types'
+import {
+  ACCESS_PAGE_CATALOG,
+  ACCESS_PERMISSION_CATALOG,
+  ACCESS_PROTECTED_ROUTE_KEYS,
+  getBuiltinPermissionKeys,
+  normalizeAccount,
+} from 'shared/utils'
+import { AppException } from '@/common/exceptions/app.exception'
+import { ACCESS_ERRORS } from '../access.errors'
+import { lockAccess, scopeColumns, scopeFilter, type AccessTx } from '../access.store'
+
+@Injectable()
+export class AccessSeedService implements OnModuleInit {
+  constructor(@Inject(DRIZZLE) private readonly db: DrizzleDB) {}
+  /** 服务启动时在权限写锁保护下同步权限目录、默认菜单和各作用域内置角色。 */
+  async onModuleInit() {
+    await this.db.transaction(async (tx) => {
+      await lockAccess(tx)
+      await this.sync(tx)
+    })
+  }
+
+  /**
+   * 幂等创建作用域内置管理员和普通成员角色，并补齐尚未清理的默认权限。
+   *
+   * 只追加缺失权限，发生追加时递增角色版本；清理墓碑标记的权限不会恢复。
+   * @returns 当前作用域的内置角色记录。
+   */
+  async ensureRoles(tx: AccessTx, scope: AccessScope) {
+    for (const builtin of ['administrator', 'member'] as const) {
+      await tx
+        .insert(roles)
+        .values({
+          ...scopeColumns(scope),
+          name: builtin === 'administrator' ? '内置管理员' : '内置普通成员',
+          builtin,
+        })
+        .onConflictDoNothing()
+    }
+    const found = await tx.select().from(roles).where(scopeFilter(scope))
+    const tombstones = new Set(
+      (await tx.select().from(cleanupTombstones)).map((t) => t.permissionKey),
+    )
+    for (const role of found.filter((r) => r.builtin)) {
+      const keys = getBuiltinPermissionKeys({
+        scopeType: scope.type,
+        builtin: role.builtin!,
+      }).filter((k) => !tombstones.has(k))
+      const current = await tx
+        .select()
+        .from(rolePermissions)
+        .where(eq(rolePermissions.roleId, role.id))
+      const additions = keys.filter((k) => !current.some((p) => p.permissionKey === k))
+      if (additions.length) {
+        await tx
+          .insert(rolePermissions)
+          .values(additions.map((permissionKey) => ({ roleId: role.id, permissionKey })))
+          .onConflictDoNothing()
+        await tx
+          .update(roles)
+          .set({ version: sql`${roles.version} + 1`, updatedAt: new Date() })
+          .where(eq(roles.id, role.id))
+      }
+    }
+    return found.filter((r) => r.builtin)
+  }
+
+  /**
+   * 将代码权限目录同步到数据库，补建菜单及各作用域内置角色，同时保留已有菜单配置。
+   *
+   * 清理墓碑中的权限不会重建；新增菜单时递增对应作用域的菜单版本。
+   */
+  async sync(tx: AccessTx) {
+    const tombstones = new Set(
+      (await tx.select().from(cleanupTombstones)).map((t) => t.permissionKey),
+    )
+    const catalog = ACCESS_PERMISSION_CATALOG.filter((p) => !tombstones.has(p.key))
+    for (const scope of ['platform', 'company', 'project'] as const)
+      await tx.insert(menuVersions).values({ scopeType: scope }).onConflictDoNothing()
+    for (const item of catalog)
+      await tx
+        .insert(permissions)
+        .values(item)
+        .onConflictDoUpdate({ target: permissions.key, set: item })
+    for (const item of catalog.filter((p) => !p.deprecated)) {
+      const [existing] = await tx.select().from(menus).where(eq(menus.permissionKey, item.key))
+      if (existing) continue
+      const [parent] = item.pagePermissionKey
+        ? await tx.select().from(menus).where(eq(menus.permissionKey, item.pagePermissionKey))
+        : []
+      const defaultIcon =
+        item.kind === 'page'
+          ? (ACCESS_PAGE_CATALOG.find((page) => page.routeKey === item.routeKey)?.icon ?? '')
+          : ''
+      await tx.insert(menus).values({
+        scopeType: item.scopeType,
+        type: item.kind,
+        name: item.title,
+        routeKey: item.routeKey,
+        permissionKey: item.key,
+        parentId: parent?.id ?? null,
+        icon: defaultIcon,
+        protected: (ACCESS_PROTECTED_ROUTE_KEYS as readonly string[]).includes(item.routeKey),
+        sort: catalog.indexOf(item),
+      })
+      await tx
+        .update(menuVersions)
+        .set({ version: sql`${menuVersions.version} + 1` })
+        .where(eq(menuVersions.scopeType, item.scopeType))
+    }
+    await this.ensureRoles(tx, { type: 'platform' })
+    for (const company of await tx.select({ id: companies.id }).from(companies))
+      await this.ensureRoles(tx, { type: 'company', companyId: company.id })
+    for (const project of await tx
+      .select({ id: projects.id, companyId: projects.companyId })
+      .from(projects))
+      await this.ensureRoles(tx, {
+        type: 'project',
+        companyId: project.companyId,
+        projectId: project.id,
+      })
+  }
+
+  /**
+   * 为有效账号执行首次平台管理员初始化，同步基础权限并写入初始化标记和审计记录。
+   *
+   * @param account - 待授予首位平台管理员身份的账号，会先进行规范化。
+   * @returns 初始化状态；相同账号重复调用可安全返回，其他账号再次初始化会被拒绝。
+   */
+  async initialize(account: string) {
+    return this.db.transaction(async (tx) => {
+      await lockAccess(tx)
+      const [user] = await tx
+        .select()
+        .from(users)
+        .where(and(eq(users.account, normalizeAccount(account)), eq(users.status, 'active')))
+        .for('share')
+      if (!user) throw new AppException(ACCESS_ERRORS.INVALID_MEMBER_ACCOUNT)
+      const [bootstrap] = await tx.select().from(accessBootstrap)
+      if (bootstrap && bootstrap.initializedAdminUserId !== user.id)
+        throw new AppException(ACCESS_ERRORS.ALREADY_INITIALIZED)
+      await this.sync(tx)
+      if (!bootstrap) {
+        const [role] = await tx
+          .select()
+          .from(roles)
+          .where(and(scopeFilter({ type: 'platform' }), eq(roles.builtin, 'administrator')))
+        await tx.insert(userRoles).values({ userId: user.id, roleId: role!.id })
+        await tx.insert(accessBootstrap).values({ id: 1, initializedAdminUserId: user.id })
+        await tx.insert(auditLogs).values({
+          actorUserId: user.id,
+          actorAccount: user.account,
+          actorName: user.name,
+          scopeType: 'platform',
+          action: 'access.initialize',
+          objectType: 'platform',
+          objectId: 'platform',
+          summary: { targetUserId: user.id },
+          requestId: crypto.randomUUID(),
+        })
+      }
+      return { initialized: true, account: user.account, alreadyInitialized: !!bootstrap }
+    })
+  }
+}

package/template-vp-monorepo-react-nestjs/apps/server/src/modules/access/workspaces/workspaces.controller.ts

@@ -0,0 +1,28 @@
+import { Controller, Get, Req } from '@nestjs/common'
+import type { FastifyRequest } from 'fastify'
+import { AccessPolicy, Authenticated } from '@/common/decorators/access-policy.decorator'
+import { actor, scopeFor } from '@/modules/access/access-http'
+import { WorkspacesService } from './workspaces.service'
+
+@Controller()
+export class WorkspacesController {
+  constructor(private readonly workspacesService: WorkspacesService) {}
+
+  /** 为已登录用户返回可进入的工作空间及其管理员身份。 */
+  @Get('workspaces')
+  @Authenticated()
+  workspaces(@Req() req: FastifyRequest) {
+    return this.workspacesService.workspaces(actor(req))
+  }
+
+  /** 根据路由推导工作空间，返回该空间的用户权限、菜单和版本上下文。 */
+  @Get([
+    'platform/access',
+    'companies/:companyId/access',
+    'companies/:companyId/projects/:projectId/access',
+  ])
+  @AccessPolicy({ scope: 'route' })
+  context(@Req() req: FastifyRequest) {
+    return this.workspacesService.context({ actor: actor(req), scope: scopeFor(req) })
+  }
+}

package/template-vp-monorepo-react-nestjs/apps/server/src/modules/access/workspaces/workspaces.service.ts

@@ -0,0 +1,94 @@
+import { Injectable } from '@nestjs/common'
+import { and, eq } from 'drizzle-orm'
+import { companies, companyMembers, projects, projectMembers, users } from '@/database/schema'
+import { AppException } from '@/common/exceptions/app.exception'
+import { AUTH_ERRORS } from '@/modules/auth/auth.errors'
+import { AccessService, type AccessActor } from '@/modules/access/access.service'
+import type { AccessScope, WorkspacesResult } from 'shared/types'
+
+@Injectable()
+export class WorkspacesService {
+  constructor(private readonly access: AccessService) {}
+
+  /** 校验用户对目标工作空间的访问资格，返回经过可见性过滤的菜单和有效权限上下文。 */
+  context(input: { actor: AccessActor; scope: AccessScope }) {
+    return this.access.read(input, async (_tx, access) => this.access.context(access))
+  }
+  /**
+   * 在一致性快照中列出有效账号可进入的平台、公司及项目工作空间。
+   *
+   * 仅包含启用的公司、项目及有效成员关系；公司管理员可进入所属公司的全部启用项目。
+   */
+  workspaces(actor: AccessActor): Promise<WorkspacesResult> {
+    return this.access.db.transaction(
+      /** 在同一快照内校验账号，汇总平台角色、有效成员关系及可继承的公司管理员身份。 */
+      async (tx) => {
+        const [user] = await tx
+          .select({ id: users.id, name: users.name, account: users.account, status: users.status })
+          .from(users)
+          .where(eq(users.id, actor.userId))
+        if (!user || user.status !== 'active') throw new AppException(AUTH_ERRORS.SESSION_INVALID)
+        const workspaces: WorkspacesResult['workspaces'] = []
+        if ((await this.access.roleAssignments(tx, { type: 'platform' }, user.id)).length)
+          workspaces.push({
+            scope: { type: 'platform' },
+            name: '平台管理',
+            administrator: (await this.access.isAdministrator(tx, { type: 'platform' }, user.id))
+              ? 'platform'
+              : null,
+          })
+        const memberships = await tx
+          .select({ company: companies })
+          .from(companyMembers)
+          .innerJoin(companies, eq(companies.id, companyMembers.companyId))
+          .where(
+            and(
+              eq(companyMembers.userId, user.id),
+              eq(companyMembers.status, 'active'),
+              eq(companies.status, 'active'),
+            ),
+          )
+        for (const { company } of memberships) {
+          const scope: AccessScope = { type: 'company', companyId: company.id }
+          const isAdmin = await this.access.isAdministrator(tx, scope, user.id)
+          workspaces.push({ scope, name: company.name, administrator: isAdmin ? 'company' : null })
+          const allProjects = await tx
+            .select()
+            .from(projects)
+            .where(and(eq(projects.companyId, company.id), eq(projects.status, 'active')))
+          const joined = await tx
+            .select()
+            .from(projectMembers)
+            .where(
+              and(
+                eq(projectMembers.companyId, company.id),
+                eq(projectMembers.userId, user.id),
+                eq(projectMembers.status, 'active'),
+              ),
+            )
+          for (const project of allProjects.filter(
+            (p) => isAdmin || joined.some((m) => m.projectId === p.id),
+          )) {
+            const projectScope: AccessScope = {
+              type: 'project',
+              companyId: company.id,
+              projectId: project.id,
+            }
+            workspaces.push({
+              scope: projectScope,
+              name: project.name,
+              companyName: company.name,
+              administrator: isAdmin
+                ? 'company'
+                : (await this.access.isAdministrator(tx, projectScope, user.id))
+                  ? 'project'
+                  : null,
+            })
+          }
+        }
+        return { user: { id: user.id, name: user.name, account: user.account }, workspaces }
+      },
+      { isolationLevel: 'repeatable read', accessMode: 'read only' },
+    )
+  }
+}

package/template-vp-monorepo-react-nestjs/apps/server/src/modules/access/workspaces/workspaces.validation.ts

@@ -0,0 +1,5 @@
+export {
+  createCompanySchema,
+  createProjectSchema,
+  updateProfileSchema as profileSchema,
+} from 'shared/utils'

package/template-vp-monorepo-react-nestjs/apps/server/src/modules/audit/audit.controller.ts

@@ -0,0 +1,26 @@
+import { Controller, Get, Query, Req } from '@nestjs/common'
+import type { FastifyRequest } from 'fastify'
+import { AccessPolicy } from '@/common/decorators/access-policy.decorator'
+import { actor, scopeFor } from '@/modules/access/access-http'
+import { parse } from '@/modules/access/access.validation'
+import { AuditService } from './audit.service'
+import { auditSchema } from './audit.validation'
+
+@Controller([
+  'platform/audit-logs',
+  'companies/:companyId/audit-logs',
+  'companies/:companyId/projects/:projectId/audit-logs',
+])
+export class AuditController {
+  constructor(private readonly audit: AuditService) {}
+  /** 校验分页、操作者及时间筛选参数，读取路由对应作用域内的审计日志。 */
+  @Get()
+  @AccessPolicy({ scope: 'route', permission: '{scope}.audit.read' })
+  list(@Req() req: FastifyRequest, @Query() raw: unknown) {
+    return this.audit.list({
+      actor: actor(req),
+      scope: scopeFor(req),
+      query: parse(auditSchema, raw),
+    })
+  }
+}

package/template-vp-monorepo-react-nestjs/apps/server/src/modules/audit/audit.module.ts

@@ -0,0 +1,11 @@
+import { Module } from '@nestjs/common'
+import { AccessModule } from '../access/access.module'
+import { AuditController } from './audit.controller'
+import { AuditService } from './audit.service'
+
+@Module({
+  imports: [AccessModule],
+  controllers: [AuditController],
+  providers: [AuditService],
+})
+export class AuditModule {}