@geekbeer/minion 4.2.1 → 4.3.3

package/skills/accounting-bookkeeping/references/api-counterparties.md

@@ -2,6 +2,9 @@
 
 取引先マスタは `book_id` スコープ。役員・従業員・仕入先・顧客などを統一管理する。
 
+> パスはすべて **ミニオン用** `$HQ_URL/api/minion/workspaces/:id/accounting/` を基準とした相対表記。
+> 認証は `Authorization: Bearer $API_TOKEN`。人間用 `/api/accounting/*` は使わない。
+
 ## kind の選び方
 
 | kind | 用途 |
@@ -22,24 +25,22 @@
 - 許容: **equity** 型(運用実態として一部の帳簿で利用されるため)
 - NG: **asset/revenue/expense** 型 → API が `invalid_default_payable_account` で 400 を返す
 
-該当科目が無い場合は先に `POST /api/accounting/accounts` で作成すること。
+該当科目が無い場合は先に `POST /accounts` で作成すること。
 
 ## エンドポイント
 
-### GET /api/accounting/counterparties
+### GET /counterparties
 
 ```
 Query:
-  ?q=<部分一致検索>
   ?kind=director,employee  (カンマ区切り)
   ?include_archived=true   (デフォルトはアクティブのみ)
-  ?limit=200               (max 500)
 
 Response:
   { "counterparties": [{ id, book_id, name, kind, member_id, default_payable_account_id, is_archived, ... }] }
 ```
 
-### POST /api/accounting/counterparties
+### POST /counterparties
 
 ```
 Body:
@@ -50,7 +51,7 @@ Body:
     "default_payable_account_id": "<account uuid>"
   }
 
-Response 201: { "counterparty": {...} }
+Response: { "counterparty": {...} }
 
 エラー:
   400 invalid_kind                       — kind 不正
@@ -58,14 +59,23 @@ Response 201: { "counterparty": {...} }
   409 counterparty_name_conflict         — 同名のアクティブな取引先が存在 (context.existing_id 参照)
 ```
 
-### GET /api/accounting/counterparties/[id]
+### GET /counterparties/:counterpartyId
+
+取引先詳細と残高サマリ。補助元帳の照会はこのエンドポイントを使う。
 
 ```
-Response: { "counterparty": {...} }
+Response:
+  {
+    "counterparty": {...},
+    "balance": { "debit_total": ..., "credit_total": ..., "net": ... }
+  }
 404 counterparty_not_found
 ```
 
-### PATCH /api/accounting/counterparties/[id]
+残高の符号: 資産/費用は `debit - credit`、負債/純資産/収益は `credit - debit`。
+明細レベルの内訳が必要な場合は `GET /entries?...` で当該取引先の line を含む仕訳を取得して集計する。
+
+### PATCH /counterparties/:counterpartyId
 
 ```
 Body (全て任意):
@@ -74,36 +84,10 @@ Body (全て任意):
 Response: { "counterparty": {...} }
 ```
 
-### DELETE /api/accounting/counterparties/[id]
-
-ソフト削除(`is_archived=true`)。物理削除はしない(過去仕訳の参照を保持するため)。
-
-```
-エラー:
-  409 has_unsettled_reimbursements — 未精算の立替が残っているとアーカイブ不可
-```
-
-### GET /api/accounting/counterparties/[id]/balance
+`is_archived: true` でソフトアーカイブできる。未精算の立替が残っている取引先は
+409 `has_unsettled_reimbursements` でアーカイブ不可(精算は人間専用なので人間に依頼)。
 
-補助元帳。取引先別の残高(勘定科目別)と明細リスト。
+### 取引先の削除 — **人間専用**
 
