create-bubbles 0.1.26 → 0.1.28

package/template-vp-monorepo-react-nestjs/apps/web/src/components/Selector/BasicTableSelector/BasicTableSelectorSelection.ts

@@ -0,0 +1,91 @@
+import type {
+  BasicTableSelectorRowKey,
+  BasicTableSelectorShowOptions,
+} from './BasicTableSelectorTypes'
+
+/** 表格选择器内部的会话快照。仅保留已选对象，不累积缓存所有访问过的页面。 */
+export class BasicTableSelectorSelection<T extends object> {
+  readonly value: Key[]
+  readonly multiple: boolean
+  readonly rowKey: BasicTableSelectorRowKey<T>
+  private readonly records: Map<Key, T>
+
+  /** 复制并去重初始选中键，校验单选约束且只保留选中记录。 */
+  constructor(
+    options: BasicTableSelectorShowOptions<T> & {
+      multiple: boolean
+      rowKey: BasicTableSelectorRowKey<T>
+    },
+  ) {
+    this.value = [...new Set(options.value ?? [])]
+    this.multiple = options.multiple
+    this.rowKey = options.rowKey
+    if (!this.multiple && this.value.length > 1) {
+      throw new Error('BasicTableSelector 单选模式的 value 最多包含一个 key')
+    }
+    const selected = new Set(this.value)
+    this.records = new Map()
+    for (const row of options.selectedRows ?? []) {
+      const key = this.keyOf(row)
+      if (selected.has(key)) this.records.set(key, row)
+    }
+  }
+
+  /** 按配置提取稳定行键，键类型不受支持时抛出错误。 */
+  keyOf(row: T): Key {
+    const key = typeof this.rowKey === 'function' ? this.rowKey(row) : row[this.rowKey]
+    if (typeof key !== 'string' && typeof key !== 'number' && typeof key !== 'bigint') {
+      throw new Error('BasicTableSelector rowKey 必须返回稳定的字符串或数字 key')
+    }
+    return key
+  }
+
+  /** 读取指定已选 key 对应的对象快照。 */
+  get(key: Key) {
+    return this.records.get(key)
+  }
+
+  /** 返回当前选中但尚未取得完整记录的键。 */
+  get missingKeys() {
+    return this.value.filter((key) => !this.records.has(key))
+  }
+
+  /** 按选中键顺序返回完整记录，记录缺失时拒绝生成不完整结果。 */
+  get rows(): T[] {
+    return this.value.map(
+      /** 按选中键读取缓存记录，缺失时抛错避免提交不完整选择。 */ (key) => {
+        const row = this.records.get(key)
+        if (!row) throw new Error('部分已选数据尚未加载，请重新选择后重试')
+        return row
+      },
+    )
+  }
+
+  /** 创建更新后的选择快照，合并已知记录并过滤尚未加载的空行。 */
+  select(options: { value: readonly Key[]; rows?: readonly T[] }) {
+    return new BasicTableSelectorSelection<T>({
+      rowKey: this.rowKey,
+      multiple: this.multiple,
+      value: options.value,
+      // Ant Table 在仅回显 key 时，selectedRows 可能包含尚未缓存的空项。
+      selectedRows: [...this.records.values(), ...(options.rows ?? []).filter(Boolean)],
+    })
+  }
+
+  /** 补充已选记录的内容，同时保留现有选中键及顺序。 */
+  remember(rows: readonly T[]) {
+    return this.select({ value: this.value, rows })
+  }
+
+  /** 按缺失键补查选中记录，仍有不可用记录时抛错阻止确认。 */
+  async resolve(requestByKeys?: (keys: Key[]) => Promise<T[]>) {
+    const missing = this.missingKeys
+    if (!missing.length) return this
+    if (!requestByKeys) throw new Error('部分已选数据尚未加载，请重新选择后重试')
+    const resolved = this.remember(await requestByKeys(missing))
+    if (resolved.missingKeys.length) {
+      throw new Error('部分已选数据已不可用，请取消对应选择后重试')
+    }
+    return resolved
+  }
+}

package/template-vp-monorepo-react-nestjs/apps/web/src/components/Selector/BasicTableSelector/BasicTableSelectorTypes.ts

