feat: 增加工作人员组织联动

2026-08-11 14:28:13 +08:00
parent 4d79a4917e
commit 4b1f045806
11 changed files with 626 additions and 22 deletions
--- a/docs/操作日志_工作人员组织联动_20260811.md
+++ b/docs/操作日志_工作人员组织联动_20260811.md
@@ -0,0 +1,68 @@
+# 工作人员气站与配送点联动操作日志
+
+操作时间：2026-08-11 14:18:22
+操作类型：扩展
+影响模块：平台总后台工作人员新建与编辑
+
+## 操作前状态
+
+- 5173 平台总后台工作人员表单中的气站和配送点是两个独立下拉框，用户可以选出不属于同一组织的组合，只能在保存时收到通用参数错误。
+- 关联选项固定预加载前 100 条；编辑记录不在当前选项中时会回显原始唯一标识，搜索也无法携带父级气站条件。
+- 平台、气站和配送点后端已经具备最终组织一致性校验；平台配送点列表也已支持 `gas_basic_identities` 过滤，无需新增接口或收紧业务规则。
+- 工作人员角色与组织归属没有一一对应的必填或互斥规则，平台主管配送点允许不设置所属气站。
+
+## 具体操作
+
+- 在资源字段中新增可选 `relationLinkage` 配置，仅为工作人员的所属配送点启用，其他标准资源和业务动作保持独立选择。
+- 工作人员字段名称调整为“所属气站”和“所属配送点”，下拉继续提交稳定唯一标识。
+- 实现双向联动：
+  - 选择气站后以 `gas_basic_identities` 查询直属配送点。
+  - 先选普通配送点时自动补载并回填所属气站。
+  - 选择平台主管配送点时保持气站为空。
+  - 更换或清空气站时，仅在已取得配送点记录并确认不兼容后清空配送点，同时给出明确提示。
+- 编辑初始化按唯一标识补载当前气站和配送点，不因前 100 条限制丢失中文回显；历史不一致组合只提示，不在加载阶段静默修改。
+- 配送点搜索始终复用当前气站条件并保留当前选项；增加请求版本控制，旧搜索或旧筛选结果不能覆盖新结果。
+- 关联请求失败时保留现有选项并显示错误，不把网络问题误判为组织关系变化。
+- 保存前增加友好的组织组合校验，后端现有一致性校验继续作为最终防线；保存失败仍保留表单和头像状态。
+
+## 操作后状态
+
+- 新增工作人员、安装人员、配送人员和运维人员入口共用同一联动能力，新建与编辑均已覆盖。
+- 气站下拉选定后，配送点下拉只展示该气站直属记录；配送点先选时可自动确定所属气站。
+- 平台直属配送点仍可在气站为空时选择；选定气站后不会混入其配送点范围。
+- 用户服务关系、配送合同、智能气阀归属和业务动作弹窗未启用本次配置，行为保持不变。
+- 5175 气站后台和 5176 配送点后台不在本次范围，继续由服务端登录组织限定可选范围。
+- 后端接口、数据库结构、角色规则和现有组织校验均未修改。
+
+## 代码变更
+
+- `frontend/platform_admin/src/api/resources.ts`：新增字段级关联联动元数据，并仅配置工作人员所属配送点。
+- `frontend/platform_admin/src/views/resource/ResourceFieldForm.vue`：关联字段搜索和变更事件携带完整字段配置。
+- `frontend/platform_admin/src/views/resource/use-resource-relation-linkage.ts`：新增父子关联的预加载、筛选、回填、清理、搜索和校验协调器。
+- `frontend/platform_admin/src/views/resource/resource-relation-linkage-policy.ts`：新增可测试的父子关系判断、筛选参数和请求版本策略。
+- `frontend/platform_admin/src/views/resource/use-resource-relations.ts`：扩展关联过滤、选中项补载、当前值保留和过期请求保护。
+- `frontend/platform_admin/src/views/resource/ResourceRecordPage.vue`：在新建与编辑页接入显式联动和保存前校验。
+- `frontend/platform_admin/src/views/resource/ResourceActionDialog.vue`：适配新的字段级搜索事件，保持业务动作不启用联动。
+- `frontend/platform_admin/scripts/check-staff-organization-linkage.mjs`、`package.json`：新增组织联动行为检查命令。
+- `docs/项目文档_标准资源全页管理_v1.0.md`：补充组织联动设计、行为和维护约定。
+
+## 验证结果
+
+- `npm.cmd run staff-organization:check`：通过；覆盖同气站保留、跨气站清除、气站清空、平台主管配送点、加载失败不误清、保存前提示、筛选参数和请求版本。
+- `npm.cmd run type:check`：通过。
+- `npm.cmd run resource-pages:check`：通过，详情 46 类、新建 25 类、编辑 23 类。
+- `npm.cmd run account-roles:check`：通过，既有角色中文展示未回退。
+- `npm.cmd run avatar-retry:check`：通过，保存失败头像重试缓存未回退。
+- `npm.cmd run contract:check`：通过，48 个资源契约一致。
+- `npm.cmd run build`：通过，Vite 生产构建完成。
+- 变更文件定向 `biome lint`：通过，无新增错误；全项目 `npm.cmd run lint` 仍被既有 2 个错误、153 个警告和 12 个提示阻断，本次未扩大范围清理历史诊断。
+- 本地浏览器只读回归：工作人员新建页显示新字段名称；选择“和气示例气站 10”后配送点范围只出现其直属“和气示例配送点 10”，选中后两项正确回显；页面控制台无错误或警告；未提交测试数据。
+- `git diff --check`：通过，未发现空白符错误。
+
+## 风险评估
+
+- 平台配送点筛选每次最多返回 100 条；用户仍可通过关键字继续搜索同一气站范围，当前已选记录会独立补载并保留。
+- 如果旧记录存在不一致组合，页面会提示并在保存前要求修正，但不会在打开页面时自动修改数据。
+- 无法加载配送点详情时前端不会主动清空；此时后端仍会在保存时执行最终组织校验。
+- 联动配置当前只允许一个显式子字段；若未来同一表单需要多组父子关系，应先扩展协调器结构并新增覆盖测试。
+- 本次不按角色新增组织必填规则，不改变平台主管配送点的数据语义，也不影响气站后台、配送点后台或其他资源。
--- a/docs/项目文档_标准资源全页管理_v1.0.md
+++ b/docs/项目文档_标准资源全页管理_v1.0.md
@@ -31,7 +31,8 @@ platforms/
 ├── frontend/platform_admin/
 │   ├── scripts/
 │   │   ├── check-backend-contract.mjs       # 前后端资源契约检查
