# 一年级宿舍「分配到班级」代理学院说明

## 业务规则

- 一年级班级的宿舍「分配到班级」由**人文学院**操作，即使班级真实归属其他学院。
- **不修改**班级/学生真实 `college_id`。
- 一年级床位须先在「分配到学院」分给人文学院，人文学院才能看到楼/房/床。
- 其他学院在「分配到班级」中**看不到也不可操作**一年级班级（防双头）。
- 一年级判定：班级表 `xg_class_msg.enrollment_year`，每年 **9 月 1 日**切届（与请假一致）。
- 配置键（复用请假）：`xg.studentLeave.freshmanProxyCollegeId`

## 实现要点

| 能力 | 说明 |
|------|------|
| 班级树主数据 | 以 `xg_class_msg` 为准；无住宿生的班级也出节点（需求人数可为 0） |
| 班级树 | `getCurrentUserStudentTree`：代理院=本院全部 ∪ 全校一年级；其它院=本院−一年级；配置缺失时按非代理处理并打 warn |
| 展示归属 | 使用班级 `college_id` / 专业维度，不用学生冗余 `sm.college_*` |
| 写校验 | `batchAllocateBedsToClass` / `batchRecallClassAllocation`：床位须属操作人学院；班级入学年必填；权限按一年级代理规则 |
| 学院解析 | `CurrentUserCollegeHelper`：沿用户部门 ancestors **向上**找 `parent_id=101` 或 `xy-` |
| 公共逻辑 | `FreshmanCollegeProxyHelper` / `FreshmanCollegeProxySupport` |

## 上线前数据核对（只读）

```sql
-- 1) 代理配置 = 现网人文学院 dept_id
SELECT config_key, config_value
FROM sys_config
WHERE config_key = 'xg.studentLeave.freshmanProxyCollegeId';

SELECT dept_id, dept_name, parent_id, dept_category
FROM sys_dept
WHERE dept_name = '人文学院' AND del_flag = '0';

-- 2) 当前届一年级班级数量（2026-09-01 后 enrollment_year = 当年）
SELECT COUNT(*) AS freshman_class_cnt
FROM xg_class_msg
WHERE deleted = 0
  AND enrollment_year = YEAR(CURDATE()) - IF(MONTH(CURDATE()) >= 9, 0, 1);

-- 3) 入学年缺失或疑似冲突
SELECT id, class_name, grade, enrollment_year, college_id, college_name
FROM xg_class_msg
WHERE deleted = 0
  AND (enrollment_year IS NULL
       OR (grade IS NOT NULL AND grade NOT LIKE CONCAT('%', enrollment_year, '%')))
LIMIT 200;

-- 4) 学生学院与班级学院漂移（树已不再依赖学生学院挂载，仍建议治理）
SELECT sm.id, sm.student_no, sm.name, sm.college_id AS stu_college,
       c.college_id AS class_college, c.class_name
FROM xg_student_msg sm
JOIN xg_class_msg c ON sm.class_id = c.id AND c.deleted = 0
WHERE sm.deleted = 0
  AND sm.student_status = '1'
  AND sm.college_id IS NOT NULL
  AND c.college_id IS NOT NULL
  AND CAST(sm.college_id AS CHAR) <> CAST(c.college_id AS CHAR)
LIMIT 200;
```

核对后：若配置值与人文 `dept_id` 不一致，更新 `sys_config` 并刷新参数缓存 / 重启后端。

## 运营注意

1. 系统参数中确认人文学院 `dept_id` 已配置且与账号解析出的学院 ID 一致。
2. 一年级床位在 `xsssfpejxy` 分给人文学院。
3. 切届后：树自动切回本学院；若床位 `college_id` 仍挂人文，需另行移交（本期未自动迁移）。
4. 班级 `enrollment_year` 为空时：不计入一年级树；分配/回收会报错，需先维护入学年。

## 验收用例

1. **人文账号**：看见本院全部班级 + 全校当前届一年级班级；可对一年级分配/回收。
2. **其它学院账号**：只见本院非一年级；操作一年级被拒。
3. **人文下级科室账号**：解析学院仍为人文学院，代理分支生效（可见全校一年级）。
4. **无住宿生的一年级空班**：树中可见，男女需求可为 0，仍可分配床位。

## 相关代码

- `backend/ruoyi-modules/ruoyi-xg/.../helper/CurrentUserCollegeHelper.java`
- `backend/ruoyi-modules/ruoyi-xg/.../helper/FreshmanCollegeProxyHelper.java`
- `backend/ruoyi-modules/ruoyi-xg/.../service/impl/XgStudentMsgServiceImpl.java`
- `backend/ruoyi-modules/ruoyi-xg/.../service/impl/XgDormBedStudentServiceImpl.java`
- `backend/ruoyi-modules/ruoyi-xg/.../resources/mapper/studentMsg/XgStudentMsgMapper.xml`
- `web/src/views/xg/xgss/ejxyfp/`（前端仍调原 API）