# 测试数据交付包 · 使用说明

订单 `SB-SAMPLE-001` ｜ 结构 `ecommerce_3tables` ｜ 随机种子 `20261122` ｜ 生成时间 2026-11-22 18:26:14

先看这页，全部内容 3 分钟能走完，不需要看任何代码。

## 一、一分钟跑通（要报 PASS）

1. 解压到一个空目录，**不要改动任何文件名**（哈希按文件名+内容算）。
2. 只需要 Python 3.8 以上，**不需要安装任何第三方库**（本包只用标准库）。
3. 在该目录执行：

   ```
   python verify.py
   ```

4. 看到最后一行 `VERDICT=PASS` 即通过；出现 `VERDICT=FAIL` 就往下看第五节。

## 二、不装 Python 也能验文件完整性

包里带 `checksums.txt`（sha256sum 格式），两条命令任选一条：

```
# Linux / macOS
sha256sum -c checksums.txt
```

```powershell
# Windows PowerShell
Get-Content checksums.txt | ForEach-Object {
  $h,$f = ($_ -split '\s+',2)
  if ((Get-FileHash $f -Algorithm SHA256).Hash.ToLower() -eq $h) { "OK   $f" } else { "FAIL $f" }
}
```

全 `OK` 说明数据文件在传输中一个字节都没变。这条路径不需要 Python，也不依赖本包的脚本，等于多一道独立复核。

## 三、包里有什么

| 文件 | 是什么 | 要不要动 |
|---|---|---|
| `orders.csv` | 数据表（54929 字节，SHA256 见验收单） | 按需导入或直接用 |
| `payments.csv` | 数据表（42725 字节，SHA256 见验收单） | 按需导入或直接用 |
| `schema.sql` | 建表语句：主键、外键约束，可直接灌测试库 | 按需执行 |
| `users.csv` | 数据表（14693 字节，SHA256 见验收单） | 按需导入或直接用 |
| `RUN.md` | 本说明（你现在看的这个） | 不用动，看完即可 |
| `checksums.txt` | 数据文件的 sha256 清单，供 sha256sum -c 使用 | 不用动 |
| `acceptance.html` | 验收单：行数、外键完整性、逐文件 SHA256、整包组合哈希 | 双击用浏览器打开，只读 |
| `verify.py` | 客户侧自查脚本，重算哈希与行数、外键孤儿，输出 PASS/FAIL | 不用改，直接跑 |
| `manifest.json` | 机器可读的清单：文件字节数、SHA256、seed、行数约定、combined 哈希 | 不用改，可给程序读 |

## 四、读结果时看三件事

1. **行数一致**：`acceptance.html` 里"约定行数"与"实际行数"一致 —— 说明数据出全了，没有被截断。
2. **外键孤儿 0**：父表在前、子表按引用生成，所以孤儿行是构造上就不存在，不是事后修补的。
3. **哈希全对**：逐文件 SHA256 与 `manifest.json` 记录一致，整包 `combined_sha256` 一致 —— 说明文件集合与内容都没被改。

`combined_sha256` 是把"文件名:哈希"按名字排序拼起来再算一次 sha256，改一个字节、少一个文件，这个值都会变，改了还对不上。

## 五、FAIL 了怎么查

| 现象 | 原因 | 怎么办 |
|---|---|---|
| `文件哈希` 有 FAIL | 文件被编辑、被截断，或下载不完整 | 重新下一遍再验；下载链接过期会返回 410，不是 404 |
| `行数` 不符 | 包不完整或 CSV 被改过 | 重新下载；仍不符请联系交付方重出 |
| `外键孤儿` 非 0 | 数据行被人工删改 | 用原始包重验，不要手改数据 |
| `combined_sha256` 不符但单文件都对 | 包里多放或少放了文件 | 检查目录里是否混入别的文件 |

## 六、可复现性

同一结构、同一 `seed` 重出，`combined_sha256` 必须与 `manifest.json` 里记录的一致（数据文件逐字节相同）；不一致说明生成器本身改过，属于交付方问题。种子与结构写在 `manifest.json` 里，可核对。

## 七、环境与边界

- 纯 Python 标准库，无第三方依赖、无网络请求、无需任何数据账号。
- 全部是**合成数据**，不含任何真实客户信息；姓名、手机号均为构造或打码。
- 适合联调、演示、压测、报表样例；**不能**当真实业务数据用，也不构成合规采集证明。涉及监管口径的正式交付，另走定制档并附规则表。
