@geekbeer/minion 4.0.1 → 4.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -5,7 +5,7 @@
5
5
  * either the Primary (user-facing) session or as a Child (specialist) session
6
6
  * dispatched from the Primary via the dispatch MCP server.
7
7
  *
8
- * See: packages/docs-internal/src/content/docs/design/llm-plugin-system.md
8
+ * See: packages/docs-internal/src/content/docs/design/llm/llm-plugin-system.md
9
9
  */
10
10
 
11
11
  /**
@@ -19,7 +19,7 @@
19
19
  * Secrets never leave the minion and are never persisted in HQ DB. Variables
20
20
  * are non-sensitive and may also be defined at HQ scopes (workspace /
21
21
  * project / workflow); see packages/docs-internal/src/content/docs/design/
22
- * variables-and-secrets.md for the full resolution model.
22
+ * workflow-execution/variables-and-secrets.md for the full resolution model.
23
23
  */
24
24
 
25
25
  const fs = require('fs')
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@geekbeer/minion",
3
- "version": "4.0.1",
3
+ "version": "4.1.1",
4
4
  "description": "AI Agent runtime for Minion - manages status and skill deployment on VPS",
5
5
  "main": "linux/server.js",
6
6
  "bin": {
@@ -0,0 +1,42 @@
1
+ # Accountant Role Guidelines
2
+
3
+ このセッションではあなたは **Accountant** ロールとして行動します。
4
+
5
+ ## 責務
6
+
7
+ - **記帳**: 取引(仕訳)をHQの会計帳簿に正確に記録する
8
+ - **立替経費の処理**: 役員・従業員が立て替えた経費を記帳・精算する
9
+ - **取引先マスタの整備**: 仕入先・顧客・役員・従業員などの取引先を整備する
10
+ - **補助元帳の照会**: 取引先別の残高・明細を確認し、PMやユーザーへ報告する
11
+
12
+ ## 利用するスキル
13
+
14
+ 会計操作の具体手順とAPI仕様は専用スキルにまとまっています。コアルールにはあえて含めていません(トークン圧迫を避けるため)。
15
+
16
+ - `/accounting-bookkeeping` — 取引記帳・立替経費・精算・補助元帳の標準フロー
17
+ - 詳細仕様は `~/.claude/skills/accounting-bookkeeping/references/` 配下を必要時に参照
18
+
19
+ スキルが未配布の場合は `minion-cli skill fetch accounting-bookkeeping` で取得してください。
20
+
21
+ ## 重要な原則
22
+
23
+ - **仕訳の確定済み(closed)期は修正しない。** 締め後の仕訳訂正はPMの承認が必要です。
24
+ - **立替経費は取引先(counterparty)を必ず紐付ける。** 「誰の立替か」を後から照会できるようにするため。
25
+ - **default_payable_account_id 未設定の取引先には立替記帳できない。** API が 422 を返します。先に取引先ページで貸方科目を設定してください。
26
+ - **判断に迷ったら勝手に進めない。** 不明な取引・推測の余地がある仕訳は、threadで PM にエスカレーションすること。
27
+
28
+ ## ブロッカー対処
29
+
30
+ 会計記帳中に自力で解決できない問題に遭遇した場合:
31
+
32
+ 1. **まずプロジェクトメモリーを検索** — 過去に同じ取引パターンの記帳例があるか確認
33
+ 2. **API のエラーレスポンスを読む** — 会計APIは `next_action` フィールドで次に取るべき操作を返す。これに従う
34
+ 3. **自己解決不可なら即ヘルプスレッドを起票** — `attempted_resolution` に試したことを記載
35
+ 4. **人間にしか判断できない問題は即エスカレーション** — 法的判断、過去取引の意図確認など
36
+
37
+ **仕訳を失敗終了させる前に、必ずヘルプスレッドでエスカレーションすること。**
38
+ 詳細は `~/.minion/rules/core.md` の「Blocker Handling」セクションを参照。
39
+
40
+ ## 実行コンテキスト
41
+
42
+ ミニオン変数・シークレット(HQ UIまたはAPI経由で設定)はサーバー起動時に `process.env` にロードされ、会計操作中も利用可能。
@@ -0,0 +1,97 @@
1
+ ---
2
+ name: accounting-bookkeeping
3
+ description: 会計帳簿の記帳・立替経費の処理・補助元帳の照会を行うワークフロー。使用タイミング:(1) 取引を仕訳として記録する時、(2) 役員・従業員の立替経費を記帳・精算する時、(3) 取引先別の残高を確認する時。accountantロールのミニオンが主に使用する。
4
+ ---
5
+
6
+ # Accounting Bookkeeping
7
+
8
+ 会計帳簿(HQ Accounting API)を操作するためのスキル。複式簿記の整合性を保ちながら、AI(ミニオン)が安全に記帳できるよう設計されている。
9
+
10
+ ## 前提
11
+
12
+ - ワークスペースで experimental_accounting feature flag が有効になっていること
13
+ - HQ API は `$HQ_URL/api/accounting/*` で利用可能(authentication は `Authorization: Bearer $API_TOKEN`)
14
+ - 1ワークスペース1帳簿の前提。`GET /books` で帳簿を取得し、勘定科目テンプレートはデフォルトで投入済み
15
+
16
+ ## 語彙
17
+
18
+ | 用語 | 説明 |
19
+ |------|------|
20
+ | **book(帳簿)** | ワークスペースに1冊。仕訳・科目・取引先のスコープ単位 |
21
+ | **account(勘定科目)** | 資産/負債/純資産/収益/費用の5型に分類。`is_wallet=true` のものが支払元(現金/預金)になる |
22
+ | **counterparty(取引先)** | 仕入先・顧客・役員・従業員などのマスタ。`kind` で種別を区別 |
23
+ | **journal entry(仕訳)** | 取引1件のヘッダ。複式簿記なので必ず複数の line を持つ |
24
+ | **journal line(仕訳明細)** | 借方/貸方の各行。`counterparty_id` を付与すると補助元帳が引ける |
25
+ | **expense reimbursement(立替経費)** | 役員/従業員が立て替えた経費。記帳仕訳と精算仕訳の対応を保持する別レイヤ |
26
+
27
+ ## 典型フロー
28
+
29
+ ### A) 通常取引の記帳
30
+
31
+ ```
32
+ 1. GET /api/accounting/accounts で勘定科目一覧取得
33
+ 2. 入金/出金口座(is_wallet=true)と相手勘定(費用 or 収益)を特定
34
+ 3. POST /api/accounting/entries でシンプル仕訳を作成
35
+ body: { entry_type: 'expense'|'income', entry_date, amount, wallet_account_id, category_account_id, description }
36
+ ```
37
+
38
+ 詳細: `references/api-journal-entries.md`
39
+
40
+ ### B) 立替経費の記帳
41
+
42
+ ```
43
+ 1. 立替者(役員/従業員)の counterparty を確認
44
+ - GET /api/accounting/counterparties?q=<name>&kind=director,employee
45
+ - 見つからなければ POST /api/accounting/counterparties で作成
46
+ - default_payable_account_id が未設定なら PATCH で先に設定する
47
+ 2. POST /api/accounting/expense-reimbursements で記帳
48
+ body: { paid_by_counterparty_id, occurred_on, amount, expense_account_id, description }
49
+ → 内部で「(借)費用 / (貸)立替者の負債科目」の仕訳が自動生成される
50
+ 3. レシートがあれば事前に POST /api/accounting/receipts でアップロードし、receipt_ids を渡す
51
+ ```
52
+
53
+ 詳細: `references/api-expense-reimbursement.md`
54
+
55
+ ### C) 立替経費の精算
56
+
57
+ ```
58
+ 1. GET /api/accounting/expense-reimbursements?settled=false で未精算リスト取得
59
+ 2. POST /api/accounting/expense-reimbursements/<id>/settle で精算
60
+ body: { settled_on, wallet_account_id }
61
+ → 内部で「(借)立替者の負債科目 / (貸)現金or預金」の仕訳が自動生成される
62
+ ```
63
+
64
+ 部分精算は非対応。全額精算のみ。
65
+
66
+ ### D) 補助元帳の照会
67
+
68
+ ```
69
+ GET /api/accounting/counterparties/<id>/balance
70
+ → 取引先別の残高(勘定科目ごと)・明細リスト・未精算立替件数を返す
71
+ ```
72
+
73
+ 詳細: `references/api-counterparties.md`
74
+
75
+ ## エラーレスポンスの読み方
76
+
77
+ 会計APIは AI 向けに以下の構造でエラーを返す:
78
+
79
+ ```json
80
+ {
81
+ "error": "missing_default_payable_account",
82
+ "message": "取引先「山田太郎」に立替用の貸方科目が未設定です",
83
+ "next_action": "PATCH /api/accounting/counterparties/<id> で default_payable_account_id を設定してください...",
84
+ "context": { "counterparty_id": "..." }
85
+ }
86
+ ```
87
+
88
+ **必ず `next_action` を読み、その指示に従うこと。** 推測で適当な処理を試みない。
89
+
90
+ 主要エラーパターンと対処は `references/troubleshooting.md` を参照。
91
+
92
+ ## 重要な制約
93
+
94
+ - **確定済み期間(closed)の日付では記帳できない。** 422/409 で拒否される。日付を変えるか PM に再オープン依頼
95
+ - **立替の貸方科目は負債(liability) or 純資産(equity)のみ許容。** 資産勘定の「立替金」(他人のために会社が立て替える勘定)は逆向きなので NG
96
+ - **counterparty マスタは book スコープ。** 別帳簿のIDは使えない
97
+ - **複式簿記の借方=貸方は trigger で強制される。** 自前で計算してから POST すること
@@ -0,0 +1,109 @@
1
+ # API: 取引先(Counterparties)
2
+
3
+ 取引先マスタは `book_id` スコープ。役員・従業員・仕入先・顧客などを統一管理する。
4
+
5
+ ## kind の選び方
6
+
7
+ | kind | 用途 |
8
+ |------|------|
9
+ | `vendor` | 仕入先・外注先・サブスク提供事業者など |
10
+ | `customer` | 顧客 |
11
+ | `director` | 役員(取締役・代表など)。立替経費の立替者になりうる |
12
+ | `employee` | 従業員。立替経費の立替者になりうる |
13
+ | `other` | その他 |
14
+
15
+ `member_id` で workspace_members に紐付け可能(役員/従業員のみ意味あり)。
16
+
17
+ ## default_payable_account_id
18
+
19
+ 立替記帳時の貸方デフォルト科目。`director`/`employee` の取引先には必ず設定すること。
20
+
21
+ - 推奨: **liability** 型の「役員借入金」「従業員未払金」など
22
+ - 許容: **equity** 型(運用実態として一部の帳簿で利用されるため)
23
+ - NG: **asset/revenue/expense** 型 → API が `invalid_default_payable_account` で 400 を返す
24
+
25
+ 該当科目が無い場合は先に `POST /api/accounting/accounts` で作成すること。
26
+
27
+ ## エンドポイント
28
+
29
+ ### GET /api/accounting/counterparties
30
+
31
+ ```
32
+ Query:
33
+ ?q=<部分一致検索>
34
+ ?kind=director,employee (カンマ区切り)
35
+ ?include_archived=true (デフォルトはアクティブのみ)
36
+ ?limit=200 (max 500)
37
+
38
+ Response:
39
+ { "counterparties": [{ id, book_id, name, kind, member_id, default_payable_account_id, is_archived, ... }] }
40
+ ```
41
+
42
+ ### POST /api/accounting/counterparties
43
+
44
+ ```
45
+ Body:
46
+ {
47
+ "name": "山田太郎",
48
+ "kind": "director",
49
+ "member_id": null,
50
+ "default_payable_account_id": "<account uuid>"
51
+ }
52
+
53
+ Response 201: { "counterparty": {...} }
54
+
55
+ エラー:
56
+ 400 invalid_kind — kind 不正
57
+ 400 invalid_default_payable_account — 指定した科目が立替貸方として不適切
58
+ 409 counterparty_name_conflict — 同名のアクティブな取引先が存在 (context.existing_id 参照)
59
+ ```
60
+
61
+ ### GET /api/accounting/counterparties/[id]
62
+
63
+ ```
64
+ Response: { "counterparty": {...} }
65
+ 404 counterparty_not_found
66
+ ```
67
+
68
+ ### PATCH /api/accounting/counterparties/[id]
69
+
70
+ ```
71
+ Body (全て任意):
72
+ { "name", "kind", "member_id", "default_payable_account_id", "is_archived" }
73
+
74
+ Response: { "counterparty": {...} }
75
+ ```
76
+
77
+ ### DELETE /api/accounting/counterparties/[id]
78
+
79
+ ソフト削除(`is_archived=true`)。物理削除はしない(過去仕訳の参照を保持するため)。
80
+
81
+ ```
82
+ エラー:
83
+ 409 has_unsettled_reimbursements — 未精算の立替が残っているとアーカイブ不可
84
+ ```
85
+
86
+ ### GET /api/accounting/counterparties/[id]/balance
87
+
88
+ 補助元帳。取引先別の残高(勘定科目別)と明細リスト。
89
+
90
+ ```
91
+ Query:
92
+ ?as_of=YYYY-MM-DD (任意。これより前の仕訳のみ集計)
93
+ ?limit=500 (明細最大件数)
94
+
95
+ Response:
96
+ {
97
+ "counterparty": {...},
98
+ "balance_by_account": [
99
+ { "account_id", "code", "name", "type", "debit", "credit", "balance" }
100
+ ],
101
+ "lines": [
102
+ { "id", "account_id", "debit", "credit", "memo", "entry": {...}, "account": {...} }
103
+ ],
104
+ "unsettled_reimbursements_count": 2,
105
+ "as_of": null
106
+ }
107
+ ```
108
+
109
+ 残高の符号: 資産/費用は `debit - credit`、負債/純資産/収益は `credit - debit`。
@@ -0,0 +1,120 @@
1
+ # API: 立替経費(Expense Reimbursements)
2
+
3
+ 立替経費は「立替記帳の仕訳」と「精算の仕訳」の対応関係を保持する別レイヤ。両仕訳の line に同じ `counterparty_id` が付与される。
4
+
5
+ ## 仕訳パターン
6
+
7
+ **立替記帳時:**
8
+ ```
9
+ (借) 費用科目 amount [counterparty_id=<立替者>]
10
+ (貸) counterparty.default_payable_account_id amount [counterparty_id=<立替者>]
11
+ ```
12
+
13
+ **精算時:**
14
+ ```
15
+ (借) counterparty.default_payable_account_id amount [counterparty_id=<立替者>]
16
+ (貸) wallet_account (現金 or 普通預金) amount [counterparty_id=<立替者>]
17
+ ```
18
+
19
+ ## エンドポイント
20
+
21
+ ### POST /api/accounting/expense-reimbursements
22
+
23
+ 立替経費を記帳する。
24
+
25
+ ```
26
+ Body:
27
+ {
28
+ "paid_by_counterparty_id": "<立替者のcounterparty uuid>",
29
+ "occurred_on": "YYYY-MM-DD",
30
+ "amount": 1000,
31
+ "expense_account_id": "<費用科目 uuid>",
32
+ "description": "新幹線代 東京→大阪", // 任意
33
+ "receipt_ids": ["<receipt uuid>"], // 任意。既存の未添付レシートを紐付ける
34
+ "category_dimensions": { // 任意。一般社団法人プロファイル等で expense 行に
35
+ "net_asset_restriction": "general" // ディメンションが必要な場合に指定。expense 行(借方)のみに付与される
36
+ }
37
+ }
38
+
39
+ Response 201: { "reimbursement": { "id", "expense_journal_entry_id" } }
40
+
41
+ 主要エラー:
42
+ 400 invalid_amount — amount が正の数値でない
43
+ 400 expense_account_not_found — 費用科目が見つからない / 別帳簿
44
+ 400 invalid_expense_account_type — expense_account_id が expense 型でない
45
+ 404 counterparty_not_found — 立替者が見つからない (next_action: POST で先に作成)
46
+ 409 counterparty_archived — 立替者がアーカイブ済み
47
+ 409 period_closed — occurred_on が締め済期間内
48
+ 422 missing_default_payable_account — 立替者の default_payable_account_id が未設定
49
+ ```
50
+
51
+ ### POST /api/accounting/expense-reimbursements/[id]/settle
52
+
53
+ 立替を全額精算する。**部分精算は非対応**。
54
+
55
+ ```
56
+ Body:
57
+ {
58
+ "settled_on": "YYYY-MM-DD",
59
+ "wallet_account_id": "<is_wallet=true の account uuid>"
60
+ }
61
+
62
+ Response: { "reimbursement": { "id", "expense_journal_entry_id" } }
63
+ ※ expense_journal_entry_id は精算仕訳のIDが返る
64
+
65
+ 主要エラー:
66
+ 404 reimbursement_not_found
67
+ 409 already_settled — 既に精算済み (context.settled_at 参照)
68
+ 409 period_closed — settled_on が締め済期間内
69
+ 400 wallet_account_not_found — 支払口座が見つからない
70
+ 400 not_a_wallet_account — is_wallet=false の科目を指定した
71
+ 422 missing_default_payable_account — 立替者の貸方科目が後から消去された場合
72
+ ```
73
+
74
+ ### GET /api/accounting/expense-reimbursements
75
+
76
+ ```
77
+ Query:
78
+ ?counterparty_id=<uuid>
79
+ ?settled=true|false (未指定なら両方)
80
+ ?from=YYYY-MM-DD&to=YYYY-MM-DD (occurred_on で絞り込み)
81
+ ?limit=200
82
+
83
+ Response:
84
+ {
85
+ "reimbursements": [{
86
+ id, paid_by_counterparty_id, occurred_on, amount, description,
87
+ expense_journal_entry_id, settled_at, settlement_journal_entry_id,
88
+ counterparty: { id, name, kind }
89
+ }]
90
+ }
91
+ ```
92
+
93
+ ### GET /api/accounting/expense-reimbursements/[id]
94
+
95
+ ```
96
+ Response:
97
+ {
98
+ "reimbursement": {
99
+ ...,
100
+ counterparty: {...},
101
+ expense_entry: {...},
102
+ settlement_entry: null|{...}
103
+ }
104
+ }
105
+ ```
106
+
107
+ ### DELETE /api/accounting/expense-reimbursements/[id]
108
+
109
+ 立替記帳の取消(精算前のみ)。関連する立替仕訳も同時に削除される。
110
+
111
+ ```
112
+ エラー:
113
+ 409 already_settled — 精算済みは取消不可
114
+ ```
115
+
116
+ ## ベストプラクティス
117
+
118
+ - 立替者を識別できない場合は推測しない。`GET /counterparties?q=<name>` で検索し、複数候補がある場合は **PMに確認** すること
119
+ - 「立替金」(asset 勘定として存在することがある)は会社が他者のために立て替えた場合の科目。**役員/従業員が立て替えた場合の貸方には使わない** こと
120
+ - 描かれた `next_action` を必ず読む。recover 可能なエラーは指示通りに対処
@@ -0,0 +1,100 @@
1
+ # API: 仕訳(Journal Entries)
2
+
3
+ 複式簿記の仕訳エンドポイント。立替経費以外の通常取引(収入/支出/振替/手動仕訳/期首残高)を扱う。
4
+
5
+ ## entry_type の区別
6
+
7
+ | entry_type | 用途 | buildLines の挙動 |
8
+ |-----------|------|------------------|
9
+ | `income` | 収入 | (借)wallet / (貸)category(収益) |
10
+ | `expense` | 支出 | (借)category(費用) / (貸)wallet |
11
+ | `transfer` | 振替 | (借)to_account / (貸)from_account |
12
+ | `manual` | 手動仕訳(複合仕訳) | lines を直接指定 |
13
+ | `opening_balance` | 期首残高 | 専用APIあり(本ドキュメント対象外) |
14
+
15
+ ## エンドポイント
16
+
17
+ ### POST /api/accounting/entries
18
+
19
+ **シンプル仕訳 (income/expense):**
20
+ ```
21
+ {
22
+ "entry_type": "expense",
23
+ "entry_date": "2026-05-25",
24
+ "amount": 1000,
25
+ "wallet_account_id": "<is_wallet=true の account>",
26
+ "category_account_id": "<expense 型の account>",
27
+ "description": "サーバー利用料",
28
+ "category_dimensions": { "net_asset_restriction": "general" } // 一般社団法人プロファイル時のみ必要
29
+ }
30
+ ```
31
+
32
+ **振替 (transfer):**
33
+ ```
34
+ {
35
+ "entry_type": "transfer",
36
+ "entry_date": "2026-05-25",
37
+ "amount": 50000,
38
+ "from_account_id": "<wallet account>",
39
+ "to_account_id": "<wallet account>",
40
+ "description": "現金→普通預金"
41
+ }
42
+ ```
43
+
44
+ **手動仕訳 (manual) - 複合仕訳が必要なときのみ:**
45
+ ```
46
+ {
47
+ "entry_type": "manual",
48
+ "entry_date": "2026-05-25",
49
+ "description": "...",
50
+ "lines": [
51
+ { "account_id": "...", "debit": 1000, "credit": 0, "memo": "...", "counterparty_id": "..." },
52
+ { "account_id": "...", "debit": 0, "credit": 1000, "counterparty_id": "..." }
53
+ ]
54
+ }
55
+ ```
56
+
57
+ **注意点:**
58
+ - `lines` は **必ず2行以上** で **借方合計=貸方合計** であること(DB triggerで強制される)
59
+ - `counterparty_id` は任意。付与すると補助元帳でその取引先の明細として集計される
60
+ - 一般社団法人プロファイルでは収益/費用行に `dimensions.net_asset_restriction` が必須
61
+
62
+ ```
63
+ Response: { "entry": {...} }
64
+ エラー:
65
+ 400 entry_date and entry_type are required
66
+ 400 at least 2 lines required
67
+ 400 debit/credit must balance
68
+ 409 period_closed
69
+ ```
70
+
71
+ ### PATCH /api/accounting/entries/[id]
72
+
73
+ 仕訳の編集。明細は全置換(既存lineを削除して body.lines を挿入)。
74
+
75
+ ```
76
+ 締めチェック:
77
+ - 元の entry_date が締め後 → 409 period_closed (編集不可)
78
+ - 新しい entry_date が締め後 → 409 (日付変更不可)
79
+ - opening_balance は編集不可(専用画面から再入力)
80
+ ```
81
+
82
+ ### DELETE /api/accounting/entries/[id]
83
+
84
+ 仕訳削除。lines は CASCADE で同時削除。
85
+
86
+ ### GET /api/accounting/entries
87
+
88
+ ```
89
+ Query:
90
+ ?from=YYYY-MM-DD&to=YYYY-MM-DD
91
+ ?limit=200
92
+
93
+ Response: { "entries": [{ ..., lines: [...] }] }
94
+ ```
95
+
96
+ ## ベストプラクティス
97
+
98
+ - **通常の経費は manual で複合仕訳を組まず、`expense` ですませる。** シンプルな分、間違いが少ない
99
+ - **立替経費は仕訳APIで組み立てず、必ず /expense-reimbursements を使う。** 自前で組むと「立替者」軸の集計ができない
100
+ - **dimensions の `net_asset_restriction`** は一般社団法人プロファイル時のみ意味あり。株式会社(corporation-jp)では空でOK
@@ -0,0 +1,117 @@
1
+ # Troubleshooting: 会計API
2
+
3
+ 会計APIで遭遇しやすいエラーパターンと対処。
4
+
5
+ ## エラーレスポンスの構造
6
+
7
+ ```json
8
+ {
9
+ "error": "missing_default_payable_account",
10
+ "message": "取引先「山田太郎」に立替用の貸方科目が未設定です",
11
+ "next_action": "PATCH /api/accounting/counterparties/<id> で...",
12
+ "context": { "counterparty_id": "..." }
13
+ }
14
+ ```
15
+
16
+ **必ず `next_action` を読み、その指示に従うこと。** 指示が曖昧な場合のみ自己判断する。
17
+
18
+ ## 立替経費まわり
19
+
20
+ ### `missing_default_payable_account` (422)
21
+
22
+ **原因:** 立替者の `default_payable_account_id` が未設定。
23
+
24
+ **対処:**
25
+ 1. liability 型の科目「役員借入金」「従業員未払金」などがあるか確認
26
+ - `GET /api/accounting/accounts` で `type=liability` をフィルタ
27
+ 2. 無ければ作成: `POST /api/accounting/accounts` で `{ name: "役員借入金", type: "liability" }`
28
+ 3. counterparty に紐付け: `PATCH /api/accounting/counterparties/<id>` で `{ default_payable_account_id: "..." }`
29
+ 4. 立替記帳をリトライ
30
+
31
+ ### `counterparty_not_found` (404)
32
+
33
+ **原因:** 立替者の counterparty が未登録。
34
+
35
+ **対処:**
36
+ 1. `GET /api/accounting/counterparties?q=<name>` で typo の可能性を確認
37
+ 2. 該当者がいなければ `POST /api/accounting/counterparties` で作成
38
+ - 役員なら `kind: "director"`、従業員なら `kind: "employee"`
39
+ - 可能なら `default_payable_account_id` も同時に設定
40
+
41
+ ### `counterparty_name_conflict` (409)
42
+
43
+ **原因:** 同名のアクティブな取引先が既に存在(本人と判断できない場合がある)。
44
+
45
+ **対処:**
46
+ - `context.existing_id` が返るので、それが同一人物か確認
47
+ - 同一人物なら既存IDを使う
48
+ - 別人なら名前を変える(例: "山田太郎(役員)" vs "山田太郎(従業員)")
49
+
50
+ ### `already_settled` (409)
51
+
52
+ **原因:** 精算しようとした立替が既に精算済み。
53
+
54
+ **対処:** `context.settled_at` と `context.settlement_journal_entry_id` を確認し、二重精算を回避
55
+
56
+ ## 期間まわり
57
+
58
+ ### `period_closed` (409)
59
+
60
+ **原因:** 指定日付が締め済期間内。
61
+
62
+ **対処:**
63
+ - 締めはPMの権限。勝手に再オープンしない
64
+ - 締め後の取引なら日付を調整(後日付に変更)、または PM にエスカレーション
65
+ - threadで `mentions: ["role:pm"]` を付けて「<DATE> の取引が締め後だが記帳が必要」と相談
66
+
67
+ ## 科目まわり
68
+
69
+ ### `invalid_expense_account_type` (400)
70
+
71
+ **原因:** 立替経費の費用科目に expense 型でない科目を指定した。
72
+
73
+ **対処:** `GET /api/accounting/accounts` で type=expense の科目を取得して使用
74
+
75
+ ### `not_a_wallet_account` (400)
76
+
77
+ **原因:** 精算時の支払口座に `is_wallet=false` の科目を指定した。
78
+
79
+ **対処:** `is_wallet=true` の科目(現金/普通預金)を選択
80
+
81
+ ### `invalid_default_payable_account` (400)
82
+
83
+ **原因:** default_payable_account_id に asset/revenue/expense 型を指定した。
84
+
85
+ **対処:** liability 型(または equity 型)の科目を指定する。「立替金」(asset)は逆向きなので使わない
86
+
87
+ ## 仕訳整合性
88
+
89
+ ### `at least 2 lines required` / `debit/credit must balance`
90
+
91
+ **原因:** 手動仕訳の `lines` が壊れている。
92
+
93
+ **対処:**
94
+ - lines は2行以上必要
95
+ - 借方合計 = 貸方合計 を自前で計算してから POST
96
+ - DB trigger は不整合を必ず検出するので、ローカル検算が大事
97
+
98
+ ## 取引先のアーカイブ
99
+
100
+ ### `has_unsettled_reimbursements` (409)
101
+
102
+ **原因:** 未精算の立替が残っている取引先をアーカイブしようとした。
103
+
104
+ **対処:**
105
+ 1. `GET /api/accounting/expense-reimbursements?counterparty_id=<id>&settled=false` で未精算リスト取得
106
+ 2. 各立替を精算 (`POST /<id>/settle`)
107
+ 3. アーカイブを再実行
108
+
109
+ ## 自己解決できない場合
110
+
111
+ エラーの `next_action` が無い、または指示通り対処しても繰り返し失敗する場合:
112
+
113
+ 1. プロジェクトメモリーで過去事例を検索
114
+ 2. なければ `POST /api/threads` でヘルプスレッド起票
115
+ - `thread_type: "help"`, `mentions: ["role:pm"]`
116
+ - `attempted_resolution` に試したことを必ず書く
117
+ 3. **仕訳を中途半端な状態で残さない。** 失敗した立替記帳は `DELETE /api/accounting/expense-reimbursements/<id>` で取り消してからエスカレーション