fix: 优化工作人员重复信息提示

docs/操作日志_工作人员唯一冲突提示_20260811.md

@@ -0,0 +1,67 @@
+# 工作人员唯一冲突提示操作日志
+
+操作时间：2026-08-11 13:29:44
+操作类型：修改
+影响模块：平台总后台、气站后台、配送点后台工作人员新增与编辑
+
+## 操作前状态
+
+- `staff_account` 的用户名和非空联系电话分别由数据库唯一索引保护，但三个后台的工作人员写入入口都会把 PostgreSQL 原始错误直接返回前端。
+- 用户遇到重复数据时会看到约束名、SQLSTATE 等数据库实现细节，无法判断需要修改用户名还是联系电话。
+- 保存失败后各前端会保留现有表单；5173平台后台若已上传头像，重新保存时仍会再次上传同一文件，可能产生重复或孤立资源。
+- 公共 `UpdateAllowedByIdentity` 没有为特定资源转换数据库错误的扩展点。
+
+## 具体操作
+
+- 新增工作人员写入错误转换器：
+  - 精确识别 `idx_staff_account_username`，返回“该用户名已存在”。
+  - 精确识别 `idx_staff_account_phone`，返回“该联系电话已被其他工作人员使用”。
+  - 未识别数据库错误只写服务端日志，客户端统一收到“保存失败，请稍后重试”。
+- 新增公共工作人员创建函数，让平台、气站、配送点三个入口统一执行错误转换。
+- 以向下兼容方式扩展公共白名单更新函数：原函数签名和行为保持不变，工作人员编辑入口使用带错误转换器的新函数。
+- 三个后台的工作人员创建均接入用户名和联系电话冲突转换；三个后台的工作人员编辑均接入联系电话冲突转换。
+- 新增5173头像上传结果缓存：
+  - 头像上传成功但资源保存失败时，下一次保存复用同一受控 URI。
+  - 选择新文件、清除头像或重新加载资料时清空缓存。
+  - 头像上传本身失败时自动清空缓存，允许再次上传。
+- 新增头像失败重试行为检查脚本，并加入平台后台脚本命令。
+
+## 操作后状态
+
+- 三个后台均不再向工作人员表单暴露数据库表名、索引名或 SQLSTATE。
+- 用户名重复只在新建时返回明确提示；联系电话重复在新建和编辑时均返回明确提示。
+- 联系电话继续允许留空，非空值保持全表唯一；已归档工作人员继续占用用户名和非空联系电话。
+- 保存失败后表单、下拉选择和头像预览保持不变；5173再次保存不会重复上传已经成功上传的头像。
+- 现有 HTTP 200 加 JSON 业务错误结构保持不变，没有新增保存前查重接口或数据库迁移。
+
+## 代码变更
+
+- `backend/api/internal/logic/common/staff_error.go`：新增 `CreateStaffRecord` 和 `StaffWriteError`，统一处理创建写入、唯一冲突与未知错误脱敏。
+- `backend/api/internal/logic/common/staff_error_test.go`：覆盖已知冲突、包装错误、未知错误脱敏、创建和编辑写入路径。
+- `backend/api/internal/logic/common/staff_wiring_test.go`：验证三个后台的创建和编辑入口均接入公共错误转换链路。
+- `backend/api/internal/logic/common/base.go`：新增 `UpdateAllowedByIdentityWithError`，原 `UpdateAllowedByIdentity` 保持兼容。
+- `backend/api/internal/logic/platform/staff/staff.go`：接入平台工作人员创建和编辑错误转换。
+- `backend/api/internal/logic/gas/staff.go`：接入气站工作人员创建和编辑错误转换。
+- `backend/api/internal/logic/delivery/staff.go`：接入配送点工作人员创建和编辑错误转换。
+- `frontend/platform_admin/src/views/resource/avatar-upload-cache.ts`：新增单次保存流程头像 URI 缓存。
+- `frontend/platform_admin/src/views/resource/use-resource-avatar.ts`：接入头像上传缓存及失效规则。
+- `frontend/platform_admin/scripts/check-avatar-upload-cache.mjs`、`package.json`：新增头像失败重试行为检查命令。
+
+## 验证结果
+
+- `go test ./internal/logic/common`：通过，工作人员冲突转换、未知错误脱敏、创建和编辑路径均通过。
+- `go test ./internal/logic/platform/staff ./internal/logic/gas ./internal/logic/delivery`：通过，三个工作人员处理器编译与既有测试正常。
+- `go test ./...`：通过，后端完整回归测试正常。
+- `npm.cmd run avatar-retry:check`：通过，同一头像保存重试仅上传一次，重置与上传失败后可以再次上传。
+- `npm.cmd run type:check`：通过。
+- `npm.cmd run resource-pages:check`：通过，详情46类、新建25类、编辑23类。
+- `npm.cmd run build`：通过，Vite生产构建完成。
+- `git diff --check`：通过，未发现空白符错误。
+
+## 风险评估
+
+- 唯一冲突识别依赖当前 PostgreSQL 约束名；模型继续沿用现有索引定义时行为稳定，相关常量和测试可防止无意改名。
+- 未识别工作人员写入错误会对客户端脱敏，但原始错误仍写入服务端日志，便于定位数据库连接或约束异常。
+- 头像 URI只在当前5173资料页实例中缓存；页面卸载、选择新头像或清除头像后立即失效，不跨账户复用。
+- 气站后台和配送点后台当前没有真实头像文件上传能力，本次不为其增加头像缓存或改变现有表单结构。
+- 本次不修改气站与配送点联动、详情唯一标识展示或编辑页冗余详情请求等独立问题。