电表批量清零

# 学生公寓智能电表批量清零工作流程

## 适用范围
适用于能源信息化系统管理的智能电表清零操作，覆盖航空港校区学生公寓1-18栋、龙泉校区学生公寓1-9栋及青年公寓。

## 目的
通过管理系统批量清零智能电表余额的操作。

## 适用场景

1. 因每年暑期学生公寓房间粉刷、维修、施工等原因项目结束后（校外单位需结算施工用电），新生入住前需将电表归零。
2. 其他需要

## 操作流程图

## 责任分工

公寓服务中心（`当前责任人：张晓东`）：
1. 提供清零房间清单，确保数据准确。
2. 抽样复核清零数据，验证结果一致性。
3. 通过OA系统提交清零需求。

能源服务中心：（`当前责任人：梁姝`）
1. 导出当前电表余额数据，移交安玉处理。
2. 安玉利用电表清零Python脚本处理数据，并返回公寓服务中心进行抽样复核。
3. 接收OA系统复核后的清零数据，导入管理系统执行批量清零操作。
4. 与公寓服务中心协作，通知各楼栋清零操作完成，密切监控是否存在误操作（如影响老生房间）等异常情况，并及时跟进处理（异常可能性低，但需严格执行）。

## 基础数据要求
每次清零前需准备以下数据：

| 序号 | 表格名称 | 数据来源 |当前责任人 |
| --- | --- | --- | --- |
| 01 | 充值导表模板.xlsx |能源信息化系统下载  | 梁姝 |
|02  |余额.xlsx  | 能源信息化系统下载 | 梁姝 |
|  03| 航空港清零房间.xlsx ｜ [点击下载模板](/media/attachment/2025/08/%E8%88%AA%E7%A9%BA%E6%B8%AF%E6%B8%85%E9%9B%B6%E6%88%BF%E9%97%B4.xls) | 公寓服务中心提供 | 张晓东 |
|  04| 龙泉清零房间.xlsx｜  [点击下载模板](/media/attachment/2025/08/%E9%BE%99%E6%B3%89%E6%B8%85%E9%9B%B6%E6%88%BF%E9%97%B4.xls)| 公寓服务中心提供 | 张晓东 |

<br/>

## 脚本逻辑

### 概述
此脚本用于处理学生公寓电费清零数据，生成按校区分类的清零数据文件。脚本强调精准匹配、字段清洗、异常处理，并确保输出字段顺序与模板表一致。

### 功能要求
1. **输入文件处理**：
   - 读取 `充值导表模板.xlsx`、`余额.xlsx`、`航空港清零房间.xlsx` 和 `龙泉清零房间.xlsx`。
   - 清零房间表 `宿舍房间号` 替换中文括号（`（` → `(`，`）` → `)`），重命名为 `单元名称`。
   - 清洗 `所属机构` 和 `单元名称`（转字符串、去首尾空格、替换特殊空白）。
2. **数据匹配**：
   - 以清零房间表 `单元名称` 为基准，验证是否在余额表和模板表中匹配。
   - 合并余额表 `当前余额` 到模板表 `电费` 列，并取反（正变负，负变正）。
3. **输出**：
   - 生成 `OUT/航空港校区清零数据.xlsx` 和 `OUT/龙泉校区清零数据.xlsx`。
   - 输出字段顺序严格遵循 `充值导表模板.xlsx`。
4. **异常处理**：
   - 检查文件/列缺失、空值、重复、未匹配，打印详细错误并终止。

### 全局配置
#### 输入输出
- **输入目录**：`../projects/GYZZ/ToZero/IN`
- **输出目录**：`../projects/GYZZ/ToZero/OUT`
- **输入文件**：
  - `充值导表模板.xlsx`：需包含 `所属机构`、`单元名称`、`电费` 等字段。
  - `余额.xlsx`：需包含 `所属机构`、`单元名称`、`当前余额`。
  - `航空港清零房间.xlsx`：需包含 `宿舍房间号`。
  - `龙泉清零房间.xlsx`：需包含 `宿舍房间号`。
- **输出文件**：
  - `OUT/航空港校区清零数据.xlsx`
  - `OUT/龙泉校区清零数据.xlsx`
