create-bubbles 0.1.26 → 0.1.28

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

@@ -0,0 +1,230 @@
+import { Injectable } from '@nestjs/common'
+import { eq, sql } from 'drizzle-orm'
+import { menus, menuVersions, rolePermissions } from '@/database/schema'
+import type { CreateMenuRequest, MenuTreeResult, ScopeType, UpdateMenuRequest } from 'shared/types'
+import {
+  ACCESS_CATALOG_VERSION,
+  ACCESS_ICON_KEY_PATTERN,
+  ACCESS_PAGE_CATALOG,
+  ACCESS_PERMISSION_CATALOG,
+  ACCESS_PROTECTED_ROUTE_KEYS,
+} from 'shared/utils'
+import { AppException } from '@/common/exceptions/app.exception'
+import { AccessService, type AccessActor } from '@/modules/access/access.service'
+import { ACCESS_ERRORS } from '@/modules/access/access.errors'
+import { checkVersion, requireFound, type AccessDb } from '@/modules/access/access.store'
+
+type MenuRow = typeof menus.$inferSelect
+@Injectable()
+export class MenusService {
+  constructor(private readonly access: AccessService) {}
+  /** 读取指定作用域类型的完整菜单树及版本，供管理端展示和并发修改校验。 */
+  async tree(db: AccessDb, scopeType: ScopeType): Promise<MenuTreeResult> {
+    const rows = await db.select().from(menus).where(eq(menus.scopeType, scopeType))
+    const [version] = await db
+      .select()
+      .from(menuVersions)
+      .where(eq(menuVersions.scopeType, scopeType))
+    return { scopeType, version: version?.version ?? 1, items: this.access.tree(rows) }
+  }
+  /** 校验平台菜单读取权限后，返回指定作用域类型的代码权限目录和目录版本。 */
+  catalog(input: { actor: AccessActor; scopeType: ScopeType }) {
+    return this.access.read(
+      { actor: input.actor, scope: { type: 'platform' }, permission: 'platform.menus.read' },
+      async () => ({
+        catalogVersion: ACCESS_CATALOG_VERSION,
+        items: ACCESS_PERMISSION_CATALOG.filter((p) => p.scopeType === input.scopeType).map(
+          (p) => ({ ...p }),
+        ),
+      }),
+    )
+  }
+  /** 校验平台菜单读取权限后，读取指定作用域类型的完整菜单树。 */
+  list(input: { actor: AccessActor; scopeType: ScopeType }) {
+    return this.access.read(
+      { actor: input.actor, scope: { type: 'platform' }, permission: 'platform.menus.read' },
+      (tx) => this.tree(tx, input.scopeType),
+    )
+  }
+  /**
+   * 校验菜单父子类型、作用域、权限绑定、图标和无环约束，并保护管理入口及其祖先可见可用。
+   *
+   * @param rows - 拟保存的完整作用域菜单集合，权限绑定在该集合内必须唯一。
+   * @throws 非法结构、重复权限绑定或受保护菜单被隐藏停用时抛出业务异常。
+   */
+  validate(rows: MenuRow[]) {
+    const byId = new Map(rows.map((m) => [m.id, m]))
+    for (const row of rows) {
+      if (row.icon && !ACCESS_ICON_KEY_PATTERN.test(row.icon))
+        throw new AppException(ACCESS_ERRORS.INVALID_MENU_STRUCTURE)
+      const parent = row.parentId ? byId.get(row.parentId) : undefined
+      if (row.parentId && (!parent || parent.scopeType !== row.scopeType))
+        throw new AppException(ACCESS_ERRORS.INVALID_MENU_STRUCTURE)
+      if (row.type === 'operation') {
+        const permission = ACCESS_PERMISSION_CATALOG.find((p) => p.key === row.permissionKey)
+        if (
+          !parent ||
+          parent.type !== 'page' ||
+          parent.permissionKey !== permission?.pagePermissionKey
+        )
+          throw new AppException(ACCESS_ERRORS.INVALID_MENU_STRUCTURE)
+      } else if (parent && parent.type !== 'directory')
+        throw new AppException(ACCESS_ERRORS.INVALID_MENU_STRUCTURE)
+      const visited = new Set([row.id])
+      let ancestor = parent
+      while (ancestor) {
+        if (visited.has(ancestor.id)) throw new AppException(ACCESS_ERRORS.INVALID_MENU_STRUCTURE)
+        visited.add(ancestor.id)
+        ancestor = ancestor.parentId ? byId.get(ancestor.parentId) : undefined
+      }
+      if (row.protected) {
+        let protectedNode: MenuRow | undefined = row
+        while (protectedNode) {
+          if (protectedNode.status !== 'active' || protectedNode.hidden)
+            throw new AppException(ACCESS_ERRORS.PROTECTED_MENU)
+          protectedNode = protectedNode.parentId ? byId.get(protectedNode.parentId) : undefined
+        }
+      }
+    }
+    const bindings = rows.filter((r) => r.permissionKey).map((r) => r.permissionKey)
+    if (new Set(bindings).size !== bindings.length)
+      throw new AppException(ACCESS_ERRORS.DUPLICATE_RESOURCE)
+  }
+  /**
+   * 校验平台菜单创建权限和树版本，将目录、页面或操作绑定到合法权限后加入菜单树。
+   *
+   * 校验整棵树的结构，写入菜单、递增树版本并记录审计，返回更新后的菜单树。
+   */
+  create(input: { actor: AccessActor; scopeType: ScopeType; body: CreateMenuRequest }) {
+    return this.access.write(
+      { actor: input.actor, scope: { type: 'platform' }, permission: 'platform.menus.create' },
+      /** 依据当前树版本解析权限绑定并验证新增节点，菜单写入与版本、审计同步提交。 */
+      async (tx, access) => {
+        const tree = await this.tree(tx, input.scopeType)
+        checkVersion(tree.version, input.body.expectedVersion)
+        const rows = await tx.select().from(menus).where(eq(menus.scopeType, input.scopeType))
+        const body = input.body
+        const permission =
+          body.type === 'page'
+            ? ACCESS_PERMISSION_CATALOG.find(
+                (p) =>
+                  p.kind === 'page' &&
+                  p.routeKey === body.routeKey &&
+                  p.scopeType === input.scopeType,
+              )
+            : body.type === 'operation'
+              ? ACCESS_PERMISSION_CATALOG.find(
+                  (p) =>
+                    p.key === body.permissionKey &&
+                    p.kind === 'operation' &&
+                    p.scopeType === input.scopeType,
+                )
+              : undefined
+        if (
+          (body.type !== 'directory' && (!permission || permission.deprecated)) ||
+          (body.type === 'directory' && (body.routeKey || body.permissionKey)) ||
+          (body.type === 'page' && body.permissionKey) ||
+          (body.type === 'operation' && body.routeKey)
+        )
+          throw new AppException(ACCESS_ERRORS.INVALID_MENU_STRUCTURE)
+        const now = new Date()
+        const defaultIcon =
+          body.type === 'page'
+            ? (ACCESS_PAGE_CATALOG.find((page) => page.routeKey === permission?.routeKey)?.icon ?? '')
+            : ''
+        const row: MenuRow = {
+          id: crypto.randomUUID(),
+          scopeType: input.scopeType,
+          parentId: body.parentId ?? null,
+          type: body.type,
+          name: body.name,
+          icon: body.icon ?? defaultIcon,
+          sort: body.sort ?? 0,
+          hidden: body.hidden ?? false,
+          status: body.status ?? 'active',
+          routeKey: permission?.routeKey ?? null,
+          permissionKey: permission?.key ?? null,
+          protected: permission
+            ? (ACCESS_PROTECTED_ROUTE_KEYS as readonly string[]).includes(permission.routeKey)
+            : false,
+          createdAt: now,
+          updatedAt: now,
+        }
+        this.validate([...rows, row])
+        await tx.insert(menus).values(row)
+        await tx
+          .update(menuVersions)
+          .set({ version: sql`${menuVersions.version} + 1` })
+          .where(eq(menuVersions.scopeType, input.scopeType))
+        await this.access.audit(tx, {
+          actor: input.actor,
+          access,
+          action: 'menu.create',
+          objectType: 'menu',
+          objectId: row.id,
+          summary: { scopeType: input.scopeType },
+        })
+        return this.tree(tx, input.scopeType)
+      },
+    )
+  }
+  /**
+   * 按平台菜单操作权限修改或删除节点，校验树版本、结构与受保护入口限制。
+   *
+   * 删除前要求没有子节点及角色权限引用；成功后递增树版本、记录审计并返回更新后的树。
+   */
+  change(input: {
+    actor: AccessActor
+    menuId: string
+    body: UpdateMenuRequest | { expectedVersion: number }
+    action: 'update' | 'delete'
+  }) {
+    return this.access.write(
+      {
+        actor: input.actor,
+        scope: { type: 'platform' },
+        permission: `platform.menus.${input.action}`,
+      },
+      /** 读取锁内最新菜单，验证修改或删除条件后同步更新菜单树版本与审计。 */
+      async (tx, access) => {
+        const [existing] = await tx.select().from(menus).where(eq(menus.id, input.menuId))
+        const row = requireFound(existing)
+        checkVersion((await this.tree(tx, row.scopeType)).version, input.body.expectedVersion)
+        const rows = await tx.select().from(menus).where(eq(menus.scopeType, row.scopeType))
+        if (input.action === 'delete') {
+          if (row.protected) throw new AppException(ACCESS_ERRORS.PROTECTED_MENU)
+          const references = row.permissionKey
+            ? await tx
+                .select()
+                .from(rolePermissions)
+                .where(eq(rolePermissions.permissionKey, row.permissionKey))
+            : []
+          if (rows.some((r) => r.parentId === row.id) || references.length)
+            throw new AppException(ACCESS_ERRORS.RESOURCE_IN_USE)
+          await tx.delete(menus).where(eq(menus.id, row.id))
+        } else {
+          const { expectedVersion: _, ...changes } = input.body as UpdateMenuRequest
+          const updated = { ...row, ...changes, updatedAt: new Date() }
+          this.validate(rows.map((r) => (r.id === row.id ? updated : r)))
+          await tx.update(menus).set(changes).where(eq(menus.id, row.id))
+        }
+        await tx
+          .update(menuVersions)
+          .set({ version: sql`${menuVersions.version} + 1` })
+          .where(eq(menuVersions.scopeType, row.scopeType))
+        await this.access.audit(tx, {
+          actor: input.actor,
+          access,
+          action: `menu.${input.action}`,
+          objectType: 'menu',
+          objectId: row.id,
+          summary: {
+            scopeType: row.scopeType,
+            changedFields: Object.keys(input.body).filter((k) => k !== 'expectedVersion'),
+          },
+        })
+        return this.tree(tx, row.scopeType)
+      },
+    )
+  }
+}

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

