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 标准格式：

{
  "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。

示例：

GET /jeecg-boot/sys/user/scada/queryUser?pageNo=1&pageSize=500&includeDetail=false

6.2 增量同步（断网续传）

1. 使用本地 syncCursor 作为 updatedAfter。
2. 分页拉取，直到无新增数据。
3. 每处理完一页更新本地游标（建议按返回中最大 updateTime）。

示例：

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