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

工作人员资质关联项目文档 v1.0

1. 项目概述

• 项目名称：平台总后台工作人员资质关联修复。
• 项目目标：消除安装/运维人员资质页面显示裸 UUID 的问题，并建立可维护的工作人员字段级过滤和安全校验机制。
• 主要功能：角色化人员查询、资质所有者锁定、姓名与角色回显、异常来源阻断、工作人员状态过滤。
• 技术栈：Vue 3、TypeScript、Vue Router、Arco Design、Go、Gin、GORM。
• 运行环境：平台总后台 frontend/platform_admin；平台 API backend/api。

2. 目录结构

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。
• 修改工作人员过滤参数后运行：

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 条，更多记录通过关键字搜索获取。
• 多角色查询不返回“调用者有权访问的部分集合”；任何目标角色权限不足都会拒绝整次请求。
• 本次只覆盖平台总后台；气站和配送点后台继续使用各自组织范围内的工作人员接口。
• 不新增人员姓名历史快照；人员已归档后，当前平台权限模型会阻止继续新建资质。