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

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 条；用户仍可通过关键字继续搜索同一气站范围，当前已选记录会独立补载并保留。
+- 如果旧记录存在不一致组合，页面会提示并在保存前要求修正，但不会在打开页面时自动修改数据。
+- 无法加载配送点详情时前端不会主动清空；此时后端仍会在保存时执行最终组织校验。
+- 联动配置当前只允许一个显式子字段；若未来同一表单需要多组父子关系，应先扩展协调器结构并新增覆盖测试。
+- 本次不按角色新增组织必填规则，不改变平台主管配送点的数据语义，也不影响气站后台、配送点后台或其他资源。

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. 已知边界