sdx/wucaixing-backend

Fork 0

Files

18980591175 8f9d286bec 电子签名

2026-05-14 16:10:51 +08:00

4.9 KiB

Raw Blame History

电子签名后端对接说明

目标

支持前端在“点击使用电子签名”时，自动获取当前登录人员已配置的电子签名并回填。

当当前人员未配置电子签名时，后端返回提示：

暂未设置电子签名，请在个人资料内设置后重试或使用手动签名

数据设计

表名

sys_user_electronic_signature

核心设计说明

一条记录对应“当前登录人员”的一份电子签名配置
人员唯一性通过 tenant_id + person_key 控制
person_key 生成规则：loginPort:companyId:businessUserId
当 businessUserId 为空时，回退为 loginPort:companyId:userId
签名文件本体继续复用现有 OSS 表，不重复存文件内容，只存 sign_oss_id
支持“清空签名”：保留记录，将 status 置为 0，并清空 sign_oss_id

主要字段

person_key：当前登录人员唯一键
user_id：系统用户 ID
business_user_id：业务人员 ID，例如驾驶员/安全员 ID
company_id：当前企业 ID
login_port：当前登录端口
sign_oss_id：电子签名图片 OSS ID
sign_name：签署人名称快照
status：1=已设置，0=未设置

建表脚本见：

sql/1289/3_user_electronic_signature.sql

接口列表

统一前缀：

/system/user/profile

1. 查询当前登录人员电子签名信息

方法：GET
路径：/system/user/profile/electronic-signature/info
用途：个人资料页进入时查询当前签名配置状态
特点：即使未配置，也返回成功，前端通过 data.configured 判断

响应示例：

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "id": 1,
    "configured": true,
    "personKey": "port-driver:1001:DRV0001",
    "userId": 20001,
    "businessUserId": "DRV0001",
    "companyId": 1001,
    "loginPort": "port-driver",
    "signOssId": 98765,
    "signUrl": "https://xxx/signature.png",
    "signName": "张三",
    "status": "1"
  }
}

未配置时示例：

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "configured": false,
    "personKey": "port-driver:1001:DRV0001",
    "userId": 20001,
    "businessUserId": "DRV0001",
    "companyId": 1001,
    "loginPort": "port-driver",
    "signOssId": null,
    "signUrl": null,
    "signName": "张三",
    "status": "0"
  }
}

2. 业务页获取当前电子签名并回填

方法：GET
路径：/system/user/profile/electronic-signature/current
用途：点击“使用电子签名”时直接调用
特点：已配置时返回签名信息；未配置时直接返回失败提示，前端弹出 msg 即可

已配置响应示例：

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "configured": true,
    "signOssId": 98765,
    "signUrl": "https://xxx/signature.png",
    "signName": "张三"
  }
}

未配置响应示例：

{
  "code": 500,
  "msg": "暂未设置电子签名，请在个人资料内设置后重试或使用手动签名",
  "data": null
}

前端建议处理：

当接口成功时，将 data.signUrl 回填到下方签名展示区域
同时保留 data.signOssId，提交业务表单时直接透传
当接口失败时，直接提示后端返回的 msg

3. 保存当前登录人员电子签名

方法：PUT
路径：/system/user/profile/electronic-signature
用途：个人资料页设置或更换电子签名

请求参数：

{
  "signOssId": 98765
}

说明：

signOssId 必填
文件需要先通过现有 OSS 上传接口上传成功
后端会校验该文件是否存在，且是否为图片格式

成功响应示例：

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "configured": true,
    "signOssId": 98765,
    "signUrl": "https://xxx/signature.png",
    "signName": "张三",
    "status": "1"
  }
}

4. 清空当前登录人员电子签名

方法：DELETE
路径：/system/user/profile/electronic-signature
用途：个人资料页删除当前电子签名配置

成功响应示例：

{
  "code": 200,
  "msg": "操作成功",
  "data": null
}

与前端交互建议

个人资料页

页面加载时调用 GET /electronic-signature/info
若 configured = true，展示当前签名图片
用户更换签名时，先调用现有 OSS 上传接口，再把返回的 ossId 提交到保存接口
用户删除签名时，调用清空接口

业务签署页

点击“使用电子签名”
调用 GET /electronic-signature/current
若成功：
- 回填 signUrl
- 保存 signOssId
若失败：
- 直接提示 msg
- 保留“手动签名”入口

依赖的现有上传接口

上传签名图片时继续复用现有 OSS 上传能力：

方法：POST
路径：/resource/oss/upload
表单字段：file

返回示例中的 data.ossId 即为后续保存电子签名所需的 signOssId。

4.9 KiB Raw Blame History Unescape Escape