V6600 数据集成对接指南

技能定位

本技能封装了万傲瑞达 V6600 数据集成模块 的完整对接知识。第三方开发人员无需深入了解万傲瑞达内部架构，只需按本技能定义的标准化模式即可完成与万傲瑞达的数据双向同步。

核心能力： 万傲瑞达的数据可推送给第三方系统，第三方系统的数据也可拉取到万傲瑞达。推送和拉取均支持 API 和数据库两种对接方式。

加载条件

本技能在以下任意场景触发时应当加载：

• 第三方系统需要从万傲瑞达读取或写入人员信息、组织架构、门禁事件、考勤记录等业务数据
• 需要为第三方系统配置API 推送，编写请求参数 JSON 映射
• 需要为第三方系统配置API 拉取，编写返回内容 JSON 映射（. 和 # 语法）
• 需要为第三方系统配置数据库推送/拉取，编写含 ${add}/${modify}/${del}/${search} 的 SQL 语句
• 需要为门禁事件或考勤记录设置数据过滤规则
• 需要配置异常返回码的处理机制和自动重试
• 第三方需要新建数据库表来接收万傲数据

快速入门（第三方开发人员 5 分钟上手）

确定你的集成模式

整体配置流程（万傲端操作）

服务对象（命名标识）
    ↓
服务配置（选择方向 + 填写我方连接信息）
    ↓
服务详细配置（选择业务对象 + 配置字段映射或 SQL）
    ↓
返回码类型配置（标记异常返回码）
    ↓
启用服务 + 执行验证

必备参考速查表

字段引用规则： 在 API 请求参数或 SQL 中引用万傲数据时，使用 ${fieldName} 格式。字符串加引号，数字不加。详见 内置变量与方法。

业务对象与字段映射（核心参考）

以下 9 个表中的 字段名 是配置 API 请求参数 / 返回内容 / 数据库 SQL 时的唯一合法字段名。字段名拼写错误是数据同步失败的首要原因。

部门（Department）

人员（Person）

区域（Area）

卡（PersCard）

职位（Position）

对比照片（PersBioPhoto）

生物模板——指纹（PersBioTemplate）

门禁事件记录（AccTransaction）

考勤记录（AttTransaction）

场景 1：API 推送配置

适用条件

万傲瑞达作为数据源，主动调用第三方 HTTP API 推送数据。

服务配置参数

请求参数编写规则

位置： 服务详细配置 → 请求参数字段。

数据类型对应格式：

完整示例：部门新增推送

接口地址：/api/department/add?access_token=${token}
请求方式：POST
请求参数：
{
  "code": "${code}",
  "name": "${name}",
  "parentCode": "${parentCode}",
  "sortNo": ${sortNo}
}

完整示例：人员新增推送

接口地址：/api/person/addPersonnel?access_token=${token}
请求方式：POST
请求参数：
{
  "pin": "${pin}",
  "name": "${name}",
  "lastName": "${lastName}",
  "gender": "${gender}",
  "cardNo": "${cardNo}",
  "mobilePhone": "${mobilePhone}",
  "deptCode": "${deptCode}",
  "email": "${email}",
  "personPhoto": "${personPhoto}"
}

完整示例：人员删除推送

接口地址：/api/person/delete/${pin}?access_token=${token}
请求方式：POST
请求参数：（删除操作通常为空，标识在 URL 中）

完整示例：卡新增推送

接口地址：/api/card/cardManage?access_token=${token}
请求方式：POST
请求参数：
{
  "cardNo": "${cardNo}",
  "pin": "${personPin}",
  "status": "1"
}

> "status": "1" 是固定值，不是变量——表示每次调用都传 1。

业务对象需要配置的操作组合

场景 2：API 拉取配置

适用条件

第三方系统作为数据源，万傲瑞达定时调用第三方的 HTTP API 获取数据。

与推送的关键区别

拉取的核心在于 返回内容映射——将第三方 API 返回的 JSON 结构翻译成万傲业务对象的标准字段。

返回内容映射规则

{
  "msg": "message",                    // 左侧固定，右侧填第三方返回的消息字段路径
  "ret": "code",                       // 左侧固定，右侧填第三方返回的状态码路径
  "data": {
    "count": "data.total",             // 数据总数路径
    "items": [
      {
        "deptnumber": "data.data#code",  // 万傲字段: "第三方路径#数组元素字段"
        "deptname": "data.data#name"
      }
    ]
  }
}

路径语法：
- .（点号）= JSON 层级下降。data.total 表示 response.data.total
- #（井号）= 数组中的每个元素。data.data#code 表示 response.data.data 数组中每个元素的 code 字段
- 禁止使用 data[0].code 这种下标写法，统一用 data#code

完整示例：拉取部门列表

接口地址：/api/department/getDepartmentList?pageNo=${pageNo}&pageSize=${pageSize}&access_token=${token}
请求方式：POST
返回内容：
{
  "msg": "message",
  "ret": "code",
  "data": {
    "count": "data.total",
    "items": [
      {
        "deptnumber": "data.data#code",
        "deptname": "data.data#name",
        "parentnumber": "data.data#parentCode"
      }
    ]
  }
}

完整示例：拉取人员列表

