附录 B　接口与数据清单

明·如归 · 宿舍管理白皮书 ｜ 附录

说明：本清单如实披露接口层与数据层的分块口径与总量。所有数字都是 2026-09-21 当日实测，代码库继续演进的以最新一次统计为准。统计一律排除 bin/ obj/ node_modules/ dist/ 目录。

B.1 后端接口层

总量：71 个控制器 · 795 个端点。

• 端点计数方式：按网络接口方法特性声明（HttpGet / HttpPost / HttpPut / HttpDelete / HttpPatch）逐条计数；不是"业务动作数"，也不是"URL 去重数"。同一 URL 前缀下的 GET 列表、GET 详情、POST 新增、PUT 更新、DELETE 删除分别计 5 条。
• 控制器计数方式：按后端控制器目录里的 *.cs 文件计；不含实时通道目录里的两个通道集线器（另算 2 个）。
• 不构成"纯后台数"：管理端与教师端与学生端与移动端共用同一后端，端点里包含所有前端消费的接口。

按模块分布（每模块一个或多个控制器）：

模块	控制器	主要端点范围
住宿资源	4 个	建筑、楼层、房间、床位、户型、物资、收费
住宿分配	5 个	分配、批次、床位视图、变更记录、统计
新入住预分配	2 个	批次管理、规则配置、五步流程、智能预排
人员信息	3 个	学生、教师、账号、历史人员
外出与请假	1 个	请假申请、销假、审批链
在住与考勤	3 个	考勤日志、自动考勤、假日与考勤日型
住宿变更	1 个	调宿申请、退住办理、走读
检查与评级	3 个	检查记录、评分、星级、奖惩
设施服务	3 个	设备台账、报修工单、评价
通知公告	1 个	消息管理、订阅、公告
系统与配置	6 个	学校组织、字典、枚举、字段元数据、菜单权限、角色
治理与判断	4 个	质量规则、问题工作台、归寝异常、审计日志
集成与开放	4 个	连接器、开放接口客户端、事件回调、地图配置
定时任务与调度	1 个	处理器目录、执行历史、手动执行
统计与大屏	3 个	概览、趋势、下钻、大屏聚合
报告与导出	2 个	报表、异步导出、字段清单
一人一档与画像	2 个	360 画像、住宿履历
其他	与上合并计入	应急联系人、假单、暂不考勤、认证

合计 71 控制器 · 795 端点。任何单一投标承诺里出现"某某接口"必须能指到具体控制器与端点名。

B.2 实时推送通道

2 个 Hub：

• 通知 Hub：站内信、预警告警、系统公告的实时送达。
• 大屏 Hub：定时推送统计口径到实时的可视化界面。

边界：两条实时通道是本系统内的即时消息通道，不承诺微信/企业微信消息推送、短信、邮件——那些通道在通道注册接口上标记为"预留未启用"。

B.3 前端页面

总量：四端合计 139 个页面。

• 管理端（100 页）：住宿资源、住宿分配、预分配、人员、请假、考勤、变更、评级、设施、通知、系统配置、治理工作台、开放接口、日志审计、地图、字段元数据、大屏。
• 移动端（20 页）：我的宿舍、打卡、考勤、请假、调宿、报修、评价、消息、画像。
• 教师端（9 页）：工作台、在住登记、巡查、审批、评分、统计、报修审批、人员查询、预警。
• 学生端（7 页）：我的住宿、我的登记、外出申请、住宿调整、服务评价、消息、画像。
• 通用页（3 页）：登录、403、404。

统计方式：按前端 src/views/**/*.vue 匹配计。组件文件（src/components/）与布局文件（src/layouts/）不入这 139 页。

B.4 数据层

