# 操作手册：销售订单履约跟踪（POC）

| 项 | 值 |
|---|---|
| 对应 PRD | PRD-SCE-OTC-001 v1.0 |
| 版本 | v1.0 · POC |
| 适用对象 | 实施工程师、销售跟单员、财务应收、销售负责人、仓储发货 |
| 更新日期 | 2026-09-29 |

> 本手册分两条线：**POC 线**（本地 CSV + 规则引擎，可当场跑通验证口径）与 **生产线**（简道云表单 + 定时扫描 + 企微推送）。两条线口径完全一致，POC 跑通的数字就是生产版会上线的数字。

---

## 一、五分钟跑通（POC 线）

### 1.1 环境准备

```bash
# Python 3.9+ 即可，无需安装第三方依赖（脚本只用标准库 + openpyxl）
python --version
# 仅在需要重新生成 Excel 测试数据时才装 openpyxl
pip install openpyxl
```

### 1.2 目录结构

```
售前资料包-销售订单履约跟踪/
├─ 01-文档/            场景描述、操作手册
├─ 02-测试数据/        销售订单履约跟踪-测试数据-600单.xlsx（9 张表）
├─ 03-规则引擎/        gen_data.py（造数）、runner.py（跑批）、out/（结果）
├─ 04-skill包/         order-fulfillment-tracker（场景专家，含 data/*.csv + verify.py）
├─ 05-演示页面/        售前演示页
└─ 06-视频/            操作效果录屏
```

### 1.3 一键体检（先跑这个）

```bash
cd 04-skill包/order-fulfillment-tracker
python verify.py
```

**预期输出**：

```
========================================================
质检通过：指标口径可执行 ✅
  异常 80 条（L1 43 / L2 33 / L3 4）
  OTIF 91.7%（应交付 241，按时 221）
  逾期应收 ¥17,964,219（9 单），账龄四桶与基准一致
  演示构造单 SO-2026-0926-01：通知后 48.5 小时未出库
```

> 这一步是**闸3 质检门禁**。跑不过就说明数据或口径被改坏了，不要带病演示。

### 1.4 完整跑批（产出异常清单与账龄表）

```bash
cd 03-规则引擎
python runner.py
```

产出在 `03-规则引擎/out/`：

| 文件 | 内容 |
|---|---|
| `异常清单.csv` | 80 条异常：订单号 / 客户 / 异常类型 / 滞留天数 / 状态 / 责任人 / 级别 / 判定依据 |
| `应收账龄表.csv` | 9 单逾期：未收金额 / 到期日 / 逾期天数（按逾期降序） |
| `kpi_summary.json` | 全部 KPI、状态分布、Top 榜、阈值配置 |

### 1.5 重新生成测试数据（可选）

```bash
cd 03-规则引擎
python gen_data.py
```

会同时刷新 `02-测试数据/*.xlsx` 与 `04-skill包/.../data/*.csv`。
> ⚠️ 重新造数后基准值会变，须同步更新 `verify.py` 顶部的 `BASE_*` 常量，否则闸3 会失败。

---

## 二、数据准备：9 张表怎么填

### 2.1 表清单与关联键

**关联键统一用「订单号」**，9 张表全部靠它串起来。

| # | 表 | 作用 | 关键字段 |
|---|---|---|---|
| 主 | 履约跟踪主表 | 每单一行，全景 | 订单号 / 客户 / 承诺交期 / 各节点时间 / 当前状态 / 应收金额 / 到期日 |
| DS1 | 01-销售订单行 | 订单明细 | 订单号 / 订单行号 / 产品型号 / 数量 / 单价 |
| DS2 | 02-发货通知 | 通知节点 | 订单号 / 通知单号 / 通知时间 / 通知数量 |
| DS3 | 03-出库记录 | 出库节点 | 订单号 / 出库单号 / 出库时间 / 出库数量 |
| DS4 | 04-物流在途 | 在途轨迹 | 订单号 / 承运商 / 最近轨迹时间 / 轨迹描述 |
| DS5 | 05-签收记录 | 签收节点（POD） | 订单号 / 签收时间 / 签收数量 |
| DS6 | 06-开票应收 | 开票与应收 | 订单号 / 开票时间 / 应收金额 |
| DS7 | 07-收款记录 | 回款核销 | 订单号 / 收款时间 / 收款金额 |
| DS8 | 08-缺件标志 | 生产侧缺件 | 订单号 / 缺件标志 / 缺件数量 / 短缺物料 / 更新日期 |

### 2.2 主表字段填写规范

