修复工作人员资质关联与角色过滤

按安装、配送、运维菜单显式过滤工作人员，锁定资质所有者并使用姓名和角色回显。

扩展工作人员状态与多角色查询，补充权限校验、回归测试、操作日志和项目文档。

docs/操作日志_工作人员资质关联修复_20260811.md

@@ -0,0 +1,71 @@
+# 工作人员资质关联修复操作日志
+
+操作时间：2026-08-11 18:28:22
+操作类型：修改、扩展
+影响模块：平台总后台工作人员资质、订单分配、用户服务关系、平台工作人员列表接口
+
+## 操作前状态
+
+- 平台前端只要加载 `/staff_account` 关联选项，就会无条件附加 `role_code=delivery`。
+- 从安装人员或运维人员页面进入资质新建页时，预填 UUID 无法在配送人员选项中匹配，选择器只能显示裸 UUID。
+- 资质新建页仍允许更换工作人员，可能破坏“指定人员下的资质管理”上下文。
+- `owner_name` 来自 URL，缺少服务端人员详情校验；直接访问、角色变化和归档人员没有统一阻断规则。
+- 工作人员列表接口只支持单一 `role_code`，不能表达“全部角色中的启用人员”或“启用且在岗的配送人员”。
+
+## 具体操作
+
+- 新增工作人员关系策略：
+  - 人员资质按来源菜单角色查询，并锁定已预填人员。
+  - 订单分配只查询启用且在岗的配送人员。
+  - 用户服务关系查询安装、配送、运维三类启用人员。
+  - 未声明策略的工作人员关联立即报错，不再继承隐含默认值。
+- 新增资质来源校验：
+  - 显式传递 `staff_type`，并允许从安全站内 `return_to` 回退解析。
+  - 始终按 UUID 查询服务端人员详情，不信任 `owner_name`。
+  - 人员缺失、归档、无权访问或真实角色与来源冲突时阻止创建。
+- 优化人员展示：主值显示“姓名（角色）”，资质页 UUID 作为次要可复制信息；详情与表单都会按当前值补载关系记录，避免分页筛选后退化成裸标识。
+- 扩展工作人员列表接口：新增可选 `role_codes`、`status`、`work_status` 参数；保留原 `role_code` 和无过滤查询兼容性。
+- 扩展平台访问控制：多角色查询要求调用账号拥有每一种目标角色对应的菜单权限；订单菜单仍仅可查询配送人员。
+- 增加前后端回归测试和前端策略检查命令。
+
+## 操作后状态
+
+- 安装人员资质新建页能够稳定显示“曹（安装人员）”，人员控件不可修改。
+- 页面只显示可复制的唯一标识尾号，不再把完整 UUID 当作人员名称候选项。
+- 无人员/角色来源的直接新建地址显示“无法执行此操作”，不渲染可保存表单。
+- 角色冲突不会静默改绑；用户需要从工作人员当前角色菜单重新进入。
+- 三个工作人员关联场景各自拥有明确的角色、启用状态和在岗状态契约。
+- 后端仍以真实工作人员记录和菜单权限作为最终鉴权依据，前端查询参数不能扩大权限。
+
+## 代码变更
+
+- `frontend/platform_admin/src/api/resource-staff-relation.ts`：新增角色闭集、字段过滤、返回路径解析和资质所有者校验。
+- `frontend/platform_admin/src/api/resources.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/use-staff-credential-owner-guard.ts`：拆分资质所有者回查、角色校验与错误结果。
+- `frontend/platform_admin/src/views/resource/load-resource-record-relations.ts`：拆分关系补载与动态平台角色加载，控制主页面文件规模。
+- `frontend/platform_admin/src/views/resource/ResourceFieldForm.vue`、`ResourceDetailContent.vue`、`resource-display.ts`：展示人员姓名、角色和可复制标识。
+- `frontend/platform_admin/src/views/shared/CrudListPage.vue`：在工作人员、资质列表及记录页面之间传递 `staff_type`。
+- `backend/api/internal/logic/platform/staff/staff.go`：解析并应用角色、状态和工作状态过滤。
+- `backend/api/internal/logic/platform/platform/access.go`：校验单角色和多角色工作人员查询权限。
+- `backend/api/internal/logic/platform/staff/staff_test.go`、`platform/access_test.go`：覆盖过滤闭集和访问控制。
+- `frontend/platform_admin/scripts/check-staff-relation-policy.mjs`、`package.json`：新增前端关系策略回归检查。
+
+## 验证结果
+
+- `npm.cmd run type:check`：通过。
+- `npm.cmd run staff-relations:check`：通过。
+- `npm.cmd run build`：通过，Vite 生产构建完成。
+- `go test ./internal/logic/platform/staff ./internal/logic/platform/platform`：通过。
+- `go test ./internal/logic/platform/...`：通过。
+- 本地浏览器只读验证：安装人员名称和角色正确回显，人员控件禁用，唯一标识可复制；直接访问缺少上下文时正确阻断；未提交测试数据。
+- `git diff --check`：通过。
+
+## 风险评估
+
+- 多角色工作人员查询采用严格权限交集：调用账号必须同时拥有安装、配送和运维人员菜单权限；权限不足时服务端拒绝整次查询，避免返回部分结果造成误解。
+- 关系下拉仍以每次最多 100 条加载并支持关键字搜索；已保存或预填人员会按 UUID 独立补载。
+- 资质编辑和详情按工作人员当前角色鉴权；角色变更不会删除历史资质，但旧角色来源的新建上下文会被阻断。
+- 本次不修改数据库结构、资质归属关系或工作人员角色变更规则，不触碰现有运行日志和 `runtime/` 数据。
+- `ResourceRecordPage.vue` 原本已超过 500 行；本次把新增校验和关系加载职责拆到两个独立文件，将主文件由实施中峰值 588 行降至 522 行，未继续重构既有保存和状态流程以控制改动范围。

