saas-accounting-system

プラットフォームに関する注意事項

• オプションのヘルパープラグインは一部の環境で役立つ場合がありますが、このスキルに必須であると見なしてはなりません。

SaaS 会計システム

謝辞: Peter Bamuhigire、techguypeter.com、+256 784 464178 氏による共有。

必須入力

入力	必須	用途
テナント、製品、ライフサイクルのスコープ	はい	SaaS の判断範囲を定める
現在のアーキテクチャ、計画、ポリシー、制約	はい	強制可能な動作を維持する
本番データまたは検証済みのエビデンス	条件付き	しきい値と移行を検証する

権限およびアクセス許可の契約

デフォルトでは読み取り専用の分析とします。構成、請求、アイデンティティ、テナントデータ、インフラストラクチャ、または顧客とのコミュニケーションを変更するのは、明示的な権限、最小権限の認証情報、テナントスコープ、ロールバック、および監査可能な承認がある場合に限ります。シークレットやテナント境界をまたいで公開してはなりません。

縮退モード

本番アクセス、ポリシー、テレメトリ、または権威ある記録が利用できない場合は、ラベル付けされた設計またはドライラン計画を作成します。デプロイ、照合、削除、配信、または測定された成果を主張してはなりません。不足しているエビデンスと検証を列挙してください。

判断ルール

条件	アクション	停止条件
テナント分離、金銭、アイデンティティ、または削除が影響を受ける	承認とロールバックのエビデンスを要求する	スコープまたは権限が曖昧である
エビデンスが可逆的な変更を裏付ける	ステージング、テスト、および記録を行う	受け入れチェックが失敗する
一部のコンテキストしか利用できない	前提と検証を返す	本番に関する主張を検証できない

ドメインのアンチパターン

• あるテナントのポリシーまたはデータを別のテナントに適用すること。修正: すべての境界でテナントスコープを強制します。
• 助言的なリクエストから本番を変更すること。修正: 権限が明示されるまで読み取り専用を維持します。
• 制限、価格、メトリクス、またはコンプライアンスの主張をでっち上げること。修正: 権威ある記録を使用するか、未解決としてマークします。
• ロールバックと監査のエビデンスなしでリリースすること。修正: 変更前後の証拠をステージングして保持します。
• 依存関係の欠如を成功として扱うこと。修正: ブロックされた検証を明示します。

使用する場面

• 任意の SaaS アプリ内に完全な複式簿記会計システムを実装します。ユーザーは取引(売上、経費、在庫)を自然に入力し、システムは内部で仕訳を自動転記します。ユーザーフレンドリーなレポートと技術的な...の両方を生成します。

生成されるエビデンス

カテゴリ	成果物	形式	例
正確性	複式簿記会計テスト計画	仕訳の貸借一致、期間締め、および照合シナリオを網羅する Markdown ドキュメント	docs/accounting/double-entry-tests.md
データ安全性	勘定科目表および転記ルール登録簿	skill-composition-standards/references/entity-model-template.md に準拠し、勘定科目、転記ルール、および監査証跡の要件を網羅する Markdown ドキュメント	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 行以上の仕訳行を 1 つの仕訳として生成します。その仕訳は貸借が一致しなければなりません。

参照: 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 enum: DRAFT、POSTED、VOIDED

参照: references/schema-design.md

補助元帳と統制勘定の規律

すべての財務モジュールは、統制勘定を通じて総勘定元帳と照合できなければなりません:

• 売掛金エイジングは売掛金統制勘定と照合できなければなりません。
• 買掛金エイジングは買掛金統制勘定と照合できなければなりません。
• 在庫評価は在庫統制勘定と照合できなければなりません。
• 固定資産台帳の正味簿価は、資産原価から減価償却累計額を差し引いた額と照合できなければなりません。
• 銀行勘定調整は、銀行明細書と帳簿残高の差異を説明できなければなりません。
• 税務スケジュールは、未払税額/未収税額の勘定を申告可能なエビデンスと照合できなければなりません。

理由、承認、監査証跡を伴う統制された調整ワークフローを通す場合を除き、ユーザーが統制勘定に直接転記できるようにしてはいけません。

管理会計レイヤー

システムが製造、サービス、プロジェクト、学校、クリニック、小売、または ERP の管理レポートをサポートする場合、転記にコストセンター、プロフィットセンター、プロジェクト、支店、部門、製品のディメンションを追加します。これらのディメンションを予算、フレキシブル予算レポート、標準原価差異、限界利益、活動基準原価計算、および管理パックに使用し、法定の総勘定元帳構造を損なわないようにします。

デュアルレポーティングシステム

ユーザーフレンドリーなレポート (非会計士向け)