@@ -0,0 +1,30 @@
+import { z } from 'zod'
+import { ACCESS_ICON_KEY_PATTERN } from 'shared/utils'
+import { idSchema, scopeTypeSchema, versionSchema } from '@/modules/access/access.validation'
+
+export const menuQuerySchema = z.strictObject({ scopeType: scopeTypeSchema })
+const menuFields = {
+  parentId: idSchema.nullable().optional(),
+  name: z.string().trim().min(1).max(100),
+  icon: z
+    .string()
+    .max(64)
+    .refine((value) => !value || ACCESS_ICON_KEY_PATTERN.test(value))
+    .optional(),
+  sort: z.number().int().min(0).max(100000).optional(),
+  hidden: z.boolean().optional(),
+  status: z.enum(['active', 'disabled']).optional(),
+}
+export const createMenuSchema = z.strictObject({
+  expectedVersion: versionSchema,
+  type: z.enum(['directory', 'page', 'operation']),
+  ...menuFields,
+  parentId: idSchema.nullable(),
+  routeKey: z.string().max(120).optional(),
+  permissionKey: z.string().max(150).optional(),
+})
+export const updateMenuSchema = z.strictObject({
+  expectedVersion: versionSchema,
+  ...menuFields,
+  name: menuFields.name.optional(),
+})

