# 工具与输出协议

本文档定义 dsh 工具 `tariff_prepare`、`tariff_describe` 的输入参数、返回对象和落盘文件格式。

## 工具调用顺序

```text
原始 XLSX / CSV
  -> tariff_prepare
  -> prepared/<原文件名>-<原始文件哈希前12位>/normalized_tariff.csv
  -> tariff_describe
  -> reports/normalized_tariff-<标准化文件哈希前12位>/
```

`tariff_describe` 应分析 `tariff_prepare` 生成的标准化 CSV，而不是直接分析未经校验的原始文件。

## tariff_prepare

### 作用

读取 `dataDir` 内已授权的本地 XLSX、XLSM 或 CSV 文件，完成字段标准化、数据质量校验、字段字典生成和运行清单记录。

工具只返回质量结果、文件路径和聚合元数据，不返回用户级记录。

### 参数

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `file` | string | 是 | `dataDir` 下的相对 `.xlsx`、`.xlsm` 或 `.csv` 文件路径，例如 `raw/老旧资费特征.xlsx`。 |
| `sheet` | string | 否 | XLSX/XLSM 主数据工作表名称；默认使用配置中的 `defaultSheet`，通常为 `数据`。 |
| `dictionarySheet` | string | 否 | XLSX/XLSM 字段说明工作表名称；默认使用配置中的 `dictionarySheet`，通常为 `字段说明`。 |

### 返回值

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `status` | string | `pass`、`warning` 或 `failed_quality`。 |
| `prepared_dir` | string | 本次准备阶段的输出目录绝对路径。 |
| `normalized_file` | string | 标准化 CSV 的绝对路径。 |
| `field_dictionary_file` | string | 字段字典 CSV 的绝对路径。 |
| `manifest_file` | string | 准备阶段清单 JSON 的绝对路径。 |
| `source_sha256` | string | 原始输入文件的完整 SHA-256。 |
| `normalized_sha256` | string | 标准化 CSV 的完整 SHA-256。 |
| `row_count` | integer | 标准化后样本量。 |
| `column_count` | integer | 标准化后字段数。 |
| `errors` | array | 数据质量错误列表。 |
| `warnings` | array | 数据质量警告列表。 |

### 落盘文件

| 文件 | 说明 | 主要字段 |
| --- | --- | --- |
| `normalized_tariff.csv` | 标准化后的分析输入数据。 | 见 [数据口径](DATA_SCHEMA.zh-CN.md) 中的 19 个标准字段。 |
| `field_dictionary.csv` | 标准字段与源系统字段映射。 | `展示字段`、`原始字段名`、`说明`。 |
| `prepare_manifest.json` | 准备阶段的可复现清单。 | `status`、`source_file`、`source_sha256`、`normalized_file`、`normalized_sha256`、`field_dictionary_file`、`row_count`、`column_count`、`columns`、`sheet`、`dictionary_sheet`、`errors`、`warnings`、`python_version`、`pandas_version`、`openpyxl_version`。 |

## tariff_describe

### 作用

读取 `dataDir` 内的标准化 CSV，生成数据质量报告、连续变量描述统计、分类分布、二元特征汇总、分组统计和可复现清单。

工具只返回聚合摘要与报告路径，不返回用户级记录。

### 参数

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `file` | string | 是 | `dataDir` 下的相对 `.csv` 文件路径，例如 `prepared/老旧资费特征-<哈希>/normalized_tariff.csv`。 |

分组统计的最小样本量与分类分布的 Top N 数量由插件配置中的 `minimumGroupSize`、`topCategoryLimit` 控制。

### 返回值

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `status` | string | `pass` 或 `failed_quality`。数据质量仅有警告时，分析仍完成，`status` 为 `pass`。 |
| `quality_status` | string | `pass`、`warning` 或 `failed_quality`。 |
| `report_dir` | string | 本次描述统计报告目录的绝对路径。 |
| `row_count` | integer | 输入 CSV 的样本量。 |
| `column_count` | integer | 输入 CSV 的字段数。 |
| `input_sha256` | string | 输入 CSV 的完整 SHA-256。 |
| `errors` | array | 数据质量错误列表。 |
| `warnings` | array | 数据质量警告列表。 |

### 落盘文件

| 文件 | 说明 | 字段 |
| --- | --- | --- |
| `data_quality.csv` | 逐字段数据质量结果。 | `field`、`dtype`、`missing_count`、`missing_rate`、`distinct_count`、`duplicate_count`、`negative_count`、`invalid_domain_count`、`out_of_range_count`、`is_constant`、`quality_level`。 |
| `numeric_summary.csv` | 数值字段描述统计。 | `field`、`count`、`mean`、`std`、`min`、`p25`、`median`、`p75`、`max`。 |
| `categorical_distribution.csv` | 分类字段 Top N 频数及占比。 | `field`、`value`、`count`、`rate`、`total_distinct_count`、`is_truncated`。 |
| `binary_feature_summary.csv` | 二元字段正例统计。 | `field`、`sample_size`、`positive_count`、`positive_rate`、`invalid_count`。 |
| `grouped_numeric_summary.csv` | 按套餐名称、用户属地、品牌系列的分组统计。 | `group_field`、`metric`、`group_value`、`sample_size`、`mean`、`median`、`p25`、`p75`。 |
| `manifest.json` | 描述阶段可复现清单。 | `status`、`quality_status`、`input_file`、`input_sha256`、`row_count`、`column_count`、`columns`、`python_version`、`pandas_version`、`platform`、`date_summary`、`minimum_group_size`、`top_category_limit`、`errors`、`warnings`。 |
| `report.md` | 报告索引。 | 输入文件名、输入哈希、样本量、字段数、质量状态和输出文件清单。 |

## 状态含义

| 状态 | 含义 | 后续处理建议 |
| --- | --- | --- |
| `pass` | 没有阻断分析的问题；对 `tariff_describe` 而言，也可能同时存在质量警告。 | 可以阅读聚合报告并开展后续分析。 |
| `warning` | 准备阶段发现非阻断性问题，例如常量列、缺少非必需字段或无法解析的入网日期。 | 可以继续分析，但应在解读结果时说明限制。 |
| `failed_quality` | 存在阻断性数据质量错误，例如重复用户标识、关键字段缺失、非法二元值或饱和度越界。 | 先修复或确认源数据问题，再据此开展正式分析。 |

## 哈希与上下游串联

1. `tariff_prepare` 计算原始文件的 `source_sha256`。
2. 准备目录名称使用 `<原文件名>-<source_sha256 前12位>`。
3. 准备脚本生成 `normalized_tariff.csv`，并计算其 `normalized_sha256`。
4. 调用 `tariff_describe` 时，将该标准化文件作为输入；其 `input_sha256` 应等于上游的 `normalized_sha256`。
5. 描述统计报告目录名称使用 `<标准化文件名>-<input_sha256 前12位>`。
6. 因此，可以从报告的 `manifest.json` 反向定位标准化数据，再从 `prepare_manifest.json` 反向定位原始输入及其字段说明。

该链路用于核验“同一输入是否经过同一标准化过程并产生同一分析结果”。