销售周报核验与异常定位 1.0.0
面向每周从订单系统导出订单和退款两份 CSV 的销售运营：输入 CSV + 明确期间 + 时区，
输出可追溯的现金流周报（summary.md）、逐行异常清单（anomalies.csv）、
机器可读汇总（reconciled_totals.json）和运行存证（run_manifest.json）。
只做现金流核验，不做利润、不做会计收入确认、不改动任何系统数据。
适用与不适用
适用：两份 UTF-8 CSV、人民币、按周核对收款/退款/净流入、定位重复与孤儿退款等异常。
不适用（本版明确拒绝）：XLSX 或其他格式、多币种与汇率换算、利润与毛利、
会计收入确认、自动发送周报、直连店铺或订单系统。
快速开始
python3 scripts/audit.py \
--orders examples/normal/orders.csv \
--refunds examples/normal/refunds.csv \
--start 2026-10-19 --end 2026-10-26 \
--timezone Asia/Shanghai \
--output out-2026-10-19
--output 必须是尚不存在的目录；工具不覆盖已有产物，也不修改输入文件。
本仓库自带的最小合成样本（examples/normal）实测结果：
收款 24995 分 / 退款 1990 分 / 净流入 23005 分，状态 ok，退出码 0。
输入契约
| 文件 | 必需列 |
|---|---|
| 订单 CSV | order_id,paid_at,channel,paid_amount_cny |
| 退款 CSV | refund_id,order_id,refunded_at,refund_amount_cny |
- 编码 UTF-8（可带 BOM），标准 CSV 解析，支持引号包裹的中文与内嵌逗号/换行。
- 列名
strip()后不得重名，也不得为空列名：出现空列名（如导出时多出的,,）一律按歧义表头
返回needs_input（empty_header），不会跳过空名继续算。 - 允许额外列；若存在
currency列，该列每行都必须为CNY/RMB，空白按缺值missing_value
拒绝该行，不默认按人民币计入。 - 键一律按表头索引位置取值（不假定
order_id在第 1 列）；字段数与表头不符的行若仍能按
表头索引取到非空键，该键同样计入全表键索引，因此同键的合法行会一起被判为重复并全部排除，
而坏行本身仍保留row_length_mismatch。 - 标识按文本处理，保留前导零。
- 金额：非负十进制、最多 2 位小数，
0/0.00合法；拒绝负号、千分位、货币符号、
科学计数法、NaN/Infinity、超过 2 位小数。内部一律整数分，无浮点。 - 时间：ISO8601 日期时间，可带
Z或±HH:MM偏移；无偏移按--timezone解释。
夏令时跳跃（不存在）或回拨（两解）的时间拒绝该行，不猜测。 - 上限：每文件 10 MiB、每表 100000 条记录，超限拒绝整个输入。
期间口径
[start, end)：起点包含、终点不包含。--start/--end 可写 YYYY-MM-DD
（该时区当日 00:00）或 ISO8601 日期时间。收款按订单支付事件日期，
退款按退款事件日期（可关联期外历史订单），净流入 = 收款 − 退款。
输出契约
| 文件 | 内容 |
|---|---|
summary.md |
人读周报：状态徽标、期间、金额（分与元）、覆盖与排除范围、异常代码分布、口径与限制 |
anomalies.csv |
逐行异常：source_file,table,record_key,row_number,code,reason,next_step，row_number 为原始 CSV 物理行（表头为 1） |
reconciled_totals.json |
固定顶层 status、paid_cents、refund_cents、net_cents（整数分；诊断失败时三者 null），附期间、时区、覆盖说明 |
run_manifest.json |
工具版本、参数、输入 SHA-256 与记录数、产物哈希、限制与确定性声明 |
状态与退出码
| 状态 | 退出码 | 含义 |
|---|---|---|
ok |
0 | 所有提供记录均可核验（含仅表头的空表） |
partial |
1 | 存在行级异常或关联无法核对。非法/重复行整行排除、不计入；孤立退款与超额退款仍计入现金流。报告显著标注部分结果 |
needs_input |
2 | 缺参数/文件/列、重复表头、空列名、无效期间或时区、非 CSV、输出目录已存在 |
error |
3 | 编码错误、CSV 损坏、大小或行数超限、目录不可写 |
失败时同样写 reconciled_totals.json（金额为 null）与诊断版 summary.md，
不产出任何看似完整的成功周报。
异常代码
| 代码 | 含义 | 是否计入现金流 |
|---|---|---|
duplicate_order_id / duplicate_refund_id |
同键多条，全部排除并逐行定位 | 否 |
order_not_found |
退款指向的订单不在提供的订单文件中 | 是 |
order_not_verifiable |
订单存在但该行已被排除，无法核对 | 是 |
excess_refund |
按提供数据累计退款超过订单金额 | 是（仅真实退款额） |
invalid_amount / missing_value / invalid_timestamp / unsupported_currency / row_length_mismatch / empty_row |
行级非法或必需单元格空白（含 currency 列声明存在但值为空），排除该行 |
否 |
anomalies.csv 中的不可信文本做公式注入安全编码（危险前缀加单引号）。
reconciled_totals.json 只含汇总金额与覆盖计数，不含逐行原始记录标识
（原始标识只出现在 anomalies.csv 的 record_key），也不执行任何单元格内容。
“排除”只适用于上表标注「否」的行；标注「是」的关联异常不是排除，
其金额仍留在现金流合计里，故未核验项不等于已排除。
加装与运行
- 依赖：Python 3.9+，仅标准库（
csv、zoneinfo、json、argparse等），无需联网、无需账号。 - 时区数据依赖操作系统 tzdata；精简容器需先安装
tzdata。 - 无安装步骤：把本目录放到任意位置，直接
python3 scripts/audit.py ...。
文件清单
SKILL.md
scripts/audit.py
references/schema.md
templates/orders.csv
templates/refunds.csv
examples/normal/orders.csv
examples/normal/refunds.csv
examples/usage.md
LICENSE.md
NOTICE.md
分发与许可
本版本通过SkillHub社区分发，版权由作者保留。允许下载安装、在个人或组织内部运行、
备份及为内部使用修改，本版本不另收上述使用许可费。再发布、转售、再许可及
对外托管服务转售需另行许可；本包未授予开源许可。后续版本、定制或支持可另行安排。
宿主运行仍可能消耗平台额度。完整条款见 LICENSE.md 与 NOTICE.md。
验证声明
- 已由实现者在本地对本包
examples/normal完成端到端运行（Python 3.13.12 与 3.9.6），
退出码 0，收款 24995 分 / 退款 1990 分 / 净流入 23005 分，四份产物均已读回。 - 未验证：真实客户数据、真实节省时间、Windows/Linux 环境、XLSX 输入、多币种。
- 全部样本为合成数据，不含任何真实客户或个人信息。
