create-bubbles 0.1.25 → 0.1.27

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

@@ -0,0 +1,68 @@
+import type { DrizzleDB } from '@/database/db.module'
+import { and, eq, ilike, isNull, or, sql, type SQLWrapper } from 'drizzle-orm'
+import { roles } from '@/database/schema'
+import type { AccessScope, PageQuery } from 'shared/types'
+import { AppException } from '@/common/exceptions/app.exception'
+import { ACCESS_ERRORS } from './access.errors'
+
+export type AccessTx = Parameters<Parameters<DrizzleDB['transaction']>[0]>[0]
+export type AccessDb = DrizzleDB | AccessTx
+/** 获取权限域的 PostgreSQL 事务级咨询锁，串行化权限相关写操作，事务结束时自动释放。 */
+export const lockAccess = (tx: AccessTx) => tx.execute(sql`select pg_advisory_xact_lock(7421, 1)`)
+/** 将访问作用域转换为数据库列，未适用的公司或项目标识写为 null。 */
+export const scopeColumns = (scope: AccessScope) => ({
+  scopeType: scope.type,
+  companyId: scope.type === 'platform' ? null : scope.companyId,
+  projectId: scope.type === 'project' ? scope.projectId : null,
+})
+/** 构造角色表的精确作用域条件，使用空值约束隔离平台、公司和项目角色。 */
+export const scopeFilter = (scope: AccessScope) =>
+  and(
+    eq(roles.scopeType, scope.type),
+    scope.type === 'platform' ? isNull(roles.companyId) : eq(roles.companyId, scope.companyId),
+    scope.type === 'project' ? eq(roles.projectId, scope.projectId) : isNull(roles.projectId),
+  )
+/** 将数据库中的作用域列还原为访问作用域对象，依赖行数据满足作用域完整性约束。 */
+export const toScope = (row: {
+  scopeType: 'platform' | 'company' | 'project'
+  companyId: string | null
+  projectId: string | null
+}): AccessScope =>
+  row.scopeType === 'platform'
+    ? { type: 'platform' }
+    : row.scopeType === 'company'
+      ? { type: 'company', companyId: row.companyId! }
+      : { type: 'project', companyId: row.companyId!, projectId: row.projectId! }
+/** 要求资源存在并返回原值；查询未命中时抛出统一资源不存在异常。 */
+export function requireFound<T>(value: T | undefined | null): T {
+  if (!value) throw new AppException(ACCESS_ERRORS.NOT_FOUND)
+  return value
+}
+/**
+ * 比较数据库版本与客户端预期版本，阻止过期数据覆盖后续修改。
+ *
+ * @throws 版本不一致时抛出版本冲突异常。
+ */
+export function checkVersion(actual: number, expected: number) {
+  if (actual !== expected) throw new AppException(ACCESS_ERRORS.VERSION_CONFLICT)
+}
+/**
+ * 构造多列忽略大小写的包含搜索条件，并转义关键词中的 SQL 通配符。
+ *
+ * @returns 各列之间以 OR 连接的条件；没有关键词时返回 undefined。
+ */
+export function searchSql(columns: SQLWrapper[], query?: string) {
+  return query
+    ? or(...columns.map((column) => ilike(sql`${column}`, `%${query.replace(/[\\%_]/g, '\\$&')}%`)))
+    : undefined
+}
+/**
+ * 根据分页参数计算查询窗口，缺省使用第 1 页、每页 20 条。
+ *
+ * @returns 页码、每页数量及数据库查询偏移量。
+ */
+export function pageWindow(query: PageQuery) {
+  const page = query.page ?? 1
+  const pageSize = query.pageSize ?? 20
+  return { page, pageSize, offset: (page - 1) * pageSize }
+}

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

