create-bubbles 0.1.26 → 0.1.27

package/template-vp-monorepo-react-nestjs/apps/server/src/modules/organization/initialization/project-organization-initialization.service.ts

@@ -0,0 +1,189 @@
+import { randomUUID } from 'node:crypto'
+import { Injectable } from '@nestjs/common'
+import { and, eq } from 'drizzle-orm'
+import { AppException } from '@/common/exceptions/app.exception'
+import {
+  organizationTemplates,
+  organizationTrees,
+  organizationUnits,
+  positions,
+} from '@/database/schema'
+import { ACCESS_ERRORS } from '@/modules/access/access.errors'
+import {
+  AccessService,
+  type AccessActor,
+  type VerifiedAccess,
+} from '@/modules/access/access.service'
+import { requireFound, type AccessTx } from '@/modules/access/access.store'
+import type { ProjectOrganizationInitialization } from 'shared/types'
+import { OrganizationTemplatesService } from '../templates/organization-templates.service'
+
+export interface ProjectOrganizationInitializationResult {
+  mode: 'blank' | 'template'
+  templateId: string | null
+  templateVersion: number | null
+  unitCount: number
+  positionCount: number
+}
+
+@Injectable()
+export class ProjectOrganizationInitializationService {
+  constructor(
+    private readonly access: AccessService,
+    private readonly templates: OrganizationTemplatesService,
+  ) {}
+
+  /** 创建项目唯一组织树，调用方必须与项目创建处于同一事务。 */
+  private async createTree(
+    tx: AccessTx,
+    input: { companyId: string; projectId: string },
+  ): Promise<string> {
+    const [tree] = await tx
+      .insert(organizationTrees)
+      .values({
+        scopeType: 'project',
+        companyId: input.companyId,
+        projectId: input.projectId,
+      })
+      .returning({ id: organizationTrees.id })
+    return requireFound(tree).id
+  }
+
+  /**
+   * 把模板指定版本的完整组织单元与岗位复制为项目独立资源，并保留来源子项 ID。
+   */
+  private async copyTemplate(
+    tx: AccessTx,
+    input: {
+      companyId: string
+      projectId: string
+      treeId: string
+      templateId: string
+      templateVersion: number
+    },
+  ): Promise<{ unitCount: number; positionCount: number }> {
+    const snapshot = await this.templates.snapshot(tx, {
+      templateId: input.templateId,
+      templateVersion: input.templateVersion,
+    })
+    const unitIds = new Map(snapshot.units.map((unit) => [unit.id, randomUUID()]))
+    if (snapshot.units.length)
+      await tx.insert(organizationUnits).values(
+        snapshot.units.map((unit) => ({
+          id: unitIds.get(unit.id)!,
+          treeId: input.treeId,
+          parentId: unit.parentId ? unitIds.get(unit.parentId)! : null,
+          name: unit.name,
+          nameKey: unit.nameKey,
+          code: unit.code,
+          codeKey: unit.codeKey,
+          description: unit.description,
+          sort: unit.sort,
+          status: 'active' as const,
+          sourceTemplateUnitId: unit.id,
+        })),
+      )
+    if (snapshot.positions.length)
+      await tx.insert(positions).values(
+        snapshot.positions.map((position) => ({
+          scopeType: 'project' as const,
+          companyId: input.companyId,
+          projectId: input.projectId,
+          name: position.name,
+          nameKey: position.nameKey,
+          code: position.code,
+          codeKey: position.codeKey,
+          description: position.description,
+          status: position.status,
+          sourceTemplatePositionId: position.id,
+        })),
+      )
+    return {
+      unitCount: snapshot.units.length,
+      positionCount: snapshot.positions.length,
+    }
+  }
+
+  /**
+   * 在项目创建事务内初始化空组织或复制当前企业模板，并以项目作用域写初始化审计。
+   *
+   * 模板模式额外要求企业模板读取权限，且只允许复制所属企业中启用的当前版本。
+   */
+  async initializeProject(
+    tx: AccessTx,
+    input: {
+      companyId: string
+      projectId: string
+      initialization: ProjectOrganizationInitialization
+      actor: AccessActor
+      access: VerifiedAccess
+    },
+  ): Promise<ProjectOrganizationInitializationResult> {
+    let result: ProjectOrganizationInitializationResult
+    if (input.initialization.mode === 'blank') {
+      await this.createTree(tx, input)
+      result = {
+        mode: 'blank',
+        templateId: null,
+        templateVersion: null,
+        unitCount: 0,
+        positionCount: 0,
+      }
+    } else {
+      if (!input.access.permissionKeys.includes('company.organization.templates.read'))
+        throw new AppException(ACCESS_ERRORS.FORBIDDEN)
+      const [template] = await tx
+        .select()
+        .from(organizationTemplates)
+        .where(
+          and(
+            eq(organizationTemplates.companyId, input.companyId),
+            eq(organizationTemplates.id, input.initialization.templateId),
+          ),
+        )
+        .limit(1)
+      const currentTemplate = requireFound(template)
+      if (currentTemplate.status !== 'active')
+        throw new AppException(ACCESS_ERRORS.TEMPLATE_UNAVAILABLE)
+      if (currentTemplate.version !== input.initialization.templateVersion)
+        throw new AppException(ACCESS_ERRORS.TEMPLATE_VERSION_CONFLICT)
+      const treeId = await this.createTree(tx, input)
+      const counts = await this.copyTemplate(tx, {
+        companyId: input.companyId,
+        projectId: input.projectId,
+        treeId,
+        templateId: currentTemplate.id,
+        templateVersion: currentTemplate.version,
+      })
+      result = {
+        mode: 'template',
+        templateId: currentTemplate.id,
+        templateVersion: currentTemplate.version,
+        ...counts,
+      }
+    }
+
+    await this.access.audit(tx, {
+      actor: input.actor,
+      access: {
+        ...input.access,
+        scope: {
+          type: 'project',
+          companyId: input.companyId,
+          projectId: input.projectId,
+        },
+      },
+      action: 'project.organization.initialize',
+      objectType: 'project',
+      objectId: input.projectId,
+      summary: {
+        mode: result.mode,
+        templateId: result.templateId,
+        templateVersion: result.templateVersion,
+        unitCount: result.unitCount,
+        positionCount: result.positionCount,
+      },
+    })
+    return result
+  }
+}

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