-```
-Query:
-  ?as_of=YYYY-MM-DD  (任意。これより前の仕訳のみ集計)
-  ?limit=500         (明細最大件数)
-
-Response:
-  {
-    "counterparty": {...},
-    "balance_by_account": [
-      { "account_id", "code", "name", "type", "debit", "credit", "balance" }
-    ],
-    "lines": [
-      { "id", "account_id", "debit", "credit", "memo", "entry": {...}, "account": {...} }
-    ],
-    "unsettled_reimbursements_count": 2,
-    "as_of": null
-  }
-```
-
-残高の符号: 資産/費用は `debit - credit`、負債/純資産/収益は `credit - debit`。
+物理削除 (`DELETE`) はミニオンには提供されない(過去仕訳の参照を保持するため)。
+不要な取引先は上記 PATCH の `is_archived: true` でアーカイブする。完全削除が必要な場合は人間に依頼する。

package/skills/accounting-bookkeeping/references/api-expense-reimbursement.md

@@ -2,15 +2,24 @@
 
 立替経費は「立替記帳の仕訳」と「精算の仕訳」の対応関係を保持する別レイヤ。両仕訳の line に同じ `counterparty_id` が付与される。
 
+> パスはすべて **ミニオン用** `$HQ_URL/api/minion/workspaces/:id/accounting/` を基準とした相対表記。
+> ミニオン側のリソース名は **`reimbursements`**(人間用の `expense-reimbursements` ではない)。
+> 認証は `Authorization: Bearer $API_TOKEN`。
+
+## ミニオンが扱える操作
+
+ミニオンに提供されるのは **一覧取得 (GET)** と **記帳 (POST)** の2つだけ。
+精算・編集・削除は実出金や取消を伴うため **人間専用**(後述)。
+
 ## 仕訳パターン
 
-**立替記帳時:**
+**立替記帳時 (POST /reimbursements が自動生成):**
 ```
 (借) 費用科目                 amount    [counterparty_id=<立替者>]
   (貸) counterparty.default_payable_account_id   amount    [counterparty_id=<立替者>]
 ```
 
-**精算時:**
+**精算時 (人間が HQ UI で実行):**
 ```
 (借) counterparty.default_payable_account_id   amount    [counterparty_id=<立替者>]
   (貸) wallet_account (現金 or 普通預金)         amount    [counterparty_id=<立替者>]
@@ -18,9 +27,27 @@
 
 ## エンドポイント
 
-### POST /api/accounting/expense-reimbursements
+### GET /reimbursements
+
+```
+Query:
+  ?status=settled|unsettled|all   (default: 全件相当。未精算だけ見たいときは unsettled)
+  ?counterparty_id=<uuid>
+  ?limit=100&offset=0
+
+Response:
+  {
+    "reimbursements": [{
+      id, paid_by_counterparty_id, occurred_on, amount, description,
+      expense_journal_entry_id, settled_at, settlement_journal_entry_id,
+      counterparty: { id, name, kind }
+    }]
+  }
+```
+
+### POST /reimbursements
 
-立替経費を記帳する。
+立替経費を記帳する。仕訳(借方=expense, 貸方=payable)を自動生成する。
 
 ```
 Body:
@@ -30,13 +57,10 @@ Body:
     "amount": 1000,
     "expense_account_id": "<費用科目 uuid>",
     "description": "新幹線代 東京→大阪",      // 任意
-    "receipt_ids": ["<receipt uuid>"],         // 任意。既存の未添付レシートを紐付ける
-    "category_dimensions": {                   // 任意。一般社団法人プロファイル等で expense 行に
-      "net_asset_restriction": "general"        // ディメンションが必要な場合に指定。expense 行(借方)のみに付与される
-    }
+    "payable_account_id": "<貸方科目 uuid>"   // 任意。省略時は counterparty.default_payable_account_id を使用
   }
 
-Response 201: { "reimbursement": { "id", "expense_journal_entry_id" } }
+Response: { "reimbursement": { "id", "expense_journal_entry_id" } }
 
 主要エラー:
   400 invalid_amount                       — amount が正の数値でない
@@ -44,137 +68,26 @@ Response 201: { "reimbursement": { "id", "expense_journal_entry_id" } }
   400 invalid_expense_account_type         — expense_account_id が expense 型でない
   404 counterparty_not_found               — 立替者が見つからない (next_action: POST で先に作成)
   409 counterparty_archived                — 立替者がアーカイブ済み
