# ARHB-POC 操作手册

**场景**：应收红蓝票对冲与收款核销自动化（含账龄分层）  
**对应 PRD**：PRD-ARHB-001 v1.1  
**执行环境**：Windows 10/11，Python 3.10+  
**最后更新**：2026-09-29

---

## 一、交付物清单

| 文件 | 作用 | 是否必读 |
|---|---|---|
| `数据源电子表格/T1_应收明细台账.xlsx` | 源台账：应收单/发票/红票 | 是 |
| `数据源电子表格/T2_收款明细台账.xlsx` | 源台账：收款单 | 是 |
| `数据源电子表格/T3_客户账期表.xlsx` | 源台账：客户标准账期 | 是 |
| `数据源电子表格/T4_汇率表.xlsx` | 源台账：币种中间价 | 是（多币种场景） |
| `run_arhb_poc.py` | 跑批引擎主脚本 | 是 |
| `generate_demo_data.py` | 脱敏演示数据生成脚本 | 可选 |
| `结果工作簿_ARHB_POC.xlsx` | 跑批输出（7 张结果页） | 是 |
| `arhb_poc_run.log` | 跑批留痕/审计日志 | 建议保留 |

---

## 二、环境准备

1. 确保已安装 Python 3.10+。
2. 打开 PowerShell / Git Bash / CMD，进入交付物目录：
   ```bash
   cd "D:/workbuggy/2026-09-29-14-44-54/POC试跑-应收红蓝票对冲/交付物"
   ```
3. 创建虚拟环境并安装依赖（推荐）：
   ```bash
   python -m venv .venv
   .venv\Scripts\pip install pandas openpyxl
   ```

> 交付包里未带虚拟环境，首次运行前请执行安装。

---

## 三、执行步骤

### 3.1 使用默认演示数据跑批

```bash
python run_arhb_poc.py --base-date 2026-09-29
```

脚本默认读取 `数据源电子表格/` 目录下的四张表，输出 `结果工作簿_ARHB_POC.xlsx`。

### 3.2 使用客户真实台账

将客户台账按 **4.1 字段要求** 整理为四张表，替换 `数据源电子表格/` 下的对应文件，保持文件名不变，再次执行上述命令即可。

> 注意：源台账**只读**，跑批结果会另存为新的 Excel，不会改写客户原件。

### 3.3 命令行参数说明

| 参数 | 必填 | 默认值 | 说明 |
|---|---|---|---|
| `--base-date` | 否 | 2026-09-29 | 数据基准日，用于账龄与逾期计算 |
| `--t1` | 否 | `数据源电子表格/T1_应收明细台账.xlsx` | 应收明细台账路径 |
| `--t2` | 否 | `数据源电子表格/T2_收款明细台账.xlsx` | 收款明细台账路径 |
| `--t3` | 否 | `数据源电子表格/T3_客户账期表.xlsx` | 客户账期表路径 |
| `--t4` | 否 | `数据源电子表格/T4_汇率表.xlsx` | 汇率表路径 |
| `--out` | 否 | `结果工作簿_ARHB_POC.xlsx` | 输出结果路径 |
| `--log` | 否 | `arhb_poc_run.log` | 跑批日志路径 |

---

## 四、字段要求

### 4.1 T1 应收明细台账

| 字段 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
| 单据号 | 文本 | 是 | 唯一标识，重复会进入差异池 |
| 单据类型 | 文本 | 是 | 蓝字应收单 / 红字应收单 / 销售退货单 / 折让单 |
| 客户编码 | 文本 | 是 | 必须在 T3 中存在 |
| 客户名称 | 文本 | 是 | 展示用 |
| 发票号 | 文本 | 建议填 | 核销与对冲的关键匹配键 |
| 关联原蓝票号 | 文本 | 红票建议填 | 用于自动对冲 |
| 币种 | 文本 | 是 | CNY / USD / EUR 等 |
| 原币金额（含税） | 数值 | 是 | 含税金额，红票用负数 |
| 税额（原币） | 数值 | 是 | 必须与关联蓝票税额绝对匹配 |
| 开票日 | 日期 | 是 | 账龄起算点 |
| 合同账期（天） | 数值 | 否 | 为空则取 T3 客户标准账期 |

### 4.2 T2 收款明细台账

