qhmes/docs/SCADA-用户同步接口文档.md

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