索引映射与交付批次

明·如归 · 宿舍管理白皮书 ｜ 第九篇 全典篇

前三章按"能力/数据/智能化"三个视角横切了一遍。现在换一个视角——按交付批次纵切：每一项能力属于四档里的哪一档：已交付、在建、按批次、依赖外部。学校选型时最关心的不是"你能做什么"，是"你什么时候能给我、我要不要等、我要不要自己凑齐一些前置条件"。

45.1 四档口径的定义

档	含义	学校侧要做什么
已交付	代码在生产环境跑着、有实证、当场可演示	直接用
在建	设计已定、代码部分实现、当前实例可预览	关注下一批发布时间；不要按已投产签合同
按批次	接口/管道已经留好、真实实现待补	与供应商约定补齐时点，进合同
依赖外部	需要外部条件（设备、身份源、政策落地）配合	学校侧准备好外部条件；本系统只负责接入

四档不是"成熟度打分"，是"责任划分"。已交付是本系统负责；在建/按批次是本系统按约定负责；依赖外部是学校侧和本系统共同负责——设备厂商、教务系统、网络与证书环境，任何一环没到位，本系统就只能显示"来源未接入"。

45.2 功能 → 控制器 → 页面：三向映射示例

系统总计 71 个控制器、139 个前端页面。全量映射清单在附录 A/B；这里给几个典型样例说明"三向映射"是怎么用的。

样例 1 · 归寝异常预警：

• 功能：夜间扫描 → 三检测器 → 问题工作台 → 站内警报 + 事件回调。
• 后端：一个专门的控制面 + 一个定时任务处理器 + 一个归寝异常扫描服务 + 一个预警数据模型。
• 前端：管理员异常工作台、教师端预警列表、大屏预警计数。
• 档：已交付（三检测器与规则口径 44.1 节已列）。

样例 2 · 智能预排：

• 功能：按批次参数（六项混编开关、四项预分配比例）跑一次预排 → 出预览。
• 后端：一个预览控制器 + 一个智能预排管理器 + 一个分配求解器（三条硬不变量 + 两类软约束）。
• 前端：新入住预分配向导、预览明细页（未名单/原因/评分回放）。
• 档：已交付（只读预览）；落库通道继续走既有分配接口——不写"一键投产"。

样例 3 · 大模型自然语言查询：

• 功能：管理员输入一句话 → 转成结构化查询条件 → 点击执行才跑。
• 后端：治理助手控制器 · 三把只读白名单（异常/质量/住宿）· 语言模型接口桩。
• 前端：治理工作台问数入口。
• 档：按批次（接口在、模型待接、白名单已投产）。合同上不能承诺"上线即可对话问数"。

样例 4 · 人脸考勤：

• 功能：设备侧完成识别，本系统只接受"某某时刻某某人从某某门进来"的事实作为考勤来源之一。
• 后端：设备同步后台服务 + 门禁日志入库。
• 前端：管理员考勤日志列表带"来源"字段。
• 档：依赖外部（厂商算法与设备不在本系统能力范围）。禁写"自研人脸算法""无感通行分析"——这是外部条件，不是本系统的判断能力。

45.3 交付批次推荐时序

不同规模学校的批次时序不一样。以下是一个通用推荐：

批次	覆盖模块	前置条件	学校侧投入
P1 · 底座	住宿资源、人员信息、系统配置、字典与元数据、迁移工具	组织架构与人员花名册到位	数据治理一个月
P2 · 日常运转	分配、在住登记、外出申请、住宿变更、通知公告	P1 完成 + 考勤时间窗和假日校历定稿	制度定稿两周
P3 · 治理与判断	质量五规则、问题工作台、操作日志、开放接口、三定时任务	P2 稳定运行一个学期	认领会主排到位
P4 · 智能化	归寝异常三检测器、智能预排、实时大屏、360 画像	P3 完成	参数调优一个月
P5 · 外部接入	五连接器（门禁、身份、教务）、地图配置、字段级加密扩面	学校侧配套设备/身份源/教务接口	视外部条件而定
P6 · 模型接入	大模型四出口真实化	P4 完成 + 学校选定合规模型供应商	政策与合规审批

