159 lines
4.9 KiB
Markdown
159 lines
4.9 KiB
Markdown
# SCADA 用户同步接口文档
|
||
|
||
## 1. 目标与适用场景
|
||
|
||
本文档用于规范 SCADA 系统对 JeecgBoot 用户数据的读取方式，支持以下场景：
|
||
|
||
- SCADA 首次全量拉取用户并缓存到本地。
|
||
- SCADA 按更新时间进行增量同步（断网续传）。
|
||
- SCADA 按条件（用户名、工号、手机号）查询特定用户。
|
||
- 在需要时拉取用户的组织与租户详细信息。
|
||
|
||
---
|
||
|
||
## 2. 接口信息
|
||
|
||
- **接口名称**：SCADA-免登录查询用户信息
|
||
- **请求方法**：`GET`
|
||
- **接口路径**：`/jeecg-boot/sys/user/scada/queryUser`
|
||
- **认证要求**：免登录（已加入后端白名单）
|
||
- **文档状态**：已在 Knife4j 中取消 `X-Access-Token` 必填限制
|
||
|
||
---
|
||
|
||
## 3. 请求参数
|
||
|
||
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|
||
|---|---|---|---|---|
|
||
| `username` | string | 否 | - | 用户名，精确匹配 |
|
||
| `workNo` | string | 否 | - | 工号，精确匹配 |
|
||
| `phone` | string | 否 | - | 手机号，精确匹配 |
|
||
| `updatedAfter` | string | 否 | - | 增量同步时间游标，仅返回更新时间或创建时间大于等于该值的数据。支持格式：`yyyy-MM-dd HH:mm:ss`、`yyyy-MM-dd'T'HH:mm:ss` |
|
||
| `pageNo` | int | 否 | `1` | 页码，从 1 开始 |
|
||
| `pageSize` | int | 否 | `200` | 每页条数，最大 `1000` |
|
||
| `includeDetail` | boolean | 否 | `false` | 是否返回部门/公司/租户详细信息；`true` 会增加查询耗时 |
|
||
|
||
> 说明：`username/workNo/phone` 三者都可为空；都为空时按分页返回“全部有效用户”。
|
||
|
||
---
|
||
|
||
## 4. 返回结构
|
||
|
||
顶层响应遵循 JeecgBoot 标准格式：
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "",
|
||
"code": 200,
|
||
"result": [
|
||
{
|
||
"id": "用户ID",
|
||
"username": "登录账号",
|
||
"realname": "真实姓名",
|
||
"password": "加密密码串",
|
||
"salt": "密码盐值",
|
||
"workNo": "工号",
|
||
"phone": "手机号",
|
||
"email": "邮箱",
|
||
"orgCode": "当前组织编码",
|
||
"post": "岗位ID/信息",
|
||
"status": 1,
|
||
"createTime": "创建时间",
|
||
"updateTime": "更新时间",
|
||
"lastPwdUpdateTime": "最后修改密码时间",
|
||
"departIds": "负责部门IDs",
|
||
"departmentList": [],
|
||
"companyList": [],
|
||
"loginTenantId": 1002,
|
||
"tenantList": []
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 4.1 字段说明（核心）
|
||
|
||
- `updateTime`：**增量同步主游标字段**，建议 SCADA 以此推进同步位点。
|
||
- `createTime`：用于补偿“新增但未更新”的数据。
|
||
- `departmentList`：仅在 `includeDetail=true` 时有值（否则为空数组）。
|
||
- `companyList`：仅在 `includeDetail=true` 时有值（否则为空数组）。
|
||
- `tenantList`：仅在 `includeDetail=true` 时有值（否则为空数组）。
|
||
- `password`/`salt`：均为后端存储态字段（非明文）；如无强依赖，建议 SCADA 侧不落库或脱敏保存。
|
||
|
||
---
|
||
|
||
## 5. 查询与同步规则
|
||
|
||
后端固定只返回“有效用户”：
|
||
|
||
- `delFlag = 0`
|
||
- `status = 1`
|
||
|
||
当传入 `updatedAfter` 时，后端过滤条件为：
|
||
|
||
- `updateTime >= updatedAfter` **或**
|
||
- `createTime >= updatedAfter`
|
||
|
||
---
|
||
|
||
## 6. 推荐调用策略（给 SCADA）
|
||
|
||
### 6.1 首次全量同步
|
||
|
||
1. `pageNo=1`，`pageSize=500`，`includeDetail=false`。
|
||
2. 按页拉取至空页（或小于 `pageSize`）。
|
||
3. 本地记录本次最大 `updateTime` 作为 `syncCursor`。
|
||
|
||
示例：
|
||
|
||
```http
|
||
GET /jeecg-boot/sys/user/scada/queryUser?pageNo=1&pageSize=500&includeDetail=false
|
||
```
|
||
|
||
### 6.2 增量同步（断网续传）
|
||
|
||
1. 使用本地 `syncCursor` 作为 `updatedAfter`。
|
||
2. 分页拉取，直到无新增数据。
|
||
3. 每处理完一页更新本地游标（建议按返回中最大 `updateTime`）。
|
||
|
||
示例：
|
||
|
||
```http
|
||
GET /jeecg-boot/sys/user/scada/queryUser?updatedAfter=2026-04-27 10:00:00&pageNo=1&pageSize=500&includeDetail=false
|
||
```
|
||
|
||
### 6.3 明细补拉策略
|
||
|
||
若 SCADA 需要组织和租户完整信息，仅对“已识别变更的用户”按条件补拉，并使用：
|
||
|
||
- `includeDetail=true`
|
||
- 同时带 `username/workNo/phone` 之一，缩小范围
|
||
|
||
---
|
||
|
||
## 7. 性能说明
|
||
|
||
- 默认 `includeDetail=false`，可避免部门与租户明细查询带来的额外耗时。
|
||
- 单次 `pageSize` 上限 `1000`，防止单请求过大。
|
||
- 如业务需要更高吞吐，建议后续将部门/租户查询改为批量聚合查询，避免 N+1 查询。
|
||
|
||
---
|
||
|
||
## 8. 安全建议
|
||
|
||
当前接口为免登录接口，建议尽快补充至少一种安全手段：
|
||
|
||
- IP 白名单（仅允许 SCADA 网段访问）
|
||
- 网关层签名校验（`appKey + timestamp + sign`）
|
||
- HTTPS 强制 + 调用方证书
|
||
|
||
---
|
||
|
||
## 9. 当前实现位置
|
||
|
||
- 控制器：`jeecg-boot/jeecg-module-system/jeecg-system-biz/src/main/java/org/jeecg/modules/system/controller/SysUserController.java`
|
||
- 文档与安全配置：`jeecg-boot/jeecg-boot-base-core/src/main/java/org/jeecg/config/Swagger3Config.java`
|
||
- 免登录白名单：`jeecg-boot/jeecg-module-system/jeecg-system-start/src/main/resources/application-*.yml`
|
||
|