• 业务实体：91 个（表前缀 app_）。口径为数据上下文里的实体集合声明去重。
• 业务管理器：111 个（含成员相关 7 个）。口径为 Domain/Managers/ 实测。
• 数据模型与传输对象文件：115 个。口径为 Domain/Models/ 实测。
• 幂等迁移脚本：18 个。口径为 Domain/Migrations/*.sql 实测。启动时自动按序执行。
• 权限码：后端在用的去重 55 个；菜单权限目录收录 57 项。前者是实际拦截值、后者是目录展示值。

边界与不做：

• 字段级加密：当前仅覆盖口令与最小必要项；扩面按投产前批次推进。禁写"字段级全面加密"。
• 增量同步：当前实现为按锚点全量比对、幂等复跑。禁写"实时增量"；时间戳与游标列按批次补齐。
• 设备侧数据：只接受设备识别结果作为考勤来源之一；不写设备侧算法与识别精度。

B.5 集成连接器与外部接口

5 个连接器：

连接器	用途	依赖
通用接口门禁	对接符合通用网络协议的门禁设备	设备侧接口文档
海康威视 ISAPI	海康设备的事件订阅与日志拉取	设备凭据与网络可达
OIDC 身份	学校统一身份 OpenID Connect	学校身份源端点与客户端凭据
CAS 身份	学校统一身份 CAS 票据	学校 CAS 服务端
教务学籍同步	学生、教师、组织架构定时拉取	教务源接口与查询权限

事件回调派发：带哈希签名，接收端可验证真实来源；派发失败进重试与执行历史。

地图服务 5 家：OpenStreetMap、CARTO 内置不可删；天地图、高德、百度由管理员配钥；同时仅一家启用；WGS84/GCJ02/BD09 三套坐标互转。

B.6 智能化能力接口

大模型四出口（当前为确定性测试桩，真实模型接入按投产前批次）：

出口	输入	输出
分配解释	一次预排的输入参数与结果摘要	自然语言解释
约束式自然语言查询	一句自然语言	结构化查询条件（人工点击执行才跑）
问数	一句问句	只读查询结果（三把白名单：异常、质量、住宿）
周报草稿	一周的告警与处理数据	结构化摘要（发布前人工确认）

共同纪律：模型只出建议、不执行操作；操作由人点击确认触发；每一次触发留审计。

B.7 政策与合规可核验清单

政策原文名与文号的引用规范见附录 D。本附录仅列接口与数据层能直接对应到政策要求的三条：

• 数据分类分级：三级分层、四类脱敏、字段级加密（按批次）、导出留痕。
• 个人信息保护：默认脱敏、显式查看才还原、每次还原入操作日志；导出走权限校验、字段清单与行数留痕。
• 安全生产留痕：操作日志带执行者、时刻、目标记录、字段前后快照；导出可回查"谁在什么时候拿过什么"。

任何一条超出接口与数据层的能力承诺，都应在合同上写清由谁负责、什么时候交付、按什么标准验收——不写在合同上就是不做。

B.8 端点计量的三条口径纪律

795 端点这个数字看起来直接、但同一套代码在不同统计口径下会得到不同数字。附录里的这个数字遵守三条纪律：

纪律一：按方法特性逐条计、不按 URL 去重。同一个 /api/student 前缀下、GET 列表、GET 详情、POST 新增、PUT 更新、DELETE 删除分别计 5 条端点。有的厂商按 URL 去重把 5 条算作 1 条、报出"我们只有 160 个 URL"——这个数字看起来少、实际上代码规模一样。学校评估时统一按方法特性逐条计。

纪律二：不含实时通道、不含内部工具接口。两个实时通道集线器（消息中心、大屏推送）不计入 795；数据同步工具接口、健康检查接口、调试接口不计入 795。795 只算业务读写接口。

纪律三：不含前端组件接口。前端框架内部使用的下拉数据源、字典查询、日期选择器接口、通用组件调用接口不计入 795。795 只算业务侧真实功能接口。

这三条纪律在附录 A/B/C 全表通用。如果一份白皮书里的"1000 端点"、"200 页面"没写清口径、这个数字没有意义。

B.9 三条关于接口清单的常见误解

误解一：端点越多系统越强。恰恰相反——端点越多意味着前端调用越复杂、维护成本越高。同一件事用一个组合端点做完、和用五个原子端点串起来做完、从用户角度是一件事、从维护角度是五倍工作量。健康的端点数量是"每一个端点都能明确对应一个业务动作"——不是越多越好、也不是越少越好。

误解二：连接器 5 个不够。5 个连接器是已实证的——每一所学校的实际接入都需要在这个框架下扩展具体设备与厂商。"5 个连接器"是产品框架、不是覆盖上限。学校评估时不要问"你们能不能接 XX 品牌门禁"、要问"你们接一个新品牌的实施工作量是多少"——答案是"配置字段映射 + 测试连接"就通过、答案是"要改代码"就不通过。

误解三：139 页 = 用户能看到的界面。139 页包括管理端 100 + 移动端 20 + 教师端 9 + 学生端 7 + 通用 3。管理端 100 页里有大量配置页与查询页、真正高频操作的页面在 20 个以内。学校培训时按高频页面优先、不要指望宿管一次学完 100 页。

这份清单不是使用说明书，是给评审、监理、审计留的对账工具。