レポート	ユーザーが見る内容	データソース
売上サマリー	期間、顧客、製品別の総売上	売上トランザクション
未払請求書	誰がいくら負債を負い、どれくらい古いか	売掛金補助元帳
経費レポート	カテゴリ別の支出	経費トランザクション
損益計算書 (簡易)	収益から経費を差し引いた額	収益/経費勘定
現金ポジション	銀行/現金にある資金	現金/銀行勘定
在庫価値	原価を含む手持在庫	在庫補助元帳

会計士/監査人向けレポート (テクニカル)

レポート	表示内容	ソース
試算表	すべての勘定残高 (借方/貸方列)	総勘定元帳
貸借対照表	資産 = 負債 + 純資産	GL (タイプ 1-3)
損益計算書	収益 - 売上原価 - 経費 = 純利益	GL (タイプ 4-6)
キャッシュフロー計算書	営業活動 + 投資活動 + 財務活動	現金勘定エントリ
総勘定元帳明細	勘定ごとのすべてのエントリ	仕訳エントリ
仕訳帳	すべての仕訳エントリを時系列順に	仕訳エントリ
売掛金エイジング	売掛金エイジング (30/60/90/120 日)	売掛金補助元帳
買掛金エイジング	買掛金エイジング	買掛金補助元帳
監査証跡	誰が何をいつ転記したか	仕訳エントリ + 監査ログ

参照: references/financial-statements.md

実装チェックリスト

フェーズ 1: 基盤 (最初に完了させる必要がある)

• COA シードデータを含む accounts テーブルを作成する
• journal_entries テーブルと journal_entry_lines テーブルを作成する
• fiscal_periods テーブルを作成する
• 残高検証ストアドプロシージャを構築する
• postJournalEntry() サービス関数を構築する
• テストを書く: 貸借が一致するエントリは通過し、一致しないものは拒否される

フェーズ 2: 自動転記の統合

• 売上請求書を連携 → AR/収益エントリを自動転記
• 入金を連携 → 現金/AR エントリを自動転記
• 仕入を連携 → 在庫または費用/AP エントリを自動転記
• 仕入先への支払を連携 → AP/現金エントリを自動転記
• 在庫移動を連携 → COGS/在庫エントリを自動転記
• テストを作成: 各取引タイプが正しいエントリを転記すること

フェーズ 3: 無効化と反転

• 取引無効化サービスを構築 (反転エントリを作成)
• 部分無効化のシナリオを処理
• カスケード依存関係を処理 (無効化前に警告)
• テストを作成: 無効化がネットゼロを生み出し、残高が正しいこと

フェーズ 4: レポート

• 試算表レポートを構築 (すべての勘定科目、借方/貸方合計)
• 貸借対照表を構築 (資産 = 負債 + 資本)
• 損益計算書を構築 (収益 - 費用)
• ユーザーフレンドリーなサマリーレポートを構築
• 監査証跡レポートを構築
• テストを作成: レポートがテストデータの期待値と一致すること

フェーズ 5: 期間管理

• 期間のオープン/クローズ機能を構築
• クローズ済み期間への転記を防止
• 年末決算エントリを構築 (収益/費用 → 繰越利益剰余金)
• テストを作成: クローズ済み期間がエントリを拒否すること

スキル間の統合

領域	スキル	適用方法
データベーススキーマ	mysql-best-practices	DECIMAL(15,2)、インデックス、FK 制約
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	在庫移動時の COGS 転記
テスト	sdlc-testing	すべての転記ルール、すべての反転をテスト
実装	plan-implementation	TDD で会計フェーズを実行
監査	implementation-status-auditor	会計システムの完全性を検証

アンチパターン

やってはいけないこと	代わりにすること
ユーザーに仕訳エントリを直接入力させる	業務取引から自動転記する
金額に FLOAT を使用する	常に DECIMAL(15,2) を使用する
仕訳エントリを削除する	反転エントリを作成する (無効化)
残高検証を省略する	ストアドプロシージャで借方=貸方を強制する
計算済み残高のみを保存する	個々のエントリを保存し、オンデマンドで計算する
会計と業務ロジックを混在させる	会計エンジンを独自のサービスレイヤーとして分離する
勘定科目コードをハードコードする	テナント固有の勘定科目を持つ設定可能な COA を使用する
監査証跡を省略する	すべての転記をユーザー、タイムスタンプ、IP とともにログに記録する
クローズ済み期間への転記を許可する	転記前に期間ステータスチェックを強制する
エンドユーザーに借方/貸方を表示する	わかりやすいラベル (収入、支払など) を表示する

精度の保証

すべての実装は以下のテストに合格しなければなりません:

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 — COA テンプレートとセットアップ
• 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 会計アーキテクチャと記帳契約	財務コントローラーおよびエンジニアリングチーム	すべてのビジネスイベントが貸借一致した仕訳に対応付けられ、テナントと期間の統制が適用され、取消が追跡可能であり、照合の証跡が定義されている