电表免费额度核算

# 学生单月补贴数据处理脚本工作流程说明
> 最后更新日期： 2025-08-31 | 撰稿人： 安玉

## 一、工作目标

通过脚本实现 **学生公寓用电补贴数据** 的自动化处理：

* 从 **学生公寓数据** 与 **充值模板** 中提取并匹配单元名称；
* 自动计算每个房间的补贴电量及电费；
* 处理特殊房间（异形房间、合并房间）；
* 过滤掉不需要充值的房间；
* 生成校区更新后的充值模板 Excel。

---

## 二、前置工作

### 1. 基础数据获取

*  **航空港校区_学生公寓.xlsx**

<br/>

*  **航空港校区_学生公寓.xlsx**

* **航空港校区充值模板.xlsx**

* **龙泉校区充值模板.xlsx**

* **龙泉校区_不充值房间.xlsx**
   * 公寓服务中心单独提供
   
* **航空港校区_不充值房间.xlsx**
  * 公寓服务中心单独提供
  <script src="https://unpkg.com/mermaid@10.9.1/dist/mermaid.min.js"></script>

### 2. 注意事项
待补充
## 三、输入与输出文件

* ### 输入文件

1. **学生公寓入住数据**

* 龙泉校区_学生公寓.xlsx
   * 航空港校区_学生公寓.xlsx

2. **充值模板**

* 龙泉校区充值模板.xlsx
   * 航空港校区充值模板.xlsx

3. **不充值房间名单**

* 龙泉校区_不充值房间.xlsx
   * 航空港校区_不充值房间.xlsx

* ### 输出文件

* 龙泉校区充值模板_更新.xlsx
* 航空港校区充值模板_更新.xlsx

---

## 四、脚本执行流程

### 1. 主流程

脚本入口在 `if __name__ == "__main__":`：
分别调用 `process_campus` 处理 **龙泉校区** 和 **航空港校区** 的数据。

---

### 2. `process_campus` 模块（核心处理函数）

输入参数：

* `campus_name`: 校区名称（龙泉 / 航空港）
* `dormitory_file`: 学生公寓数据文件路径
* `template_file`: 充值模板文件路径
* `exclude_file`: 不充值房间名单文件路径
* `output_file`: 输出文件路径
* `price`: 电费单价

处理流程：

#### 2.1 加载数据

* 读取学生公寓入住数据、充值模板、不充值房间名单。
* 根据 `campus_name` 过滤当前校区数据。

#### 2.2 删除不充值房间

* 龙泉校区：删除 **青年公寓**、删除名单文件里的房间。
* 航空港校区：删除 **19/20/21号楼、培训楼、学府嘉苑**、删除名单文件里的房间。

#### 2.3 提取与规范化单元名称

* 使用 `extract_unit_name`：去掉前缀“龙泉-”或“航空港-”，提取格式如 `3-5-510`。
* 使用 `normalize_unit_name`：修正 4 位房号中多余的 `0`（如 `5014 → 514`）。
* 使用 `clean_unit_name`：统一中英文括号、去除空格。

#### 2.4 航空港异形房间合并

* 调用 `merge_special_rooms`：将 **106/107、206/207** 等成对房间合并为一个条目，编码合并、入住人数相加。

#### 2.5 初始化模板

* 为模板新增字段：

* `查找状态`（默认“未找到”）
  * `单月免费用电量`
  * `补发月份`（默认 1）
  * `合计补发免费用电量`
  * `电费`

#### 2.6 匹配数据

* 遍历学生公寓数据：

* 如果单元名称在模板中找到：更新编码、入住人数、计算补贴电量与电费。
  * 如果未找到：打印警告信息。

#### 2.7 导出结果

* 将结果高亮（未找到 → 绿色背景）。
* 导出至 Excel 文件。

---

### 3. 功能模块说明

#### 3.1 `extract_unit_name`

* 输入：房间全称（如 "龙泉-3号楼-5-510"）
* 输出：规范单元名称（如 "3-5-510"）
* 逻辑：删除校区前缀，提取“楼号-房号”。

#### 3.2 `normalize_unit_name`

* 输入："1-5-5014"
* 输出："1-5-514"
* 逻辑：修复房号中的冗余 `0`。

#### 3.3 `clean_unit_name`

* 输入："1-1-106（107） "
* 输出："1-1-106(107)"
* 逻辑：中英文括号统一、去除空格。

#### 3.4 `merge_special_rooms`

* 仅对航空港校区生效。
* 合并异形房间：`106 + 107 → 106(107)`。
* 更新编码（拼接）、入住人数（累加）。

---

## 五、计算逻辑

1. **单月免费用电量** = 入住人数 × 7（度）
2. **合计补发免费用电量** = 单月免费用电量 × 补发月份
3. **电费** = 合计补发免费用电量 × 单价（龙泉 0.5364，航空港 0.5385）

---

## 六、异常处理与提示

* **格式错误** → 打印 `⚠️ 格式不符合预期`，跳过该条。
* **模板未找到** → 打印 `⚠️ [校区] 学生公寓单元名称 'xxx' 在充值模板中未找到对应记录`。
* **所有异常** 均不中断脚本，仅提示人工核查。

---

## 六、输出结果特性

* 未匹配的行 → Excel 中绿色高亮。
* 匹配成功的行 → 更新字段，计算补贴与电费。
* 每个校区输出一个更新后的充值模板文件。

## 程序存放路径

>i **请前往以下路径运行程序**
>
> ../projects/GYZZ/MonthlyQuota/MonthlyQuota.py