| 字段 | 必填 | 说明 | 常见错误 |
|---|---|---|---|
| 订单号 | ✅ | 唯一，不可重复不可为空 | 重复 → 该行挂起转人工（E1） |
| 客户名称 | ✅ | — | — |
| 责任人 | ✅ | 跟单员，用于分派 | — |
| 承诺交期 | ✅ | 日期，OTIF 分母依据 | 留空 → 该单不进 OTIF 统计 |
| 录单时间 | ✅ | 日期时间 | — |
| 排产时间 | 条件 | 进入 S1 后必填 | — |
| 齐套时间 | 条件 | 进入 S3 后必填 | 缺件单可空 |
| 发货通知时间 | 条件 | 进入 S4 后必填，R4 判定起点 | — |
| 首次出库时间 | 条件 | 进入 S5 后必填，R5 判定起点 | 早于通知时间 → E2 倒挂告警 |
| 出齐时间 | 条件 | 进入 S6 后必填，R6b 判定起点 | — |
| 签收时间 | 条件 | 进入 S7 后必填，**OTIF 判定依据** | 用出库时间代替 → OTIF 虚高 |
| 开票时间 | 条件 | 进入 S8 后必填 | — |
| 到期日 | 条件 | 账期到期日，逾期判定依据 | — |
| 应收金额 | ✅ | 按单合计 | — |
| 当前状态 | ✅ | 13 态枚举之一，见下 | 填自定义值 → 该单不参与判定 |

### 2.3 状态枚举（只能填这 13 个）

```
S0 已录单待排产   S1 已排产待齐套   S2 缺件挂起     S3 待发货通知
S4 已通知待出库   S5 部分出库       S6 在途         S7 已签收待开票
S8 已开票待回款   S9 部分回款       S10 已结案      S11 异常挂起
S12 已取消
```

> 状态必须写成 `S4 已通知待出库` 这种「编号 + 名称」形式，或至少以 `S4` 开头；系统按编号前缀匹配。

---

## 三、配置：阈值与责任人

### 3.1 阈值表 `[初值]`（POC 默认，需按客户历史数据校准）

| 键 | 含义 | 默认值 |
|---|---|---|
| `R1_days` | 录单后未排产 | 3 天 |
| `R2_days` | 排产后未出齐套结论 | 5 天 |
| `R3_days` | 距交期不足多少天仍未通知 | 5 天 |
| `R4_hours` | 通知后未出库 | 48 小时 |
| `R5_days` | 首出后未出齐 | 7 天 |
| `R6a_hours` | 在途无轨迹更新 | 72 小时 |
| `R6b_days` | 出库后未签收 | 7 天 |
| `R7_days` | 缺件挂起 | 5 天 |
| `R8_days` | 签收后未开票 | 5 天 |
| `R9_l2_days` | 回款逾期 L2 | 15 天 |
| `R9_l3_days` | 回款逾期 L3 | 30 天 |

改阈值：编辑 `03-规则引擎/runner.py` 顶部的 `TH` 字典，重跑即可。

**校准方法**：用客户 3 个月历史数据跑一遍，若异常占比 > 20% 说明阈值偏紧（告警风暴），< 5% 说明偏松（漏报）。目标区间 **8%~15%**。

### 3.2 责任人分派

| 规则 | 责任人 |
|---|---|
| R1 / R3 | 跟单员 |
| R2 / R7 | 计划 / 采购 |
| R4 / R5 | 仓储 + 跟单员 |
| R6a / R6b | 物流 + 跟单员 |
| R8 | 财务 |
| R9a | 财务 + 销售 |
| R9b | 财务 + 销售负责人 |

---

## 四、日常操作（按角色）

### 4.1 销售跟单员（每天 15~20 分钟）

| 时间 | 动作 | 产出 |
|---|---|---|
| 08:30 | 看板自动完成全量扫描，打开看板 | 全局状态分布 + 异常 80 条 + 风险 Top 10 |
| 08:35 | 只看 L1 清单（43 条），逐条判断是否成立 | 确认 / 驳回 |
| 08:50 | 对成立的异常点「建异常单」→ 系统按规则分派责任人 | 推送到对应岗位 |
| 18:00 | 增量扫描，看当日更新的单有无新异常 | 增量清单 |
| 随时 | 客户来问，用对话问数查 | 归因答案 + 下钻链接 |

**判断异常是否成立的三问**：
1. 数据是真的吗？（可能是台账没及时更新，不是真异常）
2. 卡点责任在谁？（缺件找计划、出库找仓储、在途找物流）
3. 需要我现在做什么？（催办 / 答复客户 / 申请交期变更）

### 4.2 财务应收（每周 1~2 次）

1. 打开「应收账龄表」，看四桶分布（1~30 / 31~60 / 61~90 / 90+）。
2. 优先处理 **90+ 桶**（1 单 ¥169 万）与 **L3 严重逾期**（4 条）。
3. 导入回款流水到 `07-收款记录`，系统自动重算未核销余额。
4. 核销匹配由财务确认——**系统不会自动核销**。

