电子签名

2026-05-14 16:10:51 +08:00
parent 1c9cbfae59
commit 8f9d286bec
9 changed files with 671 additions and 0 deletions
--- a/docs/electronic_signature_api.md
+++ b/docs/electronic_signature_api.md
@@ -0,0 +1,215 @@
+# 电子签名后端对接说明
+
+## 目标
+
+支持前端在“点击使用电子签名”时，自动获取当前登录人员已配置的电子签名并回填。
+
+当当前人员未配置电子签名时，后端返回提示：
+
+`暂未设置电子签名，请在个人资料内设置后重试或使用手动签名`
+
+## 数据设计
+
+### 表名
+
+`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` 判断
+
+响应示例：
+
+```json
+{
+  "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"
+  }
+}
+```
+
+未配置时示例：
+
+```json
+{
+  "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` 即可
+
+已配置响应示例：
+
+```json
+{
+  "code": 200,
+  "msg": "操作成功",
+  "data": {
+    "configured": true,
+    "signOssId": 98765,
+    "signUrl": "https://xxx/signature.png",
+    "signName": "张三"
+  }
+}
+```
+
+未配置响应示例：
+
+```json
+{
+  "code": 500,
+  "msg": "暂未设置电子签名，请在个人资料内设置后重试或使用手动签名",
+  "data": null
+}
+```
+
+前端建议处理：
+
+- 当接口成功时，将 `data.signUrl` 回填到下方签名展示区域
+- 同时保留 `data.signOssId`，提交业务表单时直接透传
+- 当接口失败时，直接提示后端返回的 `msg`
+
+### 3. 保存当前登录人员电子签名
+
+- 方法：`PUT`
+- 路径：`/system/user/profile/electronic-signature`
+- 用途：个人资料页设置或更换电子签名
+
+请求参数：
+
+```json
+{
+  "signOssId": 98765
+}
+```
+
+说明：
+
+- `signOssId` 必填
+- 文件需要先通过现有 OSS 上传接口上传成功
+- 后端会校验该文件是否存在，且是否为图片格式
+
+成功响应示例：
+
+```json
+{
+  "code": 200,
+  "msg": "操作成功",
+  "data": {
+    "configured": true,
+    "signOssId": 98765,
+    "signUrl": "https://xxx/signature.png",
+    "signName": "张三",
+    "status": "1"
+  }
+}
+```
+
+### 4. 清空当前登录人员电子签名
+
+- 方法：`DELETE`
+- 路径：`/system/user/profile/electronic-signature`
+- 用途：个人资料页删除当前电子签名配置
+
+成功响应示例：
+
+```json
+{
+  "code": 200,
+  "msg": "操作成功",
+  "data": null
+}
+```
+
+## 与前端交互建议
+
+### 个人资料页
+
+1. 页面加载时调用 `GET /electronic-signature/info`
+2. 若 `configured = true`，展示当前签名图片
+3. 用户更换签名时，先调用现有 OSS 上传接口，再把返回的 `ossId` 提交到保存接口
+4. 用户删除签名时，调用清空接口
+
+### 业务签署页
+
+1. 点击“使用电子签名”
+2. 调用 `GET /electronic-signature/current`
+3. 若成功：
+   - 回填 `signUrl`
+   - 保存 `signOssId`
+4. 若失败：
+   - 直接提示 `msg`
+   - 保留“手动签名”入口
+
+## 依赖的现有上传接口
+
+上传签名图片时继续复用现有 OSS 上传能力：
+
+- 方法：`POST`
+- 路径：`/resource/oss/upload`
+- 表单字段：`file`
+
+返回示例中的 `data.ossId` 即为后续保存电子签名所需的 `signOssId`。