create-bubbles 0.1.26 → 0.1.28

package/template-vp-monorepo-react-nestjs/packages/shared/src/utils/access-scope.ts

@@ -0,0 +1,97 @@
+import type {
+  AccessRoutePathInput,
+  AccessScope,
+  BuiltinPermissionKeysInput,
+  FilterSupportedAccessMenusInput,
+  MenuNode,
+} from '../types'
+import {
+  ACCESS_BUILTIN_MEMBER_PERMISSIONS,
+  ACCESS_PAGE_CATALOG,
+  ACCESS_PERMISSION_CATALOG,
+} from './access-catalog'
+
+/** 标识当前作用域，不校验成员身份或访问权限。 */
+export function accessScopeKey(scope: AccessScope): string {
+  switch (scope.type) {
+    case 'platform':
+      return 'platform'
+    case 'company':
+      return `company:${scope.companyId}`
+    case 'project':
+      return `project:${scope.companyId}:${scope.projectId}`
+  }
+}
+
+/** 生成平台、企业或项目的入口路径，并对路径中的资源 ID 编码。 */
+export function accessScopeBasePath(scope: AccessScope): string {
+  switch (scope.type) {
+    case 'platform':
+      return '/platform'
+    case 'company':
+      return `/companies/${encodeURIComponent(scope.companyId)}`
+    case 'project':
+      return `/companies/${encodeURIComponent(scope.companyId)}/projects/${encodeURIComponent(scope.projectId)}`
+  }
+}
+
+/** 按路由键查找页面目录定义；未注册时返回 `undefined`。 */
+export function getAccessPage(routeKey: string) {
+  return ACCESS_PAGE_CATALOG.find((page) => page.routeKey === routeKey)
+}
+
+/** 按权限键查找权限目录定义；未注册时返回 `undefined`。 */
+export function getAccessPermission(permissionKey: string) {
+  return ACCESS_PERMISSION_CATALOG.find((permission) => permission.key === permissionKey)
+}
+
+/** 未注册页面或不匹配的作用域没有可生成的页面路径。 */
+export function accessRoutePath({ scope, routeKey }: AccessRoutePathInput): string | null {
+  const page = getAccessPage(routeKey)
+  if (!page || page.scopeType !== scope.type) return null
+
+  let path = page.path
+  if (scope.type !== 'platform') {
+    path = path.replace(':companyId', encodeURIComponent(scope.companyId))
+  }
+  if (scope.type === 'project') {
+    path = path.replace(':projectId', encodeURIComponent(scope.projectId))
+  }
+  return path
+}
+
+/** 仅返回系统角色定义；实际访问仍须校验成员、状态及菜单。 */
+export function getBuiltinPermissionKeys({
+  scopeType,
+  builtin,
+}: BuiltinPermissionKeysInput): string[] {
+  if (builtin === 'member') return [...ACCESS_BUILTIN_MEMBER_PERMISSIONS[scopeType]]
+  return ACCESS_PERMISSION_CATALOG.filter(
+    (permission) => permission.scopeType === scopeType && !permission.deprecated,
+  ).map((permission) => permission.key)
+}
+
+/** 统一企业、项目等访问编码的空白与大小写，供保存和匹配使用。 */
+export function normalizeAccessCode(value: string): string {
+  return value.trim().toLowerCase()
+}
+
+/** 旧前端的页面兼容过滤，不更改来源菜单或服务端权限。 */
+export function filterSupportedAccessMenus({
+  menus,
+  supportedRouteKeys,
+}: FilterSupportedAccessMenusInput): MenuNode[] {
+  const supported = new Set(supportedRouteKeys)
+
+  /** 递归复制受支持的菜单，并移除过滤后没有子节点的目录。 */
+  function visit(nodes: readonly MenuNode[]): MenuNode[] {
+    return nodes.flatMap((node): MenuNode[] => {
+      if (node.type !== 'directory' && (!node.routeKey || !supported.has(node.routeKey))) return []
+      const children = visit(node.children)
+      if (node.type === 'directory' && children.length === 0) return []
+      return [{ ...node, children }]
+    })
+  }
+
+  return visit(menus)
+}

package/template-vp-monorepo-react-nestjs/packages/shared/src/utils/account.ts