- **关键字段**：
  - 机构列：`所属机构`
  - 主键列：`单元名称`（清零房间表 `宿舍房间号` 重命名）
  - 余额列：`当前余额`（余额表）→ `电费`（模板表，取反）

### 校区
- 航空港校区
- 龙泉校区

### 处理流程
#### **Step01: 预处理**
1. **读取文件**：
   - 检查文件存在性，抛出 `FileNotFoundError`。
   - 验证必须列：
     - 模板表：`所属机构`、`单元名称`、`电费`
     - 余额表：`所属机构`、`单元名称`、`当前余额`
     - 清零房间表：`宿舍房间号`
   - 保存模板表字段顺序（`template_columns`）。
2. **字段清洗**：
   - 对模板表和余额表：
     - `所属机构` 和 `单元名称` 转字符串、去首尾空格、替换特殊空白（`[\u00A0\u3000]` → 空格）。
   - 检查 `单元名称` 空值，打印前5行并终止。
3. **优化**：
   - 使用 `.copy()` 创建数据副本，避免 `SettingWithCopyWarning`。
   - 使用 `.loc` 进行赋值，确保操作安全。

#### **Step02: 按校区处理**
对每个校区（航空港、龙泉）执行以下步骤：

##### **A. 验证清零房间表**

- 读取清零房间表，检查 `宿舍房间号` 列。
- 替换中文括号（`（` → `(`，`）` → `)`）。
- 重命名 `宿舍房间号` 为 `单元名称`。
- 清洗 `单元名称`（转字符串、去空格、替换特殊空白）。
- 检查空值：若存在，打印前5行并终止。
- 检查重复：若存在，打印重复明细并终止。

##### **B. 筛选余额数据并验证**

- 筛选余额表中 `所属机构 == 校区` 的子集（`bal_sub`，副本）。
- 检查 `bal_sub` 是否为空，若为空，终止。
- 清洗 `单元名称`，检查空值。
- 检查 `当前余额` 空值，打印前5行并终止。
- 验证清零房间表 `单元名称` 是否在 `bal_sub` 中，未匹配则打印清单并终止。

##### **C. 筛选模板数据并验证**

- 筛选模板表中 `所属机构 == 校区` 的子集（`tpl_sub`，副本）。
- 检查 `tpl_sub` 是否为空，若为空，终止。
- 清洗 `单元名称`，检查空值和重复。
- 验证清零房间表 `单元名称` 是否在 `tpl_sub` 中，未匹配则打印清单并终止。

##### **D. 合并余额数据**
- 以清零房间表 `单元名称`（`allowed_keys`）为基准，筛选 `tpl_sub`。
- 使用 `merge` 将余额表 `当前余额` 合并到 `电费` 列：
  - 确保余额表 `单元名称` 唯一（`drop_duplicates`）。
  - 直接更新 `电费` 列，避免引入新字段。
- 检查 `电费` 列空值，打印前5行并终止。

##### **E. 取反电费列**
- 对 `电费` 列取反：`电费 = -电费`（例如 5 → -5，-1 → 1）。

##### **F. 确保字段顺序**
- 按模板表原始字段顺序（`template_columns`）重新排列 `result_df` 列。

##### **G. 导出结果**
- 保存到 `OUT/{校区}清零数据.xlsx`。
- 打印导出路径和行数。

#### **Step03: 异常处理**
- **文件/列缺失**：抛出 `FileNotFoundError` 或 `KeyError`，指明缺失文件/列。
- **空值**：
  - `单元名称` 空值：打印前5行，终止。
  - `当前余额` 空值：打印前5行，终止。
  - `电费` 列空值（合并后）：打印前5行，终止。
- **重复**：打印重复 `单元名称` 及次数，终止。
- **未匹配**：打印未匹配的 `单元名称` 清单，终止。

### 注意事项
- 确保输入文件存在且包含必须列。
- 清零房间表 `宿舍房间号` 可能包含中文括号，程序会正确替换。
- 余额表 `当前余额` 必须为数值，空值会导致终止。
- 输出字段顺序严格遵循模板表，`电费` 列反映取反后的余额。

## 程序存放路径

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