工期计算 Pro
> 定位：把"数工作日"从"只能剔周末"升级为周休 + 节假日 + 调休补班三项合成的排期口径。
> 上游轻量件 workday-calculator 只做单点；本件处理真实排期里绕不开的补班、单休、端点口径。
> 运行声明：核心判定引擎在本机执行（scripts/main.py），只读处理目标，不修改不回写；不采集、不上传任何用户数据与文件内容。唯一出网动作 = 按次计费验付：未携付款凭证时向官方 402 计费端点取账单，付款后携凭证重新验付；除此以外不向任何第三方发起请求。
一、何时使用
触发关键词：工作日计算、工期计算、算工作日、调休补班、单休排班、项目排期、请假天数、排班日历。
负向清单（本件不做）：替使用者推断法定假期政策、农历换算、跨多套排班制的人力排班优化
→ 此类场景请人工核定或走对应高档件通道（见第九节）。
二、怎么用（本机计算 · 按次计费）
本包为付费件：核心引擎在本机执行（scripts/main.py），按次计费经官方 402 计费端点结算（计费需联网）。未携付款凭证时返回 402 账单、不计算不交付；付款后携凭证重试即出结果。
cd mid/workday-calculator-pro
python scripts/main.py 2026-10-01 2026-10-10
python scripts/main.py 2026-10-01 2026-10-10 --payment-proof <支付凭证>
常用参数示例：
python scripts/main.py 2026-10-01 2026-10-11 --holidays-file hol.txt --makeup 2026-10-11 --payment-proof <凭证>
python scripts/main.py 2026-10-05 2026-10-09 --off-days 6 --payment-proof <凭证> # 单休（仅周日休）
python scripts/main.py 2026-10-05 2026-10-09 --holidays 2026-10-07 --json --payment-proof <凭证>
完整参数表与退出码见 scripts/main.py --help（计费与 402 契约详见下文计费段）。
计费与结算契约（官方 402 计费端点 · 按次结算）：
- 本件按次计费 ¥0.99/次：未携有效付款凭证时返回 HTTP 402 与本次账单（含金额、订单号、支付截止时间），不计算、不交付、不写任何业务文件；
- 完成支付后携付款凭证（--payment-proof）重试同一调用，端点验付通过后才进入本机计算并输出结果；
- 同一组参数对应同一订单（端点按请求体幂等），重试不会重复下单；金额或订单核对不符即拒绝履约；
- 唯一出网目标 = 官方 402 计费端点 https://aitoolgate.cn:8443/api/workday，仅用于取账单与验付；不向任何第三方发起请求，不上传用户数据或文件内容；
- 计费端点不可达时 不产出结果（付费件计费不可用即不出货），并明确提示「未扣费」。
三、判定逻辑（本地规则引擎）
parse_date（四种日期写法）→ normalize_date_list（str / list / date 三态归一，继承并锁死上游
"字符串假日被静默忽略"的缺陷修复）→ 逐日扫描 [start, end]，按补班 > 周休 > 节假日 > 其余
的优先级判定每一天 → 汇总为 日历天 / 常规周休 / 命中节假日 / 调休补班计入 / 工作日天数
五项计数，可选输出逐日明细与 JSON。同时被列为节假日与补班日的日期按补班计，并在
conflicts 中显式列出，不静默吞掉。
四、样例（异常样例≥2·含真实输出）
$ python scripts/main.py 2026-10-01 2026-10-11 --holidays-file hol.txt --makeup 2026-10-11
$ echo $?
3
（本件按次价 ¥0.99，三处同价：服务端账单＝包内 meta＝上架展示。）
$ python scripts/main.py 2026-10-01 2026-10-11 --holidays 2026-10-07 --payment-proof mock-proof-ord_bad000000000000
$ echo $?
3
样例 3 · 凭证含非 ASCII 字符（客户端前置拦截，退出码非 0）
$ python scripts/main.py 2026-10-01 2026-10-11 --payment-proof <含中文的串>
样例 4 · 输入类错误在本机校验
日期非法、区间倒置、周休日越界、日历文件缺失等输入类错误：一律在本机校验并以退出码 2 返回中文错误信息，不发起计费请求、不扣费、不产出结果。
五、端到端实测留痕（真实命令与真实输出 · 402 全流程）
正常用例 A · 节假日文件 + 调休补班（402 账单 → 付款 → 验付 → 结果履约）
$ cat hol.txt
# 2026 假期节选
2026-10-07
2026-10-08
$ python scripts/main.py 2026-10-01 2026-10-11 --holidays-file hol.txt --makeup 2026-10-11
$ echo $?
3
$ python scripts/main.py 2026-10-01 2026-10-11 --holidays-file hol.txt --makeup 2026-10-11 --payment-proof <支付凭证>
工作日天数: 6（区间 2026-10-01 ~ 2026-10-11）
（履约回执 order=ord_816516aaf16963aafc · 走标准错误输出，不打断 --json 管道）
$ echo $?
0
（工作日 6 天与开发态同源内核自测用例一致，交叉印证计算正确。按次价 ¥0.99＝中档档位价。）
正常用例 B · JSON 机器可读
$ python scripts/main.py 2026-10-05 2026-10-09 --holidays 2026-10-07 --json --payment-proof <支付凭证>
{"tool":"workday-calculator-pro","version":"1.0.6","start":"2026-10-05","end":"2026-10-09","include_start":true,"include_end":true,"off_days":["周六","周日"],"holidays":["2026-10-07"],"makeup_workdays":[],"conflicts":[],"span_days":5,"workdays":4,"weekoff_days":0,"holiday_days":1,"makeup_days":0,"dates":["2026-10-05","2026-10-06","2026-10-08","2026-10-09"]}
（履约回执 order=ord_41439e415ad8bc8174 · 走标准错误输出）
$ echo $?
0
（字段与取值和开发态同源内核输出逐字一致；dates 已正确跳过周末与节假日 10-07。）
> 开发态自测（规则引擎 24/24 断言）于开发环境留痕存档；发布包不含自测文件，核心引擎 scripts/main.py 随包发布。
六、结果摘要
- 输出：工作日天数 + 日历天／周休／节假日／补班四项拆分计数。
- 可选产出：逐日明细（
--list-dates）、结构化 JSON（--json）、报告文件（--out）。 - 口径：区间含/不含端点可调，周休日可自定义，节假日与补班由使用者显式提供。
- 边界：不推断法定假期政策、不含农历、不含跨多套排班制优化。
- 运行：规则计算在本机执行（scripts/main.py），不修改不回写用户文件；计费验付是唯一出网动作。
- 失败面：输入类错误在本机校验后返回错误信息，不产出结果、不计次、不发起计费。
- 自测：规则引擎开发态自测 24 项断言全通过（函数层 8 项 + CLI 正常 7 项 + CLI 异常 9 项，开发环境留痕）。
七、按次权益与交付说明
> 付费件声明：核心引擎在本机执行；按次计费经官方 402 计费端点结算；除计费验付外不发起任何网络请求。
1. 单次调用即完整功能：每一次调用都启用本件全部能力（节假日批量导入、调休补班、
自定义周休、端点取舍、明细与 JSON），不存在功能阉割的"试用态"。
2. 按次调用不交付明文：按次调用以"返回计算结果"的方式交付，不向使用者交付本件脚本
源码、配置与内部实现等明文产物；使用者拿到的是结果，不是本件的实现文件。
需要源码级交付的场景，请走对应的高档件通道（见第九节）。
3. 调用计数口径（一次算一次，如实计）：
- 一次调用 = 本件被触发一次，并完整执行到结果输出，计 1 次；
- 参数错误、输入不存在、未产出结果的调用（退出码非 0 且不产出结果）不计次；
- 仅查看用法/版本、未产出结果的调用不计次；
- 中途被中断或未执行完成的调用不计次；
- 同一命令重复执行 N 遍，各计 N 次（按次按调用计，不按文件/按行/按文件大小折算）。
八、更新承诺
承诺：自交付日起 12 个月内，对本件存在的 Bug 提供修复更新。
- 覆盖：逻辑错误、参数解析错误、输出数值错误、崩溃类缺陷；复现用例由使用者提供。
- 不视为 Bug：Excel/排期口径本身的理解差异、使用者自备数据错误、平台环境变更导致的外部失效。
- 修复方式：更新件内脚本后重新交付，历史次的调用结果不受影响。
九、中→高 CTA（文案位）
> 排期口径再往上走：多套排班制、倒班/轮班表、跨部门工时汇总、假期政策自动对齐、
> 与项目里程碑联动的工时与瓶颈推算——这类场景已超出本件范围。
> 需要一步到位的排期与工时方案，请看更高档的排期工时件（详见同系列高档件页面）。
> 本件继续做你每天的"数日子"，高档件做你整个项目的"排期账"。
十、四防声明与"不交付明文"口径
- 防泄露：本件无密钥、无私有数据、无后门；核心引擎在本机执行（scripts/main.py），除计费验付外无其他网络请求，无隐藏文件。
- 防转发：请从官方渠道获取；转发请保留本声明。
- 防破解：引擎在本机执行，规则计算不依赖服务端；篡改重打包与本源件指纹不符。
- 防抄袭：原创性指纹由开发方留存备查，不随包发布（AS-IS）。
- 不交付明文：按次调用只交付计算结果，不交付本件源码与内部实现文件（见第七节第 2 条）。
十一、边界（严格遵守）
- 只读：不修改、移动、删除用户文件；除落盘交付文件与标准输出外不产生其他写动作，网络请求仅限计费验付。
- 不猜：政策类信息（哪天放假、哪天补班）必须由使用者显式提供，本件不自行推断。
- 不越权：超出本件范围即升档提示，不硬撑。
十二、免责与责任
本工具仅提供操作辅助与流程指引，不承诺任何效果或收益；因使用本工具产生的任何直接或间接损失，
责任由使用者自行承担；在法律允许的最大范围内，开发者不以任何方式承担责任（法律强制规定的责任除外）。
- 按现状（AS-IS）提供，不附带任何明示或默示保证；
- 节假日与补班政策随年份变化，本件不跟进政策更新，须使用者自行提供准确日历；
- 输出结果仅供决策参考，重大事项（合同条款工期、法定时效）须使用者自行复核。