docs/项目文档_工作人员资质关联_v1.0.md

@@ -0,0 +1,121 @@
+# 工作人员资质关联项目文档 v1.0
+
+## 1. 项目概述
+
+- 项目名称：平台总后台工作人员资质关联修复。
+- 项目目标：消除安装/运维人员资质页面显示裸 UUID 的问题，并建立可维护的工作人员字段级过滤和安全校验机制。
+- 主要功能：角色化人员查询、资质所有者锁定、姓名与角色回显、异常来源阻断、工作人员状态过滤。
+- 技术栈：Vue 3、TypeScript、Vue Router、Arco Design、Go、Gin、GORM。
+- 运行环境：平台总后台 `frontend/platform_admin`；平台 API `backend/api`。
+
+## 2. 目录结构
+
+```text
+platforms/
+├── frontend/platform_admin/
+│   ├── scripts/
+│   │   └── check-staff-relation-policy.mjs       # 工作人员关系策略回归检查
+│   └── src/
+│       ├── api/
+│       │   ├── resource-staff-relation.ts        # 角色、过滤和资质来源校验
+│       │   ├── resource-display.ts               # 工作人员姓名与角色展示
+│       │   └── resources.ts                      # 字段级工作人员关系声明
+│       └── views/
+│           ├── resource/
+│           │   ├── ResourceRecordPage.vue        # 资质所有者校验与异常阻断
+│           │   ├── ResourceFieldForm.vue         # 锁定人员与标识复制
+│           │   ├── use-staff-credential-owner-guard.ts # 资质所有者守卫
+│           │   ├── load-resource-record-relations.ts   # 关系与角色加载器
+│           │   └── use-resource-relations.ts     # 策略化关系加载与补载
+│           └── shared/CrudListPage.vue           # 角色上下文路由传递
+├── backend/api/internal/logic/platform/
+│   ├── staff/staff.go                            # 人员列表组合过滤
+│   └── platform/access.go                        # 人员查询与资质访问控制
+└── docs/                                         # 项目文档与操作日志
+```
+
+## 3. 核心文件说明
+
+### 3.1 `resource-staff-relation.ts`
+
+- `StaffRelationPolicy`：声明角色范围、启用状态、工作状态、预填锁定和标识展示能力。
+- `staffRelationFilters`：把字段策略转换为稳定查询参数；工作人员字段缺少策略时立即失败。
+- `resolveCredentialStaffRole`：组合显式 `staff_type` 和安全返回路径，拒绝来源冲突。
+- `credentialOwnerValidationMessage`：校验 UUID、服务端人员记录、归档状态和真实角色。
+
+### 3.2 `use-resource-relations.ts`
+
+- `loadField`、`searchField`：根据完整字段配置加载和搜索关系，取代按资源地址写死的全局行为。
+- `ensureValues`：对表单或详情中的已保存 UUID 独立补载，避免前 100 条限制导致裸标识回显。
+- 普通关系字段保持原接口和加载行为，字段级工作人员策略属于向下兼容扩展。
+
+### 3.3 `staff.go`
+
+- `parseStaffListFilters`：解析互斥的 `role_code`/`role_codes`，并验证 `status`、`work_status` 闭集。
+- `ListStaff`：在排除归档记录的基础上按角色集合、实体状态和工作状态精确过滤。
+- 原有单角色和无过滤查询继续有效，不修改响应结构。
+
+### 3.4 `access.go`
+
+- 单角色查询要求对应工作人员菜单权限。
+- 多角色查询要求每一种角色权限都满足，禁止借助组合参数扩大数据范围。
+- 订单管理权限仍只获得配送人员查询能力。
+- 资质写入继续根据请求中的人员 UUID 查询真实角色后鉴权，不信任前端 `staff_type`。
+
+## 4. 业务行为
+
+| 场景 | 人员范围 | 页面行为 |
+| --- | --- | --- |
+| 安装人员资质 | 当前安装人员 | 姓名与角色回显，人员锁定 |
+| 配送人员资质 | 当前配送人员 | 姓名与角色回显，人员锁定 |
+| 运维人员资质 | 当前运维人员 | 姓名与角色回显，人员锁定 |
+| 订单分配 | 启用且在岗的配送人员 | 可搜索、可选择 |
+| 用户服务关系 | 三类启用工作人员 | 可搜索、可选择 |
+| 缺少资质上下文 | 无 | 阻止创建并提示从工作人员页面进入 |
+| 来源角色冲突 | 无 | 阻止创建并提示从当前角色菜单重新进入 |
+
+## 5. 接口约定
+
+`GET /staff_account` 新增以下可选参数：
+
+- `role_code`：单一角色，取值为 `installer`、`delivery`、`operations`。
+- `role_codes`：逗号分隔的多角色集合；不得与 `role_code` 同时出现，不得重复。
+- `status`：通用实体状态；关系选择当前使用 `1` 表示启用，归档状态不允许作为活动列表过滤值。
+- `work_status`：工作状态，取值为 `on_duty` 或 `off_duty`。
+
+无效、冲突或越权参数返回现有非法参数/权限错误结构，不改变公共响应协议。
+
+## 6. 变更记录
+
+- 删除前端 `/staff_account` 全局强制配送人员过滤。
+- 新增三类业务字段的显式工作人员策略。
+- 新增资质人员服务端回查、角色校验和只读展示。
+- 新增工作人员组合过滤及多角色权限校验。
+- 新增前端策略检查和 Go 单元测试。
+- 数据库结构和公共写入接口未变化。
+
+## 7. 维护指南
+
+- 新增任何 `/staff_account` 关联字段时，必须配置 `staffRelation`，明确角色、实体状态和工作状态。
+- 不能在通用关系加载器中根据资源地址添加角色默认值。
+- 新增角色前需同时更新前后端角色闭集、角色中文名称、菜单映射和回归测试。
+- 需要展示历史人员时使用当前值补载；创建型选择器则按业务策略过滤，二者不能混为同一规则。
+- 资质来源名称必须从服务端人员详情取得，禁止信任 URL 中的 `owner_name`。
+- 修改工作人员过滤参数后运行：
+
+```powershell
+cd frontend/platform_admin
+npm.cmd run staff-relations:check
+npm.cmd run type:check
+npm.cmd run build
+
+cd ../../backend/api
+go test ./internal/logic/platform/...
+```
+
+## 8. 已知边界
+
+- 关系列表单次最多返回 100 条，更多记录通过关键字搜索获取。
+- 多角色查询不返回“调用者有权访问的部分集合”；任何目标角色权限不足都会拒绝整次请求。
+- 本次只覆盖平台总后台；气站和配送点后台继续使用各自组织范围内的工作人员接口。
+- 不新增人员姓名历史快照；人员已归档后，当前平台权限模型会阻止继续新建资质。