package/template-vp-monorepo-react-nestjs/apps/server/src/modules/organization/candidates/global-account/global-account-candidates.controller.ts

@@ -0,0 +1,35 @@
+import { Body, Controller, Get, Post, Query, Req } from '@nestjs/common'
+import type { FastifyRequest } from 'fastify'
+import { AccessPolicy } from '@/common/decorators/access-policy.decorator'
+import { actor } from '@/modules/access/access-http'
+import { parse } from '@/modules/access/access.validation'
+import {
+  globalAccountCandidateQuerySchema,
+  resolveGlobalAccountCandidatesSchema,
+} from '../../organization.validation'
+import { GlobalAccountCandidatesService } from './global-account-candidates.service'
+
+@Controller()
+export class GlobalAccountCandidatesController {
+  constructor(private readonly candidates: GlobalAccountCandidatesService) {}
+
+  /** 校验用途与分页参数，并按用途对应的平台管理权限搜索全局账号候选。 */
+  @Get('platform/account-candidates')
+  @AccessPolicy({ scope: 'platform' })
+  search(@Req() req: FastifyRequest, @Query() query: unknown) {
+    return this.candidates.search({
+      actor: actor(req),
+      query: parse(globalAccountCandidateQuerySchema, query),
+    })
+  }
+
+  /** 校验最多一百个去重 userId，并按请求顺序回显有权查看的账号候选。 */
+  @Post('platform/account-candidates/resolve')
+  @AccessPolicy({ scope: 'platform' })
+  resolve(@Req() req: FastifyRequest, @Body() body: unknown) {
+    return this.candidates.resolve({
+      actor: actor(req),
+      body: parse(resolveGlobalAccountCandidatesSchema, body),
+    })
+  }
+}

