payroll-prep

工资准备

确保每个人领工资前，工时都是准确的。

工资发放是财务工作流中容错空间最小的环节。一张错误的发票下周还能更正，但一笔错误的工资意味着有人无法支付房租，而且这是老板最快失去团队的方式。本技能的设计都围绕这种不对称性展开：机器负责汇总和核对，老板负责决定。

第一步——先确定工资周期

确认工资周期的开始和结束日期、发薪日，以及本次发放涉及哪些人员。周期出错会导致某人的一周工资被重复计算或遗漏，而且当周期横跨月末时，这种错误出奇地容易发生。

同时确认员工名单：包括周期中途入职的新员工、已离职的员工，以及休假中的员工。参见 reference/timesheet_intake.md。

第二步——拉取工时表

已连接 Gusto 时，在开始构建任何内容之前，先向 Gusto 本身询问有哪些阻碍事项：调用其工资阻碍项检查（list_payroll_blockers）。如果返回了阻碍项，请逐条用通俗的语言解释：它是什么意思、由谁处理、在哪里处理。例如："check payments unsupported"表示该公司通过纸质支票付款，而本集成无法生成此类付款，因此需要老板直接在 Gusto 中处理这部分；"bank account not connected via Plaid"表示老板需要在 Gusto 的设置中连接银行账户；"hourly employees unsupported"即使本次发放只涉及薪资员工，也可能在账户层面造成阻碍。阻碍项只是一种路由信号，并不代表失败：本次运行仍会在此构建和校验，交付物则是附带阻碍项清单的发放表。

然后分别通过各自的工具拉取该周期的输入数据。**工时：**调用 list_time_records 获取该工资周期的数据，并先读取其 source 字段。native 返回包含上下班打卡时间和休息时间的班次记录；third_party 返回来自公司考勤合作伙伴的工时表，而 get_time_sheet 可为其中任一工时表提供逐日明细（它会拒绝 native 班次 ID）；none 表示 Gusto 中没有该公司的工时数据，此时由下文的电子表格路径提供工时。**假期：**调用 list_time_off_requests 并筛选该周期内 status: approved 的记录——每个已批准的日期都按带薪休假或病假发放，绝不按出勤计算，待审批的申请只作为标记，不计为带薪日。**余额：**调用 get_time_off_balances，第四步中的"PTO 超出可用余额"检查即以此为依据。**费率与岗位分类：**通过 list_employees 获取员工名单及每人的薪酬信息。费率一律来自 Gusto，绝不来自工时表。这些接口的调用格式见 ../../shared/connector-call-shapes.md。

**老板可以补填的缺失打卡记录。**当第四步标记某个班次缺少下班打卡，且老板提供了真实时间时，可使用 record_time 写入——仅写入老板提供的时间，并先向老板展示，且以对现有班次的 update 方式写入，而不是新增一条记录。若缺少则会被拒绝的参数（时区、Gusto 自身考勤中的岗位、哪个 ID 对应该班次），以及唯一需要注意的重复读取陷阱（承包商已确认的工时返回时打卡时间为空，此时不要再次写入），都记录在 ../../shared/connector-call-shapes.md 中的 record_time 条目里。调用前请先阅读该条目。这是本技能修改打卡记录的唯一途径；绝不写入推测的时间。

**在暂存任何数据之前，先确认数据源确实返回了数据。**拉取员工名单（list_employees）和排班表（list_pay_schedules）。如果公司报告了员工人数，但这两个列表中任何一个为空，或者阻碍项检查返回错误而非结果，那么该工资数据源虽已连接，但实际上并未提供数据。此时应停止暂存路径，用一句话说明（"Gusto 已连接，但未返回任何员工或工资排期，因此我无法基于它暂存工资发放"），并提供下文的电子表格路径。切勿基于空的员工名单构建工资发放，也不要把绿色的连接状态标识当作数据已到位的证明。 连接 QuickBooks Payroll 后，从那里提取相同的字段。这里有两种看起来相似的故障，但业主感知它们的方式不同。数据源为空（Gusto 的列表对一家报告了员工人数的公司返回零行）属于数据缺失：需要说明，并改用运行表。数据源自相矛盾则是工具缺陷：qbo_payroll_get_company_payroll_readiness 返回 has_employees: false 和 run_payroll_ready: false，而同一公司的 qbo_payroll_get_employees 返回 total_count 为 50，这两者不可能同时成立。这与公司拥有多少数据无关。出现这种情况时，应使用员工列表作为花名册（因为它是返回了数据行的那个调用），在就绪检查显示未就绪时不要准备发放工资，并在一行内同时向业主说明两个数字，使这一矛盾被记录在案，而不是被"未就绪"掩盖。随后按下文的表格路径，以该花名册进行处理：业主据以录入 QuickBooks Payroll 的、经过验证的运行表就是最终结果，与数据源为空的情况相同。这是一等数据源，而不是备用方案。它包含完整的员工花名册（薪资类型、费率和发放频率、雇佣状态以及 PTO 政策余额）；薪资周期及其频率；以及最近一次已完成的发薪记录（包括每位员工的税前总薪、工时和税务项目）。如果工时来自考勤表，记录中会注明，这正是步骤 4 中异常检查所需要的。

