增量同步

概念说明

名单规则版本号

version，名单规则版本号，是增量同步功能所依赖的用以计算变更集和判断是否需要进行同步的数据。

通行名单接口和通行规则接口都会返回对应通行名单/通行规则的版本号。

机具要实现增量同步时，需要在机具初始化全量同步名单和规则时，将版本号保存起来，用以后续的增量同步。

流程示意图

增量同步过程示例

机具初始化

假设机具初始化后，保存的版本号为8，同时通行名单和通行规则如下：

{
  "open": false,
  "users": [
    {
      "c": "12345678",
      "r": ["3tx", "d1"]
    },
    {
      "c": "abcdefgh",
      "r": ["d1"]
    }
  ],
  "rules": [
    {
      "mark": "3tx",
      "configs": [
        {
          "time_ranges": [
            {
              "start": "08:00:00",
              "end": "11:59:59"
            }
          ]
        }
      ]
    },
    {
      "mark": "d1",
      "configs": [
        {
          "time_ranges": [
            {
              "start": "12:00:00",
              "end": "23:59:59"
            }
          ]
        }
      ]
    }
  ],
  "version": 8
}

机具心跳

之后，机具通过心跳接口将机具保存的版本号信息8上报到门禁服务器。

当心跳接口中的返回信息告知机具需要拉取新的配置时，机具进入增量同步逻辑。否则重复心跳逻辑。

例如，返回数据如下，data.need_pull的值为true时，说明需要拉取新的名单规则。

{
  "code": 0,
  "message": "",
  "data": {
    "need_pull": true,
    "timestamp": 1608871415,
    "time": "2020-12-25T12:43:35+08:00"
  }
}

更新名单、规则以及版本号

机具调用拉取变更集接口，将机具保存的版本号信息作为参数，请求得到下一个版本的变更集和下一个版本的版本号。

TIP

当版本变更集过大时，机具可以分页处理变更集。

假设此时拉取变更集接口的返回结果为：

{
  "code": 0,
  "message": "",
  "data": {
    "diff": [
      {
        "t": 1,
        "cu": {
          "c": "123456789",
          "r": ["3tx"]
        }
      },
      {
        "t": 2,
        "cr": {
          "mark": "3tx",
          "configs": [
            {
              "time_ranges": [
                {
                  "start": "00:00:00",
                  "end": "23:59:59"
                }
              ],
              "months": [7, 8],
              "weekdays": [0]
            }
          ]
        }
      },
      {
        "t": 3,
        "du": "abcdefgh"
      },
      {
        "t": 4,
        "dr": "d1"
      }
    ],
    "open": false,
    "version": 9,
    "page": 1,
    "page_size": 20,
    "total": 4
  }
}

根据变更集的内容，按顺序处理变更项。

首先对应第一种变更项：

{
  "t": 1,
  "cu": {
    "c": "123456789",
    "r": ["3tx"]
  }
}

原有通行名单：

[
  {
    "c": "12345678",
    "r": ["3tx", "d1"]
  },
  {
    "c": "abcdefgh",
    "r": ["d1"]
  }
]

变为：

[
  {
    "c": "12345678",
    "r": ["3tx"] // ["3tx", "d1"] => ["3tx"]
  },
  {
    "c": "abcdefgh",
    "r": ["d1"]
  }
]

接着是第二种变更项：

{
  "t": 2,
  "cr": {
    "mark": "3tx",
    "configs": [
      {
        "time_ranges": [
          {
            "start": "00:00:00",
            "end": "23:59:59"
          }
        ],
        "months": [7, 8],
        "weekdays": [0]
      }
    ]
  }
}

原有规则列表：

[
  {
    "mark": "3tx",
    "configs": [
      {
        "time_ranges": [
          {
            "start": "08:00:00",
            "end": "11:59:59"
          }
        ]
      }
    ]
  },
  {
    "mark": "d1",
    "configs": [
      {
        "time_ranges": [
          {
            "start": "12:00:00",
            "end": "23:59:59"
          }
        ]
      }
    ]
  }
]

变为：

[
  {
    "mark": "3tx",
    "configs": [
      {
        "time_ranges": [
          {
            "start": "00:00:00",
            "end": "23:59:59"
          }
        ],
        "months": [7, 8],
        "weekdays": [0]
      }
    ] // 直接将对应的configs内容覆盖
  },
  {
    "mark": "d1",
    "configs": [
      {
        "time_ranges": [
          {
            "start": "12:00:00",
            "end": "23:59:59"
          }
        ]
      }
    ]
  }
]

之后是第三种变更项：

{
  "t": 3,
  "du": "abcdefgh"
}

原有通行名单：

[
  {
    "c": "12345678",
    "r": ["3tx"]
  },
  {
    "c": "abcdefgh",
    "r": ["d1"]
  }
]

变为：

[
  {
    "c": "12345678",
    "r": ["3tx"]
  }
  // 电子卡号（c值）为`abcdefgh`的名单被删除
]

然后是第四种变更项：

{
  "t": 4,
  "dr": "d1"
}

原有规则列表：

[
  {
    "mark": "3tx",
    "configs": [
      {
        "time_ranges": [
          {
            "start": "00:00:00",
            "end": "23:59:59"
          }
        ],
        "months": [7, 8],
        "weekdays": [0]
      }
    ]
  },
  {
    "mark": "d1",
    "configs": [
      {
        "time_ranges": [
          {
            "start": "12:00:00",
            "end": "23:59:59"
          }
        ]
      }
    ]
  }
]

变为：

[
  {
    "mark": "3tx",
    "configs": [
      {
        "time_ranges": [
          {
            "start": "00:00:00",
            "end": "23:59:59"
          }
        ],
        "months": [7, 8],
        "weekdays": [0]
      }
    ]
  }
  // mark为`d1`的规则被删除
]

最后机具将保存的开放通行/授权通行的值（open，见开放通行）进行更新。此处8版本中open值为false，新的版本中的open值也为false，不须更新。

处理完所有的变更项之后，机具保存的名单和规则即为新的版本（版本号9），机具需要将新的版本号保存起来，重新进入心跳逻辑中。此时机具保存的配置如下：

{
  "open": false,
  "users": [
    {
      "c": "12345678",
      "r": ["3tx"]
    }
  ],
  "rules": [
    {
      "mark": "3tx",
      "configs": [
        {
          "time_ranges": [
            {
              "start": "00:00:00",
              "end": "23:59:59"
            }
          ],
          "months": [7, 8],
          "weekdays": [0]
        }
      ]
    }
  ],
  "version": 9
}