shinkoku

# shinkoku

確定申告自動化 Claude Code Plugin。Python 3.11+、SQLite WAL モードで動作する。
会社員＋副業（事業所得・青色申告）の所得税・消費税確定申告をエンドツーエンドで支援する。
帳簿管理・税額計算は CLI で実行し、確定申告書等作成コーナーへの入力は Claude in Chrome が代行する。

## 対象ペルソナ

Full = 計算＋確定申告書等作成コーナーへの入力代行、Out = 対象外

| ペルソナ | 対応レベル | 備考 |
|---------|-----------|------|
| 個人事業主（青色申告・一般用） | Full | メインターゲット。帳簿→決算書→税額計算→作成コーナー入力 |
| 会社員＋副業（事業所得） | Full | 源泉徴収票＋事業所得の税額計算→作成コーナー入力 |
| 給与所得のみ（会社員） | Full | 還付申告・医療費控除等→作成コーナー入力 |
| 消費税課税事業者 | Full | 2割特例・簡易課税・本則課税すべて対応 |
| ふるさと納税利用者 | Full | CRUD + 控除計算 + 限度額推定 |
| 住宅ローン控除（初年度） | Full | 控除額計算。初年度は添付書類が別途必要 |
| 医療費控除 | Full | 明細集計＋控除額計算 |
| 仮想通貨トレーダー | Full | 雑所得（総合課税）として税額計算に自動反映 |
| 株式投資家（分離課税） | Out | 株式譲渡所得・配当の分離課税には対応していません |
| FXトレーダー | Out | 先物取引に係る雑所得等には対応していません |
| 不動産所得 | Out | 不動産所得用の決算書・申告に対応していません |
| 退職所得 | Out | 退職所得控除の計算に対応していません |
| 譲渡所得（不動産売却） | Out | 長期/短期税率、3,000万円特別控除なし |
| 外国税額控除 | Out | 外国税支払額の追跡・控除計算なし |
| 農業所得・山林所得 | Out | 専用所得区分なし |
| 非居住者 | Out | 日本居住者専用 |

## 対象外の機能

| 機能 | 理由 |
|------|------|
| マイナポータル連携 | freee 等の SaaS 固有機能（API 連携が前提） |

## アーキテクチャ

```
skills/ (SKILL.md)          ← 対話フロー定義（オープン標準 Agent Skills 仕様）
  skills/reading-*/SKILL.md ← OCR 画像読取スキル（旧 agents/ の後継）
src/shinkoku/cli/           ← CLI エントリーポイント（shinkoku コマンド）
  ↓
src/shinkoku/tools/         ← ビジネスロジック（純粋関数）
  ↓
src/shinkoku/               ← コア（models, db, master_accounts）
```

- ツール呼び出し: `shinkoku <command> <subcommand>` で実行（argparse サブコマンド + JSON 入出力）
- ビジネスロジック: `src/shinkoku/tools/*.py` に純粋関数として定義（CLI から呼び出し）

## コマンド

```bash
make dev          # Claude Code をプラグインモードで起動
make test         # 全テスト実行
make lint         # Ruff lint チェック

uv run pytest tests/unit/ -v      # ユニットテストのみ
uv run pytest tests/scripts/ -v   # CLI スクリプトテスト
uv run pytest tests/integration/ -v  # 統合テスト

uv run mypy src/shinkoku/ --ignore-missing-imports  # 型チェック
uv run ruff format --check src/ tests/              # フォーマットチェック
```

### CLI 呼び出し例

```bash
# 帳簿 CRUD
uv run shinkoku ledger init --db-path shinkoku.db --fiscal-year 2025
uv run shinkoku ledger journal-add --db-path shinkoku.db --input journal.json
uv run shinkoku ledger trial-balance --db-path shinkoku.db --fiscal-year 2025

# 税額計算
uv run shinkoku tax calc-income --input income_params.json

# データ取込
uv run shinkoku import csv --file-path transactions.csv

# ふるさと納税
uv run shinkoku furusato summary --db-path shinkoku.db --fiscal-year 2025

# PDF ユーティリティ
uv run shinkoku pdf extract-text --file-path document.pdf
uv run shinkoku pdf to-image --file-path document.pdf --output-dir output/images

# プロファイル
uv run shinkoku profile --config shinkoku.config.yaml
```

## コーディング規約

### 金額は必ず int（円）

- **float 禁止** — 金額を扱う変数・フィールドは全て `int`（円単位の整数）
- 消費税の按分計算も整数演算（`//` 演算子）で行う
- `amount: int = Field(gt=0, description="円単位の整数")`

### 端数処理

#### 所得税