@@ -0,0 +1,60 @@
+import type { ParamsType, ProTableProps } from '@ant-design/pro-components'
+import type { ModalProps } from 'antd'
+
+export type BasicTableSelectorRowKey<T> = (keyof T & string) | ((record: T) => Key)
+
+export interface BasicTableSelectorShowOptions<T> {
+  /** 单选也传数组；省略表示从空选择开始。 */
+  value?: readonly Key[]
+  /** 为已有 key 提供对象，避免依赖当前页数据。组件不会修改这些对象。 */
+  selectedRows?: readonly T[]
+}
+
+export interface BasicTableSelectorRef<T> {
+  /** 打开一个隔离的选择会话，并可传入已有选中值和对象。 */
+  show: (options?: BasicTableSelectorShowOptions<T>) => void
+  /** 关闭当前选择会话，不提交本轮临时修改。 */
+  hide: () => void
+}
+
+type ManagedTableProps =
+  | 'ref'
+  | 'title'
+  | 'rowKey'
+  | 'rowSelection'
+  | 'request'
+  | 'dataSource'
+  | 'defaultData'
+  | 'editable'
+  | 'onChange'
+  | 'tableAlertRender'
+  | 'tableAlertOptionRender'
+
+export type BasicTableSelectorProps<
+  T extends object,
+  Params extends ParamsType = ParamsType,
+  ValueType = 'text',
+> = Omit<ProTableProps<T, Params, ValueType>, ManagedTableProps> & {
+  ref: Ref<BasicTableSelectorRef<T>>
+  title: ReactNode
+  rowKey: BasicTableSelectorRowKey<T>
+  request: NonNullable<ProTableProps<T, Params, ValueType>['request']>
+  multiple?: boolean
+  /** 仅点击确定时触发；keys 和 rows 长度、顺序始终一致。 */
+  onChange: (keys: Key[], rows: T[]) => void | Promise<void>
+  /** 确定时补查尚未取得对象的已选 key；返回顺序不限。 */
+  requestByKeys?: (keys: Key[]) => Promise<T[]>
+  labelRender?: (record: T) => ReactNode
+  /** 可选左侧浏览面板；选择摘要、错误和分页表格仍统一保留在右侧。 */
+  sidePanel?: ReactNode
+  /** 保留 ProTable 的分页、排序、筛选回调，避免与选择结果 onChange 重名。 */
+  onTableChange?: ProTableProps<T, Params, ValueType>['onChange']
+  getCheckboxProps?: Exclude<
+    ProTableProps<T, Params, ValueType>['rowSelection'],
+    false | undefined
+  >['getCheckboxProps']
+  modalProps?: Pick<
+    ModalProps,
+    'width' | 'centered' | 'okText' | 'cancelText' | 'className' | 'styles' | 'zIndex'
+  >
+}

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

