## 11_receipt_ocr.md
# レシートOCR・電子帳簿保存 設計書

## 1. 概要

### 1.1 目的
- レシート・領収書をスマホで撮影し、仕訳データに自動入力する
- 撮影画像を仕訳データと紐付けて保存し、電子帳簿保存法に対応する
- 税務調査時に領収書原本の代わりとして電子データを提示できるようにする

### 1.2 対応法令
- **電子帳簿保存法**（令和6年1月1日以降義務化）
  - スキャナ保存要件：解像度200dpi以上、カラー保存
  - 検索要件：日付・金額・取引先で検索可能
- **インボイス制度**（令和5年10月1日以降）
  - 適格請求書の登録番号確認・保存

### 1.3 基本方針
- OCRエンジン：**Google Cloud Vision API**（月1000件まで無料）
- 画像保存先：サーバー `/data/receipts/[会社]/[年]/[月]/`
- 仕訳データと1対1で紐付け（`receipt_path` フィールド）
- スマホ・PCどちらからでも使用可能
- 入力対応範囲：カメラ撮影・画像ファイル選択・PDFファイル選択

---

## 2. 機能一覧

### 2.1 レシートOCR入力フロー
```
スマホで journal.html を開く
  ↓
「レシート読取」ボタンをタップ
  ↓
カメラ起動 → レシートを撮影（またはギャラリーから選択）
  ↓
Google Cloud Vision API で解析
  ↓
日付・金額・店名・税区分を自動抽出
  ↓
勘定科目を自動推測（店名・金額から判定）
  ↓
入力フォームに自動セット
  ↓
内容確認・修正 → 登録
  ↓
画像をサーバーに保存 + 仕訳データに紐付け
```

### 2.2 電子帳簿保存ビューア
- 仕訳一覧から「領収書」アイコンをタップ → 保存画像を表示
- 日付・金額・取引先で画像検索
- 税務署モードでも閲覧可能（編集不可）

---

## 3. OCR仕様

### 3.1 使用API
- **Google Cloud Vision API** - Document Text Detection
- エンドポイント：`https://vision.googleapis.com/v1/images:annotate`
- 認証：APIキー方式（サーバー側PHPで呼び出し、フロントにキーを露出しない）

### 3.2 OCR読取後の年切替ルール

レシートから読み取った日付の「年」が、現在選択中の年と異なる場合：

1. 年プルダウンを自動で読取年に切り替える
2. 該当年のlocalStorageキー（`journals_v2_[会社]_[年]`）のデータを再読み込みする
3. 入力フォームに読取結果をセット

これにより、過去年・翌年のレシートを入力する際も正しいキーにデータが保存される。

### 3.3 抽出項目と解析ロジック

| 項目 | 抽出方法 | 備考 |
|------|---------|------|
| 日付 | 正規表現（YYYY/MM/DD・令和○年等） | 複数候補がある場合は下記ルールで採用日を決定 |

**日付複数時の採用ルール：**

| パターン | 採用日付 | 理由 |
|---------|---------|------|
| 一般レシート・駐車場 | 後の日付（精算日・支払完了日） | 駐車場は出庫日、一般は支払日が取引完了日 |
| ETC・高速道路 | 前の日付（利用日・通過日） | 利用日が経費発生日。案件管理の経費と紐付けるため利用日が正確でないとズレる |

判定方法：OCR結果の店名・キーワードが「ETC・高速・有料道路」に該当する場合のみ前の日付を採用。それ以外はすべて後の日付。
| 金額 | 「合計」「¥」に続く数字 | 税込金額を採用 |
| 店名 | テキスト先頭付近の固有名詞 | |
| 税区分 | 「10%」「8%」「軽減」の記載 | デフォルト10% |
| インボイス番号 | 「T」+13桁数字 | あれば自動セット |

### 3.4 勘定科目自動推測ルール

仕訳仕様書（`02_journal_spec.md` 8節）の自動振り分けルールに準拠。

| 店名・キーワード | 推測科目 |
|----------------|---------|
| ETC・高速・有料道路 | 旅費交通費 |
| 駐車場・パーキング | 旅費交通費 |
| コンビニ・スーパー | 消耗品費 |
| ガソリン・燃料・SS | 車両費 |
| 飲食店（面談時） | 会議費 |
| 文具・事務用品 | 消耗品費 |
| 通信・携帯・ドコモ等 | 通信費 |
| 電車・バス・地下鉄・新幹線・ICOCA・Suica | 旅費交通費（領収書不要） |
| 該当なし | 旅費交通費（デフォルト） |

---

## 4. 画像保存仕様