| 対象 | ルール | 法的根拠 |
|------|--------|---------|
| 課税所得 | 1,000円未満切捨て `(amount // 1_000) * 1_000` | 国税通則法118条 |
| 復興特別所得税 | 1円未満切捨て `tax * 21 // 1000` | 復興財源確保法13条 |
| 所得税及び復興特別所得税の額（㊺） | 端数処理なし | — |
| 申告納税額（納付の場合のみ） | 100円未満切捨て `(amount // 100) * 100` | 国税通則法119条 |
| 還付金 | 1円単位（切捨てなし） | 国税通則法120条 |

#### 消費税

| 対象 | ルール | 法的根拠 |
|------|--------|---------|
| 課税標準額 | 1,000円未満切捨て `(amount // 1_000) * 1_000` | 国税通則法118条 |
| 消費税額（国税） | 課税標準額 × 78/1000（標準）or 624/10000（軽減） | 消費税法29条 |
| 差引税額 | 100円未満切捨て `(amount // 100) * 100` | 国税通則法119条 |
| 地方消費税 | 差引税額 × 22/78、100円未満切捨て | 地方税法72条の89 |

#### 各種控除

| 対象 | ルール | 法的根拠 |
|------|--------|---------|
| 生命保険料控除 | 1円未満切り上げ `-(-amount // divisor)` | 所得税法76条 |
| 地震保険料控除 | 1円未満切り上げ `-(-amount // divisor)` | 所得税法77条 |
| 住宅ローン控除 | 100円未満切捨て | 租税特別措置法41条2項 |
| 減価償却費 | 1円未満切捨て | 所得税法49条 |

### 型ヒント

- 全関数に型ヒントを付与する
- ファイル先頭に `from __future__ import annotations` を記述
- `X | None` 記法を使う（`Optional[X]` は使わない）

### Pydantic モデル命名

- `*Input` — ツールへの入力（例: `IncomeTaxInput`）
- `*Result` — ツールからの出力（例: `IncomeTaxResult`）
- `*Params` — 検索条件（例: `JournalSearchParams`）
- `*Record` — DBレコード（例: `JournalRecord`）
- 定義は `src/shinkoku/models.py` に集約する

### CLI モジュール規約

- エントリーポイント: `src/shinkoku/cli/__init__.py` の `main()` で全サブコマンドを登録
- 各モジュール（`src/shinkoku/cli/*.py`）は `register(subparsers)` 関数を公開し、サブコマンドを登録する
- 入力: 複雑なパラメータは `--input <json_file>` で JSON ファイル受け取り。単純パラメータは CLI 引数
- 出力: JSON を stdout に出力
- エラー: `{"status": "error", "message": "..."}` を stdout + exit code 1
- DB 系: `--db-path` 引数で SQLite パスを受け取り
- ビジネスロジックは `src/shinkoku/tools/` の純粋関数として分離する

### Ruff

- `line-length`: 100
- `target-version`: py311

### コメント

- ドメイン固有ロジック（税法の計算根拠、勘定科目の説明等）には日本語コメントを付ける
- 自明なコードにはコメントを付けない

### コミットメッセージ

- 形式: `[type]: [description]`（英語）
- type: `feat` / `fix` / `ci` / `refactor` / `test` / `docs`

### バージョン管理

セマンティックバージョニング（`MAJOR.MINOR.PATCH`）に従う。

| 変更の種類 | バージョン | 例 |
|-----------|-----------|-----|
| 後方互換性のない変更（CLI 引数削除・出力形式変更等） | MAJOR | 0.x → 1.0.0 |
| 機能追加（新コマンド・新スキル等） | MINOR | 0.1.0 → 0.2.0 |
| バグ修正・ドキュメント修正 | PATCH | 0.2.0 → 0.2.1 |

**更新が必要なファイル（2箇所を同期）:**

- `pyproject.toml` — `version` フィールド
- `.claude-plugin/plugin.json` — `version` フィールド

**更新不要なファイル:**

- `.claude-plugin/marketplace.json` — version フィールドなし（plugin.json に一元化）

**PR 作成前の必須手順:**

- `src/shinkoku/` または `skills/` に変更がある PR では、**コミット前に必ず** `pyproject.toml` と `.claude-plugin/plugin.json` のバージョンを同時にバンプすること
- バンプ忘れは CI (Version Check) で即 fail する

**CI による検証:**

- PR で `src/shinkoku/` または `skills/` に変更がある場合、`plugin.json` のバージョンがベースブランチから更新されていること、`pyproject.toml` と一致することを自動チェックする
- `tests/`・`.github/`・`*.md`・`Makefile` のみの変更ではバージョン更新不要

## DB 規約