| 字段 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
| 收款单号 | 文本 | 是 | 唯一标识 |
| 客户编码 | 文本 | 是 | 用于 FIFO 兜底 |
| 发票号 | 文本 | 建议填 | 精确核销主键 |
| 币种 | 文本 | 是 | 与 T1 币种一致 |
| 收款金额（原币） | 数值 | 是 | 正数 |
| 收款日 | 日期 | 是 | 汇率折算用 |

### 4.3 T3 客户账期表

| 字段 | 类型 | 是否必填 |
|---|---|---|
| 客户编码 | 文本 | 是 |
| 客户名称 | 文本 | 是 |
| 标准账期（天） | 数值 | 是 |
| 合同账期（天） | 数值 | 否 |

### 4.4 T4 汇率表

| 字段 | 类型 | 是否必填 |
|---|---|---|
| 币种 | 文本 | 是 |
| 日期 | 日期 | 是 |
| 中间价（对人民币） | 数值 | 是 |

> 多币种场景下，T4 必须覆盖 T1/T2 中出现的全部「币种 × 日期」组合，否则缺失行会进入差异池。

---

## 五、输出结果解读

### 5.1 首页 KPI

| 指标 | 含义 | POC 目标 |
|---|---|---|
| 对冲覆盖率（精确级） | 靠原蓝票号/金额+税额精确配对的红票占比 | ≥70% |
| 对冲覆盖率（含模糊） | 含 FIFO 兜底后的总配对红票占比 | ≥90% |
| 核销自动化率（精确级） | 靠发票号精确核销的收款行次占比 | ≥70% |
| 核销自动化率（含模糊） | 含 FIFO 兜底后可核销的收款行次占比 | ≥90% |
| 差异池条目数 | 需人工复核的异常/重大单/缺失项 | 越少越好 |
| 长账龄预警数 | 181 天以上且未核销余额 > 0 的单据 | 监控指标 |
| 勾稽通过 | 账龄分层合计 = 未核销余额合计 | 必须 100% |

### 5.2 结果页说明

| 页签 | 内容 | 用途 |
|---|---|---|
| `00_首页KPI` | 核心指标与勾稽校验 | 汇报首页 |
| `01_红蓝分区` | 每张单的红/蓝判定与依据 | 检查分区是否合理 |
| `02_对冲记录` | 红蓝配对结果、对冲金额、匹配级别 | 财务主管复核 |
| `03_收款核销` | 收款单拆分到应收单的核销明细 | 出纳/会计对账 |
| `04_账龄分层` | 六档账龄 + 逾期天数 + 长账龄预警 | 催收清单来源 |
| `05_分录草稿` | 对冲/核销对应的借贷方向与科目大类 | 交总账入账参考 |
| `06_差异池` | 异常行、重大单、数据缺失 | 人工处理入口 |

---

## 六、异常处理速查

| 现象 | 原因 | 处理动作 |
|---|---|---|
| 差异池出现「汇率表缺失」 | T4 未覆盖某外币日期 | 补齐 T4 对应汇率行后重跑 |
| 差异池出现「客户编码不在客户表」 | T3 缺少客户 | 补全 T3 或修正 T1/T2 客户编码 |
| 红票全部未对冲 | 税额不匹配或客户编码不一致 | 检查红票「税额（原币）」是否为蓝票负数 |
| 核销自动化率低 | 收款单发票号缺失 | 建议补录发票号，或接受 FIFO 兜底结果 |
| 勾稽未通过 | 余额计算出现负数或折算差异 | 检查源数据金额符号，勿手动改脚本 |

---

## 七、话术红线（对外演示时必读）

1. **不得承诺坏账计提与合规结论**：POC 只出长账龄预警，不做坏账准备。
2. **「单轮降幅 67%」不得对外**：该数字为 AI 推断，未签，仅限内部。
3. **讲「回款率 +69%」必须随附口径**：样本期与原始测算依据待补（TBD-14）。
4. **模型成本不写确定金额**：对外报价走商务流程，按实际调用量测算。

---

## 八、后续升级路径

| 版本 | 内容 |
|---|---|
| v1.1 | 事件驱动 / 对话式查询 |
| v1.2 | 正式凭证生成与总账对接 |
| v2.0 | 赊销风险 / 客户信用评级 |
| v2.1 | 账龄双口径 + 坏账计提建议 |
| v2.2 | 预收冲应收、跨年调整、汇兑损益核算 |