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