@@ -1,5 +1,6 @@
 export const ACCOUNT_PATTERN = /^[A-Za-z0-9_]+$/
 
+/** 去除账号两端空白并统一为小写，供注册、登录和唯一性检查使用。 */
 export function normalizeAccount(value: string) {
   return value.trim().toLowerCase()
 }

package/template-vp-monorepo-react-nestjs/packages/shared/src/utils/index.ts

@@ -1,2 +1,67 @@
 export { ACCOUNT_PATTERN, normalizeAccount } from './account'
 export { isSessionTerminal, SESSION_TERMINALS } from './session-terminal'
+export { toTimestampRecord } from './record'
+export {
+  ACCESS_BUILTIN_MEMBER_PERMISSIONS,
+  ACCESS_CATALOG_VERSION,
+  ACCESS_CODE_PATTERN,
+  ACCESS_DEFAULT_PAGE_SIZE,
+  ACCESS_ICON_KEY_PATTERN,
+  ACCESS_MAX_PAGE_SIZE,
+  ACCESS_PAGE_CATALOG,
+  ACCESS_PERMISSION_CATALOG,
+  ACCESS_PROTECTED_ROUTE_KEYS,
+} from './access-catalog'
+export {
+  accessRoutePath,
+  accessScopeBasePath,
+  accessScopeKey,
+  filterSupportedAccessMenus,
+  getAccessPage,
+  getAccessPermission,
+  getBuiltinPermissionKeys,
+  normalizeAccessCode,
+} from './access-scope'
+export type {
+  AccessRoutePathInput,
+  BuiltinPermissionKeysInput,
+  FilterSupportedAccessMenusInput,
+} from '../types'
+export {
+  ORGANIZATION_CODE_PATTERN,
+  ORGANIZATION_MAX_DEPTH,
+  ORGANIZATION_MAX_SORT,
+  candidateArraySchema,
+  codeSchema,
+  createCompanySchema,
+  createOrganizationTemplateSchema,
+  createOrganizationUnitSchema,
+  createPositionSchema,
+  createProjectSchema,
+  descriptionSchema as organizationDescriptionSchema,
+  entityStatusSchema,
+  globalAccountCandidateQuerySchema,
+  idSchema as organizationIdSchema,
+  moveOrganizationUnitSchema,
+  nameSchema as organizationNameSchema,
+  normalizeOrganizationCode,
+  normalizeOrganizationKey,
+  organizationMemberCandidateQuerySchema,
+  organizationTemplateListQuerySchema,
+  organizationTreeQuerySchema,
+  positionListQuerySchema,
+  replaceMemberOrganizationUnitsSchema,
+  replaceMemberPositionsSchema,
+  replaceOrganizationTemplateSchema,
+  replaceOrganizationUnitMembersSchema,
+  replacePositionMembersSchema,
+  resolveGlobalAccountCandidatesSchema,
+  resolveOrganizationMemberCandidatesSchema,
+  setAdministratorSchema,
+  statusRequestSchema,
+  updateCompanyHierarchySchema,
+  updateOrganizationTemplateStatusSchema,
+  updateOrganizationUnitSchema,
+  updatePositionSchema,
+  updateProfileSchema,
+} from './organization/contracts'

package/template-vp-monorepo-react-nestjs/packages/shared/src/utils/organization/contracts.ts