@@ -0,0 +1,34 @@
+import { Module } from '@nestjs/common'
+import { AccessModule } from '../access/access.module'
+import { GlobalAccountCandidatesController } from './candidates/global-account/global-account-candidates.controller'
+import { GlobalAccountCandidatesService } from './candidates/global-account/global-account-candidates.service'
+import { MemberCandidatesController } from './candidates/member-candidates.controller'
+import { MemberCandidatesService } from './candidates/member-candidates.service'
+import { ProjectOrganizationInitializationService } from './initialization/project-organization-initialization.service'
+import { PositionsController } from './positions/positions.controller'
+import { PositionsService } from './positions/positions.service'
+import { OrganizationTemplatesController } from './templates/organization-templates.controller'
+import { OrganizationTemplatesService } from './templates/organization-templates.service'
+import { OrganizationUnitsController } from './units/organization-units.controller'
+import { OrganizationUnitsService } from './units/organization-units.service'
+
+@Module({
+  imports: [AccessModule],
+  controllers: [
+    OrganizationUnitsController,
+    PositionsController,
+    OrganizationTemplatesController,
+    MemberCandidatesController,
+    GlobalAccountCandidatesController,
+  ],
+  providers: [
+    OrganizationUnitsService,
+    PositionsService,
+    OrganizationTemplatesService,
+    MemberCandidatesService,
+    GlobalAccountCandidatesService,
+    ProjectOrganizationInitializationService,
+  ],
+  exports: [ProjectOrganizationInitializationService, OrganizationTemplatesService],
+})
+export class OrganizationModule {}

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