-│   │   └── check-resource-pages.mjs         # 独立页面覆盖与抽屉残留检查
+│   │   ├── check-resource-pages.mjs         # 独立页面覆盖与抽屉残留检查
+│   │   └── check-staff-organization-linkage.mjs # 工作人员组织联动检查
 │   └── src/
 │       ├── api/
 │       │   ├── resource-page-rules.ts       # 新建、编辑、只读和状态限制规则
@@ -44,7 +45,7 @@ platforms/
 │       │   ├── finance-route.ts             # 钱包与财务路由分组
 │       │   └── platform.ts                  # 平台业务列表路由
 │       └── views/
-│           ├── resource/                    # 共享全页详情、表单、动作和摘要组件
+│           ├── resource/                    # 共享全页详情、表单、动作、联动和摘要组件
 │           └── shared/
 │               ├── CrudListPage.vue                 # 列表与全页跳转入口
 │               ├── ProtectedAvatarThumbnail.vue     # 受控头像缩略图
@@ -89,6 +90,9 @@ platforms/
 - 必填、密码最短 6 位、关系选项和金额转换复用统一校验与负载构建逻辑。
 - 页面检测表单和头像变更；返回、取消或浏览器路由离开时均提示是否放弃未保存内容。
 - 机构“账户管理”不再打开二级模态框，而是进入带机构过滤条件的隐藏账户列表及其独立 CRUD 页面。
+- 工作人员表单通过字段级可选配置启用气站与配送点联动：选择气站后只查询其直属配送点，先选普通配送点时自动回填所属气站；平台主管配送点仅在气站为空时可选。
+- 更换或清空气站时只在已确认配送点不兼容后清空当前值；关联数据加载失败会保留现值，编辑记录不在列表前 100 条时按唯一标识补载。
+- 配送点搜索始终携带当前气站条件，并以请求版本丢弃过期响应；未配置联动的用户服务关系、合同、产品和业务动作保持原行为。

 ### 4.4 安全与兼容

@@ -112,6 +116,7 @@ platforms/
 | 返回来源 | 关闭抽屉 | 安全 `return_to` 返回 |
 | 未保存修改 | 关闭即丢失 | 离开前二次确认 |
 | 账户列表头像 | 普通文本列固定显示“-” | 当前可视记录显示受控圆形缩略图，无头像回退默认图 |
+| 工作人员组织选择 | 气站和配送点独立选择，保存时才发现不匹配 | 双向联动、按气站筛选、切换时清除不兼容配送点 |

 ## 6. 验证方法

