设备通行与外部世界

明·如归 · 宿舍管理白皮书 ｜ 第三篇 数据篇

前面几章的数据都是系统自己长出来的——考勤是打卡打的、床位是分床分的、评分是检查查的。但宿舍不是孤岛。门口有闸机、楼里有门禁、地图要用外部服务、身份要接统一认证、数据要从教务同步——系统每时每刻都在和外部世界交换事实。面对外部世界、系统应该怎么接、怎么出、怎么在接和出之间不丢掉自己的判断力——这是数据篇最后一章的主题。

17.1 五类连接器：把外部事实接进来的五种姿势

系统里"外部世界"分五类、每类对应一种连接器：

17.1.1 通用接口连接器（门禁）

用途：任何厂商的门禁、闸机、人脸终端只要能通过标准接口推送结构化或表单格式的通行记录、都可以对接。

接入方式：管理员在系统里配一条通用接口连接器（目标地址、认证方式、字段映射）、厂商侧配一个"通行记录回调 URL"指向系统——设备一刷卡、通行事件就推过来。

这一类连接器不假设厂商是谁、只假设"你能发一个标准接口调用"。它是数据主权的关键一道门：厂商不用他们自己的管理软件、也能被系统接入。

17.1.2 海康设备协议连接器

用途：直连海康威视门禁设备、通过局域网设备协议拉取事件流。

接入方式：管理员配设备 IP、账号、口令——系统主动去拉设备的事件、而不是等设备推。

这一类连接器的价值：海康是高校宿舍最常见的门禁品牌、很多学校的存量设备就是海康的——这类连接器让存量设备不用换就能接入。

17.1.3 单点登录连接器（两种协议）

用途：让师生用学校统一身份登录宿舍系统、不再记一套密码。

两种协议：CAS 与 OIDC——两种都是高校常用的单点登录协议、覆盖 90% 的高校场景。

接入方式：管理员配授权端点、令牌端点、用户信息端点、字段映射、退出地址——测试连接通过后启用。

17.1.4 企业微信与微信连接器

用途：让师生用企业微信 / 微信身份登录、消息能推送到企业微信 / 服务号。

接入方式：管理员配企业 ID / 公众号 ID / 应用密钥——这些凭据全部落在服务器配置里、不进代码库、不进日志。

17.1.5 教务与学籍同步连接器

用途：定期从教务系统拉学生名单、班级、学院、学籍状态。

接入方式：定时任务 + 全量或增量接口 + 冲突处理策略——"以谁为准"由管理员在配置里决定（一般以教务为准、但宿舍端的字段如"床位号"以宿舍为准）。

这一类连接器接进来的是"人"的元数据、前四类接进来的是"事件"和"认证"。

17.2 设备接入的准则：把事实接进来、不替设备下结论

宿舍里可能出现的设备类型：门禁控制器、闸机、人脸识别终端、智能门锁。它们有一个共同特征：算法在设备端、系统只接收结果。一个人刷脸通过了、设备告诉系统"某人某时在某门进了"——系统不验是不是本人（那是设备侧的事）、不判是不是代刷（那是管理规则的事）。

"系统接受设备侧识别结果、不替设备下结论"——这句听上去有点保守的话、是设备接入最诚实的边界。把闸机厂商的识别率包装成自己的技术能力、出了事（误识或拒识）责任就说不清了。

已实证接入两条设备通道：

• 通用接口连接器（标准接口、任何厂商按规范推送通行记录即可对接）；
• 海康设备协议连接器（直连海康门禁设备、通过局域网协议拉取事件流）。

两条通道共用一套连接器框架：配置凭据、测试连接、拉取记录、写入考勤来源或设备事件表。其余厂商可按同一框架扩展、不需要改系统逻辑。

17.3 进来的每条记录先验归属

设备推来一条通行记录、上面可能带着卡号、学号、设备编号、时间戳。系统在入库之前做一件事：对人对床。

• 对：这条记录能匹配到哪个在住人员？
• 匹配上 → 写入设备事件表、可选作为考勤第五路来源；
• 匹配不上 → 落进"通行无主"质量规则、进问题工作台等人工处理。

"设备事实也要过治理的闸"是接入层和数据治理层的一条接缝。不验归属就入链、一个月后考勤表里会多出一堆"无主未归"——实际上人根本没来过、是设备推送了测试数据或旧卡号。

设备通道还带着心跳和日志同步：后台服务定时轮询设备状态、拉取增量通行日志。设备离线时系统不编造数据——这条来源自然为空、考勤的其他四路（学生打卡、宿舍长、宿管、自动）照常运转。

17.4 地图：一家启用、五家可选、坐标互转

宿舍管理里地图出现在两个场景：移动打卡的地理围栏判定（楼栋坐标 + 允许半径）、学生端的"我的宿舍在哪"导航可视化。

系统内置五家地图服务：

• OpenStreetMap 与 CARTO：内置不可删除的保底数据源、无需凭据即可显示底图；
• 天地图、高德、百度：管理员自行配置密钥后启用。

任何时刻只有一家地图服务处于启用状态——切一家另一家自动停用、不存在"同时用高德底图又用百度坐标"的混乱。