### 4.1 保存先
```
/backoffice/data/receipts/
├── private/            # 個人事業（SPS）
│   └── [年]/
│       └── [月]/
│           └── [仕訳ID].jpg
└── corporate/          # 法人（SCSPS）
    └── [年]/
        └── [月]/
            └── [仕訳ID].jpg
```

### 4.2 ファイル名規則
- `[仕訳ID].jpg`
- 例：`1773360600232.405.jpg`

### 4.3 画像要件（電子帳簿保存法準拠）
- 解像度：200dpi以上（スマホカメラで通常クリア）
- カラー保存（グレースケール不可）
- フォーマット：JPEG（容量削減のため最大1MB以下にリサイズ）

### 4.4 保存API
```
POST /backoffice/master/api/save_receipt.php
```

```json
リクエスト:
{
  "journal_id": "1773360600232.405",
  "company": "SPS",
  "date": "2025-01-15",
  "image": "[base64エンコード画像]"
}

レスポンス:
{
  "success": true,
  "path": "/data/receipts/private/2025/01/1773360600232.405.jpg"
}
```

---

## 5. 仕訳データの変更点

### 5.1 receipt_path フィールドを追加
```json
{
  "id": "1773360600232.405",
  "date": "2025-01-15",
  "company": "SPS",
  "entries": [...],
  "description": "ガソリン補給",
  "case_id": "",
  "locked": false,
  "receipt_path": "/data/receipts/private/2025/01/1773360600232.405.jpg"
}
```

### 5.2 後から画像を紐付ける機能
- 既存仕訳に対して後から領収書画像を追加可能
- 仕訳一覧の各行に「領収書追加」ボタンを表示

---

## 6. UI仕様

### 6.1 journal.html への追加
- 入力フォームに「レシート読取」ボタンを追加（ネイビー・38px）
- 仕訳一覧の各行に領収書列を追加
  - 画像あり → 「領収書」ボタン（タップで表示）
  - 画像なし → 「追加」ボタン

### 6.2 入力方法

以下の3つの入力方法に対応する。

| 入力方法 | 対応 | 備考 |
|---------|------|------|
| カメラ撮影 | ✅ | スマホ・タブレットのカメラを起動 |
| 画像ファイル選択 | ✅ | JPG・PNG等をファイルから選択 |
| PDFファイル選択 | ✅ | Google Vision APIのPDFモードで処理 |

**実装方法**
```html
<!-- カメラ撮影・画像ファイル選択 -->
<input type="file" accept="image/*" capture="environment" id="input-camera">

<!-- 画像ファイル・PDFファイル選択（カメラなし） -->
<input type="file" accept="image/*,application/pdf" id="input-file">
```

- ボタンテキスト：「レシート読取」（アイコン不使用）
- 撮影・選択後プレビュー表示（確認してから送信）
- PDFの場合はサーバー側（`ocr_receipt.php`）でVision APIのPDFモードを使用

### 6.3 読取結果の表示
```
┌─────────────────────────────────────┐
│ 【読取結果】                          │
│ 日付:   2025-01-15  ← 修正可         │
│ 金額:   ¥5,500      ← 修正可         │
│ 店名:   ENEOSxx店   ← 修正可         │
│ 科目:   車両費      ← 修正可         │
│ 税区分: 10%         ← 修正可         │
│                                      │
│ [この内容で登録] [やり直す]           │
└─────────────────────────────────────┘
```

---

## 7. サーバー側API

### 7.1 save_receipt.php
- 画像をbase64デコードしてサーバーに保存
- 1MB超の場合は自動リサイズ
- 保存パスをレスポンスで返す

### 7.2 ocr_receipt.php
- フロントから画像を受け取る
- Google Cloud Vision APIを呼び出し（**APIキーはサーバー側で管理・フロントに露出しない**）
- OCR結果をJSONで返す

```php
// /backoffice/master/api/ocr_receipt.php
// Google Cloud Vision APIキーはサーバーの設定ファイルに保存
// define('GOOGLE_VISION_API_KEY', 'xxxxxx'); // config.php
```

---

## 8. 電子帳簿保存法 対応チェックリスト

| 要件 | 対応方法 | 状態 |
|------|---------|------|
| 真実性の確保 | 仕訳登録と同時に画像保存・変更不可 | 設計済 |
| 可視性の確保 | ブラウザで即時閲覧可能 | 設計済 |
| 検索要件（日付） | 仕訳データの日付と紐付け | 設計済 |
| 検索要件（金額） | 仕訳データの金額と紐付け | 設計済 |
| 検索要件（取引先） | 摘要・店名で検索可能 | 設計済 |
| 解像度200dpi以上 | スマホカメラで通常クリア | 設計済 |
| カラー保存 | JPEG保存 | 設計済 |
| 保存期間7年 | サーバー保存（バックアップ対象） | 設計済 |

