hongawen
220dec9b6c
- 将 POST /system/file/upload 接口返回结构从 string 改为 { id: string, url: string }
- id 字段以字符串形式返回 infra_file.id，避免 JavaScript 数值精度丢失问题
- 保持接口路径、方法和入参完全不变，仅修改返回格式
- 添加 GET /system/file/download 接口用于文件下载功能
- 优化 AppFileController 中的文件上传实现逻辑
- 更新 AuthConvert 和 AuthUserInfoRespVO 添加用户昵称和头像字段
- 在 CLAUDE.md 中补充鉴权通道和 HTTP 动词语义说明文档
- 在 ErrorCodeConstants.java 中添加多个项目管理和执行相关的错误码定义
- 删除执行成员相关的数据库表和接口定义（执行协办人替代方案）
- 在 FileMapper 中增加按 URL 查询文件的方法支持
3.1 KiB
3.1 KiB
文件上传接口改造需求（给后端）
提单时间：2026-05-11 提单方：前端 涉及模块：
rdms-system-boot文件模块 背景：业务表单（如新建/编辑任务）的附件采用「即传即存」交互，但表单可能被用户取消或关闭。前端需要在合适时机调用删除接口清理孤儿文件。当前/system/file/upload只返回 url，前端拿不到 fileId，无法触发删除。
1. 改造：POST /system/file/upload
路径 / 方法 / 入参全部保持不变，仅修改返回结构。
1.1 现状返回
{
"code": 0,
"msg": "",
"data": "http://192.168.1.107:9009/rdms/20260508/xxx.jpg?X-Amz-..."
}
1.2 目标返回
{
"code": 0,
"msg": "",
"data": {
"id": "10001",
"url": "http://192.168.1.107:9009/rdms/20260508/xxx.jpg?X-Amz-..."
}
}
1.3 字段说明
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| id | string | 是 | 即 infra_file.id，必须以字符串形式返回，不要返回 number |
| url | string | 是 | 文件访问 URL，含义与现状完全一致（私有桶带签名，公开桶裸 URL） |
1.4 关键约束
id必须是 string，不是 number。原因：infra_file.id是 Long 类型，超过 JS 安全整数（2^53）时 JSON number 会精度丢失。前端项目 ID 统一按字符串接收。- 该改动不兼容老返回结构，前端会同步切换。
- App 端
/app-api/system/file/upload前端目前未使用，可暂不改；若希望对称建议一起改。
2. 确认：DELETE /system/file/delete
接口已存在（见 system-file-api.md §4.3.5），无需新建，但需确认以下两点：
2.1 权限
- 业务用户角色需具备
system:file:delete权限码，或该接口允许"删除自己上传的文件"无需该权限码。 - 期望：当前业务用户能直接调通
DELETE /admin-api/system/file/delete?id=xxx。
2.2 幂等性（删不存在的文件）
- 当前文档里删不存在的文件返回错误码
1001003001 / 文件不存在。 - 期望：幂等返回
code: 0（更佳），或维持现状（前端会把该错误码当作"已删除"吞掉，也能接受）。
2.3 入参
保持现状不变：
DELETE /admin-api/system/file/delete?id=10001
3. 不在本次范围（避免误解）
以下事项本次不做，属于后续「治本方案」范畴，请勿顺手改动：
- 不需要在
infra_file表加status（temp / committed）字段 - 不需要加业务引用关系表
- 不需要做孤儿文件定时清理 cron
- 不需要改
/presigned-url与/create - 不需要改 App 端
/upload鉴权策略
4. 联调要点
- 改造完成后请提供测试环境，前端会同步发版。
- 接口返回的
id请确保转为字符串再 JSON 序列化（不要直接序列化 Long）。 - 若返回里
id是 number 类型，前端视为联调未通过。
5. 一句话总结
/system/file/upload返回结构从string改成{ id: string, url: string }，id是infra_file.id的字符串形式。其它接口不动。