From fa8aee91b95cd8569bfe86ccd260082eaf299285 Mon Sep 17 00:00:00 2001
From: ar51 <th5-ar51@TH5-AR51deMacBook-Pro.local>
Date: Wed, 2 Sep 2026 18:30:32 +0800
Subject: [PATCH] docs: add AM516 workday conversion handoff

---
 ...自然日转工作日需求说明_给AR836_20260902.md | 140 ++++++++++++++++++
 1 file changed, 140 insertions(+)
 create mode 100644 capabilities/am516-delivery-prediction/docs/AM516自然日转工作日需求说明_给AR836_20260902.md

diff --git a/capabilities/am516-delivery-prediction/docs/AM516自然日转工作日需求说明_给AR836_20260902.md b/capabilities/am516-delivery-prediction/docs/AM516自然日转工作日需求说明_给AR836_20260902.md
new file mode 100644
index 0000000..724c1f8
--- /dev/null
+++ b/capabilities/am516-delivery-prediction/docs/AM516自然日转工作日需求说明_给AR836_20260902.md
@@ -0,0 +1,140 @@
+# AM516 自然日交期转换为工作日需求说明
+
+**需求提出人**：AR51
+**需求接收人**：AR836
+**日期**：2026-09-02
+**目的**：将 AM516 交期预测输出的自然日转换为工作日，并据此得到最终交货日期。
+
+## 一、需求背景
+
+AM516 当前输出的是自然日交期。销售希望得到工作日口径的交期，即：
+
+1. 预计需要多少个工作日；
+2. 按这些工作日推算出的最终交货日期。
+
+本需求只增加自然日到工作日的转换，不修改其他交期预测逻辑。
+
+## 二、最终实现逻辑
+
+### 第一步：自然日转换为工作日
+
+设 AM516 输出的自然日交期为 `N`：
+
+```text
+(q, r) = divmod(N, 7)
+```
+
+- `q`：完整的7天周期数量；
+- `r`：除以7后的余数；
+- 每个完整的7天周期按5个工作日计算。
+
+余数按以下规则转换：
+
+| 余数 | 余数中的休息日 | 余数对应工作日 |
+|---|---:|---:|
+| `r = 0` | 0天 | 0天 |
+| `1 ≤ r ≤ 4` | 1天 | `MAX(r - 1, 0)` |
+| `5 ≤ r ≤ 6` | 2天 | `r - 2` |
+
+最终公式：
+
+```text
+当 r = 0：
+W = q × 5
+
+当 1 ≤ r ≤ 4：
+W = q × 5 + MAX(r - 1, 0)
+
+当 5 ≤ r ≤ 6：
+W = q × 5 + r - 2
+```
+
+其中 `W` 为换算后的工作日交期。
+
+本轮测试中，余数等于4时按1个休息日处理。
+
+### 第二步：由工作日推算最终交货日期
+
+```text
+最终交货日期 = 从计算当天开始，向后累计 W 个国家法定工作日
+```
+
+计算当天不计入，从下一天开始累计。日期计算必须使用国家公布的实际工作日历：
+
+- 法定节假日不计为工作日；
+- 普通周六、周日不计为工作日；
+- 调休上班的周六、周日计为工作日。
+
+系统最终保留和使用三个结果：
+
+- 原始自然日交期 `N`；
+- 换算后的工作日交期 `W`；
+- 按国家法定工作日历推算的最终交货日期。
+
+## 三、国庆例外仅用于本次验证
+
+国庆例外不是最终系统逻辑，也不是最终输出字段，仅用于本次数据验证和对比。
+
+本次验证起始日为2026年9月2日。为了与 ERP 原始日期进行对比，临时采用：
+
+```text
+如果 ERP 原始日期晚于2026年10月1日：
+    ERP验证对比日期 = ERP原始日期 + 7个自然日
+否则：
+    ERP验证对比日期 = ERP原始日期
+```
+
+该规则不加入工作日数量 `W`，也不加入最终交货日期的正式计算逻辑。正式计算最终交货日期时，国庆假期已经由国家法定工作日历处理。
+
+系统不需要输出 ERP 验证对比日期或日期差异。
+
+## 四、本次测试数据
+
+测试口径：
+
+- 计算起始日：2026年9月2日；
+- 起始日当天不计；
+- 工作日交期按第二章规则转换；
+- 最终交货日期按2026年国家实际工作日历累计；
+- 国庆例外只用于本表验证。
+
+2026年相关工作日历：
+
+- 9月25日至27日放假；
+- 10月1日至7日放假；
+- 9月20日、10月10日调休上班。
+
+来源：[中国政府网｜国务院办公厅关于2026年部分节假日安排的通知](https://www.gov.cn/zhengce/zhengceku/202511/content_7047091.htm)
+
+| ERP原始日期 | 原始自然日 `N` | 商与余数 | 换算工作日 `W` | 按工作日推算的交货日期 | 验证用ERP对比日期 | 验证结果 |
+|---|---:|---|---:|---|---|---|
+| 2026-09-20 | 18天 | 2周余4天 | 13天 | 2026-09-20 | 2026-09-20 | 一致 |
+| 2026-09-25 | 23天 | 3周余2天 | 16天 | 2026-09-23 | 2026-09-25 | 早1个工作日 |
+| 2026-09-28 | 26天 | 3周余5天 | 18天 | 2026-09-28 | 2026-09-28 | 一致 |
+| 2026-09-18 | 16天 | 2周余2天 | 11天 | 2026-09-17 | 2026-09-18 | 早1个工作日 |
+| 2026-10-03 | 31天 | 4周余3天 | 22天 | 2026-10-09 | 2026-10-10 | 早1个工作日 |
+| 2026-10-05 | 33天 | 4周余5天 | 23天 | 2026-10-10 | 2026-10-12 | 早1个工作日 |
+| 2026-10-08 | 36天 | 5周余1天 | 25天 | 2026-10-13 | 2026-10-15 | 早2个工作日 |
+| 2026-10-15 | 43天 | 6周余1天 | 30天 | 2026-10-20 | 2026-10-22 | 早2个工作日 |
+| 2026-10-20 | 48天 | 6周余6天 | 34天 | 2026-10-26 | 2026-10-27 | 早1个工作日 |
+
+本次测试只用于观察换算方法与 ERP 日期的接近程度，不要求 AR836 在系统中实现或输出对比结果。
+
+## 五、给 AR836 的修改要求
+
+只需实现以下两项：
+
+1. 将 AM516 输出的自然日交期 `N` 按第二章余数规则转换为工作日交期 `W`。
+2. 以计算当天为起点，按国家法定工作日历向后累计 `W` 个工作日，得到最终交货日期。
+
+输出保留：
+
+- 原始自然日交期；
+- 换算后的工作日交期；
+- 最终交货日期。
+
+无需实现或输出：
+
+- ERP 验证对比日期；
+- 工作日结果与 ERP 日期的差异；
+- 本次测试中的国庆临时顺延规则。