@@ -0,0 +1,150 @@
+import { and, eq, isNull } from 'drizzle-orm'
+import { AppException } from '@/common/exceptions/app.exception'
+import { organizationTrees, organizationUnits, positions } from '@/database/schema'
+import { ACCESS_ERRORS } from '@/modules/access/access.errors'
+import type { OrganizationDuty, OrganizationScope, OrganizationUnitRecord } from 'shared/types'
+import { ORGANIZATION_MAX_SORT } from 'shared/utils'
+
+export type OrganizationUnitRow = typeof organizationUnits.$inferSelect
+
+export interface OrganizationUnitDerivedFields {
+  depth: number
+  fullPath: string
+  effective: boolean
+  hasChildren: boolean
+}
+
+/** 将企业或项目组织作用域转换为新领域表使用的非空租户列。 */
+export function organizationScopeColumns(scope: OrganizationScope) {
+  return {
+    scopeType: scope.type,
+    companyId: scope.companyId,
+    projectId: scope.type === 'project' ? scope.projectId : null,
+  }
+}
+
+/** 构造组织树的完整企业或项目归属条件，避免裸 ID 跨租户读取。 */
+export function organizationTreeFilter(scope: OrganizationScope) {
+  return and(
+    eq(organizationTrees.scopeType, scope.type),
+    eq(organizationTrees.companyId, scope.companyId),
+    scope.type === 'project'
+      ? eq(organizationTrees.projectId, scope.projectId)
+      : isNull(organizationTrees.projectId),
+  )
+}
+
+/** 构造岗位的完整企业或项目归属条件。 */
+export function positionScopeFilter(scope: OrganizationScope) {
+  return and(
+    eq(positions.scopeType, scope.type),
+    eq(positions.companyId, scope.companyId),
+    scope.type === 'project'
+      ? eq(positions.projectId, scope.projectId)
+      : isNull(positions.projectId),
+  )
+}
+
+/**
+ * 根据整棵树的父子关系计算路径、深度、有效状态和直接子节点标记。
+ *
+ * 数据库只保存结构字段，这些值必须在同一读取快照中派生；若检测到历史脏数据形成循环，
+ * 以领域循环错误终止查询，避免递归失控或返回错误路径。
+ */
+export function deriveOrganizationUnits(
+  rows: OrganizationUnitRow[],
+): Map<string, OrganizationUnitDerivedFields> {
+  const byId = new Map(rows.map((row) => [row.id, row]))
+  const childCounts = new Map<string, number>()
+  for (const row of rows) {
+    if (row.parentId) childCounts.set(row.parentId, (childCounts.get(row.parentId) ?? 0) + 1)
+  }
+
+  const result = new Map<string, OrganizationUnitDerivedFields>()
+  const visiting = new Set<string>()
+  /** 递归解析一个节点，并复用已经完成的祖先计算结果。 */
+  const resolve = (row: OrganizationUnitRow): OrganizationUnitDerivedFields => {
+    const cached = result.get(row.id)
+    if (cached) return cached
+    if (visiting.has(row.id)) throw new AppException(ACCESS_ERRORS.ORGANIZATION_CYCLE)
+    visiting.add(row.id)
+    const parent = row.parentId ? byId.get(row.parentId) : undefined
+    const parentDerived = parent ? resolve(parent) : undefined
+    const derived = {
+      depth: (parentDerived?.depth ?? 0) + 1,
+      fullPath: parentDerived ? `${parentDerived.fullPath} / ${row.name}` : row.name,
+      effective: row.status === 'active' && (parentDerived?.effective ?? true),
+      hasChildren: (childCounts.get(row.id) ?? 0) > 0,
+    }
+    visiting.delete(row.id)
+    result.set(row.id, derived)
+    return derived
+  }
+  for (const row of rows) resolve(row)
+  return result
+}
+
+/** 将组织单元数据库记录和派生路径信息转换为公开接口记录。 */
+export function toOrganizationUnitRecord(
+  row: OrganizationUnitRow,
+  derived: OrganizationUnitDerivedFields,
+): OrganizationUnitRecord {
+  return {
+    id: row.id,
+    treeId: row.treeId,
+    parentId: row.parentId,
+    name: row.name,
+    code: row.code,
+    description: row.description,
+    sort: row.sort,
+    status: row.status,
+    version: row.version,
+    depth: derived.depth,
+    fullPath: derived.fullPath,
+    createdAt: row.createdAt.toISOString(),
+    updatedAt: row.updatedAt.toISOString(),
+  }
+}
+
+/** 返回同级末尾的下一个排序整数；最大值耗尽时抛出明确业务错误。 */
+export function nextOrganizationSort(rows: Array<{ sort: number }>): number {
+  const maximum = rows.reduce((value, row) => Math.max(value, row.sort), 0)
+  if (maximum >= ORGANIZATION_MAX_SORT)
+    throw new AppException(ACCESS_ERRORS.ORGANIZATION_SORT_EXHAUSTED)
+  return maximum + 1
+}
+
+/** 按负责人、协助负责人、普通成员的固定优先级返回关系排序值。 */
+export function organizationDutyOrder(duty: OrganizationDuty): number {
+  return duty === 'leader' ? 0 : duty === 'deputy' ? 1 : 2
+}
+
+/** 判断职责变化是否属于需要有效成员和有效组织单元的升级。 */
+export function isOrganizationDutyUpgrade(
+  previous: OrganizationDuty | undefined,
+  next: OrganizationDuty,
+): boolean {
+  if (!previous) return true
+  const rank: Record<OrganizationDuty, number> = { member: 0, deputy: 1, leader: 2 }
+  return rank[next] > rank[previous]
+}
+
+/** 统计集合替换中的新增、移除和保留项变化，供审计摘要复用。 */
+export function relationDiff<T>(input: {
+  previous: Map<string, T>
+  next: Map<string, T>
+  changed?: (before: T, after: T) => boolean
+}) {
+  let addedCount = 0
+  let removedCount = 0
+  let changedCount = 0
+  for (const [key, value] of input.next) {
+    const oldValue = input.previous.get(key)
+    if (oldValue === undefined) addedCount += 1
+    else if (input.changed?.(oldValue, value)) changedCount += 1
+  }
+  for (const key of input.previous.keys()) {
+    if (!input.next.has(key)) removedCount += 1
+  }
+  return { addedCount, removedCount, changedCount }
+}

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