@@ -119,6 +124,7 @@ platforms/

 ```powershell
 npm.cmd run resource-pages:check
+npm.cmd run staff-organization:check
 npm.cmd run account-roles:check
 npm.cmd run contract:check
 npm.cmd run build
@@ -138,6 +144,7 @@ go test ./...
 - 服务端 Update DTO 变化时必须同步 `resource-page-rules.ts`，禁止直接把创建字段复用于更新。
 - 新增详情专属内容时优先扩展详情区块或动作适配器，不把长流程塞回列表。
 - 新增关联跳转时必须使用安全返回路径工具，不直接信任查询参数。
+- 新增父子关联表单时必须显式配置 `relationLinkage`，不得按关联资源地址做全局推断；涉及强制业务规则时应同步增加后端专用校验。
 - 新增标准资源后必须运行页面覆盖检查，保证详情、新建和编辑能力与资源模式一致。

 ## 8. 已知边界
--- a/frontend/platform_admin/package.json
+++ b/frontend/platform_admin/package.json
@@ -16,6 +16,7 @@
    "resource-pages:check": "node scripts/check-resource-pages.mjs",
    "account-roles:check": "node scripts/check-account-role-presentation.mjs",
    "avatar-retry:check": "node scripts/check-avatar-upload-cache.mjs",
+    "staff-organization:check": "node scripts/check-staff-organization-linkage.mjs",
    "audit:platform": "node scripts/check-backend-contract.mjs",
    "lint": "biome lint .",
    "lint:fix": "biome lint --write .",
--- a/frontend/platform_admin/scripts/check-staff-organization-linkage.mjs
+++ b/frontend/platform_admin/scripts/check-staff-organization-linkage.mjs
@@ -0,0 +1,138 @@
+/**
+ * 功能：验证工作人员气站与配送点联动策略及页面隔离配置。
+ * 版本：v1.0.0
+ */
+import assert from 'node:assert/strict';
+import { readFile } from 'node:fs/promises';
+import { transformWithOxc } from 'vite';
+
+const policyURL = new URL(
+  '../src/views/resource/resource-relation-linkage-policy.ts',
+  import.meta.url,
+);
+const source = await readFile(policyURL, 'utf8');
+const transformed = await transformWithOxc(source, policyURL.pathname);
+const moduleURL = `data:text/javascript;base64,${Buffer.from(transformed.code).toString('base64')}`;
+const {
+  createRelationRequestVersionGuard,
+  linkedRelationFilters,
+  linkedRelationValidationMessage,
+  optionParentIdentity,
+  shouldClearLinkedOption,
+} = await import(moduleURL);
+
+const gasA = 'gas-a';
+const gasB = 'gas-b';
+const deliveryA = { identity: 'delivery-a', gas_basic_identity: gasA };
+const platformDelivery = {
+  identity: 'delivery-platform',
+  gas_basic_identity: '',
+};
+
+assert.equal(
+  optionParentIdentity(deliveryA, 'gas_basic_identity'),
+  gasA,
+  '普通配送点必须能回填所属气站',
+);
+assert.equal(
+  optionParentIdentity(platformDelivery, 'gas_basic_identity'),
+  '',
+  '平台主管配送点必须保持气站为空',
+);
+
+assert.equal(
+  shouldClearLinkedOption(gasA, deliveryA, 'gas_basic_identity'),
+  false,
+  '同一气站的配送点必须保留',
+);
+assert.equal(
+  shouldClearLinkedOption(gasB, deliveryA, 'gas_basic_identity'),
+  true,
+  '切换到其他气站必须清空原配送点',
+);
+assert.equal(
+  shouldClearLinkedOption('', deliveryA, 'gas_basic_identity'),
+  true,
+  '清空气站时必须清空普通配送点',
+);
+assert.equal(
+  shouldClearLinkedOption('', platformDelivery, 'gas_basic_identity'),
+  false,
+  '清空气站时允许保留平台主管配送点',
+);
+assert.equal(
+  shouldClearLinkedOption(gasA, platformDelivery, 'gas_basic_identity'),
+  true,
+  '选择气站时平台主管配送点不应作为其直属配送点保留',
+);
+assert.equal(
+  shouldClearLinkedOption(gasA, undefined, 'gas_basic_identity'),
+  false,
+  '无法加载配送点记录时不得误清当前值',
+);
+
+assert.match(
+  linkedRelationValidationMessage(
+    gasB,
+    'delivery-a',
+    deliveryA,
+    'gas_basic_identity',
+  ),
+  /不属于所属气站/,
+);
+assert.match(
+  linkedRelationValidationMessage(
+    gasA,
+    'delivery-platform',
+    platformDelivery,
+    'gas_basic_identity',
+  ),
+  /平台主管配送点/,
+);
+assert.match(
+  linkedRelationValidationMessage(
+    '',
+    'delivery-a',
+    deliveryA,
+    'gas_basic_identity',
+  ),
+  /确认所属气站/,
+);
+assert.equal(
+  linkedRelationValidationMessage(
+    gasA,
+    'delivery-a',
+    deliveryA,
+    'gas_basic_identity',
+  ),
+  '',
+);
+assert.deepEqual(linkedRelationFilters(gasA, 'gas_basic_identities'), {
+  gas_basic_identities: gasA,
+});
+assert.equal(
+  linkedRelationFilters('', 'gas_basic_identities'),
+  undefined,
+  '未选气站时允许查询全部配送点，包括平台主管配送点',
+);
+
+const requestGuard = createRelationRequestVersionGuard();
+const firstRequest = requestGuard.begin('/delivery_basic');
+const secondRequest = requestGuard.begin('/delivery_basic');
+assert.equal(requestGuard.isLatest('/delivery_basic', firstRequest), false);
+assert.equal(requestGuard.isLatest('/delivery_basic', secondRequest), true);
+
+const resourcesSource = await readFile(
+  new URL('../src/api/resources.ts', import.meta.url),
+  'utf8',
+);
+assert.equal(
+  (resourcesSource.match(/relationLinkage:/g) ?? []).length,
+  1,
+  '联动配置只能显式启用于工作人员配送点字段',
+);
+assert.match(resourcesSource, /filterKey: 'gas_basic_identities'/);
+assert.match(resourcesSource, /label: '所属气站'/);
+assert.match(resourcesSource, /label: '所属配送点'/);
+
+console.log('工作人员气站与配送点联动检查通过');
--- a/frontend/platform_admin/src/api/resources.ts
+++ b/frontend/platform_admin/src/api/resources.ts
@@ -18,6 +18,14 @@ export type ResourceFieldType =
  | 'textarea'
  | 'select';

+/** 关联下拉的父子联动配置；未配置的资源继续保持独立选择。 */
+export type ResourceRelationLinkage = {
+  parentKey: string;
+  optionParentKey: string;
+  filterKey: string;
+  backfillParent?: boolean;
+};
+
 export type ResourceField = {
  key: string;
  label: string;
@@ -32,6 +40,7 @@ export type ResourceField = {
  defaultValue?: string | number | boolean;
  readonlyOnCreate?: boolean;
  unknownValueLabel?: string;
+  relationLinkage?: ResourceRelationLinkage;
 };

 export type DetailAction = {
@@ -339,7 +348,7 @@ export const resources: ResourceUiDefinition[] = [
  define('gas_account', '气站账户', 'writable', [f('username', { required: true }), f('password', { required: true }), f('display_name'), fixedAdminRole('气站管理员'), relation('gas_basic_identity', '/gas_basic', true)]),
  { ...define('delivery_basic', '配送点管理', 'writable', [f('delivery_code', { required: true }), f('name', { required: true }), f('gas_basic_identity', { label: '气站', listLabel: '气站名称', type: 'identity', relation: '/gas_basic', displayRelationLabel: true, emptyText: '平台直属', placeholder: '请选择气站，留空表示平台直属' }), f('principal'), f('address')]), accountManagement: { resource: '/delivery_account', relationKey: 'delivery_basic_identity', title: '配送点账户' }, walletOwnerType: 'delivery' },
  define('delivery_account', '配送点账户', 'writable', [f('username', { required: true }), f('password', { required: true }), f('display_name'), fixedAdminRole('配送点管理员'), relation('delivery_basic_identity', '/delivery_basic', true)]),
-  { ...define('staff_account', '工作人员', 'writable', [f('username', { required: true }), f('password', { required: true }), f('name', { required: true }), f('phone'), f('avatar'), f('role_code', { required: true, type: 'select', options: [{ label: '安装人员', value: 'installer' }, { label: '配送人员', value: 'delivery' }, { label: '运维人员', value: 'operations' }] }), relation('gas_basic_identity', '/gas_basic'), relation('delivery_basic_identity', '/delivery_basic'), f('work_status', { type: 'select', options: [{ label: '在岗', value: 'on_duty' }, { label: '离岗', value: 'off_duty' }] })]), walletOwnerType: 'staff' },
+  { ...define('staff_account', '工作人员', 'writable', [f('username', { required: true }), f('password', { required: true }), f('name', { required: true }), f('phone'), f('avatar'), f('role_code', { required: true, type: 'select', options: [{ label: '安装人员', value: 'installer' }, { label: '配送人员', value: 'delivery' }, { label: '运维人员', value: 'operations' }] }), f('gas_basic_identity', { label: '所属气站', type: 'identity', relation: '/gas_basic' }), f('delivery_basic_identity', { label: '所属配送点', type: 'identity', relation: '/delivery_basic', relationLinkage: { parentKey: 'gas_basic_identity', optionParentKey: 'gas_basic_identity', filterKey: 'gas_basic_identities', backfillParent: true } }), f('work_status', { type: 'select', options: [{ label: '在岗', value: 'on_duty' }, { label: '离岗', value: 'off_duty' }] })]), walletOwnerType: 'staff' },
  define('staff_credential', '工作人员资质', 'writable', [relation('staff_account_identity', '/staff_account', true), f('credential_type', { required: true }), f('credential_no'), f('expired_at')]),
  { ...define('user_account', '用户账户', 'writable', [f('username', { required: true }), f('password', { required: true }), f('name', { required: true }), f('phone'), f('avatar'), f('real_name')]), walletOwnerType: 'user' },
  define('user_address', '用户地址', 'writable', [relation('user_account_identity', '/user_account', true), f('address', { required: true }), f('longitude'), f('latitude'), f('is_default')]),
--- a/frontend/platform_admin/src/views/resource/ResourceActionDialog.vue
+++ b/frontend/platform_admin/src/views/resource/ResourceActionDialog.vue
@@ -25,7 +25,7 @@
        :required-keys="requiredKeys"
        :relation-options="relations.options"
        :relation-loading="relations.loading"
-        @search-relation="relations.search"
+        @search-relation="searchRelation"
      />
    </a-form>
  </a-modal>
@@ -37,7 +37,7 @@ import { computed, reactive, ref, watch } from 'vue';
 import { buildResourcePayload, isMissingField } from '@/api/resource-form';
 import { resourceApi } from '@/api/resource';
 import { platformApi } from '@/api/platform';
-import type { DetailAction } from '@/api/resources';
+import type { DetailAction, ResourceField } from '@/api/resources';
 import type { ResourceRow } from '@/api/resource-page-rules';
 import ResourceFieldForm from './ResourceFieldForm.vue';
 import { useResourceRelations } from './use-resource-relations';
@@ -70,6 +70,11 @@ const ownershipKeys = [
  'user_account_identity',
 ];

+/** 业务动作字段不启用记录页联动，只沿用普通关联搜索。 */
+function searchRelation(field: ResourceField, keyword: string) {
+  relations.search(field.relation, keyword);
+}
+
 watch(
  () => [props.visible, props.action?.name] as const,
  async ([visible]) => {
--- a/frontend/platform_admin/src/views/resource/ResourceFieldForm.vue
+++ b/frontend/platform_admin/src/views/resource/ResourceFieldForm.vue
@@ -76,7 +76,8 @@
        :loading="relationLoading[field.relation ?? '']"
        allow-clear
        allow-search
-        @search="(value: string) => emit('search-relation', field.relation, value)"
+        @change="(value: unknown) => emit('change-relation', field, value)"
+        @search="(value: string) => emit('search-relation', field, value)"
      >
        <a-option
          v-for="option in relationOptions[field.relation ?? ''] ?? []"
@@ -122,7 +123,8 @@ const props = withDefaults(
 );

 const emit = defineEmits<{
-  'search-relation': [resource: string | undefined, keyword: string];
+  'change-relation': [field: ResourceField, value: unknown];
+  'search-relation': [field: ResourceField, keyword: string];
 }>();
 const model = defineModel<Record<string, any>>({ required: true });
 const disabledSet = computed(() => new Set(props.disabledKeys));
--- a/frontend/platform_admin/src/views/resource/ResourceRecordPage.vue
+++ b/frontend/platform_admin/src/views/resource/ResourceRecordPage.vue
@@ -103,7 +103,8 @@
              :relation-options="relations.options"
              :relation-loading="relations.loading"
              :role-options="roleOptions"
-              @search-relation="relations.search"
+              @change-relation="relationLinkage.change"
+              @search-relation="relationLinkage.search"
            />
          </a-form>
          <div class="form-actions">
@@ -169,6 +170,7 @@ import ResourceFieldForm from './ResourceFieldForm.vue';
 import ResourceWalletSummary from './ResourceWalletSummary.vue';
 import { createResourceRecordNavigation } from './resource-record-navigation';
 import { useResourceAvatar } from './use-resource-avatar';
+import { useResourceRelationLinkage } from './use-resource-relation-linkage';
 import { useResourceRelations } from './use-resource-relations';
 import { useUnsavedRecord } from './use-unsaved-record';

@@ -198,6 +200,7 @@ const fieldOptions = reactive<
  Record<string, Array<{ label: string; value: string | number }>>
 >({});
 const relations = useResourceRelations();
+const relationLinkage = useResourceRelationLinkage(form, relations);
 const actionVisible = ref(false);
 const activeAction = ref<DetailAction>();
 const avatar = useResourceAvatar();
@@ -357,9 +360,11 @@ async function initialize() {
 }

 async function loadRelationsAndRoles() {
-  await relations.preload(
-    mode.value === 'detail' ? definition.value.fields : formFields.value,
-  );
+  if (mode.value === 'detail') {
+    await relations.preload(definition.value.fields);
+  } else {
+    await relationLinkage.preload(formFields.value);
+  }
  if (
    definition.value.fields.some((field) => field.key === 'platform_role_code')
  ) {
@@ -410,6 +415,11 @@ async function save() {
    Message.warning(validationError);
    return;
  }
+  const linkageError = relationLinkage.validationMessage();
+  if (linkageError) {
+    Message.warning(linkageError);
+    return;
+  }
  saving.value = true;
  try {
    const payload = buildResourcePayload(
--- a/frontend/platform_admin/src/views/resource/resource-relation-linkage-policy.ts
+++ b/frontend/platform_admin/src/views/resource/resource-relation-linkage-policy.ts
@@ -0,0 +1,76 @@
+/**
+ * 功能：提供父子关联下拉的纯业务判断，避免页面层重复推断组织归属。
+ * 版本：v1.0.0
+ */
+import type { ResourceRow } from '@/api/resource-page-rules';
+
+/** 将表单或关联记录中的标识规范化为空字符串或稳定字符串。 */
+export function relationIdentity(value: unknown) {
+  return value == null ? '' : String(value).trim();
+}
+
+/** 读取子选项记录声明的父级标识。 */
+export function optionParentIdentity(
+  option: ResourceRow | undefined,
+  optionParentKey: string,
+) {
+  return option ? relationIdentity(option[optionParentKey]) : '';
+}
+
+/**
+ * 仅在已取得子选项记录且父子关系明确不兼容时返回 true。
+ * 父级为空时只允许平台主管子项；父级有值时只允许其直属子项。
+ */
+export function shouldClearLinkedOption(
+  parentIdentity: string,
+  option: ResourceRow | undefined,
+  optionParentKey: string,
+) {
+  if (!option) return false;
+  const optionParent = optionParentIdentity(option, optionParentKey);
+  return parentIdentity ? optionParent !== parentIdentity : Boolean(optionParent);
+}
+
+/** 返回父子组合的保存前提示；无法取得子选项时交由后端最终校验。 */
+export function linkedRelationValidationMessage(
+  parentIdentity: string,
+  childIdentity: string,
+  option: ResourceRow | undefined,
+  optionParentKey: string,
+) {
+  if (!childIdentity || !option) return '';
+  const optionParent = optionParentIdentity(option, optionParentKey);
+  if (parentIdentity && !optionParent) {
+    return '平台主管配送点不能与所属气站同时选择';
+  }
+  if (parentIdentity && optionParent !== parentIdentity) {
+    return '所选配送点不属于所属气站，请重新选择';
+  }
+  if (!parentIdentity && optionParent) {
+    return '所选配送点已有所属气站，请确认所属气站';
+  }
+  return '';
+}
+
+/** 根据当前父级生成服务端筛选条件；父级为空时保留全量可选范围。 */
+export function linkedRelationFilters(
+  parentIdentity: string,
+  filterKey: string,
+) {
+  return parentIdentity ? { [filterKey]: parentIdentity } : undefined;
+}
+
+/** 为同一关联资源生成递增版本号，用于识别并丢弃过期响应。 */
+export function createRelationRequestVersionGuard() {
+  const versions = new Map<string, number>();
+  return {
+    begin(resource: string) {
+      const version = (versions.get(resource) ?? 0) + 1;
+      versions.set(resource, version);
+      return version;
+    },
+    isLatest(resource: string, version: number) {
+      return versions.get(resource) === version;
+    },
+  };
+}
--- a/frontend/platform_admin/src/views/resource/use-resource-relation-linkage.ts
+++ b/frontend/platform_admin/src/views/resource/use-resource-relation-linkage.ts
@@ -0,0 +1,195 @@
+/**
+ * 功能：协调资源表单中显式启用的父子关联下拉、搜索和保存前校验。
+ * 版本：v1.0.0
+ */
+import { Message } from '@arco-design/web-vue';
+import type { ResourceField } from '@/api/resources';
+import {
+  linkedRelationFilters,
+  linkedRelationValidationMessage,
+  optionParentIdentity,
+  relationIdentity,
+  shouldClearLinkedOption,
+} from './resource-relation-linkage-policy';
+import type { ResourceRelations } from './use-resource-relations';
+
+type ActiveLinkage = {
+  childField: ResourceField;
+  parentField?: ResourceField;
+};
+
+export function useResourceRelationLinkage(
+  form: Record<string, any>,
+  relations: ResourceRelations,
+) {
+  let active: ActiveLinkage | undefined;
+  let initialized = false;
+
+  function findOption(resource: string, identity: string) {
+    return (relations.options[resource] ?? []).find(
+      (row) => relationIdentity(row.identity) === identity,
+    );
+  }
+
+  function configure(fields: ResourceField[]) {
+    const childField = fields.find((field) => field.relationLinkage);
+    if (!childField?.relationLinkage) {
+      active = undefined;
+      return;
+    }
+    active = {
+      childField,
+      parentField: fields.find(
+        (field) => field.key === childField.relationLinkage?.parentKey,
+      ),
+    };
+  }
+
+  function childRequest() {
+    if (!active?.childField.relationLinkage) return {};
+    const linkage = active.childField.relationLinkage;
+    const parentIdentity = relationIdentity(form[linkage.parentKey]);
+    const childIdentity = relationIdentity(form[active.childField.key]);
+    return {
+      filters: linkedRelationFilters(parentIdentity, linkage.filterKey),
+      preserveIdentities: childIdentity ? [childIdentity] : [],
+    };
+  }
+
+  async function reloadChildOptions() {
+    const resource = active?.childField.relation;
+    if (!resource) return;
+    relations.cancelSearch(resource);
+    await relations.load(resource, '', childRequest());
+  }
+
+  /** 预加载普通关联项，并单独按父级条件加载启用联动的子选项。 */
+  async function preload(fields: ResourceField[]) {
+    initialized = false;
+    configure(fields);
+    if (!active?.childField.relationLinkage || !active.childField.relation) {
+      await relations.preload(fields);
+      initialized = true;
+      return;
+    }
+
+    await relations.preload(
+      fields.filter((field) => field.key !== active?.childField.key),
+    );
+    const linkage = active.childField.relationLinkage;
+    const parentIdentity = relationIdentity(form[linkage.parentKey]);
+    const childIdentity = relationIdentity(form[active.childField.key]);
+    if (parentIdentity && active.parentField?.relation) {
+      await relations.ensure(active.parentField.relation, parentIdentity);
+    }
+    if (childIdentity) {
+      await relations.ensure(active.childField.relation, childIdentity);
+    }
+    await reloadChildOptions();
+    initialized = true;
+
+    const warning = validationMessage();
+    if (warning) Message.warning(`当前组织归属需要确认：${warning}`);
+  }
+
+  async function handleParentChange(parentIdentity: string) {
+    if (!active?.childField.relationLinkage || !active.childField.relation)
+      return;
+    const linkage = active.childField.relationLinkage;
+    const childIdentity = relationIdentity(form[active.childField.key]);
+    if (childIdentity) {
+      const option =
+        findOption(active.childField.relation, childIdentity) ??
+        (await relations.ensure(active.childField.relation, childIdentity));
+      if (
+        relationIdentity(form[linkage.parentKey]) !== parentIdentity ||
+        relationIdentity(form[active.childField.key]) !== childIdentity
+      ) {
+        return;
+      }
+      if (
+        shouldClearLinkedOption(
+          parentIdentity,
+          option,
+          linkage.optionParentKey,
+        )
+      ) {
+        form[active.childField.key] = '';
+        Message.info('所属气站已变更，请重新选择配送点');
+      }
+    }
+    await reloadChildOptions();
+  }
+
+  async function handleChildChange(childIdentity: string) {
+    if (!active?.childField.relationLinkage || !active.childField.relation)
+      return;
+    const linkage = active.childField.relationLinkage;
+    if (!childIdentity) return;
+    const option =
+      findOption(active.childField.relation, childIdentity) ??
+      (await relations.ensure(active.childField.relation, childIdentity));
+    if (
+      !option ||
+      relationIdentity(form[active.childField.key]) !== childIdentity
+    ) {
+      return;
+    }
+    if (linkage.backfillParent) {
+      const nextParent = optionParentIdentity(option, linkage.optionParentKey);
+      const currentParent = relationIdentity(form[linkage.parentKey]);
+      if (nextParent && active.parentField?.relation) {
+        await relations.ensure(active.parentField.relation, nextParent);
+        if (relationIdentity(form[active.childField.key]) !== childIdentity) {
+          return;
+        }
+      }
+      if (currentParent !== nextParent) {
+        form[linkage.parentKey] = nextParent;
+        if (!nextParent && currentParent) {
+          Message.info('平台主管配送点不隶属于气站，已清空所属气站');
+        }
+      }
+    }
+    await reloadChildOptions();
+  }
+
+  /** 响应用户主动修改关联字段；初始化回显不会触发自动清理。 */
+  async function change(field: ResourceField, value: unknown) {
+    if (!initialized || !active?.childField.relationLinkage) return;
+    const identity = relationIdentity(value);
+    if (field.key === active.childField.relationLinkage.parentKey) {
+      await handleParentChange(identity);
+    } else if (field.key === active.childField.key) {
+      await handleChildChange(identity);
+    }
+  }
+
+  /** 搜索联动子项时始终保留父级过滤和当前选项。 */
+  function search(field: ResourceField, keyword: string) {
+    if (!field.relation) return;
+    if (field.key === active?.childField.key) {
+      relations.search(field.relation, keyword, childRequest());
+      return;
+    }
+    relations.search(field.relation, keyword);
+  }
+
+  /** 返回保存前的父子关系错误，空字符串代表当前组合可提交。 */
+  function validationMessage() {
+    if (!active?.childField.relationLinkage || !active.childField.relation)
+      return '';
+    const linkage = active.childField.relationLinkage;
+    const parentIdentity = relationIdentity(form[linkage.parentKey]);
+    const childIdentity = relationIdentity(form[active.childField.key]);
+    const option = findOption(active.childField.relation, childIdentity);
+    return linkedRelationValidationMessage(
+      parentIdentity,
+      childIdentity,
+      option,
+      linkage.optionParentKey,
+    );
+  }
+
+  return { preload, change, search, validationMessage };
+}
--- a/frontend/platform_admin/src/views/resource/use-resource-relations.ts
+++ b/frontend/platform_admin/src/views/resource/use-resource-relations.ts
@@ -3,29 +3,95 @@
 * 版本：v1.0.0
 */
 import { Message } from '@arco-design/web-vue';
-import { reactive } from 'vue';
+import { onBeforeUnmount, reactive } from 'vue';
 import { resourceApi } from '@/api/resource';
 import type { ResourceField } from '@/api/resources';
 import type { ResourceRow } from '@/api/resource-page-rules';
+import { createRelationRequestVersionGuard } from './resource-relation-linkage-policy';
+
+export type ResourceRelationLoadOptions = {
+  filters?: Record<string, string>;
+  preserveIdentities?: string[];
+};

 export function useResourceRelations() {
  const options = reactive<Record<string, ResourceRow[]>>({});
  const loading = reactive<Record<string, boolean>>({});
  const timers = new Map<string, ReturnType<typeof setTimeout>>();
+  const requestGuard = createRelationRequestVersionGuard();

-  /** 加载一类关联资源，工作人员关系默认只选择配送人员。 */
-  async function load(resource: string, keyword = '') {
+  /** 合并需要保留的当前选项，搜索和筛选时不让下拉框退回显示原始标识。 */
+  function mergePreserved(
+    resource: string,
+    rows: ResourceRow[],
+    identities: string[] = [],
+  ) {
+    const merged = [...rows];
+    const seen = new Set(rows.map((row) => String(row.identity ?? '')));
+    for (const identity of identities.filter(Boolean)) {
+      if (seen.has(identity)) continue;
+      const current = (options[resource] ?? []).find(
+        (row) => String(row.identity ?? '') === identity,
+      );
+      if (current) {
+        merged.push(current);
+        seen.add(identity);
+      }
+    }
+    return merged;
+  }
+
+  /** 加载一类关联资源，并丢弃已经过期的搜索或筛选响应。 */
+  async function load(
+    resource: string,
+    keyword = '',
+    request: ResourceRelationLoadOptions = {},
+  ) {
+    const version = requestGuard.begin(resource);
    loading[resource] = true;
    try {
-      const filters: Record<string, string> = keyword ? { keyword } : {};
+      const filters: Record<string, string> = {
+        ...(request.filters ?? {}),
+        ...(keyword ? { keyword } : {}),
+      };
      if (resource === '/staff_account') filters.role_code = 'delivery';
-      options[resource] = (
+      const rows = (
        await resourceApi.list<ResourceRow>(resource, 1, 100, filters)
      ).list;
+      if (!requestGuard.isLatest(resource, version)) return;
+      options[resource] = mergePreserved(
+        resource,
+        rows,
+        request.preserveIdentities,
+      );
    } catch (error) {
+      if (!requestGuard.isLatest(resource, version)) return;
      Message.error(`关联数据加载失败：${(error as Error).message}`);
    } finally {
-      loading[resource] = false;
+      if (requestGuard.isLatest(resource, version)) {
+        loading[resource] = false;
+      }
+    }
+  }
+
+  /** 按唯一标识补载当前选项，解决编辑记录不在列表前 100 条时的回显。 */
+  async function ensure(resource: string, identity: string) {
+    if (!identity) return undefined;
+    const current = (options[resource] ?? []).find(
+      (row) => String(row.identity ?? '') === identity,
+    );
+    if (current) return current;
+    try {
+      const row = await resourceApi.detail<ResourceRow>(resource, identity);
+      const resolved = (options[resource] ?? []).find(
+        (item) => String(item.identity ?? '') === identity,
+      );
+      if (resolved) return resolved;
+      options[resource] = [...(options[resource] ?? []), row];
+      return row;
+    } catch (error) {
+      Message.error(`关联数据加载失败：${(error as Error).message}`);
+      return undefined;
    }
  }

@@ -40,15 +106,42 @@ export function useResourceRelations() {
  }

  /** 对远程关系选项进行防抖搜索。 */
-  function search(resource: string | undefined, keyword: string) {
+  function search(
+    resource: string | undefined,
+    keyword: string,
+    request: ResourceRelationLoadOptions = {},
+  ) {
    if (!resource) return;
-    const timer = timers.get(resource);
-    if (timer) clearTimeout(timer);
+    cancelSearch(resource);
    timers.set(
      resource,
-      setTimeout(() => load(resource, keyword.trim()), 250),
+      setTimeout(() => {
+        timers.delete(resource);
+        void load(resource, keyword.trim(), request);
+      }, 250),
    );
  }

-  return { options, loading, load, preload, search };
+  /** 取消关联资源尚未触发的防抖搜索。 */
+  function cancelSearch(resource: string) {
+    const timer = timers.get(resource);
+    if (timer) clearTimeout(timer);
+    timers.delete(resource);
+  }
+
+  onBeforeUnmount(() => {
+    for (const resource of timers.keys()) cancelSearch(resource);
+  });
+
+  return {
+    options,
+    loading,
+    load,
+    ensure,
+    preload,
+    search,
+    cancelSearch,
+  };
 }
+
+export type ResourceRelations = ReturnType<typeof useResourceRelations>;