544 lines
29 KiB
Markdown
544 lines
29 KiB
Markdown
# 后台 API 联调文档
|
||
|
||
后台保留组件库、用户管理、操作日志三个模块。以下路径以 `/admin-api` 为前缀,默认服务地址 `http://127.0.0.1:8992`。
|
||
|
||
## 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`、`email`、`nickname`、`status`、`userType`、`createdAt`、`updatedAt`。
|
||
|
||
POST / PUT 请求:
|
||
|
||
```json
|
||
{ "email": "user@example.com", "nickname": "测试用户", "status": "ACTIVE", "userType": "NORMAL" }
|
||
```
|
||
|
||
邮箱需为有效邮箱且保持唯一(最多 254 字符),昵称必填且最多 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_EMAIL_DUPLICATE | 邮箱已占用,包含逻辑删除用户 |
|
||
| 500 | OSS_UPLOAD_SIGN_FAILED | 根据 requestId 排查签名配置或 OSS 调用 |
|
||
|
||
OSS 直传错误直接来自 OSS,不使用后台统一响应。后台保存成功才表示组件及资源引用已生效。
|
||
|
||
## 新增旋转轴 rotationAxis(2026-10-15)
|
||
|
||
组件新增、编辑请求以及详情、列表与匹配结果中的组件 DTO 增加可选顶层字段 `rotationAxis`。值为 `X`、`Y`、`Z`、`-X`、`-Y`、`-Z` 或 `null`;请求按大写提交。留空提交 `null`,表示固定连接;编辑时提交 `null` 也必须清除之前的轴。
|
||
|
||
```json
|
||
{ "rotationAxis": "Z" }
|
||
```
|
||
|
||
后端需要保存字段,且在 `/admin-api/components` 的新增/编辑响应、详情响应和前台匹配返回的 `components[].component.rotationAxis` 中返回。此字段不放到 `urdfInfo`、`basicFields` 或 BOM 内,也不修改 URDF 原文、接口坐标或零件自由度。
|
||
|
||
前台在配件实际连接到父零件后,在连接点增加一个连续旋转的装配关节。轴方向按安装连接点局部坐标系解释,初始角度为 0:`T_child = T_parent × T_parentPort × R_axis(angle) × inverse(T_childPort)`。负轴遵循对应方向的右手规则。旋转带动配件和它的所有下级零件,URDF 内部的关节与 mesh 相对位姿保持原样。
|
||
|
||
没有该字段、值为空、根零件没有父连接时,不增加活动装配关节。未能配对的零件先单独展示;前台不会凭旋转轴猜测连接点。非法返回值提示原因并保留固定连接显示。
|
||
|
||
前台“属性 → 装配关节”中的 ±180° 是查看一圈的预览范围,不作为机械限位,也不回写 URDF 的 joint limit。需要机械限位时应另外约定限位字段。
|
||
|
||
后台保存后会核对响应中的 rotationAxis。如果后端忽略新字段,会明确提示“后端未返回一致的旋转轴”,保留当前输入,避免误报保存成功。
|