附录 B　接口与数据清单

正文讲这套系统替学校办成了什么事，附录留下两组能被逐条核对的账：对外提供多少接口、数据从哪些口子进出。

这一段先说清统计口径，免得数字被误读：接口数按逐条登记的请求方法计数，按接口组所在文件归并；分块依据是目录位置，因此下面第一张表的"管理端"里同时包含了后台管理接口与挂在同一目录下的门户公开接口。所有合计与分块数字与全书基线表同源，不存在第二处取值。

B.1 接口规模与分布

分块	接口数	说明
管理端目录	842	后台管理接口，以及与后台同目录的门户与师生公开接口
移动端	160	全部挂在移动端路由前缀之下，凭学生或工作人员身份访问
学院端	55	经统一基类做组织授权范围过滤，无授权记录即为空集
合计	1057	三块相加即总数

一句实话：接口数量本身不是优势，多出来的接口往往是没人调用的历史包袱。这个数真正能说明的只有一件事——这个系统的业务面铺开过，不是演示型的壳子。

B.2 规模最大的接口组（二十组，合计 455）

下表列出接口数不少于十六个的组，其余长尾组合计 602 个。

接口组	数量	覆盖的业务动作
体检	58	排期、时段、号源、预约、结果录入、异常、通知、健康信息填报
新生名册	32	导入、扩展字段、分组隶属、检索、批量维护
批次与任务	29	批次增删改、任务装配、克隆、准备与授权连带
选宿	27	设施、配置、预选、正式选、记录、统计、资格校验
人员与账号	26	账号、身份、组织隶属、导入同步、锁定期限
缴费	25	收费项目、账单、实缴与减免、绿色通道、押金、贷款回执
宿舍	24	栋、层、房间、床位、户型、同步
移动端统计	22	学生与工作人员看到的进度与看板
身份验证	22	证件读取、号码比对、人像比对、结论与熔断、日志
学院端工作台	20	首屏四卡、报到趋势、本院待办
报表	19	各类汇总与明细报表
现场工作管理	18	工作分派、扫码核验、办理记录
学院端数据	17	本院新生、任务、统计的读取与导出
师生端新生办理	17	学生本人可见可办的动作
组织架构	17	五级组织的增删改查与同步
问卷	17	问卷、题目、发放、答卷、统计、匿名与积分
房间与床位	17	房间明细与床位状态
登录	16	账号登录、统一登录回执、令牌签发与刷新
来校行程	16	行程填报、时段统计、接站与车辆
站点配置	16	门户栏目、轮播、链接位

这二十组占了全部接口的四成余，其余六百余个散落在字典、图文、投票、标签、订单、保险、志愿者、主题、备份、日志、消息这些支撑性入口上。看接口分布比看功能清单更能看出一个系统的重心在哪：这里的重心明显在办理与数据进出，不在展示。

B.3 数据交换面

数据进出的口子是验收当天最容易出问题的地方，全部列出来。

交换动作	数量或形态	状态	边界
表格导入入口	16 个	已交付	逐个业务对象分别实现，新增一类对象的导入属于开发工作
导入错误回执	两套	已交付	一套带行号与原因，一套仅带行号；统一为在建项
进门校验	必填、类型、字典格式	已交付	值域强制收敛按批次；字典字段格式校验未全部接入线上入口
导出端点	44 个	已交付	字段列由采集字典动态列举，加一列即多一列
异步导出	排队、状态可查、临时文件十二小时后连记录一并清理	已交付	大表走这条路
同步直接下载	不落任务记录	已交付	小表用这条路，因此"每一次导出都有记录"这句话现在只能说一半
导出审批、水印、用途登记	—	按批次	四件套未到位
外部来源直连	四类	已交付	只允许查询语句且禁分号；连接超时三十秒；映射为空时按别名直通
定时同步	可配周期	已交付	同步前有防误清保护
去重合并	按唯一编号，多源定主源优先	已交付	去重键不是证件号
批量作业监控	执行中、排队、完成、失败四数	已交付	单队列串行执行，超时十分钟终止

B.4 字段登记模板

