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

## 背景

宿舍点名原先仅对「当前有效请假」自动标识为请假（状态 `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`/筛选；选房页加载房间、单间点名提交后刷新本楼汇总。