-  409 period_closed                        — occurred_on が締め済期間内
-  422 missing_default_payable_account      — 立替者の default_payable_account_id が未設定
-```
-
-### PATCH /api/accounting/expense-reimbursements/[id]
-
-未精算の立替経費を編集する。仕訳ヘッダ・明細・reimbursement ヘッダを整合させた状態で更新する。
-精算済みの立替は編集できない (先に精算を取り消す必要がある)。
-**counterparty (立替者) の変更はサポートしない** — 変更する場合は削除して再作成すること。
-
-```
-Body (すべて optional、最低1つは渡す):
-  {
-    "occurred_on": "YYYY-MM-DD",
-    "amount": 1200,
-    "expense_account_id": "<費用科目 uuid>",
-    "description": "新幹線代 東京→大阪 (金額訂正)",
-    "category_dimensions": { "net_asset_restriction": "general" }
-  }
-
-Response 200: { "reimbursement": { "id", "expense_journal_entry_id" } }
-
-主要エラー:
-  400 invalid_amount / invalid_date / expense_account_not_found / invalid_expense_account_type
-  404 reimbursement_not_found
-  409 already_settled                — 精算済み (next_action: 精算を先に取り消す)
-  409 period_closed                  — 変更前後の日付が締め済期間内
-  422 missing_default_payable_account
-```
-
-### POST /api/accounting/expense-reimbursements/[id]/settle
-
-立替を全額精算する。**部分精算は非対応**。
-
-```
-Body:
-  {
-    "settled_on": "YYYY-MM-DD",
-    "wallet_account_id": "<is_wallet=true の account uuid>"
-  }
-
-Response: { "reimbursement": { "id", "expense_journal_entry_id" } }
-  ※ expense_journal_entry_id は精算仕訳のIDが返る
-
-主要エラー:
-  404 reimbursement_not_found
-  409 already_settled                — 既に精算済み (context.settled_at 参照)
-  409 period_closed                  — settled_on が締め済期間内
-  400 wallet_account_not_found       — 支払口座が見つからない
-  400 not_a_wallet_account           — is_wallet=false の科目を指定した
-  422 missing_default_payable_account — 立替者の貸方科目が後から消去された場合
-```
-
-### POST /api/accounting/expense-reimbursements/bulk-settle
-
-複数の立替を1本の精算仕訳でまとめて精算する。実運用で「役員Aの今月分3件を1回の振込で精算」する典型ケース向け。
-
-```
-Body:
-  {
-    "reimbursement_ids": ["<uuid>", "<uuid>", ...],  // 未精算の立替IDを1件以上
-    "settled_on": "YYYY-MM-DD",
-    "wallet_account_id": "<is_wallet=true の account uuid>"
-  }
-
-仕訳 (合計1本):
-  (借) counterparty.default_payable_account   sum(amounts)   [counterparty_id=<立替者>]
-    (貸) wallet_account                         sum(amounts)   [counterparty_id=<立替者>]
-
-Response: { "settlement_entry_id": "<uuid>", "reimbursement_ids": ["<uuid>", ...] }
-
-制約:
-  - すべての reimbursement が同一 counterparty に属すこと (混在不可)
-  - 全額精算のみ (部分精算は非対応)
-
-主要エラー:
-  400 missing_required_fields        — reimbursement_ids が空 / 必須項目欠落
-  400 multiple_counterparties        — 異なる立替者が混在 (context.counterparty_ids)
-  400 not_a_wallet_account           — 支払口座が is_wallet=false
-  404 reimbursement_not_found        — 一部のIDが見つからない (context.missing_ids)
-  409 already_settled                — 一部が既に精算済み (context.settled_ids)
-  409 period_closed                  — settled_on が締め済期間内
-  422 missing_default_payable_account — 立替者の貸方科目が未設定
-```
-
-データモデル: 精算仕訳と立替の関係は `accounting_reimbursement_settlements` (junction) で多対多管理される。単発 `/settle` 経由でも junction に行が書かれるため、補助元帳の集計クエリは junction を起点に書くと統一感が出る。`accounting_expense_reimbursements.settlement_journal_entry_id` は最後に紐付いた精算仕訳のポインタとして残る (後方互換用)。
-
-### GET /api/accounting/expense-reimbursements
-
+  409 code: 'period_closed'                — occurred_on が締め済期間内
+  422 missing_default_payable_account      — 立替者の default_payable_account_id が未設定 (先に PATCH /counterparties で設定)
 ```
