# 可复现说明

本插件把复现过程拆分为“原始文件标准化”和“标准化数据描述统计”两个阶段。每个阶段都记录输入 SHA-256、行列规模、依赖版本和运行参数。

## 复现前提

在插件根目录执行以下命令：

```bash
pnpm install

python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.lock.txt
```

其中：

- `pnpm-lock.yaml` 固定 Node.js 依赖版本。
- `requirements.lock.txt` 固定 Python、pandas 和 openpyxl 版本。
- 原始业务数据不纳入 Git；请将其放在本地 `dataDir` 下。

## 第一阶段：XLSX/CSV 标准化

假设插件配置中的 `dataDir` 指向 `.local/data`，原始文件位于 `.local/data/raw/老旧资费特征.xlsx`。

```bash
.venv/bin/python python/prepare_tariff.py \
  --input ".local/data/raw/老旧资费特征.xlsx" \
  --output-dir ".local/data/prepared" \
  --sheet "数据" \
  --dictionary-sheet "字段说明"
```

命令输出包含：

- `source_sha256`：原始输入文件哈希；
- `normalized_sha256`：标准化 CSV 哈希；
- `prepared_dir`：准备阶段输出目录；
- 数据质量错误与警告。

准备目录的名称为：

```text
prepared/<原文件名>-<source_sha256 前12位>/
```

其中包含：

```text
normalized_tariff.csv
field_dictionary.csv
prepare_manifest.json
```

## 第二阶段：描述统计报告

将第一阶段生成的 `normalized_tariff.csv` 作为输入：

```bash
.venv/bin/python python/descriptive_report.py \
  --input ".local/data/prepared/<原文件名>-<哈希>/normalized_tariff.csv" \
  --output-dir ".local/reports" \
  --minimum-group-size 30 \
  --top-category-limit 20
```

报告目录名称为：

```text
reports/normalized_tariff-<normalized_sha256 前12位>/
```

其中包含数据质量报告、数值描述统计、分类分布、二元特征统计、分组统计、`manifest.json` 和 `report.md`。

## 通过 dsh 工具复现

在 dsh 对话中按顺序调用：

```text
请调用 tariff_prepare，处理 raw/老旧资费特征.xlsx。
主数据工作表是“数据”，字段说明工作表是“字段说明”。
```

确认返回结果没有 `failed_quality` 后，再调用：

```text
请调用 tariff_describe，分析：
prepared/<原文件名>-<哈希>/normalized_tariff.csv

请只基于聚合结果描述样本规模、数据质量和各项统计，不输出用户级记录，也不做运营决策。
```

`tariff_prepare` 返回的 `normalized_file` 是绝对路径；传给 `tariff_describe` 时，应转换为相对于 `dataDir` 的 `prepared/.../normalized_tariff.csv` 路径。

## 哈希核验

### 核验上下游输入关系

从准备阶段的清单中读取标准化文件哈希：

```bash
PREPARED_DIR=".local/data/prepared/<原文件名>-<哈希>"
REPORT_DIR=".local/reports/normalized_tariff-<标准化哈希前12位>"

.venv/bin/python -m json.tool \
  "$PREPARED_DIR/prepare_manifest.json"

.venv/bin/python -m json.tool \
  "$REPORT_DIR/manifest.json"
```

应满足：

```text
prepare_manifest.json 中的 normalized_sha256
=
manifest.json 中的 input_sha256
```

### 核验同一环境下的输出一致性

对同一输入文件、同一代码版本、同一 Python 环境重复执行后，计算报告文件哈希：

```bash
shasum -a 256 "$REPORT_DIR"/*
```

也可以在两次运行后分别保存哈希清单并比较：

```bash
shasum -a 256 "$REPORT_DIR"/* > /tmp/tariff-report-first.sha256

# 使用同一命令再次运行后：
shasum -a 256 "$REPORT_DIR"/* > /tmp/tariff-report-second.sha256

diff -u /tmp/tariff-report-first.sha256 /tmp/tariff-report-second.sha256
```

如果 `diff` 没有输出，说明该报告目录中的文件完全一致。

## 预期的可复现边界

下列条件保持一致时，标准化 CSV 与报告文件应可复现：

1. 原始输入文件内容不变；
2. Python 脚本与 TypeScript 插件代码不变；
3. `requirements.lock.txt` 和 `pnpm-lock.yaml` 对应的依赖环境不变；
4. 工作表名称、最小分组样本量、分类 Top N 数量等参数不变；
5. 操作系统、Python 与 pandas 版本不发生影响输出格式的变化。

`manifest.json` 与 `prepare_manifest.json` 会主动记录 Python、pandas、openpyxl 和平台信息。若统计表一致但清单哈希不同，应先检查运行环境是否变化。