mindxassociates/practice-books-kit

Practice Books Kit — 治疗私人诊所的记账与薪资处理

目的

为私人诊所老板提供一个完整、可重复的财务系统，包含两个部分：

• Part A — 月度记账。 向代理提供该月的银行和信用卡对账单。代理将每笔交易分类到固定的科目表中，并填写损益（P&L）工作表的一个月份列，然后在报告前证明该月数据对平。
• Part B — Practice Books 应用。 代理为老板构建并部署一个小型管理员专用Web应用：用于1099合同工和W-2雇员的月度薪资（薪资运行、工资单、年终总结），以及一个只读的财务仪表盘，可视化Part A中的损益工作表。

这两个部分相互加强：应用中的合同工费用可与损益表核对，仪表盘让老板始终看到当前数据，无需打开工作表。

将此工具交给您的代理（供接收此工具包的同事参考）

将整个文件夹提供给您的AI代理，然后：

1. 回答下面的设置访谈问题——代理应在执行任何其他操作前一次性询问您这些问题。
2. 确认references/categories.md中的科目表——除非某个类别确实不适用于您的诊所，否则保留名称和顺序；代理应在第一次填充前与您确认。
3. 提供一个月的对账单，让代理进行第一次填充。检查其核对结果和需判断的条目列表；纠正一次，代理会将您的裁决记录为未来的固定规则。

设置访谈（一次性收集，记录下来，每月复用）

代理必须在第一次填充或应用构建前收集——且不得猜测——以下信息：

• 诊所信息： 法定名称、所有者姓名、经营所在州、实体类型。
• 账户（仅需最后4位数字作为标签）：
  • 主要企业支票账户（付款人收入进入的账户）。
  • 薪资子账户（如果诊所用其支付合同工）。
  • 税务/储蓄子账户（如有，转入该账户视为内部转账）。
  • 企业信用卡。
  • 所有者的个人/财富账户（接收转账的账户，用于识别所有者提款）。
• 对账单： 所有者每月如何提供对账单（首选CSV导出，如果银行仅提供PDF则接受PDF），以及哪个日期列决定月份（交易日期，而非过账日期，除非所有者另有规定）。
• 支付惯例： 默认是当月1日支付上月工作。确认或记录诊所的实际惯例。
• 人员与支付条款（用于Part B）：每位合同工/雇员，其类型（1099或W-2），以及精确的支付条款——收费百分比、按每次咨询固定费用、按小时或按薪资；任何独立的私人支付/浮动费率拆分；任何经常性扣除（例如EHR座位费）。切勿猜测支付费率。 如果费率缺失，则留空并标记。
• 报表外收入： 明确询问诊所如何接收从未出现在银行对账单中的资金——例如通过Zelle/Venmo/现金/支票支付的督导费或租金。这些款项必须每月从邮件/支付提醒中提取，否则损益表会无意识地少报收入。

Part A — 月度对账单到损益表工作流

参考文件：references/categories.md（科目表 + 分类指南）和references/pl-sheet-spec.md（工作表布局、公式和填充程序）。严格遵守。

1. 收集该月的所有对账单。 主要支票账户、薪资子账户、每张企业信用卡，以及报表外提取（步骤2）。如果缺少某份对账单，请说明情况，并仅根据提供的对账单进行填充——在报告中说明缺口（例如“合同工费用等待薪资账户对账单”），而不是默默地绕过。
2. 提取报表外收入。 搜索所有者该月的邮件/支付提醒（Zelle/Venmo“您收到付款”通知等），并将确认的业务收款及其来源添加到分类账中。在同一提取过程中发现的个人收款将被排除并列出。
3. 解析每份对账单中的每笔交易至一个分类账：日期、来源账户、描述、金额（贷方为正，借方为负）。
4. 排除内部资金流动——既不是收入也不是支出：
   • 诊所自有账户之间的转账（支票账户 ↔ 薪资子账户 ↔ 税务子账户）。
   • 转出至所有者个人/财富账户的转账——这些是所有者提款，绝非费用。
   • 信用卡还款（自动支付或手动）——信用卡的消费是费用；还款只是资金在不同账户间的转移。
5. 使用references/categories.md对剩余每笔交易进行分类。 从薪资账户进行的合同工ACH付款属于合同工费用。如果某笔交易不符合任何规则，将其列入报告的待判断列表——切勿默默地删除，也绝不在未经所有者批准的情况下创建新类别。
6. 按类别汇总为该月的列值（费用为负值）。
7. 根据references/pl-sheet-spec.md写入月份列： 仅类别单元格，然后是总计公式，在信任写入结果（单元格计数）前确认。
8. 回读并核对。 从工作表中重新读取已写入的列，并与独立计算的分类账进行验证：
   • 分类收入总和 = 对账单总贷方减去排除项目（内部转入，按所有者规则处理的卡退款）。
   • 分类费用总和 = 对账单总借方减去排除项目。
   • 分类账中的每笔交易都被精确计入一次：已分类、已排除（带原因）、或列为未分类。 如果核对失败，在报告前修复——不要报告一个未对平的月份。