> 账龄按**未核销余额**（应收 − 已收）计算，部分回款的单只计剩余部分，不会重复计逾期。

### 4.3 销售负责人（每天 10~20 分钟）

1. 只看 **L3 清单**（4 条）——这是 48 小时未处置升级上来的。
2. 看「风险 Top 榜」：滞留最久的 10 单、逾期最久的 10 单。
3. 需要资源调配或商务让步的，直接在异常单里批注。

### 4.4 仓储发货（每单 1~2 分钟）

- 出库后及时在 `03-出库记录` 登记出库时间。
- **注意**：如果订单处于缺件状态（S2），系统**不会**催你出库——缺件没解决，催也没货。你只会收到「缺件挂起」的根因告警。

---

## 五、对话问数：可以这样问

| 问法 | 系统返回 |
|---|---|
| 「SO-2026-0926-01 这单卡在哪」 | 当前状态、已滞留时长、卡点责任岗位、下钻链接 |
| 「本周哪些单逾期了」 | 逾期清单，按逾期天数降序 |
| 「成都蜀工的风险订单有哪些」 | 按客户过滤的异常清单 |
| 「卡在出库的有多少单」 | 按卡点聚合的计数 + 明细 |
| 「哪些单是缺件导致的」 | R7 根因清单 |
| 「这个月 OTIF 是多少」 | OTIF + OT / IF 拆解 + 口径说明 |

**不支持**：跨订单的合并收款拆分查询（本期不做）、总账与发票查询（出界）。

---

## 六、异常闭环操作（五步）

```
① 系统检出异常
   → ② 人工确认是否成立（不成立则驳回，记录原因）
   → ③ 建异常单 → 按规则自动分派责任人 → 企微/邮件推送
   → ④ 责任人处理 → 填写处理意见 + 原因码 → 提交
   → ⑤ 系统回写主表状态 + 归档异常记录
```

**超时升级**：L1 触发即推，不升级；持续 **2 个扫描周期**未处理升 L2；**48 小时**未处置升 L3 并进周报 Top 榜。

---

## 七、周报生成

- 触发：每周一 07:30 自动生成底稿。
- 内容：OTIF 与 OT/IF 拆解 + 滞留 Top 10 + 逾期 Top 10 + 异常原因码分布。
- **必须人工复核后才能对外发布**——系统出的是底稿，不是成品。口径确认、结论措辞由人负责。

---

## 八、常见问题与排错

| 现象 | 原因 | 处理 |
|---|---|---|
| `verify.py` 报「异常总数 != 基准」 | 数据被改过或重新造数了 | 用 runner.py 重跑，同步更新 `BASE_*` |
| 某单没被判定 | 状态值不在 13 态枚举内，或必填时间为空 | 检查状态格式与必填列 |
| OTIF 异常高（接近 100%） | 签收时间被填成了出库时间 | 校正为真实 POD 时间 |
| 告警特别多 | 阈值偏紧 | 校准阈值，目标占比 8%~15% |
| 缺件单还在催出库 | 缺件标志没同步到 `08-缺件标志` | 补齐 DS8 数据，E5 抑制才会生效 |
| 账龄金额比财务手工数大 | 用了整单应收而非未核销余额 | 检查是否已导入全部收款记录 |
| 订单号重复 | 主数据问题 | 系统自动挂起该行并转人工核对，**不会**静默处理 |

---

## 九、红线（不可违反）

1. **不自动改订单、不自动下发指令**——AI 只判定提醒，动作由人发起。
2. **不自动发催款函**——涉及对客户的外发动作，必须人工确认。
3. **缺数据不能报「无异常」**——数据缺失必须显式标注为"数据不足，无法判定"（E8）。
4. **口头变更交期无效**——必须有留痕记录才改状态（E6）。
5. **不承诺未实测的效果**——K2（盯单耗时）、K3（周报耗时）是目标值，实测校准后才能写进验收报告。
6. **对外演示数据须脱敏**——客户名称、金额、联系人不得带出。

---

## 十、从 POC 到生产的切换清单

| POC 做法 | 生产版替换 |
|---|---|
| 本地 CSV | 简道云表单（履约跟踪主表 + 履约异常记录表 + 8 张节点表），或 ERP/财务/TMS 直连 |
| `python runner.py` 手动跑 | 简道云定时触发（08:30 全量 / 18:00 增量 / 周一 07:30 周报） |
| 结果写 CSV | 写入异常记录表 + 企微/邮件推送 |
| 阈值写死在脚本 | 阈值配置表，业务可自助调整 |
| 模拟数据 | 客户真实数据，先跑 3 个月历史校准阈值 |

**字段映射**（POC 列名 → 生产语义）见 `04-skill包/order-fulfillment-tracker/references/template-map.md`。生产版按**语义指纹**（字段标签）匹配，**不要硬编码字段 key**。