@@ -0,0 +1,237 @@
+import { z } from 'zod'
+
+export const ORGANIZATION_CODE_PATTERN = /^[A-Za-z0-9_-]+$/
+export const ORGANIZATION_MAX_DEPTH = 10
+export const ORGANIZATION_MAX_SORT = 999_999_999
+
+export const idSchema = z.uuid()
+export const entityStatusSchema = z.enum(['active', 'disabled'])
+export const nameSchema = z.string().trim().min(2).max(100)
+export const codeSchema = z
+  .string()
+  .trim()
+  .min(2)
+  .max(32)
+  .regex(ORGANIZATION_CODE_PATTERN)
+  .transform((value) => value.toLowerCase())
+export const descriptionSchema = z.string().trim().max(500)
+const sortSchema = z.number().int().min(0).max(ORGANIZATION_MAX_SORT)
+const versionSchema = z.number().int().positive()
+const pageFields = {
+  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(),
+}
+const queryBooleanSchema = z.preprocess((value) => {
+  if (value === 'true') return true
+  if (value === 'false') return false
+  return value
+}, z.boolean())
+export const candidateArraySchema = z
+  .array(idSchema)
+  .min(1)
+  .max(100)
+  .refine((values) => new Set(values).size === values.length)
+const candidateQueryArraySchema = z.preprocess((value) => {
+  if (typeof value === 'string') return value.split(',').map((item) => item.trim())
+  if (Array.isArray(value))
+    return value.flatMap((item) =>
+      typeof item === 'string' ? item.split(',').map((part) => part.trim()) : [item],
+    )
+  return value
+}, candidateArraySchema)
+const replacementIdArraySchema = z
+  .array(idSchema)
+  .refine((values) => new Set(values).size === values.length)
+
+/** 对显示文本执行唯一键规范化，保留内部空白并统一 Unicode 与大小写。 */
+export function normalizeOrganizationKey(value: string): string {
+  return value.trim().normalize('NFKC').toLowerCase()
+}
+
+/** 对公开编码执行首尾清理、Unicode 规范化和小写保存。 */
+export function normalizeOrganizationCode(value: string): string {
+  return normalizeOrganizationKey(value)
+}
+
+const baseResourceFields = {
+  name: nameSchema,
+  code: codeSchema,
+  description: descriptionSchema.optional(),
+}
+
+export const createCompanySchema = z.strictObject({
+  ...baseResourceFields,
+  administratorUserId: idSchema,
+  parentCompanyId: idSchema.nullable().optional(),
+  entityType: z.enum(['group', 'company']).optional(),
+  sort: sortSchema.optional(),
+})
+
+export const updateCompanyHierarchySchema = z.strictObject({
+  expectedVersion: versionSchema,
+  parentCompanyId: idSchema.nullable(),
+  entityType: z.enum(['group', 'company']),
+  sort: sortSchema.optional(),
+})
+
+const blankInitializationSchema = z.strictObject({ mode: z.literal('blank') })
+const templateInitializationSchema = z.strictObject({
+  mode: z.literal('template'),
+  templateId: idSchema,
+  templateVersion: versionSchema,
+})
+
+export const createProjectSchema = z.strictObject({
+  ...baseResourceFields,
+  administratorUserId: idSchema,
+  organizationInitialization: z.discriminatedUnion('mode', [
+    blankInitializationSchema,
+    templateInitializationSchema,
+  ]),
+})
+
+export const setAdministratorSchema = z.strictObject({
+  administratorUserId: idSchema,
+  replaceUserId: idSchema.optional(),
+})
+
+export const updateProfileSchema = z
+  .strictObject({
+    expectedVersion: versionSchema,
+    name: nameSchema.optional(),
+    code: codeSchema.optional(),
+    description: descriptionSchema.optional(),
+  })
+  .refine((value) => Object.keys(value).some((key) => key !== 'expectedVersion'))
+
+export const organizationTreeQuerySchema = z.strictObject({ parentId: idSchema.optional() })
+
+export const createOrganizationUnitSchema = z.strictObject({
+  ...baseResourceFields,
+  parentId: idSchema.nullable().optional(),
+  sort: sortSchema.optional(),
+})
+
+export const updateOrganizationUnitSchema = z
+  .strictObject({
+    expectedVersion: versionSchema,
+    name: nameSchema.optional(),
+    code: codeSchema.optional(),
+    description: descriptionSchema.optional(),
+    sort: sortSchema.optional(),
+  })
+  .refine((value) => Object.keys(value).some((key) => key !== 'expectedVersion'))
+
+export const moveOrganizationUnitSchema = z.strictObject({
+  expectedVersion: versionSchema,
+  parentId: idSchema.nullable(),
+  sort: sortSchema.optional(),
+})
+
+export const statusRequestSchema = z.strictObject({
+  expectedVersion: versionSchema,
+  status: entityStatusSchema,
+})
+
+const dutySchema = z.enum(['member', 'leader', 'deputy'])
+export const replaceMemberOrganizationUnitsSchema = z.strictObject({
+  relations: z
+    .array(z.strictObject({ organizationUnitId: idSchema, duty: dutySchema }))
+    .refine(
+      (relations) =>
+        new Set(relations.map(({ organizationUnitId }) => organizationUnitId)).size ===
+        relations.length,
+    ),
+})
+export const replaceOrganizationUnitMembersSchema = z.strictObject({
+  members: z
+    .array(z.strictObject({ userId: idSchema, duty: dutySchema }))
+    .refine((members) => new Set(members.map(({ userId }) => userId)).size === members.length),
+})
+
+export const positionListQuerySchema = z.strictObject({
+  ...pageFields,
+  status: entityStatusSchema.optional(),
+})
+export const createPositionSchema = z.strictObject(baseResourceFields)
+export const updatePositionSchema = z
+  .strictObject({
+    expectedVersion: versionSchema,
+    name: nameSchema.optional(),
+    code: codeSchema.optional(),
+    description: descriptionSchema.optional(),
+  })
+  .refine((value) => Object.keys(value).some((key) => key !== 'expectedVersion'))
+export const replaceMemberPositionsSchema = z.strictObject({
+  positionIds: replacementIdArraySchema,
+})
+export const replacePositionMembersSchema = z.strictObject({ userIds: replacementIdArraySchema })
+
+const templateUnitSchema = z.strictObject({
+  clientKey: z.string().trim().min(1).max(100),
+  parentClientKey: z.string().trim().min(1).max(100).nullable(),
+  ...baseResourceFields,
+  sort: sortSchema,
+})
+const templatePositionSchema = z.strictObject({
+  ...baseResourceFields,
+  status: entityStatusSchema,
+})
+const templateDefinitionFields = {
+  name: nameSchema,
+  description: descriptionSchema.optional(),
+  units: z.array(templateUnitSchema),
+  positions: z.array(templatePositionSchema),
+}
+export const organizationTemplateListQuerySchema = z.strictObject({
+  ...pageFields,
+  status: entityStatusSchema.optional(),
+})
+export const createOrganizationTemplateSchema = z.strictObject({
+  ...templateDefinitionFields,
+  isDefault: z.boolean().optional(),
+})
+export const replaceOrganizationTemplateSchema = z.strictObject({
+  expectedVersion: versionSchema,
+  ...templateDefinitionFields,
+  isDefault: z.boolean(),
+})
+export const updateOrganizationTemplateStatusSchema = z
+  .strictObject({
+    expectedVersion: versionSchema,
+    status: entityStatusSchema.optional(),
+    isDefault: z.boolean().optional(),
+  })
+  .refine(({ status, isDefault }) => status !== undefined || isDefault !== undefined)
+
+const globalPurposeSchema = z.enum(['createCompanyAdministrator', 'setCompanyAdministrator'])
+const organizationPurposeSchema = z.enum([
+  'browseOrganization',
+  'assignPositionMembers',
+  'createProjectAdministrator',
+  'setProjectAdministrator',
+  'addProjectMember',
+])
+export const globalAccountCandidateQuerySchema = z.strictObject({
+  ...pageFields,
+  purpose: globalPurposeSchema,
+})
+export const resolveGlobalAccountCandidatesSchema = z.strictObject({
+  userIds: candidateArraySchema,
+  purpose: globalPurposeSchema,
+})
+export const organizationMemberCandidateQuerySchema = z.strictObject({
+  ...pageFields,
+  purpose: organizationPurposeSchema.optional().default('browseOrganization'),
+  organizationUnitIds: candidateQueryArraySchema.optional(),
+  positionIds: candidateQueryArraySchema.optional(),
+  roleIds: candidateQueryArraySchema.optional(),
+  projectIds: candidateQueryArraySchema.optional(),
+  unassigned: queryBooleanSchema.optional(),
+  includeDisabled: queryBooleanSchema.optional().default(true),
+})
+export const resolveOrganizationMemberCandidatesSchema = z.strictObject({
+  userIds: candidateArraySchema,
+  purpose: organizationPurposeSchema.optional().default('browseOrganization'),
+})