@@ -0,0 +1,23 @@
+export {
+  createOrganizationTemplateSchema,
+  createOrganizationUnitSchema,
+  createPositionSchema,
+  globalAccountCandidateQuerySchema,
+  moveOrganizationUnitSchema,
+  organizationMemberCandidateQuerySchema,
+  organizationTemplateListQuerySchema,
+  organizationTreeQuerySchema,
+  positionListQuerySchema,
+  replaceMemberOrganizationUnitsSchema,
+  replaceMemberPositionsSchema,
+  replaceOrganizationTemplateSchema,
+  replaceOrganizationUnitMembersSchema,
+  replacePositionMembersSchema,
+  resolveGlobalAccountCandidatesSchema,
+  resolveOrganizationMemberCandidatesSchema,
+  statusRequestSchema,
+  updateCompanyHierarchySchema,
+  updateOrganizationTemplateStatusSchema,
+  updateOrganizationUnitSchema,
+  updatePositionSchema,
+} from 'shared/utils'

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

@@ -0,0 +1,160 @@
+import { Body, Controller, Get, Patch, Post, Put, Query, Req } from '@nestjs/common'
+import type { FastifyRequest } from 'fastify'
+import { AccessPolicy } from '@/common/decorators/access-policy.decorator'
+import { actor, ids, scopeFor } from '@/modules/access/access-http'
+import { parse } from '@/modules/access/access.validation'
+import type { OrganizationScope } from 'shared/types'
+import {
+  createPositionSchema,
+  positionListQuerySchema,
+  replaceMemberPositionsSchema,
+  replacePositionMembersSchema,
+  statusRequestSchema,
+  updatePositionSchema,
+} from '../organization.validation'
+import { PositionsService } from './positions.service'
+
+@Controller()
+export class PositionsController {
+  constructor(private readonly positions: PositionsService) {}
+
+  /** 分页读取企业岗位。 */
+  @Get('companies/:companyId/positions')
+  @AccessPolicy({ scope: 'company', permission: 'company.positions.read' })
+  companyPositions(@Req() req: FastifyRequest, @Query() query: unknown) {
+    return this.positions.list({
+      actor: actor(req),
+      scope: scopeFor(req) as OrganizationScope,
+      query: parse(positionListQuerySchema, query),
+    })
+  }
+
+  /** 分页读取项目岗位。 */
+  @Get('companies/:companyId/projects/:projectId/positions')
+  @AccessPolicy({ scope: 'project', permission: 'project.positions.read' })
+  projectPositions(@Req() req: FastifyRequest, @Query() query: unknown) {
+    return this.positions.list({
+      actor: actor(req),
+      scope: scopeFor(req) as OrganizationScope,
+      query: parse(positionListQuerySchema, query),
+    })
+  }
+
+  /** 创建企业岗位。 */
+  @Post('companies/:companyId/positions')
+  @AccessPolicy({ scope: 'company', permission: 'company.positions.create' })
+  createCompanyPosition(@Req() req: FastifyRequest, @Body() body: unknown) {
+    return this.positions.create({
+      actor: actor(req),
+      scope: scopeFor(req) as OrganizationScope,
+      body: parse(createPositionSchema, body),
+    })
+  }
+
+  /** 创建项目岗位。 */
+  @Post('companies/:companyId/projects/:projectId/positions')
+  @AccessPolicy({ scope: 'project', permission: 'project.positions.create' })
+  createProjectPosition(@Req() req: FastifyRequest, @Body() body: unknown) {
+    return this.positions.create({
+      actor: actor(req),
+      scope: scopeFor(req) as OrganizationScope,
+      body: parse(createPositionSchema, body),
+    })
+  }
+
+  /** 更新企业岗位资料。 */
+  @Patch('companies/:companyId/positions/:positionId')
+  @AccessPolicy({ scope: 'company', permission: 'company.positions.update' })
+  updateCompanyPosition(@Req() req: FastifyRequest, @Body() body: unknown) {
+    return this.positions.update({
+      actor: actor(req),
+      scope: scopeFor(req) as OrganizationScope,
+      positionId: ids(req).positionId!,
+      body: parse(updatePositionSchema, body),
+    })
+  }
+
+  /** 更新项目岗位资料。 */
+  @Patch('companies/:companyId/projects/:projectId/positions/:positionId')
+  @AccessPolicy({ scope: 'project', permission: 'project.positions.update' })
+  updateProjectPosition(@Req() req: FastifyRequest, @Body() body: unknown) {
+    return this.positions.update({
+      actor: actor(req),
+      scope: scopeFor(req) as OrganizationScope,
+      positionId: ids(req).positionId!,
+      body: parse(updatePositionSchema, body),
+    })
+  }
+
+  /** 启停企业岗位并保留现有任职。 */
+  @Patch('companies/:companyId/positions/:positionId/status')
+  @AccessPolicy({ scope: 'company', permission: 'company.positions.update' })
+  companyPositionStatus(@Req() req: FastifyRequest, @Body() body: unknown) {
+    return this.positions.status({
+      actor: actor(req),
+      scope: scopeFor(req) as OrganizationScope,
+      positionId: ids(req).positionId!,
+      body: parse(statusRequestSchema, body),
+    })
+  }
+
+  /** 启停项目岗位并保留现有任职。 */
+  @Patch('companies/:companyId/projects/:projectId/positions/:positionId/status')
+  @AccessPolicy({ scope: 'project', permission: 'project.positions.update' })
+  projectPositionStatus(@Req() req: FastifyRequest, @Body() body: unknown) {
+    return this.positions.status({
+      actor: actor(req),
+      scope: scopeFor(req) as OrganizationScope,
+      positionId: ids(req).positionId!,
+      body: parse(statusRequestSchema, body),
+    })
+  }
+
+  /** 按企业成员全量替换岗位任职。 */
+  @Put('companies/:companyId/organization/members/:userId/positions')
+  @AccessPolicy({ scope: 'company', permission: 'company.positions.assign' })
+  replaceCompanyMemberPositions(@Req() req: FastifyRequest, @Body() body: unknown) {
+    return this.positions.replaceMemberPositions({
+      actor: actor(req),
+      scope: scopeFor(req) as OrganizationScope,
+      userId: ids(req).userId!,
+      body: parse(replaceMemberPositionsSchema, body),
+    })
+  }
+
+  /** 按项目成员全量替换岗位任职。 */
+  @Put('companies/:companyId/projects/:projectId/organization/members/:userId/positions')
+  @AccessPolicy({ scope: 'project', permission: 'project.positions.assign' })
+  replaceProjectMemberPositions(@Req() req: FastifyRequest, @Body() body: unknown) {
+    return this.positions.replaceMemberPositions({
+      actor: actor(req),
+      scope: scopeFor(req) as OrganizationScope,
+      userId: ids(req).userId!,
+      body: parse(replaceMemberPositionsSchema, body),
+    })
+  }
+
+  /** 按企业岗位全量替换成员集合。 */
+  @Put('companies/:companyId/positions/:positionId/members')
+  @AccessPolicy({ scope: 'company', permission: 'company.positions.assign' })
+  replaceCompanyPositionMembers(@Req() req: FastifyRequest, @Body() body: unknown) {
+    return this.positions.replacePositionMembers({
+      actor: actor(req),
+      scope: scopeFor(req) as OrganizationScope,
+      positionId: ids(req).positionId!,
+      body: parse(replacePositionMembersSchema, body),
+    })
+  }
+
+  /** 按项目岗位全量替换成员集合。 */
+  @Put('companies/:companyId/projects/:projectId/positions/:positionId/members')
+  @AccessPolicy({ scope: 'project', permission: 'project.positions.assign' })
+  replaceProjectPositionMembers(@Req() req: FastifyRequest, @Body() body: unknown) {
+    return this.positions.replacePositionMembers({
+      actor: actor(req),
+      scope: scopeFor(req) as OrganizationScope,
+      positionId: ids(req).positionId!,
+      body: parse(replacePositionMembersSchema, body),
+    })
+  }
+}