- SQLite WAL モード + `foreign_keys=ON`
- 接続は `db.get_connection()` / 初期化は `db.init_db()` を使う
- 勘定科目コード体系:
  - `1xxx`: 資産（asset）
  - `2xxx`: 負債（liability）
  - `3xxx`: 純資産（equity）
  - `4xxx`: 収益（revenue）
  - `5xxx`: 費用（expense）

## テスト規約

- 構成: `tests/unit/` / `tests/scripts/` / `tests/integration/`
- `tests/scripts/`: CLI の統合テスト（subprocess で `shinkoku` コマンドを呼び出し、JSON 出力を検証）
- `tests/unit/`: DB・config 等のコアモジュールのユニットテスト
- `tests/integration/`: 複数モジュールの結合テスト
- 共有フィクスチャ: `in_memory_db`, `in_memory_db_with_accounts`, `sample_journals`
- マーカー: `@pytest.mark.slow`

## 主要ファイル

### コアモジュール

| ファイルパス | 役割 |
|------------|------|
| `src/shinkoku/models.py` | Pydantic モデル定義（全ツールの入出力型） |
| `src/shinkoku/db.py` | SQLite 接続管理・マイグレーション |
| `src/shinkoku/master_accounts.py` | 勘定科目マスタ（1xxx〜5xxx） |
| `src/shinkoku/tax_constants.py` | 税制定数の一元管理（税率・控除額・速算表等） |
| `src/shinkoku/config.py` | 設定ファイル（YAML）読み込み |
| `src/shinkoku/hashing.py` | ハッシュユーティリティ |
| `src/shinkoku/duplicate_detection.py` | 重複検出ロジック |

### ビジネスロジック（純粋関数）

| ファイルパス | 役割 |
|------------|------|
| `src/shinkoku/tools/ledger.py` | 帳簿管理（仕訳CRUD・財務諸表） |
| `src/shinkoku/tools/tax_calc.py` | 税額計算（所得税・消費税・控除・減価償却） |
| `src/shinkoku/tools/import_data.py` | データ取り込み（CSV・レシート・請求書） |
| `src/shinkoku/tools/pdf.py` | PDF ユーティリティ（テキスト抽出・画像変換） |
| `src/shinkoku/tools/furusato.py` | ふるさと納税 CRUD・集計 |
| `src/shinkoku/tools/profile.py` | 納税者プロファイル取得 |

### CLI モジュール（src/shinkoku/cli/）

| ファイルパス | サブコマンド数 | 役割 |
|------------|-------------|------|
| `src/shinkoku/cli/__init__.py` | — | CLI エントリーポイント（`main()` + サブコマンド登録） |
| `src/shinkoku/cli/__main__.py` | — | `python -m shinkoku.cli` 実行用 |
| `src/shinkoku/cli/ledger.py` | 71 | 帳簿管理 CLI（init, journal-add, search, trial-balance 等） |
| `src/shinkoku/cli/tax_calc.py` | 8 | 税額計算 CLI（calc-income, calc-deductions 等） |
| `src/shinkoku/cli/import_data.py` | 9 | データ取込 CLI（csv, receipt, invoice 等） |
| `src/shinkoku/cli/pdf.py` | 2 | PDF ユーティリティ CLI（extract-text, to-image） |
| `src/shinkoku/cli/furusato.py` | 4 | ふるさと納税 CLI（add, list, delete, summary） |
| `src/shinkoku/cli/profile.py` | — | プロファイル取得 CLI（直接コマンド） |

### スキル（skills/）

| ファイルパス | 役割 |
|------------|------|
| `skills/e-tax/SKILL.md` | e-Tax 電子申告スキル（Claude in Chrome で確定申告書等作成コーナーに入力） |
| `skills/setup/SKILL.md` | セットアップウィザード（設定ファイル生成・DB初期化） |
| `skills/reading-receipt/SKILL.md` | レシート画像 OCR スキル |
| `skills/reading-withholding/SKILL.md` | 源泉徴収票 OCR スキル |
| `skills/reading-invoice/SKILL.md` | 請求書 OCR スキル |
| `skills/reading-deduction-cert/SKILL.md` | 控除証明書 OCR スキル |
| `skills/reading-payment-statement/SKILL.md` | 支払調書 OCR スキル |

## 注意事項

- `output/` は `.gitignore` 対象 — 実行時に自動生成される
- `shinkoku.config.yaml` はコミットしない（テンプレートは `shinkoku.config.example.yaml`、`/setup` スキルで対話生成可能）
- 税法計算は令和7年分（2025年）および令和8年分（2026年、令和8年度税制改正）を反映済み。`fiscal_year` で年分を切り替える