更新项目配置，新增设备同步模块，优化WebSocket和Swagger配置，增强SCADA系统的免登录接口，支持数据字典项和登录日志的免登录查询与记录。调整Java编译设置，确保更好的开发体验。
This commit is contained in:
geht
158
docs/SCADA-用户同步接口文档.md
Normal file
158
docs/SCADA-用户同步接口文档.md
Normal file
@@ -0,0 +1,158 @@
|
||||
# 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`
|
||||
|
||||
Reference in New Issue
Block a user