---

## 9. 実装手順

```
① Google Cloud Console でVision APIキーを発行
       ↓
② save_receipt.php を作成（画像保存）
       ↓
③ ocr_receipt.php を作成（Vision API呼び出し）
       ↓
④ journal.html に「レシート読取」ボタンを追加
       ↓
⑤ 読取結果の確認・修正UIを実装
       ↓
⑥ 仕訳登録時に画像を同時保存
       ↓
⑦ 仕訳一覧に領収書表示・追加機能を追加
       ↓
⑧ 電子帳簿保存ビューア（検索機能）を実装
```

---

## 10. 案件経費の領収書紐付けについて

### 10.1 基本方針
案件管理は別担当が実装するため、経過書へのOCR機能は案件管理側のスコープとする。

仕訳帳側での対応は以下のみ：
- 案件経費は経過書への手入力 → 仕訳帳へ自動転記（`02_journal_spec.md` 8節）
- 転記された仕訳に対して**仕訳帳から後から領収書画像を追加**できる機能を実装する

### 10.2 案件管理担当との共用方針
案件経費の領収書保存は仕訳帳の仕組みをそのまま流用する：

1. 案件の経過書に手入力 → 仕訳帳に自動転記
2. 仕訳帳の「領収書追加」ボタンで画像を撮影・保存
3. `save_receipt.php` と画像表示の仕組みは共用

案件管理担当はOCRやUI部分を一から作る必要はない。
経過書へのカメラ起動・OCR追加が必要になった場合も `ocr_receipt.php` を共用できる。

## 11. 案件経費の確定・案件終了ルール

### 11.1 経費確定の必須条件
案件管理アプリから転記された経費（`status: "pending"`）を確定するには以下が**両方必須**：

1. 内容確認・修正済み
2. 領収書画像の撮影・紐付け済み（`receipt_path` あり）

**領収書の要否：**

| 種別 | 領収書 | 例 |
|------|-------|-----|
| 原則 | **必須** | ETC・駐車場・ガソリン・飲食・消耗品等 |
| 例外：公共交通機関 | **不要** | 電車・バス・地下鉄・新幹線等 |

公共交通機関は領収書が発行されない性質のため例外とする。ICカード（ICOCA・Suica等）利用も同様。取り忘れ・紛失は自己責任・自己負担とする。

### 11.2 案件終了条件
案件に紐付く全仕訳が以下を満たさない限り案件終了ボタンを押せない：

- 全仕訳が `status: "confirmed"`（確定済み）
- 全仕訳に `receipt_path` あり（領収書画像が存在する）

どちらか一つでも欠けている場合：
```
「未確認の経費が2件あります。領収書の撮影・確定後に案件を終了してください。」
```

### 11.3 申告時の未確認チェック
確定申告・法人税申告の「申告済みにする」実行前に `pending` データが残っていないかチェックする：

```
「未確認の仕訳が3件あります。全て確定してから申告してください。」
```

全て `confirmed` になって初めて申告ロック（`locked: true`）が可能。

### 11.4 status フィールドの定義

| status | 意味 | 集計対象 | 編集 |
|--------|------|---------|------|
| `pending` | 未確認（案件管理から転記） | ❌ 対象外 | ✅ 可能 |
| `confirmed` | 確定済み | ✅ 対象 | ✅ 可能 |
| `locked` | 申告済みロック | ✅ 対象 | ❌ 不可 |

※ 手入力の仕訳は登録時点で自動的に `confirmed` になる。`pending` になるのは案件管理アプリからの自動転記分のみ。

## 12. 今後の拡張

- **複数枚まとめて取込**（月末にまとめて撮影）
- **重複チェック**（同じレシートの二重登録を防止）
- **インボイス番号の自動検証**（国税庁APIで適格事業者確認）
- **クラウドバックアップ**（Google Drive等に自動保存）

---

## 11. 改訂履歴
| 日付 | 版 | 担当 | 内容 | 理由・影響範囲 |
|------|----|------|------|--------------|
| 2026-03-18 | 1.0 | 会計担当 | 初版作成 | |
| 2026-03-20 | 1.1 | 全体管理者 | 1.3節にPDF対応を追記・6.2節を入力方法3種に拡張 | カメラ撮影のみでは不便との要望。案件管理側OCRも同じ共用APIで対応するため共通仕様として明記 |