门禁系统集成开发

项目背景

这是一套门禁与企业办公平台的集成实现，1 个仓库，使用 TypeScript 编写并配套 Docker 容器化部署。系统打通人脸门禁设备与企业办公平台，覆盖组织架构同步、人脸下发与通行记录回流三条链路。

客户当时的状态

门禁系统单独用的时候问题不大，一旦要和办公平台打通，难点就转移到第三方限制上。办公平台的接口有权限范围和调用频率约束，人员数据不能想拉就拉、想拉多少拉多少，集成方案必须在这些约束内成立。另一头是设备：门禁设备所在位置的网络与供电条件不一定稳定，人脸下发失败并不罕见，如果失败就停在那里，平台侧显示「已下发」而设备侧其实没有，问题会一直藏着。通行记录回到平台之后如果和人员信息对不上，数据也就没有使用价值。

我们的做法与取舍

第一个取舍是组织架构以办公平台为唯一来源，门禁侧不单独维护一份人员名单。代价是同步必须稳定，收益是人员变动不会两边不一致——在门禁场景里，不一致等于安全漏洞。

第二个取舍是把失败重试和幂等处理放在核心位置。下发失败要能重试，重复请求不能变成重复写入。设备侧的不稳定是常态，把常态当异常处理，系统就永远需要人盯着。

第三个取舍是在第三方平台的约束内设计同步节奏，而不是想办法绕过限制。调用频率受限就调整同步方式，按平台开放的能力实现。

系统怎么承载这条链路

平台对接层与企业办公平台交互，获取组织架构与人员信息，并处理接口权限与频率约束；设备对接层负责人脸下发、结果回执与通行记录回流；数据与部署层保存人员对照关系与通行记录，并通过容器化方式部署。三条链路的异常都在各自层内处理。

交付状态与边界

仓库最近一次提交在 2026 年 7 月，处于维护状态。边界说明：门禁硬件设备的采购与安装由设备供应商负责，我们负责对接与数据链路；办公平台侧的功能定制不属于我们的范围，我们按平台开放能力集成，不改动平台自身；人脸数据的采集授权与合规告知由贵方在与员工约定的范围内完成，系统在授权范围内完成下发与回流。