批次不是厂商路线图，是学校与供应商的合同节奏。每一批的验收口径都在正文前面章节已经写明——学校按合同条款逐项核验即可。没有 P1 数据治理打底，P4 的智能预排就是垃圾进垃圾出；没有 P3 的问题工作台，P4 的检测器就没人认领——批次顺序不能颠倒。

45.4 明确"按批次"、"在建"、"依赖外部"的清单

对照 TOC 3.1–3.6 的取证表，把不属于"已交付"的所有项集中在这一节：

按批次推进（接口和管道已就位，生产化按投产前批次补齐）：

• 邮件通道、短信通道、WebPush 通道（站内消息 + 实时推送已可用，其余三档接口预留）。
• 真实大模型接入（四出口共用单接口，桩已就位）。
• 字段级加密扩面（当前仅覆盖口令与最小必要项）。
• 时间戳/游标列的增量同步（当前只有按锚点全量对账）。

在建（部分实现，本实例可预览）：

• 数据同步连接器扩展（除已实证 5 个之外的通用协议）。
• 地图服务凭据管理界面完善（当前管理员可配钥；OpenStreetMap/CARTO 内置不可删）。

依赖外部（学校侧准备好前置条件，本系统只接入）：

• 门禁/闸机/人脸设备（厂商算法与设备运维不在本系统能力范围）。
• 教务系统接口（连接器只能对接已实证的通道，其他教务源需专项评估）。
• 学校统一身份认证（CAS/OIDC/企业微信/超星/微哨/为笑/DS7 已就位；其余按连接器框架扩展）。
• 局域网 IP 上的移动打卡必须走受信任 HTTPS；证书由学校或供应商配合准备，微信与企业微信不绕过安全来源限制。

明确不做：

• 自研人脸识别、活体检测、防替考级算法。
• 智能问答/对话式界面（当前只有大模型出口桩 + 白名单问数）。
• 无凭据可用的通用教务接口（不写"支持所有主流教务系统"）。

45.5 索引怎么用

评审、投标、内部合规检查的时候，拿着这个索引做三件事：

• 看功能对不对得上系统：附录 A 每一项功能都能指到具体的控制器和页面。投标承诺里出现"某某功能"却找不到对应控制器 → 立即降级表述。
• 看数字对不对得上口径：附录 B 每一个数字都能指到具体的统计方式。"795 端点"按网络接口特性计、"139 页面"按 views/**/*.vue 计——不按"纯后台数"引用。
• 看档对不对得上合同：任何"按批次""在建""依赖外部"的项目，合同上都要写清"到什么时候、由谁、按什么标准补齐"；不写在合同里就是不做。

索引映射不是给作者自查的，是给学校采购、监理、审计、评估留下的可对账接口。一本讲得再好的白皮书，如果最后不能落到"具体哪一行代码、哪一个页面、哪一份合同"，就还是营销材料。

45.6 三向映射的另外四个样例

前面 45.2 举了四个典型样例。为了说明"任何一项功能都能三向映射到具体实现"，这里再补四个：

样例 5 · 学生 360 画像：

• 功能：按学生 ID 一次拉出五维聚合（基本信息 / 考勤统计 / 住宿变更 / 请假 / 评分）。
• 后端：一个学生画像控制器 + 四个数据管理器（考勤、住宿、请假、评分）分别提供子集接口。
• 前端：管理员画像详情页 + 教师端受限画像 + 学生本人自助画像。
• 档：已交付（画像的五维构成、权限边界在第十六章详述）。

样例 6 · 操作日志与导出留痕：