针对此数据源有两点注意事项。员工的雇佣状态与在职标记是分开的，因此被标记为在职的人员仍可能未在薪资名单上或处于带薪休假状态；在将任何人纳入运行之前，两者都要查看。此外，单个员工可能有十几个甚至更多薪资费率，其中大多数工时为零，因此应以实际有工时的那个费率进行合计，而不是列表中的第一个费率。

两者都没有时，则采用上传的电子表格或 CSV 文件。这是完全受支持的路径，业主据以录入其薪资服务商的、经过验证的运行表即为完整的结果。许多小型工作组仍使用周末拍照留存的纸质考勤表，这同样可行。

将数据规范化为每人每天一行：日期、上班、下班、休息、常规工时、加班工时、PTO，以及（如果企业按项目或工种核算人工）所属项目或工种。

步骤 3 — 合计工时

按人统计常规、加班、双倍加班、PTO、节假日和无薪工时，然后按班组统计，最后汇总整个运行。

加班规则因州以及企业对员工的分类方式而异，计算错误会导致员工少发工资。应采用业主明确说明的规则；若没有，则采用常见的每周加班默认规则，并说明所采用的规则。reference/anomaly_rules.md 涵盖了计算中的特殊情况，包括周中费率变更、一天多个项目以及跨午夜的班次。

切勿用假定的时间填补缺失的打卡记录。 只有上班打卡而没有下班打卡的班次，其工时未知，而未知工时正是需要上报的内容。

步骤 4 — 标记所有异常

这是本技能的核心。运行 reference/anomaly_rules.md 中的完整检查，并列出发现的所有问题，每项都注明员工姓名、日期以及具体的异常之处：

• 缺失打卡以及没有下班打卡的班次
• 超出该员工正常水平的加班，并附上两个对比数字
• 通常工作的员工工时为零
• 工时远超排班安排
• 自上次运行以来的费率变更
• 重复或重叠的记录
• 超出可用余额的 PTO 休假
• 上一周期发过工资但本期缺失的人员
• 出现新员工但没有入职记录

标记事项须交由业主处理，绝不静默修正。 缺失的打卡记录只有员工本人和业主才知道正确答案，而在此处做出看似合理的猜测，最终会变成一张看似正确、实则有误的工资单。

第 5 步 — 审核本次发薪再批准

展示发薪明细表：逐人列出工时（按类型）、税前工资，以及每位员工名下的所有标记。然后汇总总数：总工时、税前工资总额、雇主税费和缴款（如有数据）、所需现金总额以及发薪日期。

与上一周期对比，并说明任何超过 10% 的变动。如果发薪总额增加了 4,000 美元，必须有原因，业主应从本技能处得知，而不是在银行余额里才发现。

如果有现金数据，说明本次发薪能否顺利完成；如果没有，直接说明，不要暗示没有问题。

第 6 步 — 逐个处理标记

逐一向业主说明每个标记：发现了什么、如果保持原样会带来什么影响，以及业主希望如何处理。记录答复并执行。

不要把标记合并成一个“看起来没问题吧？”的问题。每一项都关系到某位员工的工资。

第 7 步 — 审批关口

在业主明确批准本次发薪之前，不得进行任何暂存操作。

在提问之前，需明确说明：员工人数、总工时、税前工资总额、将从账户转出的现金总额、发薪日期，以及业主选择保留未处理的标记数量。

然后提问。如果业主想跳过此关口，应告知一次即可，不必说教：保留此关口是因为直接存款到账后，错误的发薪无法撤回。

如果已连接 Gusto，则进行暂存：使用 list_payrolls，筛选条件为 processing_statuses: unprocessed，并将 end_date 设为几周之后的日期（其日期筛选基于薪资周期，直接调用可能会漏掉尚未结束的周期）；从中选取发放日最近的一条；用 get_payroll 读取；然后用 update_payroll 写入已批准的工时、带薪休假以及任何奖金条目。有两种调用形式很重要，两者都记录在 ../../shared/connector-call-shapes.md 中：数值是替换而非累加，因此“给 Maria 增加五小时”意味着发送她的新总数，并先向业主展示为“40 → 45”；如果发薪单的员工名单尚未生成，则需先用一次空的 update_payroll 调用来填充，再进行正式调用。请勿执行 run_payroll，那是业主在 Gusto 中自己操作的按钮。如果已连接 QuickBooks Payroll，连接器负责读取（员工名单、费率、排期、就绪状态、上一次发薪），且不提供暂存写入功能，因此这里的结果是业主手动录入的已验证发薪明细表；这是连接器目前支持的方式，而非降级方案。两个系统中均由业主提交。如果两者都未连接，则生成已验证的发薪明细表供手动录入。如果第 2 步中 Gusto 的阻碍因素导致无法通过连接进行暂存，那么已验证的发薪明细表加上用通俗语言列出的阻碍清单即为最终结果——需明确说明，但不应视为失败。

