saas-accounting-system

平台说明

• 可选的辅助插件在某些环境中可能有所帮助，但不得将其视为此技能的必需项。

SaaS 会计系统

致谢：由 Peter Bamuhigire 分享，techguypeter.com，+256 784 464178。

必需输入

输入	必需	用途
租户、产品和生命周期范围	是	界定 SaaS 决策
当前架构、计划、政策和约束	是	保留可执行的行为
生产数据或经过验证的证据	有条件	验证阈值和迁移

能力与权限约定

默认进行只读分析。只有在获得明确授权、遵循最小权限凭证、限定租户范围、具备回滚方案并经过可审计审批的情况下，才能更改配置、计费、身份、租户数据、基础设施或客户沟通。切勿泄露机密信息或跨越租户边界。

降级模式

如果无法获取生产访问权限、政策、遥测数据或权威记录，则应提供标注清晰的设计方案或试运行计划。不得声称已完成部署、对账、删除、交付或取得经测量的结果；应列出缺失的证据和验证项。

决策规则

条件	操作	停止条件
涉及租户隔离、资金、身份或删除	要求提供审批和回滚证据	范围或授权不明确
证据支持可逆更改	暂存、测试并记录	验收检查失败
只有部分上下文可用	返回假设和验证方案	无法验证生产声明

领域反模式

• 将一个租户的政策或数据应用到另一个租户。修正方法：在每个边界强制限定租户范围。
• 根据咨询请求修改生产环境。修正方法：在授权明确之前保持只读。
• 臆造限额、价格、指标或合规声明。修正方法：使用权威记录，或将其标记为尚未解决。
• 在没有回滚和审计证据的情况下发布。修正方法：先暂存，并保留变更前后的证明。
• 将缺失的依赖项视为成功。修正方法：明确指出受阻的验证项。

适用场景

• 在任何 SaaS 应用中实现完整的复式记账系统。用户以自然方式录入交易（销售、费用、库存），系统则在后台自动生成日记账分录。可生成面向用户的报告和技术……

生成的证据

类别	产物	格式	示例
正确性	复式记账测试计划	Markdown 文档，涵盖日记账余额、期间结账和对账场景	docs/accounting/double-entry-tests.md
数据安全	会计科目表和过账规则登记册	Markdown 文档，遵循 skill-composition-standards/references/entity-model-template.md，涵盖科目、过账规则和审计跟踪要求	docs/accounting/coa-register.md

参考资料

• 阅读下方核心工作流后，可使用 references/ 目录了解详细信息。
• 如果实现还需要符合 IFRS 的报告、管理会计、成本会计、财务控制、预测或 CFO 级审核，超出核心复式记账引擎的范围，请使用配套技能 accounting-finance-controller。

概述

弃用说明

对于处理资金的新产品，建议使用更严格的配套技能 accounting-engine。本文件仍可作为旧版实现细节的参考，但阅读其中的任何指导时，都必须遵守以下硬性规则：

• 所有分类账写入都必须经过一个 LedgerPostingService。
• 已过账的日记账分录行只能追加，绝不更新、删除或软删除。
• 更正必须使用冲销日记账。
• 汇总余额是可重建的缓存，不是权威记录。
• 业务模块绝不硬编码科目代码，也不直接写入分类账表。
• 采用 IFRS/IFRS for SMEs 的租户绝不使用 LIFO。

此技能会在业务应用中实现一个隐藏式会计引擎。最终用户永远不会看到借方、贷方或日记账分录——他们只需录入销售、记录付款、转移库存。在底层，每笔交易都会自动过账为平衡的日记账分录，会计师和审计师可随时查询。

**理念：**用户以业务术语思考，系统以复式记账方式处理。

核心架构

┌─────────────────────────────────────────────────┐
│  USER LAYER (Friendly)                          │
│  Sales, Purchases, Payments, Inventory, Expenses│
│  → User sees: "Sale #1042 to Customer X: $500"  │
└──────────────────────┬──────────────────────────┘
                       │ auto-posts
