# 架构说明

`dsh-plugin-csv-report` 将资费数据分析拆分为“数据准备”和“描述统计”两个可独立调用、可通过标准化 CSV 串联的阶段。

```text
dsh Agent
  │
  ├─ tariff_prepare
  │   │
  │   ├─ TypeScript 工具层
  │   │   ├─ 校验 dataDir 内相对输入路径
  │   │   ├─ 限制文件类型与输入大小
  │   │   └─ 传递取消信号至 Python 子进程
  │   │
  │   └─ python/prepare_tariff.py
  │       ├─ 读取 XLSX / XLSM / CSV
  │       ├─ 标准化字段、日期、数值与用户标识
  │       ├─ 执行字段结构与取值质量校验
  │       └─ 写入 prepared/<源文件名>-<源文件哈希>/
  │           ├─ normalized_tariff.csv
  │           ├─ field_dictionary.csv
  │           └─ prepare_manifest.json
  │
  └─ tariff_describe
      │
      ├─ TypeScript 工具层
      │   ├─ 校验 dataDir 内相对 CSV 路径
      │   ├─ 创建 outputDir
      │   └─ 传递分组统计参数与取消信号
      │
      └─ python/descriptive_report.py
          ├─ 再次执行数据质量校验
          ├─ 生成连续变量描述统计
          ├─ 生成分类变量分布和二元特征汇总
          ├─ 生成分组统计
          └─ 写入 reports/<标准化文件名>-<输入哈希>/
              ├─ data_quality.csv
              ├─ numeric_summary.csv
              ├─ categorical_distribution.csv
              ├─ binary_feature_summary.csv
              ├─ grouped_numeric_summary.csv
              ├─ manifest.json
              └─ report.md
```

## 组件职责

| 组件 | 职责 |
| --- | --- |
| `src/index.ts` | 插件入口；校验配置并注册两个工具。 |
| `src/config.ts` | 定义并校验目录、Python 路径、工作表名称、样本量阈值、文件大小与超时配置。 |
| `src/path-policy.ts` | 仅允许读取 `dataDir` 内相对路径文件；阻止 `..` 路径穿越、绝对路径与符号链接越界。 |
| `src/python-runner.ts` | 启动 Python 子进程、传递取消信号、限制子进程输出大小，并解析 JSON 返回值。 |
| `src/tools/tariff-prepare.ts` | 注册 `tariff_prepare`，将 XLSX/CSV 准备流程暴露给 dsh Agent。 |
| `src/tools/tariff-describe.ts` | 注册 `tariff_describe`，将描述统计流程暴露给 dsh Agent。 |
| `python/tariff_schema.py` | 集中定义 19 个业务字段、字段分组和数据质量规则。 |
| `python/prepare_tariff.py` | 读取、标准化、校验并输出标准化资费数据。 |
| `python/descriptive_report.py` | 对标准化 CSV 生成质量报告与聚合描述统计。 |

## 数据边界

- 原始数据仅由本地 Python 进程读取。
- dsh 工具参数只能指定 `dataDir` 下的相对路径。
- `tariff_prepare` 与 `tariff_describe` 的工具返回对象不包含用户级记录。
- `用户标识` 仅用于去重和质量校验，不进入聚合统计输出。
- 报告输出目录可以独立配置为 `outputDir`；其内容是聚合统计文件与可复现清单。

## 可复现链路

两个阶段分别记录输入哈希：

```text
原始文件 SHA-256
  -> prepare_manifest.json.source_sha256
  -> normalized_tariff.csv
  -> prepare_manifest.json.normalized_sha256
  -> manifest.json.input_sha256
```

在同一脚本、依赖环境和标准化输入下，描述统计文件应保持一致。具体操作见 [可复现说明](REPRODUCIBILITY.zh-CN.md)，完整字段与输出协议见：

- [数据口径](DATA_SCHEMA.zh-CN.md)
- [工具与输出协议](OUTPUT_CONTRACT.zh-CN.md)