create-bubbles 0.1.25 → 0.1.27

package/template-vp-monorepo-react-nestjs/apps/web/src/components/Selector/GlobalAccountSelect/GlobalAccountSelect.tsx

@@ -0,0 +1,211 @@
+import { useI18n } from '@bubblesjs/i18n-react'
+import { Flex, Select, Spin, Tag, Typography } from 'antd'
+import type {
+  GlobalAccountOption,
+  GlobalAccountSelectOption,
+  GlobalAccountSelectProps,
+} from './GlobalAccountSelectTypes'
+
+const DEFAULT_MIN_SEARCH_LENGTH = 2
+const DEFAULT_DEBOUNCE_MS = 300
+const DEFAULT_PAGE_SIZE = 20
+
+/** 远程搜索平台全局账号，以稳定 userId 作为单选值。 */
+export default function GlobalAccountSelect({
+  value,
+  selectedAccount,
+  request,
+  resolve,
+  minSearchLength = DEFAULT_MIN_SEARCH_LENGTH,
+  debounceMs = DEFAULT_DEBOUNCE_MS,
+  pageSize = DEFAULT_PAGE_SIZE,
+  placeholder,
+  allowClear = true,
+  onChange,
+  ...selectProps
+}: GlobalAccountSelectProps) {
+  const { tr } = useI18n()
+  const [query, setQuery] = useState('')
+  const [accounts, setAccounts] = useState<readonly GlobalAccountOption[]>([])
+  const [currentAccount, setCurrentAccount] = useState(selectedAccount)
+  const [loading, setLoading] = useState(false)
+  const [resolving, setResolving] = useState(false)
+  const [error, setError] = useState(false)
+  const requestRef = useRef(request)
+  const resolveRef = useRef(resolve)
+  const accountCacheRef = useRef(new Map<string, GlobalAccountOption>())
+  const requestSequence = useRef(0)
+  const resolveSequence = useRef(0)
+  const attemptedResolveValueRef = useRef<string | undefined>(undefined)
+  requestRef.current = request
+  resolveRef.current = resolve
+
+  /** 优先使用业务快照或当前搜索结果，并按需通过 userId 补齐账号回显。 */
+  useEffect(() => {
+    if (!value) {
+      attemptedResolveValueRef.current = undefined
+      setCurrentAccount(undefined)
+      setResolving(false)
+      return
+    }
+
+    const knownAccount =
+      (selectedAccount?.userId === value ? selectedAccount : undefined) ??
+      accountCacheRef.current.get(value)
+    if (knownAccount) {
+      accountCacheRef.current.set(knownAccount.userId, knownAccount)
+      attemptedResolveValueRef.current = undefined
+      setCurrentAccount(knownAccount)
+      setResolving(false)
+      return
+    }
+
+    if (attemptedResolveValueRef.current === value) return
+    attemptedResolveValueRef.current = value
+    const sequence = ++resolveSequence.current
+    const controller = new AbortController()
+    setCurrentAccount(undefined)
+    setResolving(true)
+    void resolveRef
+      .current([value], controller.signal)
+      .then((resolvedAccounts) => {
+        if (resolveSequence.current !== sequence || controller.signal.aborted) return
+        for (const account of resolvedAccounts) accountCacheRef.current.set(account.userId, account)
+        setCurrentAccount(accountCacheRef.current.get(value))
+      })
+      .catch(() => {
+        // 补查失败时保留受控 userId，但不伪造候选；同一值等待显式变化后再重试。
+      })
+      .finally(() => {
+        if (resolveSequence.current === sequence && !controller.signal.aborted) setResolving(false)
+      })
+
+    return () => controller.abort()
+  }, [selectedAccount, value])
+
+  /** 防抖查询候选账号，并取消或忽略已经失效的请求结果。 */
+  useEffect(() => {
+    const normalizedQuery = query.trim()
+    const sequence = ++requestSequence.current
+    setError(false)
+    setAccounts([])
+
+    if (normalizedQuery.length < minSearchLength) {
+      setLoading(false)
+      return
+    }
+
+    const controller = new AbortController()
+    setLoading(true)
+    const timer = window.setTimeout(() => {
+      void requestRef
+        .current({
+          query: normalizedQuery,
+          page: 1,
+          pageSize,
+          signal: controller.signal,
+        })
+        .then((result) => {
+          if (requestSequence.current !== sequence || controller.signal.aborted) return
+          const uniqueAccounts = new Map(
+            result.items.map((account) => [account.userId, account] as const),
+          )
+          for (const account of uniqueAccounts.values())
+            accountCacheRef.current.set(account.userId, account)
+          setAccounts([...uniqueAccounts.values()])
+        })
+        .catch(() => {
+          if (requestSequence.current !== sequence || controller.signal.aborted) return
+          setAccounts([])
+          setError(true)
+        })
+        .finally(() => {
+          if (requestSequence.current === sequence && !controller.signal.aborted) setLoading(false)
+        })
+    }, debounceMs)
+
+    return () => {
+      window.clearTimeout(timer)
+      controller.abort()
+    }
+  }, [debounceMs, minSearchLength, pageSize, query])
+
+  const accountById = new Map(accounts.map((account) => [account.userId, account] as const))
+  const options: GlobalAccountSelectOption[] = accounts.map((account) => ({
+    value: account.userId,
+    label: `${account.name} · ${account.account}`,
+    disabled: account.disabled,
+    account,
+  }))
+  const normalizedQueryLength = query.trim().length
+
+  return (
+    <Select<string | undefined, GlobalAccountSelectOption>
+      {...selectProps}
+      value={value}
+      placeholder={placeholder ?? tr('搜索姓名或账号')}
+      allowClear={allowClear}
+      showSearch={{ onSearch: setQuery, filterOption: false }}
+      loading={loading || resolving}
+      options={options}
+      onChange={
+        /** 回传稳定 userId 和本次选项快照，并保留选中账号用于后续回显。 */ (
+          userId,
+          selectedOption,
+        ) => {
+          const option = Array.isArray(selectedOption) ? selectedOption[0] : selectedOption
+          const account = userId ? (option?.account ?? accountById.get(userId)) : undefined
+          if (account) accountCacheRef.current.set(account.userId, account)
+          setQuery('')
+          setCurrentAccount(account)
+          onChange?.(userId, account)
+        }
+      }
+      labelRender={
+        /** 使用可信账号快照渲染选中值；缺失时给出不可用提示而不暴露裸 userId。 */ ({
+          value: selectedUserId,
+        }) => {
+          const account =
+            selectedAccount?.userId === selectedUserId
+              ? selectedAccount
+              : currentAccount?.userId === selectedUserId
+                ? currentAccount
+                : typeof selectedUserId === 'string'
+                  ? accountCacheRef.current.get(selectedUserId)
+                  : undefined
+          return account ? `${account.name} · ${account.account}` : tr('账号信息不可用')
+        }
+      }
+      optionRender={
+        /** 在候选项中同时展示姓名、完整账号和账号状态。 */ (option) => {
+          const account = option.data.account
+          const statusText = account.status === 'active' ? tr('启用') : tr('不可选')
+          return (
+            <Flex align="center" justify="space-between" gap={12}>
+              <Flex vertical style={{ minWidth: 0 }}>
+                <Typography.Text ellipsis>{account.name}</Typography.Text>
+                <Typography.Text type="secondary" ellipsis>
+                  {account.account}
+                </Typography.Text>
+              </Flex>
+              <Tag color={account.disabled ? 'error' : 'success'}>{statusText}</Tag>
+            </Flex>
+          )
+        }
+      }
+      notFoundContent={
+        loading ? (
+          <Spin size="small" />
+        ) : error ? (
+          <Typography.Text type="danger">{tr('请求失败，请稍后重试')}</Typography.Text>
+        ) : normalizedQueryLength < minSearchLength ? (
+          <Typography.Text type="secondary">{tr('搜索姓名或账号')}</Typography.Text>
+        ) : (
+          <Typography.Text type="secondary">
+            {tr('暂无{type}', { type: tr('全局账号') })}
+          </Typography.Text>
+        )
+      }
+    />
+  )
+}

