/journal

name: journal
description: >
  This skill should be used when the user wants to record bookkeeping entries
  (仕訳), import transaction data from CSV files, receipts, or invoices, or
  manage their general ledger. Trigger phrases include: "仕訳を入力",
  "仕訳登録", "CSVを取り込む", "レシートを読み込む", "請求書を取り込む",
  "帳簿を付ける", "経費を記録", "売上を記録", "仕訳を修正", "仕訳を検索",
  "仕訳を削除", "取引を登録", "帳簿の初期化".

仕訳入力・帳簿管理（Journal Entry & Ledger Management）

CSV・レシート・請求書からデータを取り込み、ユーザー確認のうえ仕訳を登録するスキル。 帳簿の初期化、仕訳の検索・修正・削除も本スキルで対応する。

CLI スクリプト

本スキルでは以下の CLI スクリプトを使用する:

• **帳簿管理**: `shinkoku ledger <subcommand> [args]`
• **データ取り込み**: `shinkoku import <subcommand> [args]`

すべてのコマンドは JSON を stdout に出力する。入力はコマンドライン引数または `--input <json_file>` で渡す。

設定の読み込み（最初に実行）

1. `shinkoku.config.yaml` を Read ツールで読み込む 2. ファイルが存在しない場合は `/setup` スキルの実行を案内して終了する 3. 設定値を把握し、相対パスは CWD を基準に絶対パスに変換する:

• `db_path`: CLI スクリプトの `--db-path` 引数に使用
• `output_dir`: 進捗ファイル等の出力先ベースディレクトリ
• 各ディレクトリ: ファイル参照時に使用

パス解決の例（db_path）

config の `db_path` が `./shinkoku.db` で CWD が `/home/user/tax-2025/` の場合、CLI スクリプトには絶対パス `/home/user/tax-2025/shinkoku.db` を `--db-path` で渡す。`init`, `journal-add`, `journal-batch-add`, `search`, `journal-update`, `journal-delete` すべてに同じ絶対パスを使用する。

進捗情報の読み込み

設定の読み込み後、引継書ファイルを読み込んで前ステップの結果を把握する。

1. `.shinkoku/progress/progress-summary.md` を Read ツールで読み込む（存在する場合） 2. 以下の引継書を Read ツールで読み込む（存在する場合）:

• `.shinkoku/progress/01-setup.md`

3. 読み込んだ情報を以降のステップで活用する（ユーザーへの再質問を避ける） 4. ファイルが存在しない場合はスキップし、ユーザーに必要情報を直接確認する

基本方針

• CSV取り込み → ユーザー確認 → 仕訳登録 の3ステップを基本フローとする
• 勘定科目は references/account-master.md のマスタデータに準拠する
• 仕訳登録前に必ずユーザーに内容を確認する（自動登録しない）
• 消費税区分（課税/非課税/不課税/対象外）を正確に設定する
• 日付・金額・勘定科目の整合性を検証してからツールを呼び出す
• エラー発生時はエラー内容を日本語で分かりやすく伝え、修正方法を提案する

前提条件の確認

仕訳入力を開始する前に以下を確認する:

1. **帳簿が初期化済みか**: 未初期化の場合は `init` コマンドで初期化を案内する 2. **会計年度**: 対象の会計年度（例: 2025）を確認する 3. **青色申告 or 白色申告**: 複式簿記（青色65万円控除）か簡易簿記かで記帳方法が変わる

ステップ1: 帳簿の初期化

初回利用時、または新しい会計年度を開始する際に帳簿を初期化する。

`init` コマンド

shinkoku ledger init \
  --db-path /path/to/shinkoku.db \
  --fiscal-year 2025

• 会計年度と保存先パスをユーザーに確認してから実行する
• 既存のデータベースがある場合は上書き警告を表示する
• 初期化完了後、勘定科目マスタが登録されたことを確認する

ステップ2: データの取り込み

ユーザーが持つ取引データの形式に応じて適切なインポートツールを選択する。

2-1. CSV取り込み（`csv` コマンド）

クレジットカード明細・銀行取引明細・会計ソフトのエクスポートデータ等を読み込む。

shinkoku import csv \
  --file-path /path/to/transactions.csv

戻り値（JSON）:

• `headers`: 検出されたカラムヘッダ一覧
• `rows`: パースされた各行のデータ
• `encoding`: 自動検出されたエンコーディング
• `row_count`: 行数

**取り込み後の処理手順:**

1. 取り込まれたデータのプレビューを表示する（先頭5〜10行） 2. 日付・金額・摘要のカラムを特定してユーザーに確認する 3. 各行に対して勘定科目の推定を行い、候補を提示する 4. 推定根拠を明示する（摘要のキーワードマッチ等） 5. ユーザーが科目を確認・修正したら仕訳データに変換する

**勘定科目の推定ルール:**

• 摘要に「電車」「バス」「タクシー」「JR」→ 旅費交通費（5130）
• 摘要に「Amazon」「ヨドバシ」→ 消耗品費（5190）または事務用品費（5360）
• 摘要に「ドコモ」「au」「ソフトバンク」→ 通信費（5140）
• 摘要に「東京電力」「ガス」「水道」→ 水道光熱費（5120）
• 摘要に「家賃」「賃料」→ 地代家賃（5250）
• 推定できない場合は「不明」として候補一覧を提示し、ユーザーに選択を求める

2-2. レシート取り込み（`receipt` コマンド）