@@ -0,0 +1,44 @@
+import { z } from 'zod'
+import { ZodValidationException } from 'nestjs-zod'
+
+export const idSchema = z.uuid()
+export const versionSchema = z.number().int().positive()
+export const accountSchema = z
+  .string()
+  .trim()
+  .toLowerCase()
+  .regex(/^[a-z0-9_]{4,32}$/)
+export const nameSchema = z.string().trim().min(2).max(100)
+export const descriptionSchema = z.string().trim().max(500)
+export const roleIdsSchema = z
+  .array(idSchema)
+  .max(500)
+  .refine((a) => new Set(a).size === a.length)
+export const permissionKeysSchema = z
+  .array(z.string().min(1).max(150))
+  .max(500)
+  .refine((a) => new Set(a).size === a.length)
+export const scopeTypeSchema = z.enum(['platform', 'company', 'project'])
+export const pageSchema = z.strictObject({
+  page: z.coerce.number().int().positive().default(1),
+  pageSize: z.coerce.number().int().min(1).max(100).default(20),
+  query: z.string().trim().max(100).optional(),
+})
+export const entityListSchema = pageSchema.extend({
+  status: z.enum(['active', 'disabled']).optional(),
+})
+export const statusSchema = z.strictObject({
+  expectedVersion: versionSchema,
+  status: z.enum(['active', 'disabled']),
+})
+export const deleteSchema = z.strictObject({ expectedVersion: z.coerce.number().int().positive() })
+/**
+ * 按照给定 Zod 规则校验并转换请求数据，将失败结果交给统一参数异常处理。
+ *
+ * @returns 通过校验且已应用默认值、规范化等转换的数据。
+ */
+export function parse<T>(schema: z.ZodType<T>, input: unknown): T {
+  const result = schema.safeParse(input)
+  if (!result.success) throw new ZodValidationException(result.error)
+  return result.data
+}

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

@@ -0,0 +1,27 @@
+import { Body, Controller, Get, HttpCode, Post, Req } from '@nestjs/common'
+import type { FastifyRequest } from 'fastify'
+import { AccessPolicy } from '@/common/decorators/access-policy.decorator'
+import { actor } from '../access-http'
+import { parse } from '../access.validation'
+import { PermissionsCleanupService } from './permissions-cleanup.service'
+import { cleanupSchema } from './permissions-cleanup.validation'
+
+@Controller('platform/permissions')
+export class PermissionsCleanupController {
+  constructor(private readonly cleanup: PermissionsCleanupService) {}
+
+  /** 向具备清理权限的平台管理员返回废弃权限清理预览及部署证明摘要。 */
+  @Get('cleanup-preview')
+  @AccessPolicy({ scope: 'platform', permission: 'platform.menus.cleanup', adminOnly: true })
+  preview(@Req() req: FastifyRequest) {
+    return this.cleanup.preview(actor(req))
+  }
+
+  /** 校验权限键和部署证明摘要，执行平台管理员确认的废弃权限清理。 */
+  @Post('cleanup')
+  @HttpCode(200)
+  @AccessPolicy({ scope: 'platform', permission: 'platform.menus.cleanup', adminOnly: true })
+  execute(@Req() req: FastifyRequest, @Body() body: unknown) {
+    return this.cleanup.cleanup(actor(req), parse(cleanupSchema, body))
+  }
+}

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

