#WageKit

#60 秒评审路径

1. 看著名陷阱：moon test 里的 every cliff jumps at the twelfth fen past its edge 用例——年终奖 36,000 元缴税 1,080 元，36,001 元缴税 3,390.10 元，多发一元，到手少 2,309.10 元（精确跳档点在 36,000.12 元，测试按分穷举 6 档边界）；
2. 跑独立 oracle：python tests/oracle.py 3000——Python Decimal 按官方口径独立实现同一套规则，3,000 组随机工资逐字段对比；
3. 生成工资条：node bin/wagekit.mjs examples/months.json --md，输出样张见 examples/expected-output.md；
4. 想看与现有项目的关系：本 README「与现有项目的关系」。

#四种人用它做什么

#三个完整用例

#1. 累计预扣的跨月正确性

#2. 年终奖临界点

#3. 劳务报酬并入伍算的退税

node bin/wagekit.mjs examples/settlement.json
# {"settlement":{"tax_due":69000,"prepaid":205000,"refund":136000,"payable":0,...}}

#4. 工资条

#5. 反推：到手 20,000 该开多少税前

cat > /tmp/offer.json <<'JSON'
{"year":2026,"months":[{"gross":0,"social":0,"special":300000,"other":0}],"target_net":2000000}
JSON
node bin/wagekit.mjs /tmp/offer.json

#6. 税额分解：为什么是这个数

{"month":3,"taxable_cum":6600000,"bracket":2,"rate":10,"quick":252000,
 "tax_cum":408000,"withheld":220000,"formula":"66000.00 × 10% − 2520.00 = 4080.00"}

#7. 批量：一张表出全员工资条

node bin/batch.mjs examples/employees.csv --out payslips
# 已生成 3 份工资条 → /path/to/payslips
# 月度预扣个税合计 2836.00 元｜月实发合计 89864.00 元
# 年终奖按单独计税合计 12870.00 元（是否更省见每份工资条的对比）

#怎么嵌入（一个只用 pub 接口的消费端）

let inputs : Array[@wagekit.MonthInput] = [
  { gross: 3_000_000L, social: 300_000L, special: 100_000L, other: 0L },
]
let schedule = @wagekit.cumulative_withholding(inputs)          // 逐月预扣
let why = @wagekit.explain_withholding(rules, inputs)           // 为什么是这个数
let offer = @wagekit.gross_up(2_000_000L, 300_000L, 0L, 0L)     // 到手反推税前
let impact = @wagekit.policy_impact(rules, candidate, inputs)    // 换版影响面

moon run examples/embed
# 本月预扣 630.00 元
# 档位 1：21000.00 × 3% − 0.00 = 630.00
# 到手 20000.00 元需要税前 23463.92 元（精确）
# 起征点 6000：全年少扣 30.00 元

#验证

moon check --target all --deny-warn   # 四目标零警告
moon run examples/embed               # 嵌入示例（只用 pub 接口）
moon test --deny-warn                 # 单元测试：临界点穷举、状态机不变量、舍入口径、反推往返
node scripts/build.mjs
node --test tests/cli.test.mjs tests/batch.test.mjs # 21 pass
node bin/wagekit.mjs examples/months.json          # JSON 报告
node bin/wagekit.mjs examples/months.json --md     # 全年工资条（Markdown）
node bin/wagekit.mjs examples/explain-grossup.json # 税额分解 + 反推
node bin/wagekit.mjs examples/settlement.json      # 年度汇算：应退 1,360 元
node bin/wagekit.mjs examples/policy-preview.json  # 起征点改 6,000 的影响面
python tests/oracle.py 3000           # 独立 Decimal oracle，逐字段对比

#批量性能（可复现）

node scripts/build.mjs
node bench/bench.mjs 1000 5

#为什么不是 Excel 或在线计算器

#与现有项目的关系（主动披露）

#边界（明确不做）

• 不做社保实缴对接、专项附加扣除的申报流程、汇算清缴申报；
• 各地社保基数上下限首期仅内置五城示例参数（标注 EXAMPLE），按城市扩展是数据工作；
• 不提供税务建议；计算结果以主管税务机关口径为准；
• 计算口径（舍入、临界点、并入伍算）固定在 docs/SEMANTICS.md，评审可逐条核对。