diff --git a/doc/自動承認仕様.md b/doc/自動承認仕様.md new file mode 100644 index 0000000..789f00f --- /dev/null +++ b/doc/自動承認仕様.md @@ -0,0 +1,199 @@ +# 自動承認仕様書 + +本ドキュメントは、`定期申込予約` アプリにおける「自動承認ボタン」およびそれに伴う「自動承認処理」の仕様（ボタン表示条件、チェック仕様、入出力仕様、選定・データ更新ロジック）を定義したものです。 + +--- + +## 1. 概要 + +「自動承認」機能は、`定期申込予約` レコードに対して管理者が受付・承認を行うための機能です。 +申込内容（通常申込 / IC定期申込）に応じて、空き車室の自動選定、顧客マスタの取得または新規作成、契約情報（車室情報管理）の新規作成、定期申込予約レコードの状態更新および外部システム（IC定期サービス）への連携を一括で自動実行します。 + +--- + +## 2. ボタン表示条件・実行前チェック仕様 + +### 2.1. ボタン表示条件 +`定期申込予約` レコードの詳細画面において、以下の条件を満たす場合に画面ヘッダーに **「受付」** ボタンが表示されます。 + +- レコードの **状態** (`status`) が以下のいずれかであること： + - `新規` + - `選考当選` + - `予約` + - `空き待ち` + +上記以外の状態（例: 既に承認済み、キャンセル等）の場合はボタンは非表示となります。 + +### 2.2. 実行前・入力チェック仕様 +「受付」ボタン押下時、以下の順序でチェックおよびユーザー確認が行われます。 + +1. **台数チェック** + - レコードの `台数` フィールドの値が `"1"` であることを確認します。 + - `"1"` 以外の場合はエラーメッセージ「`台数を１にしてください`」を表示し、処理を中断します。 +2. **承認確認ダイアログ** + - 「承認しますか」の確認ダイアログを表示します。ユーザーが「キャンセル」を選択した場合は処理を終了します。 +3. **IC定期利用時の定期券番号入力** + - 申込プランが IC 定期申込（プランの `IC定期駐車場` が「該当」）かつ `IC定期駐車場利用方法` が `"貸与ICカード"` の場合： + - 定期券番号の入力フォームダイアログ（数値入力）を表示します。 + - 入力されなかった（キャンセル等）場合は処理を終了します。 + +--- + +## 3. 入出力仕様 + +### 3.1. 入力データ + +#### (1) 定期申込予約レコード +- `駐車場`: 駐車場名（必須） +- `定期駐車場プラン`: プラン名（必須） +- `利用開始希望日`: 契約開始日基準（必須） +- `氏名`, `フリガナ`, `電話番号`, `メールアドレス`, `住所`: 顧客マスタ登録/照合用 +- `車両番号`: 契約情報登録用 +- `IC定期駐車場利用方法`: IC定期時の利用方法（例: `"貸与ICカード"`, `"交通系ICカード"` 等） +- `台数`: `"1"` であること + +#### (2) 関連マスタ・管理テーブル +- **車室情報 (`車室情報２`)**: 対象駐車場の車室一覧および自動承認対象フラグ +- **車室情報管理 (`契約`)**: 対象駐車場の現在の契約中レコード一覧 +- **定期駐車場プランマスタ**: 契約金額、保証金合計額、IC定期属性情報 +- **自動承認グループ**: プランごとに設定された自動承認対象の車室番号リストおよび割当順 +- **顧客マスタ**: メールアドレスをキーとした既存親顧客の存在チェック + +#### (3) ユーザーからの動的入力 +- 定期券番号（IC定期・貸与ICカード選択時のみ） +- 既存顧客一致時の確認ダイアログ応答（既存顧客への追加 / 子アカウント新規作成 / キャンセル） + +--- + +### 3.2. 出力データ・Side Effects (データ作成・更新) + +| 対象アプリ/サービス | 操作タイプ | 主な設定内容 / 副作用 | +| :--- | :--- | :--- | +| **顧客マスタ** | 作成 / 取得 | 既存顧客への追加、または新規顧客マスタ（親/子アカウント）を作成。
・`顧客コード`: 自動発番
・`SMBC契約番号`: 自動発番
・`支払方法`: IC定期なら「その他」、それ以外は「口座振替」
・`振替開始日`: 利用開始希望日が1日なら「当月27日」、それ以外は「翌月27日」
・`IC定期関連情報_ユーザーID`: IC定期API連携によるユーザーID | +| **車室情報管理** | 作成 | 新規契約レコードの作成。
・`顧客コード`
・`契約日`: 利用開始希望日
・`車両番号`
・`車室番号`: 自動選定された車室番号（IC定期の場合は `"IC定期"`）
・`プラン名`
・`定額_1月〜12月`: プランの契約金額
・`IC定期関連情報_*`: IC契約ID、定期券番号、車種、契約者種類等（IC定期の場合） | +| **定期申込予約** | 更新 | 対象申込レコードの完了更新。
・`状態`: `承認_自動承認`
・`自動承認ステータス`: `承認済`
・`定期駐車料金`: プランの契約金額
・`初回入金予定_必要分`: 必要項目をセット（`初月分`, `日割り分`, `保証金`）※IC定期除く
・`自動承認契約情報`: 作成された車室情報管理のレコードID | +| **IC定期API連携** | 外部API呼び出し | IC定期申込の場合に実行。
・`利用者情報新規作成` API呼び出し
・`定期契約新規作成` API呼び出し | + +--- + +## 4. 詳細処理フロー + +```mermaid +sequenceDiagram + autonumber + actor User as ユーザー + participant Button as 自動承認ボタン + participant Logic as 自動承認ロジック (申込クラス) + participant Kintone as kintone API (bulkRequest) + participant ICApi as IC定期 API + + User->>Button: 「受付」ボタン押下 + Button->>Button: 台数 === "1" チェック + Button->>User: 承認確認ダイアログ + User-->>Button: 承認 OK + + Button->>Logic: 初期化() + Logic->>Kintone: 車室一覧・契約中一覧・プラン・自動承認グループ取得 + Logic-->>Button: 初期化完了 + + Button->>Button: IC定期かつ貸与ICカードの場合、定期券番号ダイアログ表示 + User-->>Button: 定期券番号入力 + + Button->>Logic: 選定() + + rect rgb(240, 240, 240) + note over Logic: 1. 空き車室選定 + Logic->>Logic: 対象車室取得 (割当順最小の空き車室) + end + + rect rgb(240, 240, 240) + note over Logic: 2. 顧客マスタ処理 + Logic->>Kintone: メールアドレスで既存親顧客検索 + alt 既存顧客が存在する場合 + Logic-->>User: 既存顧客追加 / 子アカウント作成 ダイアログ + User-->>Logic: 選択 (既存追加 or 子アカウント作成) + end + opt 新規作成 or 子アカウント作成の場合 + opt IC定期申込の場合 + Logic->>ICApi: 利用者情報新規作成 API + ICApi-->>Logic: 利用者ID返却 + end + Logic->>Kintone: 顧客マスタ作成予約 (顧客コード・振替開始日等) + end + end + + rect rgb(240, 240, 240) + note over Logic: 3. 契約情報作成 + opt IC定期申込の場合 + Logic->>ICApi: 定期契約新規作成 API + ICApi-->>Logic: 契約ID・定期券番号等返却 + end + Logic->>Kintone: 車室情報管理 (契約) レコード作成予約 + end + + rect rgb(240, 240, 240) + note over Logic: 4. 申込情報完了更新 & 一括保存 + Logic->>Kintone: 定期申込予約 更新予約 (状態=承認_自動承認, 初回入金予定等) + Logic->>Kintone: 一括保存実行 (save / bulkRequest) + Logic->>Kintone: 定期申込予約に作成後契約IDを紐付け更新 + end + + Logic-->>Button: 選定完了 + Button->>User: SuccessDialog 表示 + opt IC定期以外の場合 + Button->>User: WarningDialog ("各初回請求データを作成してください") + end + Button->>User: 契約情報更新イベント発火 & 画面リロード +``` + +--- + +## 5. 詳細ビジネスロジック仕様 + +### 5.1. 空き車室選定ロジック（通常申込） +IC定期申込（プランの `IC定期駐車場` が「該当」）でない場合、以下の手順で空き車室を1つ特定します。 + +1. プランに紐づく `自動承認グループ` の `対象車室番号` 一覧を取得。 +2. 車室ごとに以下をチェック： + - 車室が `車室情報` に存在し、`自動承認対象` であること。 + - `車室情報管理`（契約中一覧）に同一車室番号の契約中レコードが存在しないこと（空き車室であること）。 +3. 条件を満たす車室を `割当順` の数値昇順でソート。 +4. 最も割当順が小さい車室を対象として選定。 + - 対象車室が存在しない場合はエラー「`空き車室がありません`」をスローして中断。 + +### 5.2. 顧客マスタ照合・新規作成ロジック +申込者の `メールアドレス` をキーに既存親顧客を検索します。 + +- **既存顧客が存在する場合**: + - ダイアログを表示: 「`既存顧客[顧客名]様へ契約を追加しますか`」 + - **「はい」 (確定)**: 検索された既存顧客の `顧客コード` および `IC定期関連情報_ユーザーID` を引き継いで使用。 + - **「子アカウント新規作成」 (Deny)**: 既存顧客を親アカウント（`顧客コード親` / `IC定期関連情報_親ユーザーID`）として新規子顧客マスタを作成。 + - **「キャンセル」**: 処理をキャンセル (`CancelError`)。 +- **既存顧客が存在しない場合**: + - 親アカウントなしで新規顧客マスタを作成。 + +#### 顧客マスタ作成時の自動算出ルール +- **振替開始日**: + - `利用開始希望日` の「日」が **1日** の場合: 当月の27日 (`YYYY-MM-27`) + - `利用開始希望日` の「日」が **1日以外** の場合: 翌月の27日 (`YYYY-MM-27`)（日割りが発生するため） +- **郵便番号 / 住所**: + - 住所文字列の先頭8文字からハイフンを除去・整形し `XXX-XXXX` 形式の郵便番号として抽出。9文字目以降を住所本文として登録。 +- **支払方法**: + - IC定期申込の場合は `"その他"`、通常申込の場合は `"口座振替"`。 + +### 5.3. 初回入金予定_必要分 の自動設定ルール +定期申込予約レコードの更新時、`初回入金予定_必要分`（チェックボックス）に以下の条件で値を自動セットします（※IC定期申込の場合は空配列）。 + +1. `初月分`: 常にセット。 +2. `日割り分`: `利用開始希望日` の「日」が **1日以外**（日割り発生）の場合にセット。 +3. `保証金`: プランマスタの `保証金合計額` が 0 より大きい場合にセット。 + +### 5.4. IC定期連携時の動作 +プランの `IC定期駐車場` が「該当」の場合： + +- **車室番号**: 特定の物理車室番号ではなく一律 `"IC定期"` とする。 +- **利用者情報新規作成 API**: 顧客マスタ作成時に外部サービスへユーザーを作成し、レスポンスの `id` を `IC定期関連情報_ユーザーID` に保存。 +- **定期契約新規作成 API**: 契約情報作成時に外部サービスへ契約を作成。 + - 駐車場利用方法の名称変換: `"交通系ICカード"` は API送信時に `"個人所有Felica"` に変換。 + - 返却された `id`, `season_ticket_seq_no` 等を `車室情報管理` の `IC定期関連情報_*` フィールドに格納。 +- **完了後の通知**: IC定期申込でない場合のみ、事後に「`各初回請求データを作成してください`」の警告ダイアログ（2秒表示）が出力されます。