@@ -0,0 +1,260 @@
+import { Injectable } from '@nestjs/common'
+import { createHash } from 'node:crypto'
+import { readFile } from 'node:fs/promises'
+import { z } from 'zod'
+import { eq, inArray, sql } from 'drizzle-orm'
+import {
+  cleanupTombstones,
+  menus,
+  menuVersions,
+  permissions,
+  rolePermissions,
+  roles,
+} from '@/database/schema'
+import type { CleanupPreview, CleanupRequest, CleanupResult } from 'shared/types'
+import { ACCESS_CATALOG_VERSION, ACCESS_PERMISSION_CATALOG } from 'shared/utils'
+import { AppException } from '@/common/exceptions/app.exception'
+import { AccessService, type AccessActor } from '../access.service'
+import { ACCESS_ERRORS } from '../access.errors'
+import type { AccessDb } from '../access.store'
+
+const proofSchema = z.strictObject({
+  deploymentId: z.string().min(1).max(150),
+  completed: z.literal(true),
+  verifiedAt: z.iso.datetime(),
+  expiresAt: z.iso.datetime(),
+  serviceVersions: z
+    .array(
+      z.strictObject({
+        version: z.string().min(1),
+        instanceIds: z.array(z.string().min(1)).min(1),
+        requiredPermissionKeys: z.array(z.string().min(1)),
+      }),
+    )
+    .min(1),
+})
+@Injectable()
+export class PermissionsCleanupService {
+  constructor(private readonly access: AccessService) {}
+  /**
+   * 读取并验证部署证明的时间窗口、服务版本、实例唯一性及当前权限目录完整性。
+   *
+   * @returns 有效证明及原文件 SHA-256 摘要；证明缺失、格式无效或校验未通过时返回 null。
+   * 未知文件读取异常继续上抛，交给全局异常处理。
+   */
+  async proof() {
+    const path = process.env.ACCESS_DEPLOYMENT_PROOF_FILE
+    if (!path) return null
+    // 证明缺失/格式失效是明确的维护阻断，不能降级为允许清理。
+    try {
+      const raw = await readFile(path, 'utf8')
+      const proof = proofSchema.parse(JSON.parse(raw))
+      const now = Date.now()
+      if (
+        Date.parse(proof.verifiedAt) > now ||
+        Date.parse(proof.expiresAt) <= now ||
+        Date.parse(proof.expiresAt) - Date.parse(proof.verifiedAt) > 86_400_000
+      )
+        return null
+      const versions = proof.serviceVersions.map((v) => v.version)
+      const instances = proof.serviceVersions.flatMap((v) => v.instanceIds)
+      if (
+        new Set(versions).size !== versions.length ||
+        new Set(instances).size !== instances.length
+      )
+        return null
+      const current = proof.serviceVersions.find(
+        (v) => v.version === (process.env.ACCESS_RELEASE_VERSION ?? ACCESS_CATALOG_VERSION),
+      )
+      const expected = ACCESS_PERMISSION_CATALOG.filter((p) => !p.deprecated)
+        .map((p) => p.key)
+        .sort()
+      if (
+        !current ||
+        JSON.stringify([...current.requiredPermissionKeys].sort()) !== JSON.stringify(expected)
+      )
+        return null
+      if (
+        proof.serviceVersions.some(
+          (v) =>
+            new Set(v.requiredPermissionKeys).size !== v.requiredPermissionKeys.length ||
+            v.requiredPermissionKeys.some(
+              (k) => !ACCESS_PERMISSION_CATALOG.some((p) => p.key === k),
+            ),
+        )
+      )
+        return null
+      return { proof, digest: createHash('sha256').update(raw).digest('hex') }
+    } catch (error) {
+      if (
+        error instanceof SyntaxError ||
+        error instanceof z.ZodError ||
+        (error instanceof Error &&
+          'code' in error &&
+          ['ENOENT', 'EACCES'].includes(String(error.code)))
+      )
+        return null
+      throw error
+    }
+  }
+  /**
+   * 检查尚未清理的废弃权限及其菜单、角色引用，汇总部署依赖与结构上的清理阻断原因。
+   *
+   * @returns 只读清理预览，包含证明摘要、候选项、阻断原因和预计移除数量。
+   */
+  async inspect(db: AccessDb): Promise<CleanupPreview> {
+    const proof = await this.proof()
+    const tombstones = new Set(
+      (await db.select().from(cleanupTombstones)).map((t) => t.permissionKey),
+    )
+    const candidates = ACCESS_PERMISSION_CATALOG.filter(
+      (p) => p.deprecated && !tombstones.has(p.key),
+    )
+    const rows = await db.select().from(menus)
+    const grants = await db.select().from(rolePermissions)
+    const candidateKeys = new Set(candidates.map((p) => p.key))
+    /** 汇总单个废弃权限的菜单、授权引用及部署阻断原因，供清理确认使用。 */
+    const items = candidates.map((p) => {
+      const bound = rows.filter((m) => m.permissionKey === p.key)
+      const blockedReasons: string[] = []
+      if (bound.some((m) => m.status === 'active')) blockedReasons.push('功能尚未停用')
+      if (bound.some((m) => m.protected)) blockedReasons.push('属于受保护管理入口')
+      /** 递归判断菜单是否包含不在本轮废弃候选集合中的后代，避免清理时误删保留节点。 */
+      const hasActiveDescendant = (id: string): boolean =>
+        rows
+          .filter((m) => m.parentId === id)
+          .some(
+            (m) =>
+              !m.permissionKey || !candidateKeys.has(m.permissionKey) || hasActiveDescendant(m.id),
+          )
+      if (bound.some((m) => hasActiveDescendant(m.id))) blockedReasons.push('存在非废弃子节点')
+      if (proof?.proof.serviceVersions.some((v) => v.requiredPermissionKeys.includes(p.key)))
+        blockedReasons.push('在用服务版本仍依赖此权限')
+      return {
+        permissionKey: p.key,
+        title: p.title,
+        menuIds: bound.map((m) => m.id),
+        roleCount: grants.filter((g) => g.permissionKey === p.key).length,
+        blockedReasons,
+      }
+    })
+    const blockedReasons = proof ? [] : ['缺少有效且完整的部署证明']
+    return {
+      catalogVersion: ACCESS_CATALOG_VERSION,
+      deploymentId: proof?.proof.deploymentId ?? null,
+      proofDigest: proof?.digest ?? null,
+      eligible:
+        items.length > 0 && !blockedReasons.length && items.every((i) => !i.blockedReasons.length),
+      blockedReasons,
+      items,
+      totals: {
+        permissions: items.length,
+        menus: items.reduce((n, i) => n + i.menuIds.length, 0),
+        roleAssignments: items.reduce((n, i) => n + i.roleCount, 0),
+      },
+    }
+  }
+  /** 要求平台管理员具备清理权限，在只读事务内生成废弃权限清理预览。 */
+  preview(actor: AccessActor) {
+    return this.access.read(
+      { actor, scope: { type: 'platform' }, permission: 'platform.menus.cleanup', adminOnly: true },
+      (tx) => this.inspect(tx),
+    )
+  }
+  /**
+   * 在权限写锁保护下复核部署证明和引用关系，清理指定废弃权限及其菜单、角色授权。
+   *
+   * 写入清理墓碑以保证重复请求幂等，递增受影响版本并记录审计；任何阻断均使事务回滚。
+   * @param body - 待清理权限键及用户预览时确认的部署证明摘要。
+   * @returns 实际移除和此前已清理的权限键，以及受影响菜单、角色授权数量。
+   */
+  cleanup(actor: AccessActor, body: CleanupRequest) {
+    return this.access.write(
+      { actor, scope: { type: 'platform' }, permission: 'platform.menus.cleanup', adminOnly: true },
+      /** 在锁内复核证明和清理范围，按叶节点顺序删除菜单并同步版本、墓碑和审计。 */
+      async (tx, access): Promise<CleanupResult> => {
+        const preview = await this.inspect(tx)
+        if (preview.proofDigest !== body.proofDigest || preview.blockedReasons.length)
+          throw new AppException(ACCESS_ERRORS.CLEANUP_BLOCKED)
+        const cleaned = new Set(
+          (await tx.select().from(cleanupTombstones)).map((t) => t.permissionKey),
+        )
+        const requested = body.permissionKeys.filter((k) => !cleaned.has(k))
+        for (const key of requested) {
+          const item = preview.items.find((i) => i.permissionKey === key)
+          if (!item || item.blockedReasons.length)
+            throw new AppException(ACCESS_ERRORS.CLEANUP_BLOCKED)
+        }
+        const rows = requested.length
+          ? await tx.select().from(menus).where(inArray(menus.permissionKey, requested))
+          : []
+        const allRows = await tx.select().from(menus)
+        if (
+          rows.some((row) =>
+            allRows.some(
+              (child) => child.parentId === row.id && !rows.some((r) => r.id === child.id),
+            ),
+          )
+        )
+          throw new AppException(ACCESS_ERRORS.RESOURCE_IN_USE)
+        const grants = requested.length
+          ? await tx
+              .select()
+              .from(rolePermissions)
+              .where(inArray(rolePermissions.permissionKey, requested))
+          : []
+        if (requested.length) {
+          if (grants.length)
+            await tx
+              .update(roles)
+              .set({ version: sql`${roles.version} + 1`, updatedAt: new Date() })
+              .where(inArray(roles.id, [...new Set(grants.map((g) => g.roleId))]))
+          await tx.delete(rolePermissions).where(inArray(rolePermissions.permissionKey, requested))
+          const remaining = [...rows]
+          while (remaining.length) {
+            const leaf = remaining.find((r) => !remaining.some((child) => child.parentId === r.id))
+            if (!leaf) throw new AppException(ACCESS_ERRORS.RESOURCE_IN_USE)
+            await tx.delete(menus).where(eq(menus.id, leaf.id))
+            remaining.splice(remaining.indexOf(leaf), 1)
+          }
+          await tx.delete(permissions).where(inArray(permissions.key, requested))
+          await tx.insert(cleanupTombstones).values(
+            requested.map((permissionKey) => ({
+              permissionKey,
+              deploymentId: preview.deploymentId!,
+            })),
+          )
+          const scopes = [
+            ...new Set(
+              ACCESS_PERMISSION_CATALOG.filter((p) => requested.includes(p.key)).map(
+                (p) => p.scopeType,
+              ),
+            ),
+          ]
+          await tx
+            .update(menuVersions)
+            .set({ version: sql`${menuVersions.version} + 1` })
+            .where(inArray(menuVersions.scopeType, scopes))
+          await this.access.audit(tx, {
+            actor,
+            access,
+            action: 'permission.cleanup',
+            objectType: 'permission',
+            objectId: preview.deploymentId!,
+            summary: {
+              permissionKeys: requested,
+              removedMenus: rows.length,
+              removedRoleAssignments: grants.length,
+            },
+          })
+        }
+        return {
+          removedPermissionKeys: requested,
+          alreadyCleanedPermissionKeys: body.permissionKeys.filter((k) => cleaned.has(k)),
+          removedMenuCount: rows.length,
+          removedRoleAssignmentCount: grants.length,
+        }
+      },
+    )
+  }
+}

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

