all-project/docs/开发文档/API/宿舍点名假期留宿标识说明.md

宿舍点名 · 假期留宿标识说明

背景

宿舍点名原先仅对「当前有效请假」自动标识为请假（状态 1，不可修改）。
已通过审批且仍在留宿日期内的学生，点名界面会误显示为「在寝」。现已补充「假期留宿」标识与独立统计。

有效留宿判定（后端统一）

接口：getRoomStudents 在返回学生信息时附加 leaveInfo / holidayStayInfo（可同时返回）。

条件（假期留宿）：

1. apply_status = '2'（已通过）
2. 检查时刻落在 [apply_start_date, apply_end_date]（按 datetime 比较，与请假一致，含边界）
3. 同一学生多条记录时取最新一条

例：留宿结束为 2026-10-25 08:00:00，则 25 日 21 点宿舍点名不再显示「假期留宿」，恢复默认「在寝」。

若同一学生当前既有有效请假又有有效假期留宿：点名页同时展示两个标签；落库主状态仍为请假（1），并同时写入 leave_* 与 holiday_* 字段；今日汇总两类明细均可计入该生。

假期结束后，接口不再返回 holidayStayInfo，前端恢复默认「在寝」可切换。

变更说明（2026-10-26）：

1. 原先按「结束日当天整天有效」判定 → 已改为按时刻判定。
2. 原先请假优先时不返回假期留宿 → 已改为两者可同时展示。

点名状态字典 xg_dorm_roll_call_status

值	含义
0	在寝
1	请假
2	不在
3	空床位
4	假期留宿

统计字段

主表 xg_dorm_roll_call.holiday_stay_count：本房间假期留宿人数。
明细可存 holiday_stay_id / holiday_type / holiday_start_date / holiday_end_date。

交互

与请假一致：自动标为假期留宿后不可修改。

库表脚本

backend/script/sql/update/update_20261020_dorm_roll_call_holiday_stay.sql

部署时需先执行该脚本，再发布后端与前端。

当天点名人数汇总（移动端）

接口：GET /dormRollCall/dormRollCall/todaySummary?buildingId=（buildingId 可选）
权限：dormRollCall:dormRollCall:list1

口径（2026-10-21）：

字段	含义
totalStudentCount	总人数：xg_dorm_bed_student 中 status=0 且有床位、有学生的在住人数
checkedStudentCount	已点名人数：本日各寝室最新点名明细中有学生记录的去重人数
leaveCount / holidayStayCount / absentCount	最新明细状态 1 / 4 / 2，并返回对应 *Details 名单

范围：

• 不传 buildingId：全校（列表页「今日点名汇总」）
• 传 buildingId：指定楼栋（点名选房页红圈统计；请假/留宿/异常可点开本楼名单）

移动端刷新：列表页 onShow/筛选；选房页加载房间、单间点名提交后刷新本楼汇总。