# 老旧资费数据口径

本文档定义 `tariff_prepare` 与 `tariff_describe` 使用的 19 个标准字段、取值规则和数据质量校验规则。

## 使用边界

- `用户标识` 仅用于去重与数据质量校验，不写入任何聚合统计结果。
- `入网日期` 仅用于入网批次分析、最早/最晚日期概览；不据此计算当前在网时长。
- 本插件输出描述性统计与数据质量结果，为后续分析或运营决策提供数据支撑；不自动做业务决策。
- 金额类字段按源数据的金额口径处理；字段名标明“元”的字段以元展示。

## 标准字段

| 展示字段 | 原始字段名 | 类型 | 单位或格式 | 允许值/业务口径 |
| --- | --- | --- | --- | --- |
| 用户标识 | `user_id` | 字符串 | 用户唯一标识 | 非空；同一输入文件内不得重复。 |
| 入网日期 | `JOIN_DATE` | 日期字符串 | `YYYY-MM-DD` | 可解析日期；仅用于入网批次分析。 |
| 品牌系列 | `brand_series` | 整数型分类变量 | 无 | `1` 飞享；`2` 全球通；`3` 神州行；`4` 动感地带。 |
| 套餐名称 | `plan_name_next` | 字符串分类变量 | 无 | 非空套餐名称。 |
| 套餐费用（元） | `plan_fee_next` | 数值型连续变量 | 元 | 非空；应为非负数。 |
| 用户属地 | `area_name` | 字符串分类变量 | 无 | 用户所属地区。 |
| 话费（元） | `arpu_ZH` | 数值型连续变量 | 元 | 话费或 ARPU 指标；应为非负数。 |
| 流量使用（MB） | `DOU` | 数值型连续变量 | MB | 本期流量使用量；应为非负数。 |
| 资费套餐总流量（MB） | `main_total` | 数值型连续变量 | MB | 套餐内总流量；应为非负数。 |
| 本月套外语音费用 | `tw_call_arpu` | 数值型连续变量 | 源系统金额口径 | 本月套餐外语音费用；应为非负数。 |
| 本月套内语音资源（分钟） | `voice_total` | 数值型连续变量 | 分钟 | 本月套餐内语音资源；应为非负数。 |
| 流量饱和度（百分比单位） | `BHD_DOU` | 数值型比例变量 | 比例值 | `0` 到 `1`；`1` 表示 `100%`。 |
| 套外流量费用 | `gprs_tw_fee` | 数值型连续变量 | 源系统金额口径 | 本月套餐外流量费用；应为非负数。 |
| 语音饱和度（百分比单位） | `BHD_MOU` | 数值型比例变量 | 比例值 | `0` 到 `1`；`1` 表示 `100%`。 |
| 全球通等级 | `CUST_LEVEL_NAME` | 字符串分类变量 | 无 | 客户等级，例如普卡、银卡、白金卡、钻石卡。 |
| 套外流量单价（元/GB） | `tw_gprs_dj` | 数值型连续变量 | 元/GB | 套餐外流量单价；应为非负数。 |
| 价值合约（1：是，0：不是） | `ZF_JZ_FLAG` | 二元整数变量 | 无 | `1` 是；`0` 否。 |
| 异网主卡（1：是，0：不是） | `DUAL_YWZK_FLAG` | 二元整数变量 | 无 | `1` 是；`0` 否。 |
| 宽带（1：是，0：不是） | `KD_FLAG` | 二元整数变量 | 无 | `1` 是；`0` 否。 |

## 标准化规则

`tariff_prepare` 在生成 `normalized_tariff.csv` 时执行以下处理：

1. 去除字段名首尾空白字符。
2. 将 `用户标识` 转为字符串；数值形式的整数标识不保留 `.0` 后缀。
3. 将 `入网日期` 解析为 `YYYY-MM-DD`；支持普通日期与 Excel 日期序列号。
4. 将数值字段转为数值类型；无法转换的非空值记为数据质量错误。
5. 输出 UTF-8 BOM 编码的标准化 CSV，便于 Excel 与常见中文数据工具读取。

## 数据质量规则

### 错误：`failed_quality`

存在任意错误时，整体数据质量状态为 `failed_quality`。

| 规则编码 | 触发条件 |
| --- | --- |
| `duplicate_column_name` | 字段名去除空白后发生重复。 |
| `missing_required_column` | 缺少用户标识、入网日期、品牌系列、套餐名称、套餐费用（元）或用户属地。 |
| `missing_critical_value` | 用户标识、套餐名称或套餐费用（元）存在缺失或空白值。 |
| `duplicate_user_id` | 用户标识存在重复记录。 |
| `invalid_numeric_value` | 数值字段存在无法转换为数值的非空值。 |
| `saturation_out_of_range` | 流量或语音饱和度小于 `0` 或大于 `1`。 |
| `invalid_brand_series` | 品牌系列不是 `1`、`2`、`3`、`4`。 |
| `invalid_binary_value` | 任一二元字段不是 `0` 或 `1`。 |

### 警告：`warning`

不存在错误但存在任意警告时，整体数据质量状态为 `warning`。

| 规则编码 | 触发条件 |
| --- | --- |
| `missing_expected_column` | 缺少非必需的预期字段；相关统计会跳过。 |
| `unexpected_columns` | 输入中存在字段字典未定义的额外字段。 |
| `invalid_join_date` | 入网日期无法解析；该记录不参与入网批次分析。 |
| `negative_value` | 应为非负的字段出现负数。 |
| `constant_column` | 字段只有一个非缺失取值，无法进行组间比较。 |
| `dictionary_sheet_not_found` | XLSX 中未找到字段说明工作表。 |
| `dictionary_sheet_incomplete` | XLSX 字段说明工作表少于两行。 |

### 通过：`pass`

没有错误、没有警告时，整体数据质量状态为 `pass`。