package/template-vp-monorepo-react-nestjs/apps/web/src/components/Selector/GlobalAccountSelect/GlobalAccountSelectTypes.ts

@@ -0,0 +1,75 @@
+import type { SelectProps } from 'antd'
+import type { GlobalAccountCandidate } from 'shared/types'
+
+/** 全局账号选择器直接消费服务端按 purpose 裁剪后的候选记录。 */
+export type GlobalAccountOption = GlobalAccountCandidate
+
+/** 传给 Ant Design Select 的账号选项，保留完整账号快照供渲染和回调使用。 */
+export interface GlobalAccountSelectOption {
+  value: string
+  label: string
+  disabled: boolean
+  account: GlobalAccountOption
+}
+
+/** 业务侧查询全局账号候选项时接收的标准参数。 */
+export interface GlobalAccountSearchRequest {
+  /** 已去除首尾空白的姓名或账号关键词。 */
+  query: string
+  /** 当前组件只查询第一页，字段保留用于对接分页接口。 */
+  page: number
+  /** 单次最多返回的候选账号数。 */
+  pageSize: number
+  /** 新搜索或组件卸载时会中止旧请求。 */
+  signal: AbortSignal
+}
+
+/** 业务查询返回的全局账号候选结果。 */
+export interface GlobalAccountSearchResult {
+  items: readonly GlobalAccountOption[]
+  total?: number
+}
+
+/** 业务侧按稳定 userId 补查账号快照的函数，并接收组件生命周期内的取消信号。 */
+export type GlobalAccountResolver = (
+  userIds: readonly string[],
+  signal: AbortSignal,
+) => Promise<readonly GlobalAccountOption[]>
+
+type ManagedSelectProps =
+  | 'value'
+  | 'defaultValue'
+  | 'options'
+  | 'mode'
+  | 'showSearch'
+  | 'filterOption'
+  | 'labelInValue'
+  | 'loading'
+  | 'onSearch'
+  | 'onChange'
+  | 'optionRender'
+  | 'labelRender'
+  | 'notFoundContent'
+
+/** 受控全局账号 Select 的公开属性。默认值应由 Form 的 initialValues 提供。 */
+export interface GlobalAccountSelectProps extends Omit<
+  SelectProps<string | undefined, GlobalAccountSelectOption>,
+  ManagedSelectProps
+> {
+  /** 始终使用全局用户 id 作为表单值。 */
+  value?: string
+  /** 编辑回显时提供已选账号，避免组件只能显示裸 userId。 */
+  selectedAccount?: GlobalAccountOption
+  /** 由业务侧注入受权限保护的候选账号查询。 */
+  request: (input: GlobalAccountSearchRequest) => Promise<GlobalAccountSearchResult>
+  /** 由业务侧注入与搜索 purpose 相同的 userId 补查请求。 */
+  resolve: GlobalAccountResolver
+  /** 触发远程查询所需的最少字符数，默认 2。 */
+  minSearchLength?: number
+  /** 输入停止后发起查询的等待时间，单位毫秒，默认 300。 */
+  debounceMs?: number
+  /** 单次查询的最大候选数量，默认 20。 */
+  pageSize?: number
+  /** 返回稳定 userId，并同时提供当前账号快照便于业务展示或过渡映射。 */
+  onChange?: (userId: string | undefined, account: GlobalAccountOption | undefined) => void
+}