字段清单不该只有程序看，得有一张学校签过字的登记表。下面是一份最小可用样张，前五行按本系统现有字段填实，最后一行故意留空示意。

字段	来源	是否必填	合法取值	敏感级别	出门须审批	责任人
学号	校方名册同步	是	全校唯一，不含空格	内部	否	学籍管理岗
姓名	校方名册同步	是	与名册一致	内部	是	学籍管理岗
证件号	校方名册同步	是	十八位，末位可为字母	敏感	是	信息部门
手机号	学生自填	是	十一位数字	敏感	是	学工办
住宿或走读	学生自填	是	二选一	内部	否	宿管
（留空行，由学校按校本字段续填）

三条填写纪律：

• 合法取值那一列必须写死。 现在最容易出错的地方是同一个字段在上游有四种写法，进门时没归一，出口处按四种写法各算一次。
• 敏感级别与"出门须审批"两列必须由学校签字。 分级这件事，厂商定的级别不算数，因为数据的责任主体是学校。
• 责任人一列不能空。 填不出责任人的字段，说明它没有业务归属，应当删掉。

B.5 口径速查

同样是"率"，分母不同就不是同一个指标。这张表把最容易打架的五条固定下来。

指标	分子	分母	量纲	现在能不能算
名册内报到完成率	已报到人数	已导入名册的应到人数	两种写法并存，须统一	能，但要先统一量纲
缴费率	已缴人数	名册总人数	百分数	能
宿舍分配率	已分配床位人数	名册总人数	百分数	能
体检完成率	已体检人数	名册总人数	百分数	能
任务完成率	该任务已完成人数	该任务应完成人数	小数	能，分组或前置限制时与上面四条分母不同
线上办结率	本人自助办结人数	名册总人数	百分数	算不出，无渠道列
录取报到率	报到人数	录取人数	百分数	算不出，系统内无录取与招生计划数据

一句提醒：界面上一处列名叫"招生数"，实际是已导入名册的人数。 汇报时把这一列念成招生规模，会被懂行的人当场问住。列名待改，改之前的正确说法是"名册人数"。

B.6 学校侧要准备的东西

这套系统开箱可用，但有三类事情必须在外部先落定，否则相应能力只能停在接口就绪的状态。

要准备的事项	由谁负责	提前多久启动	系统侧已就绪的部分
上游系统只读账号与视图	学校信息部门	数据接入联调前	四类来源直连、字段映射、调度、去重合并
短信或订阅消息签名与模板	学校与通道服务商	以通道审批周期为准	定向发放、逐人展开、模板占位与频控设计
统一登录平台的对接资料	学校与平台方	上线前一次联调	多家国内平台对接经验、账号映射与权限收敛
证件照或人像数据来源	学校招生或学籍部门	身份核验启用前	读取、比对、打分、熔断、留痕五段链路与替换接口
收银渠道与商户资质	学校财务	缴费上线前一到两个月	账单、分项、减免、凭证登记、对账口径导出
卡片系统与门禁设备	学校一卡通中心	领用环节启用前	任务类型与办理记录，卡片本身不归软件管
心理测评的量表与接手机制	学校心理中心	明确责任人之后再排期	入口外链与结果承接位；不自动预警
字段定级与指标口径的签字	学校分管校领导	第一批交付前	参考表、样张、填写纪律

B.7 保留与生命周期参数

数据留多久、临时东西多久清掉，这些都是要在验收材料里写死的数。

项目	现行取值	状态
每日全量备份	保留三十天	已交付
周期性基线快照	保留两份	已交付
恢复演练	还原到临时库比对表数与行数，用后即删	已交付
时点恢复的日志链	清理策略未落地	在建
异步导出临时文件与任务记录	十二小时清理	已交付
批量作业超时终止	十分钟	已交付
运行配置缓存	十分钟	已交付
界面主题下发缓存	三十分钟	已交付
身份核验防伪缓存	依赖有效期，非加密	事实边界
归档、保留期、去标识化、注销	尚无自动动作	按批次

最后一条是本附录里最该被问的一句：数据留到什么时候、由谁批准删除，现在靠学校的管理制度，不靠系统的自动机制。制度先行，系统才可能跟上。