9. 向所有者报告该月： 收入、费用、净利润；年初至今总数；做出的判断（含金额）及所有者的裁决记录为固定规则；任何未分类项目；任何缺失的对账单。保持报告事实准确、完整——所有者据此进行审计。

Part A 硬性规则

• 仅限实际数据。 使用对账单中的真实交易金额。切勿估算、平均、年化或编造数字以让月份“看起来完整”。不完整的月份应报告为不完整。
• 绝不覆盖手动输入的单元格。 如果所有者已在您即将写入的单元格中输入了值且与您的值不同，则保留他们的值，在报告中标记冲突，并公开协调——预先存在的条目通常来自您没有的信息源。
• 费用为负数在工作表中；总计公式依赖于此。
• 报销冲抵费用，绝不记为收入。 当某人偿还诊所垫付的特定费用时（经典案例：合同工偿还其在团体EHR订阅中的座位费），在收到款项的月份从该费用类别中减去还款。将其总额记为收入会夸大收入与支出双方。
• 个人交易被排除并列出在报告中，而非“为了安全”而分类。
• 一致应用所有者的裁决。 当所有者一次纠正分类后，将规则记录下来（在您针对该诊所的记忆/笔记中），并在之后的每个月应用，无需再次询问。

Part B — Practice Books 应用

参考文件：references/app-spec.md——数据模型、支付规则、运行生命周期、财务阅读器合同、图表列表和部署门禁。按照该规范构建。

工作形态：

1. 确认设置访谈数据（尤其人员和支付条款）。不在猜测的费率基础上构建任何财务功能。
2. 先在本地构建。 编写服务器+客户端代码，以及一个本地的测试工具，它能模拟电子表格层，并调用每个服务器函数，使用客户端发送的确切参数形式。至少覆盖：支付基础计算（百分比/固定/私人拆分）、运行生命周期保护（运行必须经过“已批准”才能“已支付”）、“已支付” → “支付历史”写入、1099的$600标记、W-2 FICA工资基数上限，以及针对会计格式字符串的财务解析器。
3. 带门禁部署。 推送代码，然后回读已部署的项目内容，并要求与经过测试的本地文件进行逐字节匹配，然后再创建版本——内容陈旧的部署在有人打开应用前看起来与好的部署一模一样。将现有部署升级到新版本；绝不要创建新的部署URL（每个新URL都是一个需要有人更新的链接，旧URL会继续提供旧代码）。升级后，重新列出部署以确认版本确实已移动（部署列表可能在升级后有几秒钟的延迟）。
4. 所有者授权是一次性手动步骤。 所有者打开项目一次并批准作用域（电子表格 + 发送邮件）。在此之前，应用URL将显示访问错误——这是预期行为，不是错误。
5. 所有者的首次运行检查清单： 解锁，确认数据工作表已自动创建，同步/添加人员，设置每个人的支付基础和费率，然后创建第一个（上个月的）薪资运行为草稿模式进行试运行，并在批准前检查各条目。

应用边界（事先向所有者说明）

• 该应用仅计算和记录。它不进行电子报税（1099/W-2/941），不转移资金或进行支付，也不向任何机构提交任何内容。所有者照常从银行支付人员；应用记录已发生的操作。
• W-2预扣税数字为估算值（基于可编辑税务标签的年化百分比法），供所有者的注册会计师验证——绝不将其视为可申报的数据。
• 应用工作表中不包含完整的社会安全号/雇主识别号或银行账号。 仅存储“已存档税务表格”/“已存档ACH”标记；完整标识符保留在诊所现有的安全系统中。
• 该应用为管理员专用：一个所有者登录门禁（例如，一个在服务端根据花名册验证的个人识别码），并且每个服务器函数都会重新检查调用者的授权。服务提供者永远不会看到该应用；他们自己的支付视图（如果有）是一个单独的只读界面。
• 财务仪表盘为只读——该应用绝不向损益工作表写入数据。月度填充（Part A）仍然是数字进入损益表的唯一方式。

代理的操作规则

• 遵循参考文件而非即兴发挥；当参考文件与实时指令冲突时，所有者的当前指令优先，并且变更将被记录下来。
• 从工件本身验证，而非您自己的断言：写入后回读工作表，部署后回读已部署的代码，并在代码更改后运行测试工具。
• 当某一步骤失败时，报告失败原因、事物实际所处的状态以及下一步将做什么。切勿仅凭已开始操作就报告填充、部署或支付运行为已完成。