package/template-vp-monorepo-react-nestjs/apps/web/src/components/Selector/GlobalAccountSelect/README.md

@@ -0,0 +1,35 @@
+# GlobalAccountSelect
+
+表单内使用的远程搜索单选框。它只查找平台已注册账号，不展示企业或项目组织树，并始终使用全局 `userId` 作为值。
+
+组件固定处理：
+
+- 不预加载全平台账号；默认输入至少 2 个字符后查询。
+- 默认 300ms 防抖，并取消或忽略过期请求。
+- 只展示当前关键词的服务端搜索结果，不在前端二次过滤。
+- 结果按 `id` 去重，展示姓名、完整账号和状态。
+- 锁定或停用账号显示但禁止选择。
+- 按稳定 `userId` 补查初始值或外部变更值，并缓存当前选中账号。
+- 搜索与补查必须绑定同一业务 purpose；未知账号不会伪造成候选或显示裸 `userId`。
+- 值变化、请求竞态或组件卸载时取消并忽略过期补查，同一空结果或失败值不会自动循环请求。
+- 作为受控组件使用，表单默认值放在 `Form.initialValues`，不要给字段组件传 `defaultValue`。
+
+```tsx
+import { Form } from 'antd'
+import { GlobalAccountSelect } from '@/components/Selector'
+
+export default function AdministratorField() {
+  return (
+    <Form.Item name="administratorUserId" label="首位企业管理员" required>
+      <GlobalAccountSelect
+        request={searchCompanyAdministratorCandidates}
+        resolve={resolveCompanyAdministratorCandidates}
+      />
+    </Form.Item>
+  )
+}
+```
+
+编辑场景除在 `Form.initialValues` 中提供 `administratorUserId` 外，也可通过 `selectedAccount` 传入该账号的最小快照，从而跳过首次补查。
+
+`request` 和 `resolve` 必须由业务页面同时注入，并调用与当前操作权限及 purpose 一致的候选接口。组件不能直接依赖账号管理列表接口，也不会在选择时创建成员关系或授予角色。企业/项目、角色和部门树属于另一类组织成员选择器，不应塞进这个全局账号下拉框。