┌──────────────────────▼──────────────────────────┐
│  ACCOUNTING ENGINE (Hidden)                     │
│  Journal Entries, Ledger Postings, Trial Balance│
│  → Engine posts: DR Accounts Receivable $500    │
│                  CR Sales Revenue      $500     │
└──────────────────────┬──────────────────────────┘
                       │ aggregates
┌──────────────────────▼──────────────────────────┐
│  REPORTING LAYER (Dual)                         │
│  User Reports: Sales Summary, Aging, P&L Simple │
│  Accountant Reports: Trial Balance, BS, IS, CF  │
└─────────────────────────────────────────────────┘

黄金规则

每笔交易都必须生成平衡的日记账分录。没有例外。

SUM(debits) = SUM(credits)  — ALWAYS

此规则通过存储过程或触发器在数据库层强制执行。如果分录不平衡，整个交易就会回滚。

会计科目表（COA）

COA 是会计系统的骨干。每个科目都有一个决定其正常余额的类型。

类型	代码范围	正常余额	示例
资产	1000-1999	借方	现金、银行、应收账款、库存、设备
负债	2000-2999	贷方	应付账款、贷款、应付税款、递延收入
权益	3000-3999	贷方	所有者权益、留存收益
收入	4000-4999	贷方	销售收入、服务收入、利息收入
销货成本	5000-5999	借方	销货成本、直接材料
费用	6000-6999	借方	租金、薪资、水电费、营销费用

设置规则：

• 创建租户时，为其提供默认 COA（从模板填充）
• 科目按租户隔离（franchise_id）
• 科目一旦有已过账分录，就不能删除
• 支持子科目（例如：1100 现金 → 1101 零用现金、1102 主银行账户）

另请参阅：references/chart-of-accounts.md 和 references/accounting-bookkeeping-erp-patterns.md。

自动过账规则

用户绝不手动创建日记账分录。每笔业务交易都有一条过账规则。

交易 → 日记账分录对照表

用户操作	借方科目	贷方科目
记录销售（发票）	应收账款	销售收入
记录销售 + 税款	应收账款 + 应收税款	销售收入 + 应付税款
收款（现金）	现金/银行	应收账款
记录采购	库存/费用	应付账款
支付供应商款项	应付账款	现金/银行
记录费用	费用科目	现金/银行或应付账款
销售库存（销货成本）	销货成本	库存
库存调整（+）	库存	库存调整（收入）
库存调整（-）	库存调整（费用）	库存
支付薪资	薪资费用	现金/银行
收到贷款	现金/银行	应付贷款
偿还贷款	应付贷款 + 利息费用	现金/银行
折旧	折旧费用	累计折旧
客户退款	销售退回	现金/银行或应收账款

**多行分录：**一笔包含税款和折扣的销售会生成 3 行或更多日记账分录，全部归属于同一笔分录。该分录必须平衡。

另请参阅：references/journal-posting-rules.md 和 references/accounting-bookkeeping-erp-patterns.md。

作废与冲销机制

**规则：**绝不删除已过账的日记账分录。始终创建一条冲销分录。

作废流程