@@ -0,0 +1,110 @@
+# BasicTableSelector
+
+与业务无关的表格选择弹窗，基于 ProTable。调用方提供标题、查询函数、稳定的 `rowKey` 和表格配置。默认单选，`multiple` 开启跨页多选。
+
+## 接口
+
+| 参数                       | 说明                                                                                         |
+| -------------------------- | -------------------------------------------------------------------------------------------- |
+| `ref`                      | 通过 `show({ value, selectedRows })` 打开，通过 `hide()` 关闭                                |
+| `title`                    | 弹窗标题                                                                                     |
+| `rowKey`                   | 唯一字段名或 `(record) => key`，禁止使用分页内的行索引                                       |
+| `request`                  | ProTable 原生查询函数，返回 `{ data, total, success }`                                       |
+| `multiple`                 | 默认 `false`，单选与多选的输入输出均为数组                                                   |
+| `onChange(keys, rows)`     | 点击确定后调用；两个数组长度与顺序一致。可返回 Promise，失败时保留弹窗和选择                 |
+| `requestByKeys(keys)`      | 可选，确定时补查缺失的已选对象；只请求缺失 key，结果顺序不限                                 |
+| `labelRender(record)`      | 已选标签的展示内容，默认显示 key                                                             |
+| `getCheckboxProps(record)` | 设置候选行是否禁选等属性                                                                     |
+| `onTableChange`            | ProTable 原生的分页、排序、筛选回调                                                          |
+| `modalProps`               | 弹窗宽度、居中、按钮文案、样式等配置                                                         |
+| 其他参数                   | 直接透传 `columns`、`params`、`pagination`、`search`、`scroll`、`actionRef` 等 ProTable 配置 |
+
+`show()` 的 `value` 为 key 数组，省略时从空选择开始；`selectedRows` 为这些 key 对应的对象，可选。多选支持跨分页、跨搜索保留选择，表头全选仅针对当前页。已选标签可以移除不在当前页的项，也可以清空全部。
+
+勾选仅修改弹窗内的临时选择，取消、关闭不会调用 `onChange`。空选择确认返回 `([], [])`，是否必选由业务表单校验。单选传入两个以上不同 key 会报错。
+
+## 使用
+
+```tsx
+import { Button } from 'antd'
+import {
+  BasicTableSelector,
+  type BasicTableSelectorRef,
+} from '@/components/Selector'
+
+interface Item {
+  id: string
+  name: string
+}
+
+const selectorRef = useRef<BasicTableSelectorRef<Item>>(null)
+const [keys, setKeys] = useState<Key[]>([])
+const [selectedRows, setSelectedRows] = useState<Item[]>([])
+
+<Button onClick={() => selectorRef.current?.show({ value: keys, selectedRows })}>
+  选择条目
+</Button>
+<BasicTableSelector<Item>
+  ref={selectorRef}
+  title="选择条目"
+  rowKey="id"
+  multiple
+  columns={[{ title: '名称', dataIndex: 'name' }]}
+  request={async (params, sort, filter) => {
+    const result = await queryItems({ params, sort, filter })
+    return { data: result.items, total: result.total, success: true }
+  }}
+  requestByKeys={queryItemsByKeys}
+  labelRender={(item) => item.name}
+  onChange={(nextKeys, nextRows) => {
+    setKeys(nextKeys)
+    setSelectedRows(nextRows)
+  }}
+/>
+```
+
+示例中的 `queryItems`、`queryItemsByKeys` 由业务侧提供。组件不拼接接口地址、不决定业务权限、不创建或保存业务数据。请求参数通过 `params` 提供；ProTable 原生 `request` 同时接收分页、搜索、排序与筛选参数。
+
+仅有 key 时，分页查询无法保证取得所有已选对象。再次打开优先传入已有 `selectedRows`；若只有 key，则提供 `requestByKeys`。当前页加载到的已选对象也可用于补全。没有对象的标签先展示 key，确定时补查；未查全或补查失败均不回调、不静默删项，用户可以重试或移除无效选择。
+
+每次打开创建独立会话，取消后不保留本轮勾选和对象缓存。外部数据变化不会自动覆盖已经打开的临时选择，需要时重新调用 `show()`。关闭或重开后，旧会话的迟到请求不能提交选择或关闭新弹窗。
+
+## 已选数据还要在业务表格中编辑
+
+选择器管理“选了哪些对象”，业务表格管理“这些行被编辑成什么内容”。选择结果不代表覆盖业务表格的指令。重新选择时按稳定 key 合并：保留仍被选中行的当前数据，只为新增项初始化字段，移除取消选择的项。
+
+```tsx
+interface DetailRow extends Item {
+  quantity: number
+  remark: string
+}
+
+const [details, setDetails] = useState<DetailRow[]>([])
+
+// 再次打开时，传入业务表格的当前数据。
+selectorRef.current?.show({
+  value: details.map((row) => row.id),
+  selectedRows: details,
+})
+
+// 作为 BasicTableSelector 的 onChange。函数式更新取得最新编辑结果。
+const handleSelectionChange = (_keys: Key[], selected: Item[]) => {
+  setDetails((current) => {
+    const existing = new Map(current.map((row) => [row.id, row]))
+    return selected.map(
+      (item) =>
+        existing.get(item.id) ?? {
+          ...item,
+          quantity: 1,
+          remark: '',
+        },
+    )
+  })
+}
+```
+
+这里采用一次 Map 查询完成合并，时间复杂度为 O(n + m)，不需要深比较整个对象，也不需要额外维护一份可能不同步的 keys 状态。已有行的所有字段及对象引用保持原样；如需刷新某些服务端字段，由业务明确指定合并规则。
+
+在同一次弹窗内取消再选回，已有编辑仍可保留。确认移除后，将来再次添加默认视为新行；如果需要“删除后再选回来也恢复编辑”，可由业务另存以 key 索引的草稿 Map。更复杂的表单可将 `selectedKeys` 与 `draftByKey` 分开保存，但一般表格使用上述合并即可。
+
+基础组件不返回业务增删改指令，也不负责保存草稿、校验权限或处理服务端版本冲突。

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

@@ -0,0 +1,7 @@
+export { default } from './BasicTableSelector'
+export type {
+  BasicTableSelectorProps,
+  BasicTableSelectorRef,
+  BasicTableSelectorRowKey,
+  BasicTableSelectorShowOptions,
+} from './BasicTableSelectorTypes'

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'