package/template-vp-monorepo-react-nestjs/apps/web/src/components/Selector/GlobalAccountSelect/index.ts

@@ -0,0 +1,9 @@
+export { default } from './GlobalAccountSelect'
+export type {
+  GlobalAccountOption,
+  GlobalAccountResolver,
+  GlobalAccountSearchRequest,
+  GlobalAccountSearchResult,
+  GlobalAccountSelectOption,
+  GlobalAccountSelectProps,
+} from './GlobalAccountSelectTypes'

package/template-vp-monorepo-react-nestjs/apps/web/src/components/Selector/OrganizationMemberSelector/OrganizationMemberBrowser.tsx

@@ -0,0 +1,146 @@
+import { useI18n } from '@bubblesjs/i18n-react'
+import type { OrganizationMemberCandidate } from 'shared/types'
+import BasicTableSelector, { type BasicTableSelectorRef } from '../BasicTableSelector'
+import { useOrganizationMemberCandidateColumns } from './OrganizationMemberCandidateColumns'
+import OrganizationMemberFilterPanel, {
+  createEmptyOrganizationMemberFilterValue,
+} from './OrganizationMemberFilterPanel'
+import type {
+  OrganizationMemberBrowserProps,
+  OrganizationMemberResourceFilters,
+} from './OrganizationMemberSelectorTypes'
+
+/** 提供左侧组织浏览、右侧分页选人、跨页选择和 resolve 回显。 */
+export default function OrganizationMemberBrowser({
+  ref,
+  candidateContextKey,
+  scope,
+  multiple = false,
+  title,
+  filters,
+  request,
+  resolve,
+  getCandidateDisabled,
+  onConfirm,
+}: OrganizationMemberBrowserProps) {
+  const { tr } = useI18n()
+  const columns = useOrganizationMemberCandidateColumns()
+  const selectorRef = useRef<BasicTableSelectorRef<OrganizationMemberCandidate>>(null)
+  const projectFilterRequestId = useRef(0)
+  const [filterValue, setFilterValue] = useState(createEmptyOrganizationMemberFilterValue)
+  const [projectResourceFilters, setProjectResourceFilters] =
+    useState<OrganizationMemberResourceFilters>()
+  const [projectFiltersLoading, setProjectFiltersLoading] = useState(false)
+  const loadProjectFilters = filters?.loadProjectFilters
+
+  const currentResourceFilters = useMemo<OrganizationMemberResourceFilters | undefined>(() => {
+    if (!filters) return undefined
+    return {
+      organizationUnits: filters.organizationUnits,
+      positions: filters.positions,
+      roles: filters.roles,
+      allowUnassigned: filters.allowUnassigned,
+    }
+  }, [filters])
+  const projectIdsKey = filterValue.projectIds.join('\u0000')
+
+  /** 企业范围切到项目身份域时，按实际可见权限异步加载该域筛选项。 */
+  useEffect(() => {
+    const requestId = ++projectFilterRequestId.current
+    if (!filterValue.projectIds.length) {
+      setProjectResourceFilters(undefined)
+      setProjectFiltersLoading(false)
+      return
+    }
+    if (!loadProjectFilters) {
+      setProjectResourceFilters({})
+      setProjectFiltersLoading(false)
+      return
+    }
+    setProjectResourceFilters(undefined)
+    setProjectFiltersLoading(true)
+    void loadProjectFilters(filterValue.projectIds)
+      .then((nextFilters) => {
+        if (projectFilterRequestId.current === requestId) setProjectResourceFilters(nextFilters)
+      })
+      .catch(() => {
+        if (projectFilterRequestId.current === requestId) setProjectResourceFilters({})
+      })
+      .finally(() => {
+        if (projectFilterRequestId.current === requestId) setProjectFiltersLoading(false)
+      })
+  }, [candidateContextKey, loadProjectFilters, projectIdsKey, scope.type])
+
+  useImperativeHandle(ref, () => ({
+    /** 使用既有 userId 和候选快照打开隔离会话，并重置上次浏览筛选。 */
+    show: (value, selectedRows) => {
+      projectFilterRequestId.current += 1
+      setFilterValue(createEmptyOrganizationMemberFilterValue())
+      setProjectResourceFilters(undefined)
+      setProjectFiltersLoading(false)
+      selectorRef.current?.show({ value, selectedRows })
+    },
+    /** 关闭当前选择会话并丢弃尚未确认的改动。 */
+    hide: () => {
+      projectFilterRequestId.current += 1
+      selectorRef.current?.hide()
+    },
+  }))
+
+  const resourceFilters = filterValue.projectIds.length
+    ? projectResourceFilters
+    : currentResourceFilters
+
+  return (
+    <BasicTableSelector<OrganizationMemberCandidate>
+      ref={selectorRef}
+      title={title ?? tr('选择成员')}
+      rowKey="userId"
+      multiple={multiple}
+      columns={columns}
+      params={filterValue}
+      sidePanel={
+        <OrganizationMemberFilterPanel
+          scope={scope}
+          projects={scope.type === 'company' ? filters?.projects : undefined}
+          resourceFilters={resourceFilters}
+          loading={projectFiltersLoading}
+          value={filterValue}
+          onChange={setFilterValue}
+        />
+      }
+      request={
+        /** 合并搜索、左侧身份域与资源筛选，并保持服务端分页结果。 */ async (params) => {
+          const result = await request({
+            page: params.current ?? 1,
+            pageSize: params.pageSize ?? 20,
+            query: params.query as string | undefined,
+            organizationUnitIds: filterValue.organizationUnitIds.length
+              ? filterValue.organizationUnitIds
+              : undefined,
+            positionIds: filterValue.positionIds.length ? filterValue.positionIds : undefined,
+            roleIds: filterValue.roleIds.length ? filterValue.roleIds : undefined,
+            projectIds: filterValue.projectIds.length ? filterValue.projectIds : undefined,
+            unassigned: filterValue.unassigned || undefined,
+          })
+          return { data: result.items, total: result.total, success: true }
+        }
+      }
+      requestByKeys={
+        /** 按稳定 userId 批量补查跨页或历史选择。 */ async (keys) => resolve(keys.map(String))
+      }
+      labelRender={(candidate) => `${candidate.name} · ${candidate.account}`}
+      getCheckboxProps={(candidate) => {
+        const disabled = candidate.disabled || getCandidateDisabled?.(candidate)
+        return {
+          disabled,
+          title: disabled ? tr('该成员当前不可新增，既有选择仍可移除') : undefined,
+        }
+      }}
+      onChange={(keys, rows) => onConfirm(keys.map(String), rows)}
+      pagination={{ defaultPageSize: 20, showSizeChanger: true, pageSizeOptions: [20, 50, 100] }}
+      scroll={{ y: 400 }}
+      modalProps={{ width: 1380 }}
+    />
+  )
+}

