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