学生管理系统功能规划

教务与学生系统的边界

教务系统已承担排课、成绩、课堂考勤；其学生档案不开放在线改档。学生管理系统独立建站、独立数据库，承担学工可维护的档案及住校、通行、家校等模块。小程序合为一个入口，后台与数据必须分开。

校园里两套系统、一个入口、两类设备如何接在一起

下图是功能规划的总关系：小程序只做入口；教务与学生系统按域提供功能；闸机和摄像头只挂在学生系统上。箭头表示功能依赖或数据方向，不是页面跳转。

学生系统按 5 组功能建设，小程序与 PC 共用这套模块

分组是规划结构，不是五个独立产品。学生档案是主数据，其余模块都挂在学号上。教务侧已有模块不在学生系统里重做，只读调用。

学生系统内部：以档案为中心，通行、住校、事务互相引用

下图只画学生系统内部。实线是主数据引用，虚线是状态联动（例如假已批，则查寝自动记请假、闸机允许离校）。

关键联动规则

同一功能，按角色裁剪；教师与学生菜单必须分开

小程序一个，底栏两套。家长第三套身份，不与教师共用登录。下图是功能对角色的可见性，不是操作说明书。

教师登录仍走教务账号，再换学生系统教师令牌。学生、家长只持学生系统令牌。小程序内：点「课表 / 点名」请求教务；点「查寝 / 报修 / 人脸」请求学生系统。

字段级归属，避免两本花名册

在现有教务和小程序上扩展，不另起一套入口

教务已经是 ASP.NET Core 8 + SQL Server，微信小程序也已经同时连学生端接口（默认 5001）和教务接口（默认 5002）。学生管理系统沿用同一技术栈：独立站点、独立数据库 StudentSystem，小程序继续用现有 AppID，按角色切换页面和接口。

技术选型

和小程序、教务的请求关系

微信小程序（同一 AppID）
  ├─ 学生登录  POST {STUDENT_API}/auth/login          → 学生 JWT
  ├─ 教师登录  POST {EDU_API}/auth/login               → 教务 JWT
  ├─ 教师换票  POST {STUDENT_API}/auth/from-edu        → 学生系统教师 JWT
  ├─ 家长登录  POST {STUDENT_API}/auth/wx-parent       → 家长 JWT（openid 绑学号）
  │
  ├─ 课表/成绩/课堂点名/教学材料/教师测评  → EDU_API 或经学生系统只读代理
  └─ 宿舍/报修/人脸/请假/查寝/评分/相册   → STUDENT_API

学生系统 ──同步──▶ 教务 POST /api/student/sync   （已有，请求头 X-Sync-Key）
学生系统 ──通知──▶ 教务请假/考勤写入接口
教务只读 API ──拉取──▶ 学生系统（班级、课表、成绩，避免再跨库直连）

接口、表结构、同步、设备和权限怎么落地

1. 先收口现状：学生系统不再跨库写教务

当前学生端部分模块（考勤、教学材料、质量考评）是直接查 EduSystem_DB。这样短期能出功能，但把两套系统焊在同一台库上，独立部署和权限都做不干净。目标形态：

• 教务开放只读查询接口（课表、成绩、课堂出勤、班级名单）。
• 学生系统用后台任务增量拉取，或小程序按页直调教务（已有教师端做法）。
• 写操作一律走教务公开 API：档案回写用已有 POST /api/student/sync；请假用考勤请假接口。学生系统不直接 INSERT/UPDATE 教务表。

2. 学生系统核心表（独立库）

3. 和教务的同步协议

学号是两边唯一业务键。同步分三条通道，都走 HTTPS，服务账号鉴权，不允许小程序直调同步接口。

# 档案回写（已有能力上收口字段）
POST /api/student/sync
X-Sync-Key: ***
{
  "tenantId": 2,
  "items": [
    { "studentCode": "PZ20260101", "studentName": "…", "className": "…", "phone": "…" }
  ]
}

# 设备回传（学生系统新增，闸机/摄像头共用）
POST /api/device/v1/events
Authorization: Bearer {device_token}
{
  "deviceId": "GATE-01",
  "type": "face_pass",          // 或 camera_seen
  "direction": "in",
  "occurredAt": "2026-09-01T07:12:03+08:00",
  "personNo": "PZ20260101",
  "success": true,
  "offlineSeq": 1288
}

4. 小程序：一个程序，三套身份，两套令牌

1. 登录页先选身份。学生走学生系统登录；教师走教务登录，成功后再换学生系统教师令牌，本地同时存两套 token。
2. 请求封装：eduRequest 自动带教务 JWT 和 tenantId；stuRequest 自动带学生系统 JWT。页面禁止裸写域名。
3. 底栏按角色动态配置（现有教师端已是独立 tabBar）。学生底栏：首页、课表、生活、消息、我的。教师底栏：点名、班级、审批、查寝、我的。家长无底栏杂项，首页即孩子动态。
4. 人脸录入用小程序相机，前端压缩后上传；服务端做人脸检测（是否有脸、是否过暗）。通过后进入教师审核，审核通过才进入下发队列。
5. 微信公众平台配置两个 request 合法域名（学生系统、教务）。订阅消息模板：到校、请假结果、报修完工。

5. 硬件：适配器 + 统一事件，业务不写厂家协议

闸机和摄像头品牌不同、接口不同。学生系统只实现一个设备网关：

• IAccessAdapter：下发/删除人脸、远程开门（若厂家支持）、查在线状态。
• ICameraAdapter：注册识别回调、拉取漏传。
• 厂家 HTTP、SDK 或 MQTT 都包在适配器里。第一期先接一家闸机，摄像头用同一事件模型后插。
• 设备账号按台签发 token，只能 POST 事件，不能读学生档案。
• 断网：设备本地队列用 offlineSeq 幂等写入，网关按设备号+序号去重。
• 心跳超过阈值，PC 统计页标红。查寝不依赖摄像头一定在线，人工标注始终可用。

人脸下发流程：审核通过 → 写入 face_push_log → 后台任务按楼栋/校门分组推送 → 失败重试 → 仍失败则工单给管理员。学生退学或退宿，先收回闸机权限，再改在籍状态。

6. 权限与审计

所有写操作记审计日志（谁、何时、对哪条、改前改后）。人脸照片接口必须带令牌，禁止把存储路径暴露成公开 URL。

7. PC 统计如何算

今日在校：校门当日最后一次成功记录为“进”且未有对应“出”，再扣已批准的离校假。未归：查寝批次里状态为未归，或宿舍摄像头在规定时点后无进楼记录且无请假。报修、闸机失败按工单状态和事件 success=false 聚合。大屏 30 秒轮询即可，不必上消息总线。

按依赖关系排期，硬件可以后接，人脸不用重录

软件先把身份、宿舍、请假和同步跑通。闸机、摄像头接上后，已审核人脸从同一张表下发，不必重新采集。

每期验收标准

全程约束

• 页面简洁：学生底栏不超过 5 个；教师打开后换成教师底栏，不和学生共用一个菜单。
• 数据完整：每件事留下谁、什么时候、结果是什么；同步失败进发件箱而不是静默丢。
• 使用便利：能在手机办的不要求回办公室；人脸允许随时拍。
• 系统分开：学生系统独立建站、独立存数据；小程序可以合，接口按域调用。