package/template-vp-monorepo-react-nestjs/apps/web/src/components/Selector/OrganizationMemberSelector/OrganizationMemberCandidateColumns.tsx

@@ -0,0 +1,137 @@
+import type { ProColumns } from '@ant-design/pro-components'
+import { Space, Tag, Typography } from 'antd'
+import { useI18n } from '@bubblesjs/i18n-react'
+import type { CandidateDisabledReason, OrganizationMemberCandidate } from 'shared/types'
+
+/** 把候选禁选原因转换为用户能直接处理的状态说明。 */
+function disabledReasonText(reason: CandidateDisabledReason) {
+  switch (reason) {
+    case 'accountInactive':
+      return '账号不可用'
+    case 'memberInactive':
+      return '成员已停用'
+    case 'scopeInactive':
+      return '所属企业或项目已停用'
+    case 'organizationInactive':
+      return '命中的组织已停用'
+    case 'positionInactive':
+      return '命中的岗位已停用'
+    default:
+      return '不可选择'
+  }
+}
+
+/** 没有标签时展示稳定占位，避免组织、岗位和角色被误认为同一列。 */
+function EmptyTagValue() {
+  return <Typography.Text type="secondary">—</Typography.Text>
+}
+
+/** 构造成员候选表格列，同名组织始终携带来源作用域和完整路径。 */
+export function useOrganizationMemberCandidateColumns(): ProColumns<OrganizationMemberCandidate>[] {
+  const { tr } = useI18n()
+  return [
+    {
+      title: tr('搜索'),
+      dataIndex: 'query',
+      hideInTable: true,
+      fieldProps: { placeholder: tr('搜索姓名或完整账号') },
+    },
+    { title: tr('姓名'), dataIndex: 'name', search: false, width: 130 },
+    {
+      title: tr('完整账号'),
+      dataIndex: 'account',
+      search: false,
+      copyable: true,
+      width: 180,
+    },
+    {
+      title: tr('企业 / 项目'),
+      search: false,
+      width: 180,
+      render: (_, candidate) => (
+        <Space size={[0, 4]} wrap>
+          {candidate.identities.map((identity) => (
+            <Tag key={identity.memberId}>{identity.scopeName}</Tag>
+          ))}
+        </Space>
+      ),
+    },
+    {
+      title: tr('组织'),
+      search: false,
+      width: 300,
+      render: (_, candidate) => {
+        const tags = candidate.identities.flatMap((identity) =>
+          identity.organizationUnits.map((unit) => (
+            <Tag key={`${identity.memberId}:${unit.membershipId}`} color="purple">
+              {identity.scopeName} / {unit.fullPath}
+            </Tag>
+          )),
+        )
+        return tags.length ? (
+          <Space size={[0, 4]} wrap>
+            {tags}
+          </Space>
+        ) : (
+          <EmptyTagValue />
+        )
+      },
+    },
+    {
+      title: tr('岗位'),
+      search: false,
+      width: 220,
+      render: (_, candidate) => {
+        const tags = candidate.identities.flatMap((identity) =>
+          identity.positions.map((position) => (
+            <Tag key={`${identity.memberId}:${position.id}`} color="blue">
+              {identity.scopeName} / {position.name}
+            </Tag>
+          )),
+        )
+        return tags.length ? (
+          <Space size={[0, 4]} wrap>
+            {tags}
+          </Space>
+        ) : (
+          <EmptyTagValue />
+        )
+      },
+    },
+    {
+      title: tr('权限角色'),
+      search: false,
+      width: 220,
+      render: (_, candidate) => {
+        const tags = candidate.identities.flatMap((identity) =>
+          identity.roles.map((role) => (
+            <Tag key={`${identity.memberId}:${role.id}`} color="cyan">
+              {identity.scopeName} / {role.name}
+            </Tag>
+          )),
+        )
+        return tags.length ? (
+          <Space size={[0, 4]} wrap>
+            {tags}
+          </Space>
+        ) : (
+          <EmptyTagValue />
+        )
+      },
+    },
+    {
+      title: tr('状态'),
+      search: false,
+      fixed: 'right',
+      width: 150,
+      render: (_, candidate) =>
+        candidate.disabled ? (
+          <Typography.Text type="danger">
+            {tr(disabledReasonText(candidate.disabledReason))}
+          </Typography.Text>
+        ) : (
+          <Typography.Text type="success">{tr('可选择')}</Typography.Text>
+        ),
+    },
+  ]
+}