-Query:
-  ?counterparty_id=<uuid>
-  ?settled=true|false  (未指定なら両方)
-  ?from=YYYY-MM-DD&to=YYYY-MM-DD  (occurred_on で絞り込み)
-  ?limit=200
-
-Response:
-  {
-    "reimbursements": [{
-      id, paid_by_counterparty_id, occurred_on, amount, description,
-      expense_journal_entry_id, settled_at, settlement_journal_entry_id,
-      counterparty: { id, name, kind }
-    }]
-  }
-```
-
-### GET /api/accounting/expense-reimbursements/[id]
 
-```
-Response:
-  {
-    "reimbursement": {
-      ...,
-      counterparty: {...},
-      expense_entry: {...},
-      settlement_entry: null|{...}
-    }
-  }
-```
+## 人間専用操作 (ミニオンから提供されない)
 
-### DELETE /api/accounting/expense-reimbursements/[id]
+以下は実出金・取消を伴うため、`POST /api/threads` で `@user` メンションして HQ UI 操作を依頼する。
 
-立替記帳の取消(精算前のみ)。関連する立替仕訳も同時に削除される。
+| 操作 | 説明 / 依頼先 |
+|------|--------------|
+| `settle` (個別精算) | 立替を全額精算。HQ UI `/accounting/reimbursements` の精算ボタン |
+| `bulk-settle` (一括精算) | 同一立替者の複数件を1本の精算仕訳でまとめて精算 |
+| `PATCH` (編集) | 未精算立替の金額・科目訂正 |
+| `DELETE` (取消) | 精算前の立替記帳の取消 |
 
-```
-エラー:
-  409 already_settled — 精算済みは取消不可
-```
+ミニオンができるのは「未精算リストを `GET /reimbursements?status=unsettled` で把握 → 人間に精算を依頼」まで。
 
 ## ベストプラクティス
 
-- 立替者を識別できない場合は推測しない。`GET /counterparties?q=<name>` で検索し、複数候補がある場合は **PMに確認** すること
+- 立替者を識別できない場合は推測しない。`GET /counterparties?kind=director,employee` で検索し、複数候補がある場合は **PMに確認** すること
 - 「立替金」(asset 勘定として存在することがある)は会社が他者のために立て替えた場合の科目。**役員/従業員が立て替えた場合の貸方には使わない** こと
-- 描かれた `next_action` を必ず読む。recover 可能なエラーは指示通りに対処
+- 返ってきた `next_action` を必ず読む。recover 可能なエラーは指示通りに対処
+- **記帳に失敗して中途半端な状態が残った場合、ミニオンは DELETE できない。** `POST /api/threads` で状況を報告し、人間に取消を依頼すること

package/skills/accounting-bookkeeping/references/api-journal-entries.md

@@ -1,6 +1,10 @@
 # API: 仕訳(Journal Entries)
 
-複式簿記の仕訳エンドポイント。立替経費以外の通常取引(収入/支出/振替/手動仕訳/期首残高)を扱う。
+複式簿記の仕訳エンドポイント。立替経費以外の通常取引(収入/支出/振替/手動仕訳)を扱う。
+
+> パスはすべて **ミニオン用** `$HQ_URL/api/minion/workspaces/:id/accounting/` を基準とした相対表記。
+> 認証は `Authorization: Bearer $API_TOKEN`。人間用 `/api/accounting/*` は使わない。
+> ミニオンが作成した仕訳は **常に `source='ai_generated'`** で記録される。
 
 ## entry_type の区別
 
@@ -10,11 +14,11 @@
 | `expense` | 支出 | (借)category(費用) / (貸)wallet |
 | `transfer` | 振替 | (借)to_account / (貸)from_account |
 | `manual`  | 手動仕訳(複合仕訳) | lines を直接指定 |
-| `opening_balance` | 期首残高 | 専用APIあり(本ドキュメント対象外) |
+| `opening_balance` | 期首残高 | **人間専用**(ミニオンからは設定不可) |
 
 ## エンドポイント
 
-### POST /api/accounting/entries
+### POST /entries
 
 **シンプル仕訳 (income/expense):**
 ```
@@ -72,37 +76,50 @@ Response: { "entry": {...} }
   400 manual entry requires at least 2 lines      — lines 配列が短い
   400 line[N]: exactly one of debit/credit must be positive   — 行レベル不整合
   400 指定された勘定科目がこの帳簿に存在しません          — account_id が別 book / 削除済
-  409 period_closed
+  409 code: 'period_closed'                        — entry_date が締め済期間内
 ```
 
-### PATCH /api/accounting/entries/[id]
+### PATCH /entries/:entryId
 
 仕訳の編集。明細は全置換(既存lineを削除して body.lines を挿入)。
 
+**`source='ai_generated'` の仕訳(=ミニオンが作成したもの)のみ編集可能。**
+人間作成仕訳 (`source='manual'` / `'import'`) を PATCH すると **409 `code: 'human_owned_entry'`**。
+修正が必要なら `POST /api/threads` で人間に依頼すること。
+
 ```
 締めチェック:
-  - 元の entry_date が締め後 → 409 period_closed (編集不可)
+  - 元の entry_date が締め後 → 409 code: 'period_closed' (編集不可)
   - 新しい entry_date が締め後 → 409 (日付変更不可)
-  - opening_balance は編集不可(専用画面から再入力)
+  - opening_balance は編集不可(人間専用画面から再入力)
 ```
 
-### DELETE /api/accounting/entries/[id]
+### 仕訳の削除 — **人間専用**
 
-仕訳削除。lines は CASCADE で同時削除。
+`DELETE` はミニオンには提供されない。誤記帳の取消が必要な場合は、可能なら PATCH で訂正するか、
+`POST /api/threads` で `@user` メンションして HQ UI からの削除を依頼する。
 
-### GET /api/accounting/entries
+### GET /entries
 
 ```
 Query:
   ?from=YYYY-MM-DD&to=YYYY-MM-DD
-  ?limit=200
+  ?entry_type=income,expense,...   (カンマ区切り)
+  ?limit=100&offset=0
 
 Response: { "entries": [{ ..., lines: [...] }] }
 ```
 
+### GET /entries/:entryId
+
+```
+Response: { "entry": { ..., lines: [...] } }
+```
+
 ## ベストプラクティス
 
 - **通常の経費は manual で複合仕訳を組まず、`expense` ですませる。** シンプルな分、間違いが少ない
-- **立替経費は仕訳APIで組み立てず、必ず /expense-reimbursements を使う。** 自前で組むと「立替者」軸の集計ができない
+- **立替経費は仕訳APIで組み立てず、必ず /reimbursements を使う。** 自前で組むと「立替者」軸の集計ができない
 - **dimensions の `net_asset_restriction`** は一般社団法人プロファイル時のみ意味あり。株式会社(corporation-jp)では空でOK
 - **manual を使う判断基準**: 1取引イベントで3科目以上を同時に動かす必要があるとき (給与/源泉/振込のセット、1レシートを複数費用科目に按分 等)。2科目で済むなら income/expense/transfer のいずれかに当てはまる
+- **作成した仕訳は人間がレビューしてから承認する前提。** ミニオン作成分は HQ UI で 🤖 バッジ付き表示される

package/skills/accounting-bookkeeping/references/api-receipts.md

@@ -0,0 +1,75 @@
+# API: レシート(Receipts)
+
+レシート(領収書)画像/PDF のメタデータ照会とダウンロード。OCR や内容確認の入力に使う。
+
+> パスはすべて **ミニオン用** `$HQ_URL/api/minion/workspaces/:id/accounting/` を基準とした相対表記。
+> 認証は `Authorization: Bearer $API_TOKEN`。**accountant ロール必須**(v4.3.0〜)。
+
+## ミニオンが扱える操作
+
+照会 (一覧・メタデータ) と **ダウンロード用 signed URL の取得** のみ。
+アップロードと仕訳への attach/detach は **人間専用**(後述)。
+
+## エンドポイント
+
+### GET /receipts
+
+レシート一覧。
+
+```
+Query:
+  ?attached=true|false|all   (default: false = 未添付のみ)
+  ?limit=100                 (max 500)
+
+Response:
+  { "receipts": [{ id, file_name, mime_type, uploaded_at, attached_entry_id, ... }] }
+```
+
+- `attached=false` … まだ仕訳に紐付いていないレシート(OCR → 記帳の対象を探すときに使う)
+- `attached=all` … 添付済み含む全件
+
+### GET /receipts/:receiptId
+
+単一レシートのメタデータ。
+
+```
+Response: { "receipt": { id, file_name, mime_type, uploaded_at, attached_entry_id, ... } }
+404 not_found  — ID 違い / 別ワークスペース
+```
+
+### GET /receipts/:receiptId/download
+
+**60秒だけ有効な signed URL** を返す。画像/PDF の実体取得や OCR への入力に使う。
+
+```
+Response:
+  {
+    "url": "https://...",          // 60秒で失効
+    "mime_type": "image/jpeg",
+    "file_name": "receipt-2026-05.jpg",
+    "expires_in_seconds": 60
+  }
+```
+
+URL は短命なので、取得したら即座に fetch すること。失効したら再度このエンドポイントを叩く。
+
+対応 MIME: `image/png` / `image/jpeg` / `image/webp` / `image/gif` / `image/heic` / `image/heif` / `application/pdf`。
+
+## 典型フロー (OCR → 記帳)
+
+```
+1. GET /receipts?attached=false で未処理レシートを一覧
+2. GET /receipts/:id/download で signed URL を取得し、画像/PDF を読み取り (OCR)
+3. 読み取った内容から POST /entries または POST /reimbursements で仕訳を作成
+4. レシートと仕訳の attach は人間が HQ UI で行う (下記)
+```
+
+## 人間専用操作 (ミニオンから提供されない)
+
+| 操作 | 説明 / 依頼先 |
+|------|--------------|
+| レシートのアップロード | HQ UI からユーザーがアップロード |
+| 仕訳との attach / detach (`PATCH`) | HQ UI で人間が判断・操作 |
+
+ミニオンが OCR → 仕訳作成した後、「この仕訳にこのレシートを添付してほしい」場合は
+`POST /api/threads` で `@user` メンションして依頼する(レシート ID と仕訳 ID をリンク)。

package/skills/accounting-bookkeeping/references/api-reports-tax.md

@@ -0,0 +1,106 @@
+# API: 財務諸表(Reports)・法人税計算(Tax Calculations)
+
+> パスはすべて **ミニオン用** `$HQ_URL/api/minion/workspaces/:id/accounting/` を基準とした相対表記。
+> 認証は `Authorization: Bearer $API_TOKEN`。
+
+## 財務諸表(Reports)
+
+すべて Read 専用。PM・ユーザーへの月次/期次報告で使う。取得した数値は
+**ノート (`hq note create <project_id> --title ... --content ...`)** にまとめると HQ UI で共有・検索できる。
+
+### GET /reports/trial-balance
+
+試算表 + B/S + P/L を一括で返す(最も情報量が多い)。
+
+```
+Query:
+  ?from=YYYY-MM-DD&to=YYYY-MM-DD   (任意。期間絞り込み)
+  ?includeZero=true|false          (残高ゼロ科目を含めるか。default false)
+
+Response (概略):
+  {
+    "trialBalance": [{ account_id, code, name, type, debit, credit, balance }],
+    "balanceSheet": {...},
+    "incomeStatement": {...},
+    "netAssetBalanceSheet": {...}   // 一般社団法人プロファイルのときのみ含まれる(正味財産区分付き B/S)
+  }
+```
+
+### GET /reports/income-statement
+
+P/L のみ(軽量)。当期の収益・費用・当期純利益を返す。
+
+### GET /reports/balance-sheet
+
+B/S のみ(軽量)。資産・負債・純資産の残高を返す。
+
+## 法人税計算(Tax Calculations)ウィザード
+
+**対象は `org_type=corporation` または `general_incorporated_association` の帳簿のみ**。
+それ以外は 403 `code: 'org_type_ineligible'`。
+
+ミニオンが触れるのは **`draft` 状態の計算だけ**。`finalized` / `journalized` 状態の計算を
+更新しようとすると 409 `code: 'invalid_status'`。**finalize / journalize / reopen は人間専用**。
+
+> 税率はツール側にテーブルを持たない。国税庁・自治体サイトで**最新の値をミニオン自身が調査**して入力する。
+> 税率の確定は法的責任を伴うため、最終確定(finalize)は必ず人間が行う。
+
+### エンドポイント
+
+| Method | Path | 説明 |
+|--------|------|------|
+| GET | `/tax-calculations` | 計算一覧。Query: `?fiscal_period_id=<uuid>&status=draft,finalized,journalized` |
+| GET | `/tax-calculations/:calcId` | 詳細 `{ calculation, adjustments, components }` |
+| POST | `/tax-calculations` | 新規作成。Body: `{ fiscal_period_id, notes? }`。6税目を seed |
+| PATCH | `/tax-calculations/:calcId` | `pretax_income` / `notes` 更新 |
+| GET | `/tax-calculations/:calcId/pretax-income` | P/L から税引前当期純利益を再計算(法人税科目は除外) |
+| GET | `/tax-calculations/:calcId/ensure-accounts` | 必要4科目(法人税費用/未払/仮払/未収還付)の存在確認 |
+| POST | `/tax-calculations/:calcId/ensure-accounts` | 不足4科目をテンプレから自動追加 |
+| POST | `/tax-calculations/:calcId/adjustments` | 別表四相当の加算/減算追加(下記) |
+| PATCH | `/tax-calculations/:calcId/adjustments/:adjId` | 加算/減算更新 |
+| DELETE | `/tax-calculations/:calcId/adjustments/:adjId` | 加算/減算削除 |
+| PATCH | `/tax-calculations/:calcId/components/:compId` | 税目別の税率・中間納付・(均等割のみ)直接税額を更新 |
+
+#### adjustments の Body
+
+```
+{
+  "adjustment_type": "addition" | "deduction",
+  "category": "entertainment_excess" | "depreciation_excess" | "executive_salary_excess"
+            | "reserve_addition" | "dividend_excluded" | "tax_refund_excluded" | "custom",
+  "amount": 100000,
+  "description": "交際費損金不算入",   // 任意
+  "sort_order": 1                       // 任意
+}
+```
+
+#### components (税目) の更新 Body
+
+```
+{
+  "tax_rate": 23.2,           // % 表記 (例: 23.2)
+  "prepaid_amount": 50000,    // 中間納付額 (任意)
+  "calculated_amount": 70000  // tax_type='inhabitant_per_capita' (均等割) のときのみ受理
+}
+```
+
+### 典型ワークフロー
+
+1. `GET /periods` で対象期(status='open')の id を選ぶ
+2. `POST /tax-calculations` で新規作成(pretax_income は P/L から自動取得)
+3. `POST /tax-calculations/:calcId/ensure-accounts` で必要4科目を揃える
+4. 国税庁・自治体サイトで最新税率を調査 → `PATCH /components/:compId` で各税目の `tax_rate` を入力
+5. 中間納付があれば `PATCH /components/:compId` で `prepaid_amount` を入力
+6. 必要なら `POST /adjustments` で別表四相当の加減算を追加(調査・税理士相談の上)
+7. `POST /api/threads` で `@user` メンションして finalize → journalize を依頼
+
+依頼スレッドの例:
+```json
+{
+  "thread_type": "help",
+  "mentions": ["user"],
+  "title": "法人税計算 FY3 の finalize お願いします",
+  "content": "計算ID xxxx の入力が完了しました。HQダッシュボード /accounting/tax-calculations/xxxx でレビュー後、Finalize → Journalize ボタンを押してください。",
+  "context": { "accounting_action": "tax_finalize", "calculation_id": "xxxx" }
+}
+```