紙のレシート・領収書の画像ファイルからOCRでデータを抽出する。

shinkoku import receipt \
  --file-path /path/to/receipt.jpg

**重要: 画像の読み取りは対応する reading-* スキルに委任する。**

単一レシートの場合

1. `receipt` コマンドでファイルの存在を確認する 2. 画像ファイルの読み取りには `/reading-receipt` スキルを使用する。 スキルの指示に従い、デュアル検証（2つの独立した読み取り結果の照合）を行って結果を取得する。

**結果照合:** 両方の読み取り結果から `total_amount`, `date`, `vendor` を比較する

**一致の場合:** そのまま採用。「2つの独立した読み取りで結果が一致しました」と報告

**不一致の場合:** ユーザーに元画像パスと両方の結果を提示し、正しい方を選択してもらう:

• 差異のあるフィールドを明示する
• A を採用 / B を採用 / 手動入力 の3択を AskUserQuestion で提示する

3. 読み取り結果の `---RECEIPT_DATA---` ブロックの内容を解析する 4. 日付・金額・店舗名をユーザーに表示して正しいか確認する 5. 品目から勘定科目を推定する 6. 家事按分の必要性を確認する（自宅兼事務所の場合等） 7. 確認後、仕訳データに変換する

複数レシートの一括処理

1. Glob ツールでレシート画像の一覧を取得する（例: `receipts/*.jpg`, `receipts/*.png`） 2. `receipt` コマンドで各ファイルの存在を確認する 3. 画像ファイルの読み取りには `/reading-receipt` スキルを使用する。 スキルの指示に従い、デュアル検証（2つの独立した読み取り結果の照合）を行って結果を取得する。

**結果照合:** ファイル単位で両方の読み取り結果の `total_amount`, `date`, `vendor` を比較する

**一致の場合:** そのまま採用。「2つの独立した読み取りで結果が一致しました」と報告

**不一致の場合:** 不一致のファイルについてユーザーに元画像パスと両方の結果を提示し、正しい方を選択してもらう:

• 差異のあるフィールドを明示する
• A を採用 / B を採用 / 手動入力 の3択を AskUserQuestion で提示する

4. 各レシートの結果をまとめてユーザーに提示する 5. 各レシートの勘定科目を推定し、一覧でユーザーに確認する 6. 確認後、`journal-batch-add` コマンドで一括登録する

2-3. 請求書取り込み（`invoice` コマンド）

PDFの請求書からテキストを抽出する。

shinkoku import invoice \
  --file-path /path/to/invoice.pdf

戻り値（JSON）:

• `vendor`: 請求元
• `date`: 請求日
• `due_date`: 支払期日
• `amount`: 請求金額
• `tax_amount`: 消費税額
• `items`: 明細行
• `raw_text`: 抽出生テキスト

画像ファイルの場合: OCR 読み取り

`extracted_text` が空の場合（画像ファイルまたはスキャン PDF）、画像の読み取りは `/reading-invoice` スキルを使用する。 スキルの指示に従い、デュアル検証（2つの独立した読み取り結果の照合）を行って結果を取得する。

**結果照合:** 両方の読み取り結果から `total_amount`, `tax_amount`, `date`, `vendor` を比較する

**一致の場合:** そのまま採用。「2つの独立した読み取りで結果が一致しました」と報告

**不一致の場合:** ユーザーに元画像パスと両方の結果を提示し、正しい方を選択してもらう:

• 差異のあるフィールドを明示する
• A を採用 / B を採用 / 手動入力 の3択を AskUserQuestion で提示する

**取り込み後の処理手順:**

1. 抽出結果を表示し、金額・日付・取引先が正しいか確認する 2. インボイス番号（T+13桁）の有無を確認する 3. 消費税の税率区分（10%/8%軽減税率）を確認する 4. 発生主義で未払金を計上するか、現金主義で処理するか確認する 5. 確認後、仕訳データに変換する

ステップ2.5: 重複チェック（CSVインポート時）

CSVインポートのフローに重複チェックを組み込む:

1. **ファイル重複チェック**: `check-imported` コマンドでファイルのハッシュを確認

   shinkoku import check-imported \
     --db-path DB --file-path /path/to/file.csv

• 既にインポート済みの場合はユーザーに警告し、再インポートの意思を確認する

2. **仕訳登録時の自動チェック**: `journal-batch-add` が自動的に重複を検出

• exact（完全一致）: 登録をブロック、既存の仕訳IDを表示
• similar（類似）: 警告を表示し、ユーザーに確認を求める
• ユーザーが「登録する」と回答した場合は `--force` を付けて再実行

3. **インポート記録**: 登録成功後、`record-source` コマンドでインポート履歴を記録する

   shinkoku import record-source \
     --db-path DB --file-path /path/to/file.csv --source-type csv

申告前の重複チェック

決算処理の前に `check-duplicates` コマンドを実行し、重複の疑いのある仕訳ペアを一覧表示する。

shinkoku ledger check-duplicates \
  --db-path DB --fiscal-year 2025

ユーザーに確認の上、不要な重複は `journal-delete` コマンドで削除する。

ステップ3: 仕訳の登録

ユーザーが確認したデータを帳簿に登録する。

3-1. 単一仕訳の登録（`journal-add`）

# journal.json に JournalEntry を JSON で記述
shinkoku ledger journal-add \
  --db-path DB --fiscal-year 2025 --input journal.json

`journal.json` の形式: