journal

# 仕訳入力・帳簿管理（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` コマンド

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

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

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

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

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

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

```bash
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でデータを抽出する。

```bash
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の請求書からテキストを抽出する。

```bash
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` コマンドでファイルのハッシュを確認
   ```bash
   shinkoku import check-imported \
     --db-path DB --file-path /path/to/file.csv
   ```
   - 既にインポート済みの場合はユーザーに警告し、再インポートの意思を確認する
2. **仕訳登録時の自動チェック**: `journal-batch-add` が自動的に重複を検出
   - exact（完全一致）: 登録をブロック、既存の仕訳IDを表示
   - similar（類似）: 警告を表示し、ユーザーに確認を求める
   - ユーザーが「登録する」と回答した場合は `--force` を付けて再実行
3. **インポート記録**: 登録成功後、`record-source` コマンドでインポート履歴を記録する
   ```bash
   shinkoku import record-source \
     --db-path DB --file-path /path/to/file.csv --source-type csv
   ```

### 申告前の重複チェック

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

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

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

## ステップ3: 仕訳の登録

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

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

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

`journal.json` の形式:
```json
{
  "date": "2025-01-15",
  "description": "摘要テキスト",
  "lines": [
    {"side": "debit", "account_code": "5200", "amount": 1000},
    {"side": "credit", "account_code": "1100", "amount": 1000}
  ]
}
```

### 3-2. 一括仕訳登録（`journal-batch-add`）

CSV取り込み等で複数の仕訳を一度に登録する場合に使用する。

```bash
# entries.json に JournalEntry の配列を記述
shinkoku ledger journal-batch-add \
  --db-path DB -