Files
cadworld/cadworld-adminapi/docs/admin-api.md
T
2026-10-13 13:30:43 +08:00

498 lines
24 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 后台 API 联调文档
后台保留组件库、用户管理、操作日志三个模块。以下路径以 `/admin-api` 为前缀,默认服务地址 `http://127.0.0.1:8992`。
用户端匹配与拼装接口由独立的 `cadworld-api` 服务提供,默认端口8991,详见[用户端 API 文档](../../cadworld-api/docs/api.md)。用户端默认组件、替代候选和详情同时返回 `bomList`、`urdfInfo`,通过编码访问组件,模型直接使用公开OSS/CDN地址。
## 1. 通用约定
JSON 请求设置 `Content-Type: application/json`。当前没有登录认证,操作人来自 `APP_ADMIN_OPERATOR_ID / APP_ADMIN_OPERATOR_NAME`,默认 `0 / TEST_OPERATOR`。上传令牌与该操作人绑定。
成功返回 HTTP 200,包括新增和删除:
```json
{"code":"OK","message":"success","data":{"success":true},"requestId":"请求编号"}
```
失败返回对应 HTTP 状态和错误码,`data` 可能省略:
```json
{"code":"COMPONENT_REVISION_CONFLICT","message":"组件已修改或删除,请刷新后保存","requestId":"请求编号"}
```
分页返回 `data={"items":[],"page":1,"size":20,"total":0}`。页码从 1 开始,默认每页 20,超过 100 按 100 处理。组件和日志按更新时间/操作时间、ID 倒序。数据库时间及日志筛选时间使用上海时区本地时间,例如 `2026-10-10T16:00:00`;上传会话与签名到期时间为 UTC ISO 时间,例如 `2026-10-10T08:30:00Z`。
前端保存响应中的 `requestId` 用于排查问题。避免在浏览器日志中输出上传令牌和签名字段。
## 2. 接口列表
| 方法 | 路径 | 作用 |
| --- | --- | --- |
| POST | /admin-api/storage/upload-signature | 分配编码及上传授权,或续签 |
| GET | /admin-api/components | 组件分页查询 |
| POST | /admin-api/components | 新增组件,校验上传文件后入库 |
| GET | /admin-api/components/{id} | 组件完整详情 |
| PUT | /admin-api/components/{id} | 全量更新表单,可替换资源 |
| DELETE | /admin-api/components/{id} | 逻辑删除组件 |
| GET | /admin-api/component-assets/{objectKey} | 下载资源文件 |
| GET | /admin-api/users | 用户分页查询 |
| POST | /admin-api/users | 创建用户 |
| GET | /admin-api/users/{id} | 用户详情 |
| PUT | /admin-api/users/{id} | 修改用户 |
| DELETE | /admin-api/users/{id} | 逻辑删除用户 |
| GET | /admin-api/operation-logs | 通用操作日志分页查询 |
| GET | /admin-api/operation-logs/{id} | 操作日志详情 |
接口库、端口、姿态、BREP、封面、后台文件流上传以及所有旧上传会话/确认路由均已删除,访问返回 404。上传没有独立的创建会话、上传确认接口。
## 3. 单签名接口
### 3.1 请求
`POST /admin-api/storage/upload-signature`,以下三种请求互斥:
| 场景 | JSON 请求 |
| --- | --- |
| 新增组件首次上传 | `{}` |
| 已有组件替换模型 | `{"componentId":123}` |
| 原会话签名到期后续签 | `{"uploadSessionToken":"原令牌"}` |
新增无需组件编码。后端生成 `CW-` 加无连字符的大写 UUID,例如 `CW-0123456789ABCDEF0123456789ABCDEF`,申请签名不创建组件记录。编辑使用原编码,生成新的上传批次;组件不存在返回 404。
续签不能同时提交 `componentId`。续签验证签名、有效期、操作人、环境及绑定组件,保持原编码、批次、令牌和目录。默认会话有效期 30 分钟、OSS 授权有效期 5 分钟;授权不超过会话到期时间,续签不延长会话。
### 3.2 响应
以下签名值仅为占位示例,实际表单字段必须使用后端返回值:
```json
{
"code":"OK",
"message":"success",
"requestId":"请求编号",
"data":{
"componentCode":"CW-0123456789ABCDEF0123456789ABCDEF",
"uploadSessionToken":"组件上传令牌",
"sessionExpiresAt":"2026-10-10T08:30:00Z",
"expiresAt":"2026-10-10T08:05:00Z",
"step":{
"uploadUrl":"https://linkerbot.oss-cn-beijing.aliyuncs.com/",
"keyPrefix":"cadworld_dev/components/CW-0123456789ABCDEF0123456789ABCDEF/step/abcdef0123456789abcdef0123456789/",
"uploadMethod":"POST",
"uploadFields":{
"x-oss-signature-version":"OSS4-HMAC-SHA256",
"x-oss-credential":"访问凭证范围",
"x-oss-date":"20261010T080000Z",
"success_action_status":"204",
"x-oss-forbid-overwrite":"true",
"policy":"Base64策略",
"x-oss-signature":"签名"
}
},
"urdf":{
"uploadUrl":"https://linkerbot.oss-cn-beijing.aliyuncs.com/",
"keyPrefix":"cadworld_dev/components/CW-0123456789ABCDEF0123456789ABCDEF/urdf/abcdef0123456789abcdef0123456789/",
"uploadMethod":"POST",
"uploadFields":{
"x-oss-signature-version":"OSS4-HMAC-SHA256",
"x-oss-credential":"访问凭证范围",
"x-oss-date":"20261010T080000Z",
"success_action_status":"204",
"x-oss-forbid-overwrite":"true",
"policy":"另一组Base64策略",
"x-oss-signature":"另一组签名"
}
}
}
}
```
一个 `uploadSessionToken` 同时绑定 STEP 和 URDF 两组目录,两组使用相同编码、批次。不得修改、互换授权字段或手工构造目录。
### 3.3 OSS 直传
每个文件分别向对应 `uploadUrl` 发一个 `multipart/form-data` POST:原样加入 `uploadFields`,再加入 `key=keyPrefix+相对路径`,最后加入 `file`。让浏览器自动设置 Content-Type 和 boundary。OSS 成功返回 HTTP 204。
对象键包含环境根目录,默认测试为 `cadworld_dev`,生产为 `cadworld`:
```text
{环境根目录}/components/{组件编码}/step/{批次}/{STEP文件名}
{环境根目录}/components/{组件编码}/urdf/{批次}/{URDF内部相对路径}
```
STEP 直接使用文件名。URDF 使用文件夹选择器提供的 `webkitRelativePath`,去掉最外层选中目录,保留内部结构。例如 `L20/robot.urdf`、`L20/meshes/base.stl` 分别上传为 `urdf.keyPrefix + robot.urdf`、`urdf.keyPrefix + meshes/base.stl`。不要打包 ZIP,也不要扁平化内部目录。
默认单文件上限 100 MiB。禁止同名覆盖字段已纳入签名;同批次相同对象键重复上传会被 OSS 拒绝。续签只刷新授权,已确认上传成功的文件无需再次上传。会话过期需要重新申请签名并上传至新批次;新增重新申请会分配新编码。
OSS CORS 需允许前端源站的表单 POST。OSS 上传失败由前端按 OSS 返回状态处理;OSS 成功后仍须保存组件。
## 4. 组件表单及资源规则
### 4.1 表单字段
POST 和 PUT 使用扁平 JSON,字段约定相同:
| 字段 | 类型 | 必填 / 默认值 / 限制 |
| --- | --- | --- |
| componentName | string | 必填,非空,最多 128 字符,允许同名 |
| category | string | 必填,非空,最多 64 字符,自由分类 |
| description | string | 默认 `""`,UTF-8 不超过 65535 字节 |
| material | string | 默认 `""`,最多 128 字符 |
| massKg | number | 默认 0,千克,非负 |
| degreesOfFreedom | integer | 默认 0,范围 0 至 2147483647,仅接受 JSON 整数,不接受小数或字符串 |
| functionDescription | string | 默认 `""`,最多 512 字符 |
| shape | string | 默认 `""`,最多 128 字符 |
| size | string | 默认 `""`,最多 128 字符,大小描述,可包含单位 |
| torqueNm | number | 默认 0,单位 N·m,非负 |
| bomList | JSON 对象或数组 | 默认 `[]`,内部结构自由 |
| urdfInfo | JSON 对象或数组 | POST / PUT 均必填,内部结构自由,允许 `{}` 或 `[]` |
| basicFields | 自定义字段数组 | 默认 `[]`,基本信息扩展字段 |
| parameterFields | 自定义字段数组 | 默认 `[]`,零件参数扩展字段 |
质量和扭矩最多 12 位整数、6 位小数,与 `DECIMAL(18,6)` 一致;不要在数值中提交单位文本。可选字段省略或传 null 会恢复默认值。名称、分类、材质、功能、形状和大小会裁剪首尾空白。
`bomList` 和 `urdfInfo` 直接提交 JSON 对象或数组,不接受字符串化的 JSON、数字或布尔值。`bomList` 省略或为 null 时保存为空数组;`urdfInfo` 省略或为 null 时返回 422。两者内部字段不做固定结构校验,`urdfInfo` 由前端提供,不由后端解析 URDF 文件生成。
自定义字段格式:
```json
{
"basicFields":[{"name":"供应商型号","value":"L20-RIGHT"}],
"parameterFields":[{"name":"额定电压","value":"24V"},{"name":"额定扭矩","value":"20 Nm"}]
}
```
每组最多 100 项,名称非空且最多 64 字符,值为非 null 字符串、最多 2000 字符,可以为空字符串。同组名称裁剪后不可重复,两组之间可以重名;顺序与请求一致。
PUT 是全量表单更新,前端应提交完整表单,每次都必须提交 `urdfInfo`。省略可选字段会恢复默认值,提交空数组可清空 BOM 或自定义字段。
### 4.2 保存时的资源校验
新增必须同时提交 STEP 和 URDF 资源;修改可只替换一种,未提交的资源保持原引用。文件引用只能来自当前操作人、当前组件的有效令牌和对应目录。
后端检查全部对象键合法、无重复、无路径越界且实际存在,按 OSS HEAD 返回的实际大小校验,不接受前端提供的文件大小。STEP 是直接位于 STEP 批次目录的一个非空 `.step` 或 `.stp` 文件。URDF 清单 1 至 1000 项,必须恰好包含一个非空 `.urdf` 主文件,不支持以 `.rfs` 为主文件;扩展名大小写均可。
后端根据实际对象生成 `urdfPrefix`、`urdfMainObjectKey` 和 `urdfFiles`,清单保留请求顺序,元素为 `relativePath` 和 `sizeBytes`。无需提交这些数据库维护字段。
检查全部通过才写数据库。失败不切换原资源引用。旧批次、上传后未保存及删除组件后的文件暂不自动清理。校验覆盖清单的结构和对象存在性,不解析 URDF XML 内部的依赖引用。
## 5. 组件接口
### 5.1 新增
`POST /admin-api/components`。编码由令牌读取,不接受前端指定编码。签名、直传成功后提交:
```json
{
"componentName":"四孔安装板",
"category":"安装板",
"description":"用于固定机械组件",
"material":"铝合金",
"massKg":0.35,
"degreesOfFreedom":0,
"functionDescription":"固定机械组件",
"shape":"平板",
"size":"120 × 80 × 8 mm",
"torqueNm":0,
"bomList":[{"componentCode":"PART-001","name":"安装螺钉","quantity":4}],
"urdfInfo":{"robotName":"mounting_plate","links":[{"name":"base_link"}]},
"basicFields":[{"name":"供应商型号","value":"L20-RIGHT"}],
"parameterFields":[{"name":"额定电压","value":"24V"}],
"uploadSessionToken":"签名接口返回的令牌",
"stepObjectKey":"cadworld_dev/components/CW-0123456789ABCDEF0123456789ABCDEF/step/abcdef0123456789abcdef0123456789/model.step",
"urdfObjectKeys":[
"cadworld_dev/components/CW-0123456789ABCDEF0123456789ABCDEF/urdf/abcdef0123456789abcdef0123456789/robot.urdf",
"cadworld_dev/components/CW-0123456789ABCDEF0123456789ABCDEF/urdf/abcdef0123456789abcdef0123456789/meshes/base.stl"
]
}
```
成功返回完整组件详情,初始 `version=1`。重复使用已保存编码新增返回 409,包含已逻辑删除组件的编码。
### 5.2 详情及保存响应
`GET /admin-api/components/123`,POST / PUT 成功的 `data` 也使用此结构:
```json
{
"id":123,
"componentCode":"CW-0123456789ABCDEF0123456789ABCDEF",
"componentName":"四孔安装板",
"category":"安装板",
"description":"用于固定机械组件",
"material":"铝合金",
"massKg":0.35,
"degreesOfFreedom":0,
"functionDescription":"固定机械组件",
"shape":"平板",
"size":"120 × 80 × 8 mm",
"torqueNm":0,
"bomList":[{"componentCode":"PART-001","name":"安装螺钉","quantity":4}],
"urdfInfo":{"robotName":"mounting_plate","links":[{"name":"base_link"}]},
"basicFields":[{"name":"供应商型号","value":"L20-RIGHT"}],
"parameterFields":[{"name":"额定电压","value":"24V"}],
"stepObjectKey":"cadworld_dev/components/CW-0123456789ABCDEF0123456789ABCDEF/step/abcdef0123456789abcdef0123456789/model.step",
"stepUrl":"http://127.0.0.1:8992/admin-api/component-assets/cadworld_dev/components/CW-0123456789ABCDEF0123456789ABCDEF/step/abcdef0123456789abcdef0123456789/model.step",
"urdfPrefix":"cadworld_dev/components/CW-0123456789ABCDEF0123456789ABCDEF/urdf/abcdef0123456789abcdef0123456789/",
"urdfBaseUrl":"http://127.0.0.1:8992/admin-api/component-assets/cadworld_dev/components/CW-0123456789ABCDEF0123456789ABCDEF/urdf/abcdef0123456789abcdef0123456789/",
"urdfMainObjectKey":"cadworld_dev/components/CW-0123456789ABCDEF0123456789ABCDEF/urdf/abcdef0123456789abcdef0123456789/robot.urdf",
"urdfUrl":"http://127.0.0.1:8992/admin-api/component-assets/cadworld_dev/components/CW-0123456789ABCDEF0123456789ABCDEF/urdf/abcdef0123456789abcdef0123456789/robot.urdf",
"urdfFiles":[{"relativePath":"robot.urdf","sizeBytes":4200},{"relativePath":"meshes/base.stl","sizeBytes":15000}],
"version":1,
"createdAt":"2026-10-10T16:01:00.123",
"updatedAt":"2026-10-10T16:01:00.123"
}
```
数据库只保存 Key。URL 在响应时生成,路径段经过编码。获取依赖文件时按 `/` 分段编码 `relativePath` 后拼接 `urdfBaseUrl`,不要对整个路径使用一次 `encodeURIComponent`。
### 5.3 修改
`PUT /admin-api/components/123`,必须提交最新 `version`,成功后递增。只改表单无需签名:
```json
{
"version":1,
"componentName":"四孔安装板 V2",
"category":"安装板",
"description":"更新说明",
"material":"铝合金",
"massKg":0.35,
"degreesOfFreedom":0,
"functionDescription":"固定机械组件",
"shape":"平板",
"size":"120 × 80 × 8 mm",
"torqueNm":0,
"bomList":[],
"urdfInfo":{"robotName":"mounting_plate","links":[{"name":"base_link"}]},
"basicFields":[],
"parameterFields":[{"name":"额定电压","value":"24V"}]
}
```
`componentCode` 可省略;若提交必须与原编码一致。`version` 范围 1 至 4294967295,达到上限不能继续修改。版本过期或原子更新冲突返回 409,前端重新加载详情后合并修改再保存。
替换 STEP:先用 `{"componentId":123}` 申请新批次,直传 STEP,再在完整表单和 version 之外提交:
```json
{
"uploadSessionToken":"编辑签名返回的令牌",
"stepObjectKey":"新授权的step.keyPrefix加文件名"
}
```
替换 URDF 则提交令牌和完整的 `urdfObjectKeys`,不提交 `stepObjectKey`;同时替换则两者一起提交。不替换时省略令牌及文件字段。仅提交令牌、空对象键或空 URDF 清单会被拒绝。
### 5.4 列表
`GET /admin-api/components?page=1&size=20&keyword=安装板&category=安装板`
| 参数 | 说明 |
| --- | --- |
| page / size | 分页 |
| keyword | 名称或编码模糊查询 |
| category | 分类精确筛选 |
`items` 每项包含 `id`、`componentCode`、`componentName`、`category`、`description`、`degreesOfFreedom`、`functionDescription`、`shape`、`size`、`torqueNm`、`stepUrl`、`urdfUrl`、`version`、`createdAt`、`updatedAt`。列表不查询或返回 `bomList`、`urdfInfo`、自定义表单和 URDF 文件清单。编辑先获取详情;创建和修改成功返回的详情包含全部七个新增字段。
列表查询参数 `size` 是每页条数,响应 `items` 内的 `size` 是组件大小描述。
### 5.5 删除和下载
`DELETE /admin-api/components/123` 成功返回 `data={"success":true}`。将组件的 `deleted` 标记从 `0` 改为 `1`,保留数据库记录、删除前的日志目标快照和 OSS 文件。找不到组件或组件已删除时返回 404。
已删除组件不出现在列表和详情中,不能修改、申请编辑上传签名或续签绑定该组件的上传会话。组件编码仍保持唯一,不能复用原新增会话重新创建同编码组件。删除标记仅用于数据库内部,不增加到接口响应中。
使用详情中的 `stepUrl`、`urdfUrl` 或依赖文件 URL 直接 GET 下载。下载成功返回原文件流,不包 JSON;对象不存在返回 404。对象键区分大小写且必须属于当前环境根目录。
## 6. 浏览器完整上传示例
页面文件选择器:
```html
<input id="step" type="file" accept=".step,.stp">
<input id="urdf" type="file" webkitdirectory multiple>
```
以下示例使用一次签名完成两类文件上传,授权即将到期时调用同一接口续签,上传全部成功后直接保存。表单取当前页面值;示例按顺序上传以便展示流程,实际页面可使用受控并发。
```javascript
async function adminApi(path, method, body) {
const response = await fetch(`/admin-api${path}`, {
method,
headers: { 'Content-Type': 'application/json' },
...(body === undefined ? {} : { body: JSON.stringify(body) })
});
const result = await response.json();
if (!response.ok || result.code !== 'OK') {
throw new Error(`${result.message}; requestId=${result.requestId}`);
}
return result.data;
}
function urdfRelativePath(file) {
const path = file.webkitRelativePath;
if (!path || !path.includes('/')) throw new Error('请选择完整 URDF 文件夹');
return path.slice(path.indexOf('/') + 1); // 去掉选中文件夹的最外层目录
}
async function uploadAndSave(formValues, stepFile, urdfFiles, component = null) {
// 新增传 {};编辑传已有组件 ID。编辑可仅替换 STEP 或 URDF。
const files = Array.from(urdfFiles || []);
if (!component && (!stepFile || files.length === 0)) {
throw new Error('新增组件必须选择 STEP 文件和 URDF 文件夹');
}
const body = { ...formValues };
if (component) body.version = component.version;
if (!stepFile && files.length === 0) {
return adminApi(`/components/${component.id}`, 'PUT', body);
}
let session = await adminApi('/storage/upload-signature', 'POST',
component ? { componentId: component.id } : {});
async function ensureSignature() {
if (Date.now() >= Date.parse(session.sessionExpiresAt)) {
throw new Error('上传会话已过期,请重新申请签名并重新上传');
}
if (Date.now() >= Date.parse(session.expiresAt) - 15000) {
session = await adminApi('/storage/upload-signature', 'POST', {
uploadSessionToken: session.uploadSessionToken
});
}
}
async function upload(kind, file, relativePath) {
await ensureSignature();
const authorization = session[kind];
const key = authorization.keyPrefix + relativePath;
const data = new FormData();
for (const [name, value] of Object.entries(authorization.uploadFields)) {
data.append(name, value);
}
data.append('key', key);
data.append('file', file); // 必须放最后;不要手工设置 Content-Type
const response = await fetch(authorization.uploadUrl, {
method: authorization.uploadMethod,
body: data
});
if (response.status !== 204) {
throw new Error(`OSS 上传失败,HTTP ${response.status}`);
}
return key;
}
if (stepFile) body.stepObjectKey = await upload('step', stepFile, stepFile.name);
if (files.length) {
body.urdfObjectKeys = [];
for (const file of files) {
body.urdfObjectKeys.push(await upload('urdf', file, urdfRelativePath(file)));
}
}
await ensureSignature(); // 保存前确认会话仍有效
body.uploadSessionToken = session.uploadSessionToken;
// 不需要 complete 接口;保存接口执行文件检查并写入记录。
return adminApi(component ? `/components/${component.id}` : '/components',
component ? 'PUT' : 'POST', body);
}
// formValues 只含完整表单字段,不包含详情里的资源 URL、Key 或维护字段。
const saved = await uploadAndSave({
componentName: '四孔安装板', category: '安装板',
description: '', material: '铝合金', massKg: 0, degreesOfFreedom: 0,
functionDescription: '固定机械组件', shape: '平板', size: '120 × 80 × 8 mm',
torqueNm: 0, bomList: [], urdfInfo: {}, basicFields: [], parameterFields: []
}, document.querySelector('#step').files[0], document.querySelector('#urdf').files);
// 编辑时第四个参数传 GET 详情返回的 component;未选择的资源保持原引用。
```
保存 409 时先刷新组件并处理版本冲突;保存失败不要把新 Key 当成已有资源展示。签名过期但会话有效可续签,会话过期则重新开始。对象同名覆盖被禁止,上传重试需跟踪已经确认成功的文件。
## 7. 用户管理
保持现有行为和表结构。列表支持 `page`、`size`、`keyword`(手机号或昵称)、`userType`(NORMAL / ADMIN)、`status`(ACTIVE / DISABLED)。详情返回 `id`、`phone`、`nickname`、`status`、`userType`、`createdAt`、`updatedAt`。
POST / PUT 请求:
```json
{"phone":"13812345678","nickname":"测试用户","status":"ACTIVE","userType":"NORMAL"}
```
手机号需符合大陆手机号格式并保持唯一,昵称必填且最多 64 字符。创建省略状态和类型时默认为 ACTIVE / NORMAL;修改省略则保留原值。逻辑删除后列表及详情不再返回该用户,手机号仍被占用。用户管理只记录运行日志。
## 8. 通用操作日志
当前仅组件 CREATE / UPDATE / DELETE 的成功、失败写入 `sys_operation_log`。文件校验失败及资源替换属于对应保存操作。签名、续签、列表、详情、下载和用户管理不写业务审计。
审计保持通用:当前组件事件使用 `module=COMPONENT`、`targetType=COMPONENT`,未来模块可使用其他编码。查询不写死组件模块。目标 ID 为字符串,可兼容其他业务的字符串主键。
### 8.1 查询条件
`GET /admin-api/operation-logs`
| 参数 | 说明 |
| --- | --- |
| page / size | 分页 |
| module / action | 模块及动作精确筛选,支持其他业务编码 |
| success | true / false |
| operatorId | 操作人 ID |
| targetType / targetId / targetCode | 目标类型、主键、业务编码精确筛选 |
| keyword | 目标名称或编码模糊筛选 |
| from / to | 操作时间闭区间,ISO 本地时间,from 不可晚于 to |
例如:`/admin-api/operation-logs?module=COMPONENT&action=DELETE&success=true&targetId=123`。
### 8.2 列表元素及详情
`GET /admin-api/operation-logs/{id}` 返回相同日志结构:
```json
{
"id":900,
"module":"COMPONENT",
"action":"DELETE",
"targetType":"COMPONENT",
"targetId":"123",
"targetCode":"CW-0123456789ABCDEF0123456789ABCDEF",
"targetName":"四孔安装板",
"operatorId":0,
"operatorName":"TEST_OPERATOR",
"requestPath":"/admin-api/components/{id:[0-9]+}",
"requestMethod":"DELETE",
"clientIp":"127.0.0.1",
"requestId":"请求编号",
"operatedAt":"2026-10-10T16:05:00.123",
"durationMs":35,
"success":true,
"httpStatus":200,
"errorCode":"",
"errorSummary":""
}
```
删除保留操作前目标快照。失败事件记录已安全确认的目标标识,无法确定的字段为空字符串;新增失败可能尚无目标 ID。请求路径为路由模板,不保存查询参数。日志不保存请求体、表单自定义值、上传令牌或 OSS 签名。
审计写入独立事务,写日志失败不改变业务结果,运行日志记录安全定位信息和 requestId。
## 9. 常见错误
| HTTP | code | 处理 |
| --- | --- | --- |
| 422 | INVALID_REQUEST | 必填、类型、长度、精度、版本参数等错误,修正请求 |
| 422 | INVALID_UPLOAD_SIGNATURE_REQUEST | 续签令牌为空或与 componentId 同时提交 |
| 422 | INVALID_COMPONENT_UPLOAD_SESSION | 令牌无效、过期、操作人/环境/组件不匹配 |
| 422 | INVALID_STORAGE_OBJECT_KEY | 非当前环境相对对象键,或非法/越界路径 |
| 422 | INVALID_COMPONENT_UPLOAD_OBJECT | 文件类型、清单、目录、主文件数量或实际大小信息无效 |
| 422 | COMPONENT_UPLOAD_OBJECT_MISSING | OSS 未检测到文件,确认直传完成及 Key 正确 |
| 422 | DUPLICATE_CUSTOM_FIELD | 同一组自定义字段名称重复 |
| 422 | INVALID_COMPONENT_FORM | 说明超出 TEXT 字段容量 |
| 422 | COMPONENT_CODE_IMMUTABLE | 修改请求试图改变编码 |
| 413 | UPLOAD_TOO_LARGE | 实际文件超过大小限制 |
| 409 | COMPONENT_REVISION_CONFLICT | 重新加载最新组件并处理冲突 |
| 409 | COMPONENT_CODE_DUPLICATE | 同一编码已保存,不要重复新增 |
| 404 | COMPONENT_NOT_FOUND | 组件不存在或已删除 |
| 404 | USER_NOT_FOUND / OPERATION_LOG_NOT_FOUND | 对应记录不存在 |
| 409 | USER_PHONE_DUPLICATE | 手机号已占用,包含逻辑删除用户 |
| 500 | OSS_UPLOAD_SIGN_FAILED | 根据 requestId 排查签名配置或 OSS 调用 |
OSS 直传错误直接来自 OSS,不使用后台统一响应。后台保存成功才表示组件及资源引用已生效。