ZKEco Pro 中间表对接

概述

E-ZKEco Pro 中间表对接是一种数据库直连同步方案：第三方系统向约定的 middle_table 表写入记录，
E-ZKEco Pro 后台定时扫描并处理，处理结果回写到同一张表的状态字段中。

与 REST API 对接的区别：中间表方案无需 HTTP 调用，通过共享数据库表完成数据交换，
适合内网环境或无法开放 API 端口的场景。

快速上手（30 秒关键约定）

中间表结构

CREATE TABLE middle_table (
    id            INT IDENTITY(1,1) PRIMARY KEY,  -- 自增主键
    table_name    NVARCHAR(30)  NOT NULL,          -- 业务标识：dept/userinfo/area/position
    data_content  NVARCHAR(MAX) NOT NULL,          -- JSON 格式业务数据
    op_type       NVARCHAR(10)  NOT NULL,          -- create/update/delete
    create_time   DATETIME      NOT NULL,          -- 第三方写入时间
    flag          INT           NOT NULL DEFAULT 0,-- 0=未处理 1=成功 2=失败
    msg           NVARCHAR(250) NULL,              -- E-ZKEco Pro 回写错误信息
    update_time   DATETIME      NULL               -- E-ZKEco Pro 回写处理时间
);

> 注意：建表 SQL 以 SQL Server 为例。Oracle / PostgreSQL 语法见 references/ 下的建表脚本。

四类业务数据格式

1. 部门（table_name = "dept"）

{
  "DeptNumber": "D001",
  "DeptName": "研发部",
  "parentCode": "D000"
}

2. 人员（table_name = "userinfo"）

{
  "pin": "10001",
  "name": "张三",
  "deptCode": "D001",
  "positionCode": "P001",
  "OffDuty": 0,
  "gender": 1,
  "zonecode": [1, 2],
  "mobile": "13800138000",
  "card": "A0001",
  "hiredday": "2024-01-15",
  "email": "zhangsan@example.com",
  "hiretype": "0"
}

3. 区域（table_name = "area"）

{
  "code": "A001",
  "name": "厦门总部",
  "parentCode": "A000"
}

4. 职务（table_name = "position"）

{
  "code": "P001",
  "name": "工程师",
  "level": 3
}

核心工作流

第三方系统                              E-ZKEco Pro
    │                                       │
    │  INSERT middle_table                  │
    │  (flag=0, create_time=now)            │
    │ ──────────────────────────────────►   │
    │                                       │ 定时扫描 flag=0
    │                                       │ 解析 JSON，执行业务
    │                                       │
    │  ◄── 回写 flag=1/2, msg, update_time  │
    │                                       │
    │  轮询 flag=1/2 确认结果               │
    │  清理或标记已处理记录                 │

第三方职责

1. 写入：向 middle_table 插入记录，flag 设为 0
2. 轮询：定期查询 flag 是否变为 1 或 2
3. 处理结果：成功则清理记录；失败则读取 msg 排查并重试
4. 清理：建议定期删除 flag=1 的历史记录，避免表膨胀

错误提示速查

部门错误

人员错误

区域错误

职务错误

示例代码

assets/ 目录提供可运行的 Python 与 Java 封装：

• assets/middle_table_python.py — 仅依赖标准库（sqlite3/pyodbc 可选），含 MiddleTableClient 封装类、
  4 类业务写入方法、结果轮询、失败重试、批量插入，直接复制使用。
• assets/middle_table_java.java — Java 8+ JDBC 实现，含连接管理、批量写入、轮询查询、
  错误处理，含 Maven 依赖注释。

使用方式

1. 复制 assets/ 下对应语言文件到项目
2. 修改数据库连接参数（host/port/db/user/password）
3. 调用 create_dept() / create_user() / create_area() / create_position() 等方法

详细文档

references/ 目录提供完整文档：

• references/ZKEcoPro_中间表对接说明书_V8.0.md — 完整说明书原文，含所有字段定义、示例、注意事项。
  需要查阅某个业务的完整字段或错误场景时读取此文件。

常见问题

Q: 中间表方案和 REST API 方案怎么选？

Q: 如何配置同步频率？

在 E-ZKEco Pro 管理后台：系统选项 → 数据对接设置 → 中间表对接，选择按时间点（如 07:09）、
按小时间隔、或立即同步。

Q: flag=2 处理失败后怎么办？

读取 msg 字段获取失败原因，修正 data_content 后重新插入一条新记录（flag=0）。
原失败记录建议保留以备审计，或定期清理。

Q: data_content 字段长度限制？

部门/区域/职务表中 data_content 为 nvarchar(250)，人员表为 nvarchar(max)。
人员数据字段较多时注意不要超过 250 字符限制——建议建表时统一使用 nvarchar(max)。

Q: 是否支持批量操作？

支持。一次 INSERT 多条记录即可，每条记录独立处理、独立回写 flag。
建议单批 ≤500 条以避免数据库锁竞争。

Q: 删除操作需要注意什么？

删除时 data_content 中只需提供主键字段（如部门的 DeptNumber、人员的 pin）。
级联约束：存在下级或关联人员时删除会被拒绝，需先处理子节点。

集成检查清单

向第三方交付时确认以下项：

• [ ] 数据库连接参数已确认（host/port/db/user/password）
• [ ] middle_table 表已在 E-ZKEco Pro 数据库中创建
• [ ] E-ZKEco Pro 管理后台已启用中间表对接
• [ ] 同步频率已配置（时间点 / 间隔 / 立即）
• [ ] 写入逻辑：flag=0, create_time=当前时间
• [ ] 轮询逻辑：定期检查 flag 是否变为 1 或 2
• [ ] 失败处理：读取 msg 后修正数据并重试
• [ ] 历史记录清理策略已制定（避免表膨胀）
• [ ] JSON 格式校验已实现（写入前校验合法性）
• [ ] 级联删除约束已了解（先删子节点再删父节点）

📞 帮助与支持

• 联系微信 <u>Principles_RD</u>（备注协议对接）获得技能使用支持；