package/template-vp-monorepo-react-nestjs/apps/server/src/modules/organization/candidates/global-account/global-account-candidates.service.ts

@@ -0,0 +1,109 @@
+import { Injectable } from '@nestjs/common'
+import { asc, count, inArray, sql } from 'drizzle-orm'
+import { users } from '@/database/schema'
+import {
+  AccessService,
+  type AccessActor,
+  type AccessRequirement,
+} from '@/modules/access/access.service'
+import { pageWindow, searchSql } from '@/modules/access/access.store'
+import type {
+  GlobalAccountCandidate,
+  GlobalAccountCandidatePurpose,
+  GlobalAccountCandidateQuery,
+  PageResult,
+  ResolveGlobalAccountCandidatesRequest,
+} from 'shared/types'
+
+@Injectable()
+export class GlobalAccountCandidatesService {
+  constructor(private readonly access: AccessService) {}
+
+  /** 根据平台账号候选用途映射固定权限，禁止客户端直接指定权限键。 */
+  private requirement(
+    actor: AccessActor,
+    purpose: GlobalAccountCandidatePurpose,
+  ): AccessRequirement {
+    return {
+      actor,
+      scope: { type: 'platform' },
+      permission:
+        purpose === 'createCompanyAdministrator'
+          ? 'platform.companies.create'
+          : 'platform.companies.administrator',
+      adminOnly: true,
+    }
+  }
+
+  /** 将账号数据库行转换为全局候选，并为不可用账号附加稳定禁选原因。 */
+  private candidate(
+    row: Pick<typeof users.$inferSelect, 'id' | 'account' | 'name' | 'status'>,
+  ): GlobalAccountCandidate {
+    const disabled = row.status !== 'active'
+    return {
+      userId: row.id,
+      account: row.account,
+      name: row.name,
+      status: row.status,
+      disabled,
+      disabledReason: disabled ? 'accountInactive' : null,
+    }
+  }
+
+  /** 按用途鉴权后，以姓名或完整账号执行服务端分页搜索。 */
+  search(input: {
+    actor: AccessActor
+    query: GlobalAccountCandidateQuery
+  }): Promise<PageResult<GlobalAccountCandidate>> {
+    return this.access.read(this.requirement(input.actor, input.query.purpose), async (tx) => {
+      const { page, pageSize, offset } = pageWindow(input.query)
+      const condition = searchSql([users.name, users.account], input.query.query)
+      const [total] = await tx.select({ value: count() }).from(users).where(condition)
+      const rows = await tx
+        .select({
+          id: users.id,
+          account: users.account,
+          name: users.name,
+          status: users.status,
+        })
+        .from(users)
+        .where(condition)
+        .orderBy(
+          asc(sql<string>`lower(normalize(btrim(${users.name}), NFKC))`),
+          asc(users.account),
+          asc(users.id),
+        )
+        .limit(pageSize)
+        .offset(offset)
+      return {
+        items: rows.map((row) => this.candidate(row)),
+        total: total!.value,
+        page,
+        pageSize,
+      }
+    })
+  }
+
+  /** 按请求 userId 顺序回显已知账号；未知 ID 不返回占位，停用账号仍稳定回显。 */
+  resolve(input: {
+    actor: AccessActor
+    body: ResolveGlobalAccountCandidatesRequest
+  }): Promise<GlobalAccountCandidate[]> {
+    return this.access.read(this.requirement(input.actor, input.body.purpose), async (tx) => {
+      const rows = await tx
+        .select({
+          id: users.id,
+          account: users.account,
+          name: users.name,
+          status: users.status,
+        })
+        .from(users)
+        .where(inArray(users.id, input.body.userIds))
+      const byUserId = new Map(rows.map((row) => [row.id, this.candidate(row)]))
+      return input.body.userIds.flatMap((userId) => {
+        const candidate = byUserId.get(userId)
+        return candidate ? [candidate] : []
+      })
+    })
+  }
+}

