Journal Kazukinagata Shinkoku 2

---
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` コマンド

```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 --fiscal-year 2025 --input entries.json [--force]
```

**登録前の確認事項:**

- 登録件数と合計金額をサマリーとして提示する
- 「以下の N 件の仕訳を登録します。よろしいですか？」と確認する
- ユーザーの明示的な承認を得てから `journal-batch-add` を実行する

### 登録時の検証ルール

以下を検証し、不備があれば登録前に警告する:

1. **日付の妥当性**: 会計年度の範囲内であるか（例: 2025-01-01 〜 2025-12-31）
2. **勘定科目の存在**: 借方・貸方の科目コードがマスタに存在するか
3. **金額の正値**: 金額が正の整数であるか
4. **貸借の一致**: 複合仕訳の場合、借方合計 = 貸方合計であるか
5. **消費税区分の整合**: 科目の tax_category と税率の組み合わせが妥当か

## ステップ4: 仕訳の検索

登録済みの仕訳を検索する。

### `search` コマンド

```bash
# search_params.json に JournalSearchParams を記述
shinkoku ledger search \
  --db-path DB --input search_params.json
```

`search_params.json` の形式:
```json
{
  "fiscal_year": 2025,
  "date_from": "2025-01-01",
  "date_to": "2025-03-31",
  "account_code": "5200",
  "description_contains": "Amazon"
}
```

**検索結果の表示:**

- 検索結果を日付順の一覧表で表示する
- 各仕訳には journal_id を表示する（修正・削除で使用）
- 合計金額を末尾に表示する

## ステップ5: 仕訳の修正・削除

### 5-1. 仕訳の修正（`journal-update`）

```bash
shinkoku ledger journal-update \
  --db-path DB --fiscal-year 2025 --journal-id 42 --input updated.json
```

- 修正前後の差分を表示してから確認する
- 修正理由を摘要に追記することを推奨する

### 5-2. 仕訳の削除（`journal-delete`）

```bash
shinkoku ledger journal-delete \
  --db-path DB --journal-id 42
```

- 削除対象の仕訳内容を表示して確認する
- 「この仕訳を削除します。よろしいですか？」と最終確認する
- 削除は取り消しできない旨を注意喚起する

## よくある仕訳パターン

### 売上の計上

```
借方: 売掛金(1010) / 貸方: 売上(4001)   金額: 110,000円  税率: 10%
摘要: ○○社 Webサイト制作費 請求書No.2025-001
```

### 経費の支払い（事業用口座から）

```
借方: 消耗品費(5190) / 貸方: 普通預金(1002)  金額: 5,500円  税率: 10%
摘要: Amazon ワイヤレスキーボード
```

### 個人の財布から事業経費を支払った場合

```
借方: 旅費交通費(5130) / 貸方: 事業主借(3010)  金額: 1,200円  税率: 10%
摘要: JR 新宿→渋谷 打ち合わせ往復
```

### 事業資金を個人利用した場合

```
借方: 事業主貸(1200) / 貸方: 普通預金(1002)  金額: 50,000円
摘要: 生活費引き出し
```

## 次のステップの案内

仕訳入力が完了したら、以下を案内する:

- `settlement` スキルで決算整理・決算書作成を行う
- `trial-balance` コマンドで残高試算表を確認して仕訳漏れがないか検証する:
  ```bash
  shinkoku ledger trial-balance \
    --db-path DB --fiscal-year 2025
  ```
- 全取引の登録完了を確認してから決算処理に進む

## 引継書の出力

サマリー提示後、以下のファイルを Write ツールで出力する。
これにより、セッションの中断や Compact が発生しても次のステップで結果を引き継げる。

### ステップ別ファイルの出力

`.shinkoku/progress/04-journal.md` に以下の形式で出力する:

```
---
step: 4
skill: journal
status: completed
completed_at: "{当日日付 YYYY-MM-DD}"
fiscal_year: {tax_year}
---

# 仕訳入力・帳簿管理の結果

## インポート済みソース

| ソース名 | 件数 | インポート日 |
|---------|------|------------|
| {CSV名やレシート等} | {件数} | {日付} |

## 登録済み仕訳

- 総仕訳件数: {件数}件

## 主要勘定科目の残高（試算表スナップショット）

| 勘定科目 | コード | 残高 |
|---------|--------|------|
| {科目名} | {コード} | {残高}円 |
（売上、主要経費、現預金、売掛金、買掛金など主要科目を記載）

## 重複チェック結果

- チェック実施: {済み/未実施}
- 重複の疑い: {なし/あり（件数）}

## 未処理の項目

- {あれば記載、なければ「なし」}

## 次のステップ

/settlement で決算整理・決算書作成を行う
```

### 進捗サマリーの更新

`.shinkoku/progress/progress-summary.md` を更新する（存在しない場合は新規作成）:

- YAML frontmatter: fiscal_year、last_updated（当日日付）、current_step: journal
- テーブル: 全ステップの状態を更新（journal を completed に）
- 次のステップの案内を記載

### 出力後の案内

ファイルを出力したらユーザーに以下を伝える:
- 「引継書を `.shinkoku/progress/` に保存しました。セッションが中断しても次のスキルで結果を引き継げます。」
- 次のステップの案内