• 功能：所有写操作与所有导出操作留日志，含操作者、时间、目标记录、字段清单、修改前值。
• 后端：操作日志管理器 + 数据层变更快照；导出接口在写入响应前先落一条日志。
• 前端：管理员操作日志查询页 + 按人 / 按时间 / 按操作类型三维筛选。
• 档：已交付（第十三章、第八章详述）。

样例 7 · 考勤日历五级判定：

• 功能：一个日期是不是"要考勤"取决于五级判定：学期范围 → 调休日 → 假日 → 周末 → 工作日。
• 后端：考勤日历服务 + 校历数据模型 + 调休数据模型；每天判定一次并缓存当日结果。
• 前端：校历管理页 + 调休管理页 + 移动端"今日是否考勤"显示。
• 档：已交付（第十章详述）。

样例 8 · 地图服务一家启用：

• 功能：五家地图中任意时刻只有一家启用，切换时其他自动停用；坐标系统一互转。
• 后端：地图服务配置控制器 + 五类服务商实现 + 坐标转换服务。
• 前端：管理员地图配置页（可配密钥、可测试连接、可切换启用）+ 前端底图组件。
• 档：已交付（第十七章详述；OpenStreetMap 与 CARTO 为内置不可删除的保底数据源）。

45.7 交付基线的量化清单

全书所有数字都锚定在下面这张表上。任何一处引用与这张表不一致，都应当以这张表为准修订：

维度	数量	计量口径
后端控制器	71	独立控制器类总数
后端接口端点	795	按网络接口方法特性计
后端数据管理器	111	提供读写与聚合的管理器类
后端数据实体	91	领域模型实体类
前端页面	139	按 views 目录下的页面组件计
后端权限码	55	独立权限枚举数
幂等迁移脚本	18	结构变更脚本数
定时任务处理器	3	自动考勤 / 质量扫描 / 归寝异常预警
数据质量规则	5	一人多占 / 性别不符 / 离校在住 / 证件校验位 / 通行无主
归寝异常检测器	3	连续未归 / 作息突变 / 同寝连带
数据连接器	5	通用接口门禁 / 海康设备 / 两种单点登录 / 教务同步
地图服务商	5	OpenStreetMap / CARTO / 天地图 / 高德 / 百度
认证链	12	本地口令 + 多种票据
大模型出口	4	分配解释 / 约束式查询 / 问数 / 周报草稿
实时推送通道	2	站内消息中心 + 移动端实时通知
后台服务	5	三个处理器 + 设备心跳 + 消息发布

每一项数字都可以在附录 A/B 找到具体清单——不接受厂商按"大约""差不多"回答。学校评估时把这张表打印出来、逐条对照问："你们的 55 个权限码是哪 55 个？你们的 3 个处理器分别在什么时刻跑？"能对答如流的、才是真做过。

45.8 三条关于交付批次的常见误解

误解一：所有批次可以同时启动。看起来系统所有能力都在、学校一次签全量合同最省事。实际上 P1 数据治理没做完就上 P4 智能预排，出来的分配结果一定被大面积人工推翻；P3 问题工作台没人认领就上 P4 检测器，预警生成一堆没人处理。批次顺序不是厂商路线图、是让学校每一步都能真正消化。

误解二：按批次 = 厂商拖延。恰恰相反——"按批次"是厂商诚实的表现。真实大模型接入、渠道扩展、字段级加密扩面——这些每一项都需要合规审批与外部条件，厂商写"已投产"才是把学校当傻子。合同上把每一批的补齐时点、验收标准、违约金写清楚、比"什么都有"更重要。

误解三：依赖外部 = 厂商推责。设备厂商的算法、教务的接口、学校统一身份、证书环境——这些确实不在宿舍系统范围内。承认边界不是推责、是让学校知道"我需要为这个能力自己准备什么"。一个把所有事情都答应下来、最后设备不通就把责任推给厂商的实施方、比一个明说"这一块学校自己准备"的实施方更危险。

下一章：术语与品牌口径——把这本书里所有反复出现的词做一次统一，避免"同一件事两个说法"造成的理解漂移。