三家国内服务的坐标系各不相同（WGS84 / GCJ02 / BD09）、系统做坐标互转——从 A 服务拿到的坐标可以正确显示在 B 服务底图上、不会偏出几百米。移动打卡的地理围栏判定走统一坐标系、不管用户手机给的原始坐标来自哪家定位服务。

"一家启用"这条硬约束的价值：地图服务密钥是学校的敏感凭据、同时启用多家会出现"两个密钥都用过、都留下调用记录、泄露时不知道哪一家"的困境。一家启用把这个风险降到最小。

17.5 身份：十二种认证链、一套本地兜底

宿舍系统不应该让师生再记一套密码。系统里可选的认证链有 12 种：

• 本地口令：兜底、永远存在；
• 两种单点登录协议（CAS、OIDC）；
• 企业微信：账号 + 扫码 + 小程序三种入口；
• 微信：服务号 + 小程序两种入口；
• 几家主流校园 App 的票据体系：对接学校自己的移动门户；
• 短信验证码：口令找回和二次校验；
• 临时令牌：设备侧回调鉴权。

认证依赖第三方站点可用、但保底有本地口令入口——统一的身份、不统一的风险。学校统一认证挂了、宿管还能用本地口令进入系统处理应急事务；如果所有认证都依赖学校统一认证、学校一挂宿舍就成黑箱。

17.6 数据进出：两条通道、一套受管出口

• 数据出去走开放接口：第六章讲过、每第三方应用有独立凭据和限流、每条调用全量留痕；
• 数据进来走连接器：教务同步、设备通道、身份认证回调——都归连接器框架管。

"数据能出去"和"数据能被随便拿走"之间、隔的就是这一层受管出口。受管的三个含义：

• 可追溯：谁在什么时候拿了什么数据、都有记录；
• 可限流：单个应用超量拉数据会被临时禁用；
• 可撤销：一个应用不再需要访问、管理员一键禁用它的凭据。

17.7 外部世界的不可控与三条应对

闸机会坏、教务接口会改版、地图服务会限流——外部世界不总是配合的。系统的应对策略有三条：

17.7.1 降级不造假

地图服务不可用时显示空白底图加文字地址、不画一个假的位置点。门禁设备离线时考勤照常运转（少了那一路来源）、不补录假数据。企业微信推送失败时站内消息照常、外部通道留失败日志供重试。

17.7.2 留痕不猜测

通行记录时间戳和设备状态全部原样存储。设备推了个错误时间？存进去、标出来、让质量规则报。系统不在存储层"修正"外部数据——修正需要授权、修正的授权来自人工确认、不来自算法猜测。

17.7.3 测试连接是独立动作

管理员配了一个新的设备通道、第一步是点"测试连接"——通了再启用、不通不会误写入业务数据。这一条看起来简单、很多系统会忽略——"启用一个失败的连接器"是运维事故的高频起点。

17.8 三条关于外部接入的常见误解

误解一：接进来就是自己的。闸机推的通行记录、教务同步的学生信息——这些数据的"所有权"仍然在原系统。原系统改了口径、撤了接口、清了历史、宿舍端就要跟着变。"接进来"不等于"锁定了"——每次外部数据变动都要留一份快照、以便上游改口径时能追溯当时接的是什么。

误解二：外部服务越权威越好。学校统一身份、企业微信、国家地图服务——这些确实权威、但依赖它们的可用性就是把系统命脉交到别人手里。健康的做法是"外部为主 + 本地兜底"：认证依赖学校统一身份、但保留本地口令入口；地图用天地图、但内置 OpenStreetMap 保底。

误解三：一个接口通了就永远通。所有外部接口的可用性都是会变的。每个连接器都要有独立的"最后成功时间"和"最近一次失败原因"——这两个字段应该出现在管理员首页、不应该等到有人投诉才发现闸机已经三天没推数据。

17.9 一张表：外部接入能力清单

能力	当前状态	说明
通用接口门禁连接器	已投产	任何厂商按规范推送即可
海康设备协议连接器	已投产	直连设备、拉事件流
单点登录（两种协议）	已投产	CAS + OIDC
企业微信与微信认证	已投产	三入口企业微信、两入口微信
教务与学籍同步	已投产	定时 + 冲突处理
五家地图（一家启用）	已投产	保底 + 三家国内可配
十二种认证链 + 本地兜底	已投产	不锁死在外部
开放接口受管出口	已投产	独立凭据、限流、留痕
其余厂商设备扩展	按框架扩展	不改系统逻辑
数据修正回写上游	不做	只做只读接入、不改外部源

17.10 给学校的一件事

把你学校宿舍门口那台闸机（或门禁、人脸终端）的厂商叫来、问一句："你能不能用标准接口把通行记录推到我们的系统？"

• 如果他说能 —— 恭喜、不需要买他的管理软件、通用连接器就能收；
• 如果他说不能、必须用他的平台 —— 你面对的选择就清晰了：是要他的平台、还是要你的数据主权。

宿舍的数据不该锁在设备里。系统的责任是提供一条通道、让数据流向该流向的地方——然后替这笔数据守住归属和尊严。

数据篇到此结束。系统能做什么、数据怎么被对待、都已经摊开了。下一篇要谈的是更高一层的问题：攒够了数据之后、拿它做什么判断——智能化篇。