Files
cadworld/cadworld-adminapi/docs/admin-api.md
T

30 KiB
Raw Blame History

后台 API 联调文档

后台保留组件库、用户管理、操作日志三个模块。以下路径以 /admin-api 为前缀,默认服务地址 http://127.0.0.1:8992。

用户端匹配与拼装接口由独立的 cadworld-api 服务提供,默认端口8991,详见用户端 API 文档。用户端默认组件、替代候选和详情同时返回 bomList、urdfInfo,通过编码访问组件,模型直接使用公开OSS/CDN地址。

1. 通用约定

JSON 请求设置 Content-Type: application/json。先完成管理员邮箱与图片验证码登录,业务接口统一携带 Authorization: Bearer <token>。仅允许已启用的 ADMIN 账号,不自动注册;上传会话及审计使用真实登录管理员。

/admin-api/** 跨域白名单按 profile 区分:test 允许 https://dev-cadworld-admin.robotquan.com,prod 允许 https://cadworld-admin.robotquan.com。可通过 APP_ADMIN_ALLOWED_ORIGINS 覆盖,多个完整 origin 用逗号分隔,禁止通配符;显式留空关闭跨域。允许 GET / HEAD / POST / PUT / DELETE / OPTIONS,请求头允许 Content-Type / Authorization / X-Request-Id,支持凭证,并向前端暴露 X-Request-Id;预检缓存 3600 秒。OSS 直传上传的 CORS 仍需在 OSS 单独配置。

成功返回 HTTP 200,包括新增和删除:

{"code":"OK","message":"success","data":{"success":true},"requestId":"请求编号"}

失败返回对应 HTTP 状态和错误码,data 可能省略:

{"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. 接口列表

方法 路径 作用
GET /admin-api/auth/captcha 获取图片验证码,无需登录
POST /admin-api/auth/login 管理员邮箱登录,无需登录
POST /admin-api/auth/logout 退出当前管理端登录态
GET /admin-api/users/me 当前管理员,不返回主键
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- 加 16 位随机字符,总长 19,例如 CW-7K3M9Q2R6V8X4T5N。随机字符使用数字及大写字母,排除容易混淆的 I/L/O/U;使用密码学安全随机数生成,具有 80 位随机空间,保存时仍由 component_code 唯一索引约束。申请签名不创建组件记录。编辑使用原编码,生成新的上传批次;组件不存在返回 404。

旧版 CW- 加 32 位大写十六进制字符的组件编码和上传会话继续有效,包括升级前申请、尚未保存的上传会话。已有组件不重编码,资源目录保持原编码;前端必须直接使用接口返回的编码,不能假定固定为 35 字符。

续签不能同时提交 componentId。续签验证签名、有效期、操作人、环境及绑定组件,保持原编码、批次、令牌和目录。默认会话有效期 30 分钟、OSS 授权有效期 5 分钟;授权不超过会话到期时间,续签不延长会话。

3.2 响应

以下签名值仅为占位示例,实际表单字段必须使用后端返回值:

{
  "code":"OK",
  "message":"success",
  "requestId":"请求编号",
  "data":{
    "componentCode":"CW-7K3M9Q2R6V8X4T5N",
    "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-7K3M9Q2R6V8X4T5N/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-7K3M9Q2R6V8X4T5N/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:

{环境根目录}/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。新增业务字段仅 stepObjectKey 必填,仍须提交有效的 uploadSessionToken;全量修改保留名称、分类和 URDF 信息必填规则:

字段 类型 必填 / 默认值 / 限制
componentName string POST 可选,默认 "";PUT 必填、非空;最多 128 字符,允许同名
category string POST 可选,默认 "";PUT 必填、非空;最多 64 字符,自由分类
status string / null 仅接受 ENABLED(启用)、DISABLED(禁用);POST 省略或为 null 时默认启用,PUT 省略或为 null 时保留原状态
description string 默认 "",UTF-8 不超过 65535 字节
material string 默认 "",最多 128 字符
massKg number 默认 0,千克,非负
degreesOfFreedom integer 默认 0,范围 0 至 2147483647,仅接受 JSON 整数,不接受小数或字符串
rotationAxis string / null 可选,默认 null;仅接受大写 X、Y、Z,不接受空字符串、小写或数字
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) 一致;不要在数值中提交单位文本。除 PUT 的 status 保留原值外,可选字段省略或传 null 会恢复默认值。名称、分类、材质、功能、形状和大小会裁剪首尾空白。

bomList 和 urdfInfo 直接提交 JSON 对象或数组,不接受字符串化的 JSON、数字或布尔值。bomList 省略或为 null 时保存为空数组;新增时 urdfInfo 省略或为 null 也保存为空数组,修改时仍须提供 JSON 对象或数组。两者内部字段不做固定结构校验,urdfInfo 由前端提供,不由后端解析 URDF 文件生成。

自定义字段格式:

{
  "basicFields":[{"name":"供应商型号","value":"L20-RIGHT"}],
  "parameterFields":[{"name":"额定电压","value":"24V"},{"name":"额定扭矩","value":"20 Nm"}]
}

每组最多 100 项,名称非空且最多 64 字符,值为非 null 字符串、最多 2000 字符,可以为空字符串。同组名称裁剪后不可重复,两组之间可以重名;顺序与请求一致。

PUT 是全量表单更新,前端应提交完整表单,每次都必须提交 urdfInfo。除 status 外,省略可选字段会恢复默认值,提交空数组可清空 BOM 或自定义字段。

status 对应数据库 status,新增和存量组件默认 ENABLED。通过现有 PUT 编辑接口切换状态,仍须提交完整必填表单和最新 version,保存成功后版本递增。非法状态(包括小写、空字符串和数字)返回 422。禁用组件仍可在管理端列表、详情中查看和编辑,也可重新启用;禁用后不参与新生成的结构化匹配、AI 拼装或替代候选。用户端按编码查询详情、历史生成结果和已保存项目继续可查看。

rotationAxis 对应数据库 rotation_axis,下拉选项值使用 X、Y、Z;未设置时返回 null。PUT 省略该字段或传 null 会清空已有旋转轴。该字段是组件元数据,不替代 urdfInfo 中每个关节的 axis。

4.2 保存时的资源校验

新增必须提交 STEP,URDF 可选,urdfObjectKeys 省略、为 null 或空数组均表示未上传 URDF;此时 urdfPrefix、urdfMainObjectKey 保存为 "",urdfFiles 保存为 []。修改可只替换一种,未提交的资源保持原引用。文件引用只能来自当前操作人、当前组件的有效令牌和对应目录。

后端检查全部对象键合法、无重复、无路径越界且实际存在,按 OSS HEAD 返回的实际大小校验,不接受前端提供的文件大小。STEP 是直接位于 STEP 批次目录的一个非空 .step 或 .stp 文件。提交非空 URDF 清单时,清单须为 1 至 1000 项,必须恰好包含一个非空 .urdf 主文件,不支持以 .rfs 为主文件;扩展名大小写均可。

后端根据实际对象生成 urdfPrefix、urdfMainObjectKey 和 urdfFiles,清单保留请求顺序,元素为 relativePath 和 sizeBytes。无需提交这些数据库维护字段。

数据库中的 step_object_key、urdf_main_object_key、urdf_prefix 仅保存从 components/ 开始的相对路径,不包含 app.storage.root-prefix 环境根目录;目录前缀保留末尾 /。上传授权、保存请求和详情响应中的对象键仍包含环境根目录,访问 URL 根据当前环境配置生成,前端用法不变。兼容读取带当前环境根目录的旧记录,组件再次成功保存时统一转换这三个字段(仅修改业务信息也会转换),读取不会修改数据库,无需批量更新旧数据。

检查全部通过才写数据库。失败不切换原资源引用。旧批次、上传后未保存及删除组件后的文件暂不自动清理。校验覆盖清单的结构和对象存在性,不解析 URDF XML 内部的依赖引用。

4.3 旋转轴字段部署

部署管理端和用户端新代码前,在两端使用的组件数据库中执行以下 SQL。已有记录保持 null,应用不会自动执行迁移;仓库 .sql 文件不修改。

ALTER TABLE `component`
  ADD COLUMN `rotation_axis` ENUM('X','Y','Z')
    CHARACTER SET ascii COLLATE ascii_bin
    NULL DEFAULT NULL
    COMMENT '旋转轴:X、Y、Z;NULL表示未设置'
    AFTER `degrees_of_freedom`;

4.4 组件状态字段部署

部署管理端和用户端新代码前,在两端使用的组件数据库中手动执行以下 SQL。已有记录自动获得启用状态,应用不会自动执行迁移;仓库 .sql 文件不修改。

ALTER TABLE `component`
  ADD COLUMN `status` ENUM('ENABLED', 'DISABLED')
    CHARACTER SET ascii COLLATE ascii_bin
    NOT NULL DEFAULT 'ENABLED'
    COMMENT '组件状态:ENABLED-启用,DISABLED-禁用'
    AFTER `category`;

5. 组件接口

5.1 新增

POST /admin-api/components。编码由令牌读取,不接受前端指定编码。仅上传 STEP 后即可提交最小请求:

{
  "uploadSessionToken":"签名接口返回的令牌",
  "stepObjectKey":"cadworld_dev/components/CW-7K3M9Q2R6V8X4T5N/step/abcdef0123456789abcdef0123456789/model.step"
}

其余业务字段按默认值保存;bomList、urdfInfo 虽为 NOT NULL,后端会显式写入空数组。部署前须完成上面的旋转轴和组件状态字段迁移。需要填写元数据或上传 URDF 时,可提交完整请求:

{
  "componentName":"四孔安装板",
  "category":"安装板",
  "status":"ENABLED",
  "description":"用于固定机械组件",
  "material":"铝合金",
  "massKg":0.35,
  "degreesOfFreedom":0,
  "rotationAxis":"Z",
  "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-7K3M9Q2R6V8X4T5N/step/abcdef0123456789abcdef0123456789/model.step",
  "urdfObjectKeys":[
    "cadworld_dev/components/CW-7K3M9Q2R6V8X4T5N/urdf/abcdef0123456789abcdef0123456789/robot.urdf",
    "cadworld_dev/components/CW-7K3M9Q2R6V8X4T5N/urdf/abcdef0123456789abcdef0123456789/meshes/base.stl"
  ]
}

成功返回完整组件详情,初始 version=1。重复使用已保存编码新增返回 409,包含已逻辑删除组件的编码。

5.2 详情及保存响应

GET /admin-api/components/123,POST / PUT 成功的 data 也使用此结构:

{
  "id":123,
  "componentCode":"CW-7K3M9Q2R6V8X4T5N",
  "componentName":"四孔安装板",
  "category":"安装板",
  "status":"ENABLED",
  "description":"用于固定机械组件",
  "material":"铝合金",
  "massKg":0.35,
  "degreesOfFreedom":0,
  "rotationAxis":"Z",
  "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-7K3M9Q2R6V8X4T5N/step/abcdef0123456789abcdef0123456789/model.step",
  "stepUrl":"http://127.0.0.1:8992/admin-api/component-assets/cadworld_dev/components/CW-7K3M9Q2R6V8X4T5N/step/abcdef0123456789abcdef0123456789/model.step",
  "urdfPrefix":"cadworld_dev/components/CW-7K3M9Q2R6V8X4T5N/urdf/abcdef0123456789abcdef0123456789/",
  "urdfBaseUrl":"http://127.0.0.1:8992/admin-api/component-assets/cadworld_dev/components/CW-7K3M9Q2R6V8X4T5N/urdf/abcdef0123456789abcdef0123456789/",
  "urdfMainObjectKey":"cadworld_dev/components/CW-7K3M9Q2R6V8X4T5N/urdf/abcdef0123456789abcdef0123456789/robot.urdf",
  "urdfUrl":"http://127.0.0.1:8992/admin-api/component-assets/cadworld_dev/components/CW-7K3M9Q2R6V8X4T5N/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,成功后递增。只改表单无需签名:

{
  "version":1,
  "componentName":"四孔安装板 V2",
  "category":"安装板",
  "status":"ENABLED",
  "description":"更新说明",
  "material":"铝合金",
  "massKg":0.35,
  "degreesOfFreedom":0,
  "rotationAxis":"Z",
  "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 之外提交:

{
  "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、status、description、degreesOfFreedom、rotationAxis、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 下载。若 URL 指向 /admin-api/component-assets/**,fetch 或模型加载器须携带管理端 Authorization 头,文件可转 Blob URL 展示或下载;Token 不放在 URL 中。若指向公开 OSS/CDN,则沿用公开资源加载方式。下载成功返回原文件流,不包 JSON;对象不存在返回 404。对象键区分大小写且必须属于当前环境根目录。

6. 浏览器完整上传示例

页面文件选择器:

<input id="step" type="file" accept=".step,.stp">
<input id="urdf" type="file" webkitdirectory multiple>

以下示例使用一次签名完成两类文件上传,授权即将到期时调用同一接口续签,上传全部成功后直接保存。表单取当前页面值;示例按顺序上传以便展示流程,实际页面可使用受控并发。

// adminToken 为管理员登录返回的 Token,保存在应用登录状态中。
async function adminApi(path, method, body) {
  const response = await fetch(`/admin-api${path}`, {
    method,
    headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${adminToken}` },
    ...(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) {
    throw new Error('新增组件必须选择 STEP 文件');
  }
  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, rotationAxis: 'Z',
  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. 用户管理

用户字段以邮箱版 sys_user 为准,发布前执行用户编码迁移 SQL。列表支持 page、size、keyword(邮箱或昵称)、userType(NORMAL / ADMIN)、status(ACTIVE / DISABLED)。详情返回 id、userCode、email、nickname、status、userType、createdAt、updatedAt;后台路径仍使用 /{id},用户端只返回业务编码。

POST / PUT 请求:

{"email":"user@example.com","nickname":"测试用户","status":"ACTIVE","userType":"NORMAL"}

邮箱去除首尾空格并转小写后校验,最多 254 字符且唯一,重复返回 409 / USER_EMAIL_DUPLICATE。昵称必填且最多 64 字符。创建自动生成不可变 userCode,省略状态和类型时默认为 ACTIVE / NORMAL;修改省略则保留原值。

DELETE /admin-api/users/{id} 将状态设为 DISABLED,不删除记录。禁用用户仍能在列表和详情中查询,邮箱继续占用,可通过 PUT 将状态恢复为 ACTIVE。禁用后用户端登录返回 403,已有登录态的后续请求返回 401。用户管理只记录运行日志。

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} 返回相同日志结构:

{
  "id":900,
  "module":"COMPONENT",
  "action":"DELETE",
  "targetType":"COMPONENT",
  "targetId":"123",
  "targetCode":"CW-7K3M9Q2R6V8X4T5N",
  "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,不使用后台统一响应。后台保存成功才表示组件及资源引用已生效。