package/template-vp-monorepo-react-nestjs/packages/shared/src/utils/record.ts

@@ -0,0 +1,10 @@
+/** 复制数据库记录，将创建和更新时间转为接口可传输的 ISO 字符串。 */
+export function toTimestampRecord<T extends { createdAt: Date; updatedAt: Date }>(
+  row: T,
+): Omit<T, 'createdAt' | 'updatedAt'> & { createdAt: string; updatedAt: string } {
+  return {
+    ...row,
+    createdAt: row.createdAt.toISOString(),
+    updatedAt: row.updatedAt.toISOString(),
+  }
+}

package/template-vp-monorepo-react-nestjs/packages/shared/src/utils/session-terminal.ts

@@ -6,6 +6,7 @@ export const SESSION_TERMINALS = [
   'mobile',
 ] as const satisfies readonly SessionTerminalType[]
 
+/** 判断外部输入是否属于支持的会话终端，并收窄为终端类型。 */
 export function isSessionTerminal(value: unknown): value is SessionTerminalType {
   return SESSION_TERMINALS.includes(value as SessionTerminalType)
 }

package/template-vp-monorepo-react-nestjs/packages/shared/test/access.spec.ts

@@ -0,0 +1,194 @@
+import { describe, expect, it } from 'vite-plus/test'
+import type { MenuNode, ScopeType } from '../src/types'
+import {
+  ACCESS_BUILTIN_MEMBER_PERMISSIONS,
+  ACCESS_ICON_KEY_PATTERN,
+  ACCESS_PAGE_CATALOG,
+  ACCESS_PERMISSION_CATALOG,
+  ACCESS_PROTECTED_ROUTE_KEYS,
+  accessRoutePath,
+  accessScopeBasePath,
+  accessScopeKey,
+  filterSupportedAccessMenus,
+  getAccessPermission,
+  getBuiltinPermissionKeys,
+} from '../src/utils'
+
+describe('共享权限目录约束', () => {
+  it('每个页面和操作都有唯一且同作用域的有效绑定', () => {
+    expect(new Set(ACCESS_PAGE_CATALOG.map((page) => page.routeKey)).size).toBe(
+      ACCESS_PAGE_CATALOG.length,
+    )
+    expect(new Set(ACCESS_PERMISSION_CATALOG.map((permission) => permission.key)).size).toBe(
+      ACCESS_PERMISSION_CATALOG.length,
+    )
+
+    for (const page of ACCESS_PAGE_CATALOG) {
+      expect(ACCESS_ICON_KEY_PATTERN.test(page.icon)).toBe(true)
+      expect(getAccessPermission(page.permissionKey)).toMatchObject({
+        kind: 'page',
+        scopeType: page.scopeType,
+        routeKey: page.routeKey,
+      })
+      for (const key of page.operationKeys) {
+        expect(getAccessPermission(key)).toMatchObject({
+          kind: 'operation',
+          scopeType: page.scopeType,
+          routeKey: page.routeKey,
+          pagePermissionKey: page.permissionKey,
+        })
+      }
+    }
+
+    for (const permission of ACCESS_PERMISSION_CATALOG) {
+      if (permission.kind === 'operation') {
+        expect(getAccessPermission(permission.pagePermissionKey!)).toMatchObject({
+          kind: 'page',
+          scopeType: permission.scopeType,
+          routeKey: permission.routeKey,
+        })
+      }
+    }
+  })
+
+  it('管理员专属操作准确隔离，默认成员不获得管理操作', () => {
+    expect(
+      ACCESS_PERMISSION_CATALOG.filter((permission) => permission.adminOnly)
+        .map((permission) => permission.key)
+        .sort(),
+    ).toEqual([
+      'company.projects.administrator',
+      'company.projects.create',
+      'platform.companies.administrator',
+      'platform.companies.create',
+      'platform.menus.cleanup',
+    ])
+    for (const scopeType of ['platform', 'company', 'project'] satisfies ScopeType[]) {
+      const memberKeys = getBuiltinPermissionKeys({ scopeType, builtin: 'member' })
+      expect(memberKeys).toEqual(ACCESS_BUILTIN_MEMBER_PERMISSIONS[scopeType])
+      for (const key of memberKeys)
+        expect(getAccessPermission(key)).toMatchObject({
+          kind: 'page',
+          scopeType,
+          adminOnly: false,
+        })
+      expect(getBuiltinPermissionKeys({ scopeType, builtin: 'administrator' })).toEqual(
+        ACCESS_PERMISSION_CATALOG.filter(
+          (permission) => permission.scopeType === scopeType && !permission.deprecated,
+        ).map((permission) => permission.key),
+      )
+    }
+  })
+
+  it('恢复管理涉及的四个页面均受到保护', () => {
+    for (const routeKey of [
+      'platform.companies',
+      'platform.accounts',
+      'platform.roles',
+      'platform.menus',
+    ]) {
+      expect(ACCESS_PROTECTED_ROUTE_KEYS).toContain(routeKey)
+      expect(ACCESS_PAGE_CATALOG.some((page) => page.routeKey === routeKey)).toBe(true)
+    }
+  })
+})
+
+describe('作用域路径', () => {
+  it('不同企业下相同项目 ID 不会共享作用域标识', () => {
+    const first = { type: 'project', companyId: 'company-a', projectId: 'project-a' } as const
+    const second = { ...first, companyId: 'company-b' }
+    expect(accessScopeKey(first)).not.toBe(accessScopeKey(second))
+    expect(accessScopeBasePath(first)).toBe('/companies/company-a/projects/project-a')
+    expect(accessRoutePath({ scope: first, routeKey: 'project.members' })).toBe(
+      '/companies/company-a/projects/project-a/members',
+    )
+  })
+
+  it('拒绝不匹配或未知 routeKey，并转义路径参数', () => {
+    const scope = { type: 'company', companyId: 'company/a' } as const
+    expect(accessScopeBasePath(scope)).toBe('/companies/company%2Fa')
+    expect(accessRoutePath({ scope, routeKey: 'company.profile' })).toBe(
+      '/companies/company%2Fa/profile',
+    )
+    expect(accessRoutePath({ scope, routeKey: 'project.profile' })).toBeNull()
+    expect(accessRoutePath({ scope, routeKey: 'company.future' })).toBeNull()
+  })
+})
+
+function menuNode(overrides: Partial<MenuNode>): MenuNode {
+  return {
+    id: 'directory',
+    scopeType: 'company',
+    parentId: null,
+    type: 'directory',
+    name: '目录',
+    icon: '',
+    sort: 0,
+    hidden: false,
+    status: 'active',
+    routeKey: null,
+    permissionKey: null,
+    protected: false,
+    children: [],
+    ...overrides,
+  }
+}
+
+describe('旧前端菜单过滤', () => {
+  it('过滤未知页面及其按钮、移除空目录，并保留已知页面及源数据', () => {
+    const operation = menuNode({
+      id: 'operation',
+      parentId: 'known',
+      type: 'operation',
+      routeKey: 'company.members',
+      permissionKey: 'company.members.add',
+    })
+    const known = menuNode({
+      id: 'known',
+      parentId: 'mixed',
+      type: 'page',
+      routeKey: 'company.members',
+      permissionKey: 'company.members.read',
+      children: [operation],
+    })
+    const unknown = menuNode({
+      id: 'unknown',
+      type: 'page',
+      routeKey: 'company.future',
+      permissionKey: 'company.future.read',
+      children: [
+        menuNode({ id: 'future-operation', type: 'operation', routeKey: 'company.future' }),
+      ],
+    })
+    const menus = [
+      menuNode({ id: 'mixed', children: [known, unknown] }),
+      menuNode({ id: 'empty-after-filter', children: [unknown] }),
+    ]
+    const result = filterSupportedAccessMenus({
+      menus,
+      supportedRouteKeys: new Set(['company.members']),
+    })
+
+    expect(result.map((node) => node.id)).toEqual(['mixed'])
+    expect(result[0]?.children.map((node) => node.id)).toEqual(['known'])
+    expect(result[0]?.children[0]?.children.map((node) => node.id)).toEqual(['operation'])
+    expect(menus[0]?.children).toHaveLength(2)
+    expect(menus[1]?.children).toHaveLength(1)
+    expect(result[0]).not.toBe(menus[0])
+    expect(result[0]?.children[0]).not.toBe(known)
+  })
+
+  it('已知页面没有操作按钮也不会被当成空目录移除', () => {
+    const home = menuNode({
+      id: 'home',
+      type: 'page',
+      routeKey: 'company.home',
+      permissionKey: 'company.home.read',
+    })
+    expect(
+      filterSupportedAccessMenus({ menus: [home], supportedRouteKeys: ['company.home'] }).map(
+        (node) => node.id,
+      ),
+    ).toEqual(['home'])
+  })
+})