# 予約番号統一化 実装手順（現行DB向け）

このドキュメントは、現行構成（`reservations` と `group_bookings` が併存）で、
予約番号統一を段階導入するための実装手順です。

## 1. 追加ファイル

- SQL: `admins/sql/add_unified_booking_code.sql`
- SQL: `admins/sql/add_invoice_tables.sql`
- SQL: `admins/sql/alter_invoice_items_for_group.sql`
- API: `admins/api/update_booking_code.php`
- Helper: `lib/booking_code_helper.php`

## 2. 方針

- 個人予約: `reservations.booking_code` を正本にする
- 当日予約: `reservations.booking_code` を正本にする
- 団体予約: `group_bookings.booking_code` を正本にする
- 旧番号（`reservation_seq`, `reservation_number`, `gb_number`）は互換用で残す
- 管理者の手修正は履歴テーブル `booking_code_change_history` に保存する

## 3. 予約番号フォーマット

- 個人: `P` + `YYMMDD` + `NNNN`（例: `P2602130123`）
- 当日: `T` + `YYMMDD` + `NNNN`（例: `T2602130456`）
- 団体: `GRP` + `YYMMDD` + `NNNN`（例: `GRP2602130001`）
- `YYMMDD` は発番日（created_at）固定、手修正は `NNNN`（下4桁）のみ
- 出航日変更時も新予約番号は変更しない（`-xxx` などの枝番は付与しない）
- 新規発番時の `NNNN` は、同日同スコープ内で **最小の空き番号** を採用（例: `0001` が空いていれば `0001`）

## 4. 適用手順

### 4-1. SQL適用

```bash
mysql -u doto_yoyaku -p -D doto_yoyaku < admins/sql/add_unified_booking_code.sql
mysql -u doto_yoyaku -p -D doto_yoyaku < admins/sql/add_invoice_tables.sql
mysql -u doto_yoyaku -p -D doto_yoyaku < admins/sql/alter_invoice_items_for_group.sql
```

### 4-2. API利用（手修正）

- エンドポイント: `POST /admins/api/update_booking_code.php`

#### 個人予約

```bash
curl -X POST "https://<host>/admins/api/update_booking_code.php" \
  -d "scope=individual" \
  -d "reservation_id=733" \
  -d "new_suffix=0999"
```

#### 当日予約

```bash
curl -X POST "https://<host>/admins/api/update_booking_code.php" \
  -d "scope=walk_in" \
  -d "reservation_id=734" \
  -d "new_suffix=1001"
```

#### 団体予約

```bash
curl -X POST "https://<host>/admins/api/update_booking_code.php" \
  -d "scope=group" \
  -d "group_booking_id=122" \
  -d "new_suffix=0123"
```

## 5. 重複チェック仕様

APIは更新前に以下を確認します。

- 同じテーブル内の重複
- 他テーブル（個人/当日 ↔ 団体）との重複

重複があれば更新を拒否します。

## 6. 監査/履歴

更新時に以下が記録されます。

- `booking_code_change_history`: 旧番号、新番号、理由、更新者、IP、UA、日時
- `audit_logs`: `update_booking_code` イベント

## 7. 画面/API連携の実装済み箇所

- 個人予約詳細画面: `admins/reservation_detail.php`
- 団体予約詳細画面: `admins/group_booking_detail.php`
- 個人・当日予約一覧: `admins/reservations.php`（新予約番号表示・検索）
- 団体予約一覧: `admins/group_bookings.php`（新予約番号表示）

## 8. 新規作成時の自動採番（実装済み）

- 管理画面 個人予約作成: `admins/api/create_reservation.php`
- POS 当日予約作成: `posrg/api/create_reservation.php`
- Web予約作成: `web_yoyaku/process_booking.php`
- Web決済予約作成: `web_yoyaku/payment.php`
- 団体確定作成: `admins/api/confirm_booking.php`

いずれも作成直後に `booking_code` が空なら自動採番します。
採番は `lib/booking_code_helper.php` の最小空き下4桁方式（`接頭辞 + yymmdd + NNNN`）を使用します。

## 9. チケット/領収書番号の枝番統一（実装済み）

- チケット番号: `新予約番号-TKNNN`
  - 例: `P2602130001-TK001`
- 正規領収書: `新予約番号-RCNNN`
  - 例: `GRP2602130001-RC001`
- 逆領収書: `新予約番号-RVNNN`
  - 例: `GRP2602130001-RV001`
- 返金番号: `新予約番号-RFNNN`
  - 例: `T2602130002-RF001`, `GRP2602130001-RF001`
- 請求書番号: `INV-YYMMDD-NNNN`
  - 例: `INV-260213-0001`

### 適用済み箇所

- 個人予約作成: `admins/api/create_reservation.php`
- Web予約作成: `web_yoyaku/payment.php`, `web_yoyaku/process_booking.php`
- 当日予約作成: `posrg/api/create_reservation.php`
- 団体確定/追加発券: `admins/api/confirm_booking.php`, `admins/api/add_group_booking_tickets.php`
- 団体領収書発行: `admins/print_receipt.php`
- 返金処理（POS/欠航全額返金）: `posrg/api/process_refund.php`, `admins/api/process_full_refund.php`
- 請求書採番: `admins/api/generate_invoice.php`, `admins/print_invoice.php`
- POS検索互換（新予約番号検索）: `posrg/api/search_reservation_for_payment.php`, `posrg/api/search_for_print.php`

## 10. 返金履歴テーブルの番号保存統一（実装済み）

- `refund_history.refund_code` を追加し、返金時に `新予約番号-RFNNN` を保存
- 新規保存対応:
  - `admins/api/process_single_refund.php`
  - `admins/api/process_refunds.php`
  - `admins/api/refund_payment.php`
  - `admins/api/process_full_refund.php`
  - `posrg/api/process_refund.php`
- 既存データバックフィルSQL:
  - `admins/sql/add_refund_code_to_refund_history.sql`

## 11. ステージング検証メモ

- `update_booking_code.php` を実行し、以下を確認済み
  - 個人: 更新成功
  - 団体: 更新成功
  - 重複番号: エラーで更新拒否
  - 履歴: `booking_code_change_history` に記録
  - 監査: `audit_logs.action_type = update_booking_code` で記録
- テストで変更した番号は元の値へ戻し済み