216 lines
4.9 KiB
Markdown
216 lines
4.9 KiB
Markdown
# 电子签名后端对接说明
|
||
|
||
## 目标
|
||
|
||
支持前端在“点击使用电子签名”时，自动获取当前登录人员已配置的电子签名并回填。
|
||
|
||
当当前人员未配置电子签名时，后端返回提示：
|
||
|
||
`暂未设置电子签名，请在个人资料内设置后重试或使用手动签名`
|
||
|
||
## 数据设计
|
||
|
||
### 表名
|
||
|
||
`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`。
|