第 8 步 — 同步到账簿

本次发薪提交后，将日记账分录过入总账：税前工资、雇主税费，以及分配到项目的人工成本。应检验的是功能而非品牌：如果已连接的总账其连接器没有日记账写入路径，则无法完成过账，需用一行说明此情况，并将平衡的分录交给业主或簿记员手动录入——这是完整的结果，而非失败。确认金额与实际发放的一致，而非原先的预案金额——只要业主在上一步修改过任何内容，两者就会不同。

不要做的事

• 不要猜测打卡记录、费率或分类。 对于未知的工时，需与相关人员及日期一并标注出来。
• 不要悄悄修正异常， 即使异常看起来很明显。负责人可能掌握你不了解的情况。
• 不要提交工资。 只做暂存，由负责人提交。本 Skill 从不调用 run_payroll。这一点对 QuickBooks Payroll 同样适用，与对 Gusto 一样——连接了工资系统并不等于获得了运行工资的许可。
• 不要向 update_payroll 发送增量。 它的数值是替换而非累加。应先从 get_payroll 计算新的总额，同时展示两个数字，然后发送总额。
• 不要写入负责人未说明的打卡记录。 record_time 只能录入负责人给出的时间，并且只能在他们看过记录之后才能录入。
• 不要在未核对工时的情况下读取工资费率。 在 QuickBooks Payroll 中，一个人可能对应多个费率，其中大多数费率的工时为零。
• 不要把标记隐藏在摘要里。 应将每个标记附在受其影响的人员身上。
• 不要批量处理标记审核。 每个人每个问题都需要单独做出决定。
• 不要把缺失的连接器视为阻碍。 输入电子表格、输出经过验证的运行表，是本 Skill 设计好的路径。
• 不要跳过上一期对比。 数值大幅变动却没有解释，是最有价值的预警信号。
• 不要从报告有员工但返回为空的工资数据源暂存运行。 已连接并不等于有数据。应说明该数据源没有返回数据，并改用电子表格路径。
• 不要在运行表、对话或任何渲染页面中复现员工的社会安全号码、出生日期、家庭住址、银行或银行卡号。 Gusto 和 QuickBooks Payroll 的数据载荷中包含这些信息；应跳过这些字段（../../shared/personal-data.md）。

输出

按负责人保存的输出偏好交付经过验证的运行表——绝不默认生成 Markdown 文件。 请检查 ## Business context 区块中的 Output preference（共享样式指南规则，../../shared/artifact-style.md）：

• 可视化产物（默认）： 以本站风格将运行表渲染为 HTML 页面——人数、工资总额以及从账户流出的现金以统计卡片展示，每人一行并以等宽数字显示工时和薪酬，每个标记以胶囊标签形式附在对应的人员上。若 Gusto 报告了阻碍项，则单独放入一个用通俗英文描述的面板。
• 偏好 docx / md / notion / canva： 以该形式交付相同内容——DOCX 或 Markdown 文件；通过连接器创建的 Notion 页面（指定目标名称，绝不覆盖已有页面）；或通过 Canva 连接器创建的 Canva 文档（每次运行新建一个设计，以日期命名；表格转为列表）。若未连接 Notion 或 Canva，则回退为可视化产物，并说明原因。
• Skill 最佳形式： 使用可视化产物——该输出是负责人逐人审批的表单。

运行之后

运行已暂存，标记已处理，账簿分录已过账。如果运行前最担心的是现金，自然的下一步是“我能否发工资”——/plan-payroll 会在下一次运行前进行预测并追讨发票。相关的还有：“现金预测”（cash-flow-snapshot），用于查看本次运行对未来 30 天的影响；以及“税务”（/tax-prep），适用于季度预估税或 1099 表格即将到期的情况。最多提供三项建议，并跳过负责人本次会话中已拒绝的建议。

参考文件

• reference/timesheet_intake.md — Gusto 数据拉取、电子表格上传、名册与周期设置
• reference/anomaly_rules.md — 每项检查、其阈值及表述方式
• reference/run_sheet_format.md — 运行表版式及合计区块
• reference/books_sync.md — 日记账分录结构与工作成本分摊
• reference/gotchas.md — 导致员工少领工资或同一周期重复付款的常见错误

使用未列出的工具

本技能中列出的连接器是经过测试的路径，但并非唯一选项。如果所有者希望此流程使用尚未连接或未列出的工具，可以提供 build-connector。它会先检查连接器目录，若目录中没有，则通过 Zapier 进行连接，绝不直接对原始 API 手动构建。连接建立后，该工具会像其他可选连接器一样加入本技能，并受相同的审批关卡约束。