@@ -0,0 +1,7 @@
+import { z } from 'zod'
+import { permissionKeysSchema } from '../access.validation'
+
+export const cleanupSchema = z.strictObject({
+  permissionKeys: permissionKeysSchema.min(1),
+  proofDigest: z.string().regex(/^[a-f0-9]{64}$/),
+})

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

@@ -0,0 +1,80 @@
+import { Body, Controller, Delete, Get, Patch, Post, Put, Query, Req } from '@nestjs/common'
+import type { FastifyRequest } from 'fastify'
+import { AccessPolicy } from '@/common/decorators/access-policy.decorator'
+import { RolesService } from './roles.service'
+import { actor, ids, scopeFor } from '../access-http'
+import { deleteSchema, pageSchema, parse } from '../access.validation'
+import { createRoleSchema, permissionsSchema, updateRoleSchema } from './roles.validation'
+
+@Controller(['platform', 'companies/:companyId', 'companies/:companyId/projects/:projectId'])
+export class RolesController {
+  constructor(private readonly roles: RolesService) {}
+  /** 校验分页查询参数，按路由作用域返回可读取的角色列表。 */
+  @Get('roles')
+  @AccessPolicy({ scope: 'route' })
+  list(@Req() req: FastifyRequest, @Query() query: unknown) {
+    return this.roles.list({
+      actor: actor(req),
+      scope: scopeFor(req),
+      query: parse(pageSchema, query),
+    })
+  }
+  /** 校验路由标识，读取当前作用域中的指定角色详情。 */
+  @Get('roles/:roleId')
+  @AccessPolicy({ scope: 'route' })
+  get(@Req() req: FastifyRequest) {
+    return this.roles.get({ actor: actor(req), scope: scopeFor(req), roleId: ids(req).roleId! })
+  }
+  /** 按路由作用域获取角色授权页面所需的权限树和可授权权限键。 */
+  @Get('permissions')
+  @AccessPolicy({ scope: 'route' })
+  permissions(@Req() req: FastifyRequest) {
+    return this.roles.permissions({ actor: actor(req), scope: scopeFor(req) })
+  }
+  /** 校验创建请求并在路由对应作用域创建自定义角色。 */
+  @Post('roles')
+  @AccessPolicy({ scope: 'route', permission: '{scope}.roles.create' })
+  create(@Req() req: FastifyRequest, @Body() body: unknown) {
+    return this.roles.create({
+      actor: actor(req),
+      scope: scopeFor(req),
+      body: parse(createRoleSchema, body),
+    })
+  }
+  /** 校验角色标识、预期版本和资料字段，提交当前作用域的角色更新。 */
+  @Patch('roles/:roleId')
+  @AccessPolicy({ scope: 'route', permission: '{scope}.roles.update' })
+  update(@Req() req: FastifyRequest, @Body() body: unknown) {
+    return this.roles.change({
+      actor: actor(req),
+      scope: scopeFor(req),
+      roleId: ids(req).roleId!,
+      action: 'update',
+      body: parse(updateRoleSchema, body),
+    })
+  }
+  /** 校验预期版本与权限键集合，提交当前作用域的角色权限全量替换。 */
+  @Put('roles/:roleId/permissions')
+  @AccessPolicy({ scope: 'route', permission: '{scope}.roles.permissions' })
+  permissionsUpdate(@Req() req: FastifyRequest, @Body() body: unknown) {
+    return this.roles.change({
+      actor: actor(req),
+      scope: scopeFor(req),
+      roleId: ids(req).roleId!,
+      action: 'permissions',
+      body: parse(permissionsSchema, body),
+    })
+  }
+  /** 从查询参数校验预期版本，提交当前作用域的自定义角色删除。 */
+  @Delete('roles/:roleId')
+  @AccessPolicy({ scope: 'route', permission: '{scope}.roles.delete' })
+  remove(@Req() req: FastifyRequest, @Query() query: unknown) {
+    return this.roles.change({
+      actor: actor(req),
+      scope: scopeFor(req),
+      roleId: ids(req).roleId!,
+      action: 'delete',
+      body: parse(deleteSchema, query),
+    })
+  }
+}