feat(changelog): 参数类型错误文案升级 + 富文本上传前端联动建议 (PR #1308)

changelogs/2026-04/2026-04-23_typemismatch-error-msg-and-upload-timeout-tips.md

@@ -0,0 +1,114 @@
+# 参数类型错误响应文案升级 + 富文本上传前端联动建议
+
+**日期**: 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: 备品详细介绍富文本上传报『资源不存在』偶发『请求超时』