接口地址：/api/person/getPersonList?pageNo=${pageNo}&pageSize=${pageSize}&access_token=${token}
请求方式：POST
返回内容：
{
  "msg": "message",
  "ret": "code",
  "data": {
    "count": "data.total",
    "items": [
      {
        "pin": "data.data#pin",
        "name": "data.data#name",
        "deptCode": "data.data#deptCode",
        "cardNo": "data.data#cardNo",
        "gender": "data.data#gender",
        "personPhoto": "data.data#personPhoto"
      }
    ]
  }
}

> 注意：items 内的左侧字段名（如 pin、name）必须是上方 业务对象与字段映射 中定义的标准字段名。

场景 3：数据库推送配置

适用条件

万傲瑞达作为数据源，直接向第三方数据库写入数据（第三方无 API 但开放数据库访问）。

服务配置参数

必须点击"测试连接"验证通过。

SQL 编写规则

使用内置变量代替 SQL 关键字：

类型规则： 字符串类型变量用单引号 '${var}'，数字类型变量不用引号 ${var}。

完整示例：人员新增推送

业务对象：人员
接口操作：新增
SQL：
${add} INTO pers_person (id, pin, name, last_name, gender, car_plate, photo_path, dept_code)
VALUES ('${id}', '${pin}', '${name}', '${lastName}', '${gender}', '${carPlate}', '${photoPath}', '109999');

完整示例：人员编辑推送

业务对象：人员
接口操作：编辑
SQL：
${modify} pers_person
SET name = '${name}',
    gender = '${gender}'
WHERE pin = '${pin}';

完整示例：生物模板新增推送

业务对象：生物模板
接口操作：新增
SQL：
${add} INTO pers_biotemplate (id, person_pin, version, template, template_no, template_no_index, duress)
VALUES ('${id}', '${personPin}', '${version}', '${template}', '${templateNo}', ${templateNoIndex}, ${duress});

场景 4：数据库拉取配置

适用条件

万傲瑞达作为接收方，从第三方数据库读取数据（第三方无 API 但开放数据库访问）。

与推送的关键区别

服务类型选 拉取，SQL 使用 ${search} 代表 SELECT，AS 后的别名必须是 业务对象与字段映射 中定义的标准字段名。

完整示例：部门拉取

${search} t.code as code, t.name as name, p.code as parentCode
FROM auth_department t
LEFT JOIN auth_department p ON t.parent_code = p.code

完整示例：人员拉取

${search} t.id AS id, t.pin AS pin, t.name AS name,
t.last_name AS lastName, t.gender AS gender,
t.dept_code AS deptCode, t.card_no AS cardNo
FROM pers_person t

分页说明

数据库拉取默认分页，自带变量：
- ${pageNo} — 当前页码（从 1 开始）
- ${pageSize} — 每页大小（默认 800）

在 SQL 末尾按数据库语法添加 LIMIT ${pageSize} OFFSET (${pageNo} - 1) * ${pageSize} 即可实现分页。

内置变量与方法速查

内置全局变量（数据库 SQL 用）

内置加密/格式化方法

内置局部变量

门禁/考勤数据过滤

适用条件

仅当业务对象选择 门禁事件记录 或 考勤记录 时可用。

作用

只推送满足条件的数据，不满足规则的忽略。

语法规则

仅允许：参数名、参数值、In、NotIn、(、)、AND、OR
- 参数之间用 逗号 分隔
- 参数之间 不允许有空格
- 大小写敏感

示例

(pinNotIn(1,2,3) AND devSnIn(aa,bb)) OR devSnIn(cc,dd)

含义：设备 SN 为 cc/dd 的数据推送 或 设备 SN 为 aa/bb 且人员 PIN 不是 1/2/3 的数据推送。

支持的过滤参数

返回码配置

作用

将第三方 API 的返回状态码标记为"正常"或"异常"等级。标记为"异常"的返回码会触发自动重试机制。

配置

重试行为

当接口返回异常码时，系统持续重试该条数据：
1. 直到接口返回非异常码（即请求被正确处理）
2. 或 该返回码的等级被人为改为"正常"（系统跳过该数据）

第三方建表脚本

当第三方需要新建数据库表接收万傲数据时，本技能 bundling 了 3 种数据库的完整建表 DDL。

包含的 9 张表： auth_area / auth_department / pers_person / pers_position / pers_card / pers_biophoto / pers_biotemplate / acc_transaction / att_transaction

脚本位置： references/ 目录

脚本文件内容包含完整的 CREATE TABLE 语句、主键约束、字段注释（中文），可直接在对应数据库中执行。

配置脚本导入导出

用途

系统重装、环境迁移、版本升级时的配置恢复。

三张配置表

导入步骤

1. 先导入 intg_servername
2. 再导入 intg_base_server
3. 最后导入 intg_base_server_info

已知问题

导入后页面打开报错 → 大概率是密码不匹配。将 intg_base_server_info.sql 中的密码字段值改为 NULL 后重新导入即可。

故障排查清单

按优先级依次排查：

体系文件索引

协议对接/数据集成/
├── v6600-data-integration.zip           # 本技能的可分发 ZIP 包
├── 数据集成对接详细指南.md               # 完整字段映射表和详细示例（17 章）

006培训资料/2、V6600各模块讲解/数据集成/
├── 万傲瑞达-数据集成-2026.5.pptx        # 培训 PPT（业务背景）
├── 集成模块操作手册.docx                 # 官方操作手册（界面截图）
└── 软件配置&数据库创建脚本/
    ├── 第三方数据库表语句/                # 建表脚本（3种数据库）
    └── 软件配置脚本/                     # 示例配置数据（导入用）

📞 帮助与支持

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