package/template-vp-monorepo-react-nestjs/apps/server/src/modules/organization/candidates/member-candidates.controller.ts

@@ -0,0 +1,60 @@
+import { Body, Controller, Get, Post, 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 type { OrganizationScope } from 'shared/types'
+import {
+  organizationMemberCandidateQuerySchema,
+  resolveOrganizationMemberCandidatesSchema,
+} from '../organization.validation'
+import { MemberCandidatesService } from './member-candidates.service'
+
+@Controller()
+export class MemberCandidatesController {
+  constructor(private readonly candidates: MemberCandidatesService) {}
+
+  /** 按动态 purpose 权限分页搜索企业成员及获准项目身份。 */
+  @Get('companies/:companyId/organization/member-candidates')
+  @AccessPolicy({ scope: 'route' })
+  searchCompany(@Req() req: FastifyRequest, @Query() query: unknown) {
+    return this.candidates.search({
+      actor: actor(req),
+      scope: scopeFor(req) as OrganizationScope,
+      query: parse(organizationMemberCandidateQuerySchema, query),
+    })
+  }
+
+  /** 按动态 purpose 权限分页搜索当前项目成员身份。 */
+  @Get('companies/:companyId/projects/:projectId/organization/member-candidates')
+  @AccessPolicy({ scope: 'route' })
+  searchProject(@Req() req: FastifyRequest, @Query() query: unknown) {
+    return this.candidates.search({
+      actor: actor(req),
+      scope: scopeFor(req) as OrganizationScope,
+      query: parse(organizationMemberCandidateQuerySchema, query),
+    })
+  }
+
+  /** 按请求 userId 顺序回显企业候选，未知或越权用户不返回占位。 */
+  @Post('companies/:companyId/organization/member-candidates/resolve')
+  @AccessPolicy({ scope: 'route' })
+  resolveCompany(@Req() req: FastifyRequest, @Body() body: unknown) {
+    return this.candidates.resolve({
+      actor: actor(req),
+      scope: scopeFor(req) as OrganizationScope,
+      body: parse(resolveOrganizationMemberCandidatesSchema, body),
+    })
+  }
+
+  /** 按请求 userId 顺序回显项目候选，未知或越权用户不返回占位。 */
+  @Post('companies/:companyId/projects/:projectId/organization/member-candidates/resolve')
+  @AccessPolicy({ scope: 'route' })
+  resolveProject(@Req() req: FastifyRequest, @Body() body: unknown) {
+    return this.candidates.resolve({
+      actor: actor(req),
+      scope: scopeFor(req) as OrganizationScope,
+      body: parse(resolveOrganizationMemberCandidatesSchema, body),
+    })
+  }
+}