wucaixing-backend/docs/electronic_signature_api.md

# 电子签名后端对接说明

## 目标

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

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

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

## 数据设计

### 表名

`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`。