1. User clicks "Void" on a transaction (e.g., Sale Invoice #1042)
2. System marks the original transaction as VOIDED (status change)
3. System auto-creates a REVERSING journal entry:
   - Same accounts, opposite directions
   - Reference: "REVERSAL of JE-{original_id}"
   - Same date OR current date (configurable)
4. Original entry + reversal entry net to ZERO
5. All sub-ledger balances update automatically

冲销分录示例

Original (Sale Invoice #1042):
  DR  Accounts Receivable    500.00
  CR  Sales Revenue           500.00

Reversal (Void of #1042):
  DR  Sales Revenue           500.00
  CR  Accounts Receivable    500.00

Net effect: ZERO

部分作废规则

• 部分付款的发票：仅作废剩余余额
• 已收到付款：必须先作废付款，再作废发票
• 库存已交付：必须先冲销库存变动
• 级联保护：如果存在依赖交易，系统会发出警告

参见：references/void-reversal-patterns.md

数据库架构（核心表）

-- Chart of Accounts
accounts (id, franchise_id, code, name, type, parent_id,
          is_active, normal_balance, created_at)

-- Journal Entries (Header)
journal_entries (id, franchise_id, entry_date, reference_type,
                 reference_id, narration, is_reversal, reversed_entry_id,
                 posted_by, status, created_at)

-- Journal Entry Lines (Detail)
journal_entry_lines (id, journal_entry_id, account_id,
                     debit_amount, credit_amount, narration,
                     franchise_id, created_at)

-- Fiscal Periods
fiscal_periods (id, franchise_id, period_name, start_date,
                end_date, status, closed_by, closed_at)

-- Account Balances (Materialized for performance)
account_balances (id, franchise_id, account_id, period_id,
                  opening_balance, debit_total, credit_total,
                  closing_balance, updated_at)

完整性约束：

• journal_entry_lines.debit_amount 和 credit_amount 为 DECIMAL(15,2)
• CHECK 约束：每一行只能有借方或贷方，不能同时有两者，也不能两者都为零
• 存储过程会验证每笔分录的 SUM(debit) = SUM(credit)
• 每张表都有 franchise_id（用于多租户隔离）
• status 枚举值：DRAFT、POSTED、VOIDED

参见：references/schema-design.md

子分类账与控制账户规范

每个财务模块都必须通过控制账户与总账对账：

• 应收账款账龄必须与应收账款控制账户对账。
• 应付账款账龄必须与应付账款控制账户对账。
• 库存估值必须与库存控制账户对账。
• 固定资产登记册的净账面价值必须与资产成本减累计折旧的金额对账。
• 银行对账必须说明银行对账单与账面余额之间的差异。
• 税务明细表必须将应付／应收税款账户与可用于申报的凭证对账。

除通过受控的调整工作流（包含原因、审批和审计跟踪）外，不要允许用户直接过账到控制账户。

管理会计层

当系统支持制造、服务、项目、学校、诊所、零售或 ERP 管理报告时，应在过账中加入成本中心、利润中心、项目、分支机构、部门和产品等维度。使用这些维度编制预算、灵活预算报告、标准成本差异、边际贡献、作业成本法和管理报表包，同时避免破坏法定总账结构。

双重报告体系

用户友好型报告（非会计人员）

报告	用户看到的内容	数据来源
销售摘要	按期间、客户、产品统计的总销售额	销售交易
未结发票	欠款方、欠款金额及账龄	应收账款子分类账
费用报告	按类别统计的支出	费用交易
损益表（简版）	收入减去费用	收入／费用账户
现金状况	银行／现金中的资金	现金／银行账户
库存价值	现有库存及其成本	库存子分类账

会计师／审计师报告（技术型）

报告	显示内容	来源
试算平衡表	所有账户余额（借方／贷方列）	总账
资产负债表	资产 = 负债 + 权益	总账（类型 1-3）
利润表	收入 - 销售成本 - 费用 = 净利润	总账（类型 4-6）
现金流量表	经营活动 + 投资活动 + 筹资活动	现金账户分录
总账明细	每个账户的所有分录	日记账分录
日记账登记簿	按时间顺序排列的所有日记账分录	日记账分录
应收账款账龄	应收账款账龄（30／60／90／120 天）	应收账款子分类账
应付账款账龄	应付账款账龄	应付账款子分类账
审计跟踪	谁在何时过账了什么	日记账分录 + 审计日志

参见：references/financial-statements.md

实施清单

阶段 1：基础（必须首先完成）

• 创建包含 COA 初始数据的 accounts 表
• 创建 journal_entries 和 journal_entry_lines 表
• 创建 fiscal_periods 表
• 构建余额验证存储过程
• 构建 postJournalEntry() 服务函数
• 编写测试：平衡分录通过，不平衡分录被拒绝

第 2 阶段：自动过账集成

• 接入销售发票 → 自动过账应收账款/收入分录
• 接入收款 → 自动过账现金/应收账款分录
• 接入采购 → 自动过账库存或费用/应付账款分录
• 接入供应商付款 → 自动过账应付账款/现金分录
• 接入库存变动 → 自动过账销售成本/库存分录
• 编写测试：每种交易类型均过账正确的分录

第 3 阶段：作废与冲销

• 构建交易作废服务（创建冲销分录）
• 处理部分作废场景
• 处理级联依赖（作废前发出警告）
• 编写测试：作废后净额为零、余额正确

第 4 阶段：报表

• 构建试算平衡表报表（所有科目、借方/贷方合计）
• 构建资产负债表（资产 = 负债 + 权益）
• 构建损益表（收入 - 费用）
• 构建便于用户使用的汇总报表
• 构建审计追踪报表
• 编写测试：报表与测试数据的预期值一致

第 5 阶段：期间管理

• 构建期间开启/关闭功能
• 禁止向已关闭期间过账
• 构建年末结账分录（收入/费用 → 留存收益）
• 编写测试：已关闭期间会拒绝分录

跨技能集成

领域	技能	应用方式
数据库架构	mysql-best-practices	DECIMAL(15,2)、索引、外键约束
API 端点	api-error-handling	为过账失败提供一致的错误响应
多租户	multi-tenant-saas-architecture	所有表都包含 franchise_id
UI 报表	webapp-gui-design	用于分类账的 DataTables、用于损益表的图表
移动端报表	jetpack-compose-ui	使用表格的报表页面
PDF 导出	android-pdf-export、report-print-pdf	财务报表 PDF
安全	vibe-security-skill	保护财务数据、审计追踪
身份验证	dual-auth-rbac	权限：谁可以过账/作废/查看报表
库存关联	inventory-management	库存变动时过账销售成本
测试	sdlc-testing	测试每条过账规则和每种冲销
实施	plan-implementation	使用 TDD 执行会计阶段
审计	implementation-status-auditor	验证会计系统的完整性

反模式

不要这样做	应改为
允许用户直接输入日记账分录	根据业务交易自动过账
使用 FLOAT 存储金额	始终使用 DECIMAL(15,2)
删除日记账分录	创建冲销分录（作废）
跳过余额验证	在存储过程中强制执行 DR=CR
只存储计算后的余额	存储单独的分录，按需计算
将会计与业务逻辑混在一起	将会计引擎作为独立服务层
硬编码科目代码	使用可配置的 COA 和租户专属科目
跳过审计追踪	记录每次过账的用户、时间戳和 IP
允许向已关闭期间过账	过账前强制检查期间状态
向最终用户显示借方/贷方	显示易懂的标签（收入、付款等）

准确性保证

每项实现都 MUST 通过以下测试：

1. 余额测试： SELECT SUM(debit) - SUM(credit) FROM journal_entry_lines = 0.00
2. 分录测试： 每条日记账分录的 SUM(debit) = SUM(credit)
3. 试算平衡表测试： 借方总额 = 贷方总额
4. 资产负债表测试： 资产 = 负债 + 权益
5. 冲销测试： 已作废交易与冲销分录相抵后净额为零
6. 期间测试： 已关闭期间内没有分录
7. 租户测试： 任何查询都不会发生跨租户数据泄露

另请参阅

• references/chart-of-accounts.md — 科目表模板和设置
• references/journal-posting-rules.md — 每笔交易的完整过账规则
• references/void-reversal-patterns.md — 作废机制和边界情况
• references/financial-statements.md — 报表 SQL 查询和格式
• references/schema-design.md — 完整数据库架构及约束
• references/accounting-bookkeeping-erp-patterns.md — 记账、子账控制、ERP 财务配置、成本会计、管理报告和验收测试

质量标准

只有在分录平衡、源事件具备幂等性、期间和租户相互隔离、冲销保留历史记录，且控制证据与报告核对一致时，过账设计才能通过。

输出

产物	使用方	验收条件
SaaS 会计架构和过账约定	财务控制人员和工程团队	每个业务事件都对应平衡分录；租户和期间控制得到强制执行；冲销可追溯；并已定义对账证据