# 参数类型错误响应文案升级 + 富文本上传前端联动建议

**日期**: 2026-04-23
**PR**: #1308 (Closes #1307, Closes #1305)
**服务**: hl-common-log（全局异常处理器）/ hl-user-service（SysOssController）
**类型**: fix（错误文案诊断性增强 + 前端联动建议）

---

## 背景

本次批量修复源于用户反馈 2 个后台 bug：

1. **Bug1**：资源服务 → 服务人员管理，点删除按钮报『参数类型错误: staffId』，但看不到实际值，无法判断是前端 undefined、NaN 还是类型不匹配。
2. **Bug2**：资源服务 → 组合配品（备品）→ 详细介绍富文本上传图片，偶发『资源不存在』和『请求超时』。

代码层排查结论：
- 后端 URL 和前端 URL 字符级一致 ✓
- StaffListVO.staffId 是 String（雪花 ID 保护）✓
- toListVO 用 String.valueOf 填 VO ✓
- 前端 row.staffId 取值正确 ✓

最可能成因：
- Bug1：测试服部署的前端 dist 为旧版本，取 `row.id` 而非 `row.staffId`，URL 变成 `/admin/staff/undefined`，Spring 抛 `MethodArgumentTypeMismatchException` 但响应不含实际值。
- Bug2：前端 axios upload 默认 15s 超时对 10MB 富文本图片偏紧，慢网撞线 → 前端报『请求超时』或 HTTP 404 兜底『资源不存在』。

本次后端只做诊断增强，前端需要配合几处小调整。

---

## 后端行为变化（前端必读）

### 1. 全局参数类型错误响应文案升级

#### 之前（PR #1308 前）
```http
DELETE /admin/staff/undefined
→ 200 {
    "code": 400,
    "message": "参数类型错误: staffId",
    "data": null,
    "success": false
  }
```

#### 之后（PR #1308 后）
```http
DELETE /admin/staff/undefined
→ 200 {
    "code": 400,
    "message": "参数类型错误: staffId='undefined'（需要 Long 类型）",
    "data": null,
    "success": false
  }
```

**前端影响**：
- 若前端某处对 message 做了**关键词匹配**（例如 `if (msg.includes("参数类型错误: staffId")) { ... }`），仍能命中（新文案仍以 `参数类型错误: staffId` 开头）。**向后兼容，无需改动**。
- 若前端直接展示 message（默认情况），用户会看到更具诊断性的文案，能直接推断传给后端的非法值是什么。

### 2. 备品详细介绍上传端点保持不变

URL、请求方法、参数、响应体格式完全保持：
```http
POST /admin/sys/oss/upload
Content-Type: multipart/form-data
file=<MultipartFile>
→ 200 {
    "code": 200,
    "data": { "url": "https://...", "fileId": "...", "fileName": "..." },
    "success": true
  }
```

后端仅加了 trace 日志（`[oss-upload] start/success/failed`），供运维排查。**前端无任何签名变化，无需改动业务代码**。

---

## 前端联动建议（⭐ 请前端同事落地）

### 建议 1：`src/utils/request.js` 的 upload 方法 timeout 15000 → 60000

**原因**：后端富文本上传允许文件最大 10MB，经 OSS putObject + MD5 计算，在慢网环境常撞 axios 默认 15s 超时。实测 user 反馈偶发『请求超时』多是此原因。

**参考改动**：
```js
// src/utils/request.js
upload(url, file, config = {}) {
  const formData = new FormData()
  formData.append('file', file)
  return request.post(url, formData, {
    timeout: 60000,  // ← 从 15000 改为 60000
    retry: false,
    ...config,
  })
}
```

### 建议 2：富文本上传组件 Result.code != 0 时显示后端 message

**原因**：目前前端 `src/utils/request.js:519-524` 把 HTTP 404 统一映射成『请求的资源不存在』。但后端 SysOssController 失败时抛的是 BusinessException，HTTP 依然 200，body 有 code != 0 和具体 message（如 OSS SignatureError / OssInvalidAccessKey / OssNetworkError 等）。

**参考改动**：富文本编辑器的上传失败回调直接 `message.error(res.message)`，不走 404 分支的统一文案。

### 建议 3：服务人员列表删除按钮取字段核对

**原因**：若前端线上 dist 取的是 `row.id` 而不是 `row.staffId`，会触发 `/admin/staff/undefined`。请核对当前 `src/views/resource/personnel/index.vue` 的删除按钮 handler + useCRUD 的 idKey 均为 `staffId`（最新代码已正确）。如仍有残留 `row.id` 引用请替换。

---

## 关联工单

- #1307 — fix: 服务人员删除报错『参数类型错误: staffId』
- #1305 — fix: 备品详细介绍富文本上传报『资源不存在』偶发『请求超时』
