横断/運用基盤 / バッチ運用
横断/運用基盤 / バッチ運用
本ページは 2 段構成。上段が biz/CS 向け（ユーザー提示可）、下段（
## 🔧 実装詳細以降）が dev 向け。biz/CS がユーザーへ提示・転用してよいのは上段のみ。
概要
fincs サービスの定期処理（バッチ）の全体像をまとめた運用基盤ページ。サブスク自動決済・配信実行・ファイル管理・整合性チェック・統計集計など、合計 16 種の定期処理を扱う。
主な定期処理:
- 月次決済: サブスク契約の自動更新・決済
- 銀行振込期限切れキャンセル: 期限超過の振込待ち契約を失効
- 契約日数の更新: 契約残日数の集計
- 顧客情報 CSV 出力: 金商法対応の月次出力
- 一斉配信送信: 予約された一斉配信メッセージのバッチ実行
- ステップ配信送信: ステップ配信シナリオのバッチ実行
- 記事公開通知: 公開予定記事の到来検知 + プッシュ通知
- ライブ強制終了: 長時間継続している配信の自動停止
- バッジ判定・付与: バッジ獲得条件のチェックと自動付与
- 受講者数集計: 講座ごとの受講者数を集計
- コンテンツ受講数集計: コンテンツ単位の受講数集計
- 論理削除済みコンテンツファイル削除: ファイル本体の物理削除
- 助言会社向けファイルコピー: コンテンツファイルとトーク内容のエクスポート
- トークファイルコピー: ストレージ間でのファイル移送
- アーカイブ作成: ライブ配信終了後のアーカイブ動画生成
- ストレージ整合性チェック: ファイル不整合の検出 + 通知
主な利用想定は、運用担当者・SRE による定期処理の運用監視、障害対応時の手動再実行、運営アドミンによる緊急停止対応。
実行スケジュールはコードリポ外で管理: バッチ自体は Spring Boot CLI コマンドとして起動するが、実行時刻・実行頻度・引数は外部スケジューラ（k8s CronJob / Cloud Scheduler 等）側で管理されており、本コードリポからは確認できない。スケジュール変更や障害発生時の確認は、インフラ運用側のスケジューラ設定を参照する運用となる。
緊急停止スイッチは別途提供: 一斉配信・ステップ配信については、運営アドミン経路から緊急停止ロックの取得・解除が可能（
../admin/system.md参照）。配信誤爆・運用停止が必要なときに利用する。
バッチ手動実行・実行履歴閲覧は専用 UI 未提供: 運営アドミンによる「特定バッチを手動で再実行する」「実行履歴を画面で確認する」UI は現時点では提供しておらず、外部スケジューラ側のログ確認・運用担当による手動再実行が運用となる。
📝 レビュー観点:
- 目的: 定期処理の集約管理、運用障害時の手動再実行
- 誰が使うか: 運用担当・SRE
- どこで使うか: 外部スケジューラから起動、運営アドミンが緊急停止/解除（
../admin/system.md参照）- 隣接機能との関係: 配信エンジン（
./delivery-engine.md）、メディアパイプライン（./media-pipeline.md）、運営アドミンシステム運用（../admin/system.md）- CS 問い合わせで頻発する論点: 「月次決済の実行タイミング」「銀行振込が翌日キャンセルされた」「配信が時間通りに送られない」「アーカイブ生成の遅延」
- [本機能特有] 実行スケジュールはコードリポ外: 外部スケジューラ（k8s CronJob / Cloud Scheduler 等）で管理
- [本機能特有] 二重起動防止が外部依存: 素の CommandLineRunner は内部ロックなし、Redis ロックは配信系のみ
- [本機能特有] monthly-payment は 2 経路: Spring Batch Job 経路と素の Runner 経路が併存
- [本機能特有] バッチ層に Slack 通知の横断機構なし: 個別 UseCase 内で明示的に Slack 通知
利用シナリオ
シナリオ 1: 月次決済の実行
サブスク契約の自動更新タイミングに合わせて、外部スケジューラがバッチを起動。対象契約の決済を実行し、契約期間を延長または失敗時の対応（受講者本人による再決済を促す等）に進む。
シナリオ 2: 配信バッチの短サイクル実行
一斉配信・ステップ配信は短いサイクルで動作するバッチで、配信予定時刻に到達した配信を逐次送信。配信誤爆を検知した場合は運営アドミン経路の緊急停止ロックでバッチ実行を一時停止できる。
シナリオ 3: 銀行振込の期限切れキャンセル
日次バッチで銀行振込待ちの契約のうち、期限を過ぎても入金確認が取れない契約を自動的にキャンセル状態へ遷移。
シナリオ 4: ライブ強制終了
短サイクルで長時間継続している配信を検知し、自動的に配信終了状態へ遷移。配信ホストが操作を忘れた場合の補修。
シナリオ 5: アーカイブ作成
ライブ配信終了後、バッチがファイルを検出し次第アーカイブ動画として昇格。受講者が後日アーカイブ受講できるようにする。
シナリオ 6: 障害対応での手動再実行
特定バッチが失敗した場合、運用担当者が外部スケジューラから手動で再実行。実行日付を引数指定することでバックフィル対応が可能（決済・銀行振込キャンセル・契約日数更新等で利用）。
よくある失敗ケース
- 外部スケジューラ障害: スケジューラ自体が動かないと全バッチが止まる。インフラ運用側の監視が重要
- バッチ二重起動: 外部スケジューラ側で同時実行禁止が設定されていない場合のリスク。スケジューラ側で制御
- 長時間ロック残存: 配信系のロックが何らかの理由で長時間残った場合の運用対応（
../admin/system.md参照） - 実行日付の誤指定: 手動再実行時に日付を誤って指定すると、想定外の対象に処理が走る
権限別仕様
権限定義は ../user-roles.md 参照。
バッチは運用基盤のため、ユーザー権限軸での直接の操作は無い。運営アドミンによる緊急停止・ロック解除は ../admin/system.md 参照。
機能詳細（ふるまい）
バッチ起動方式
- 各バッチは Spring Boot ベースの CLI コマンドとして起動
- 起動時の引数で「どのバッチを起動するか」を指定する仕組み
- 1 回の起動で 1 つのバッチのみが有効化される
- 外部スケジューラ（インフラ運用側で管理）が指定時刻にコマンド起動を行う運用
- 実行日付を引数で指定することで、過去日付のバックフィル実行も可能
バッチ一覧（運用観点での頻度）
| カテゴリ | バッチ | 想定頻度 |
|---|---|---|
| 決済 | 月次決済 | 日次（契約更新日に動く） |
| 決済 | 銀行振込期限切れキャンセル | 日次 |
| 決済 | 契約日数更新 | 日次 |
| 決済・運用 | 顧客情報 CSV 出力 | 月次 |
| 配信 | 一斉配信送信 | 短サイクル（数分〜十数分間隔） |
| 配信 | ステップ配信送信 | 短サイクル |
| 配信 | 記事公開通知 | 短サイクル |
| 配信 | ライブ強制終了 | 短サイクル |
| 統計 | バッジ判定・付与 | 日次 |
| 統計 | 受講者数集計 | 日次 |
| 統計 | コンテンツ受講数集計 | 日次 |
| ファイル | 論理削除済コンテンツのファイル削除 | 日次 |
| ファイル | 助言会社向けファイルコピー | 臨時 / 月次 |
| ファイル | トークファイルコピー | 日次 |
| ファイル | アーカイブ作成 | 日次 / オンデマンド |
| 監視 | ストレージ整合性チェック | 日次 |
実際の頻度・時刻はインフラ運用側のスケジューラ設定が真実。
二重起動防止
- バッチ層自体に共通の二重起動制御機構はない
- 配信系（一斉・ステップ）のみ、内部的にロック機構で重複実行を防止
- それ以外のバッチは、外部スケジューラ側の「同時実行禁止」設定に依存して制御
失敗時の通知
- バッチ層に横断的な失敗通知機構はない
- 失敗時の通知は個別の処理内で明示的に Slack 通知を呼び出す形式
- 例: ストレージ整合性チェックで不整合検出時の通知、助言会社向けコピーでの失敗通知
緊急停止スイッチ（運営アドミン経路）
- 一斉配信・ステップ配信については、運営アドミンが緊急停止ロックを取得することで以降のバッチ実行をスキップ可能
- 詳細は
../admin/system.md参照
手動再実行
- 障害対応での手動再実行は外部スケジューラ画面・運用担当者の CLI 操作で実施
- 多くのバッチは実行日付を引数で受け付けるため、過去日付のバックフィルが可能
📝 レビュー観点:
- 入力 → 処理 → 出力: 外部スケジューラ → CLI 起動 → UseCase 実行 → 結果ログ
- エッジケース: 二重起動、長時間ロック、引数誤投入での日付バックフィル
- エラー表示: バッチ失敗は外部スケジューラ側のログで検知
- [本機能特有] バッチ間の依存関係は明示なし: 暗黙の競合可能性あり
admin 操作
該当なし / 実装されていない
- バッチ手動実行の運営アドミン UI: 未実装（外部スケジューラから手動起動）
- バッチ実行履歴の運営アドミン閲覧: 未実装
📝 レビュー観点:
- 運営アドミンからの手動実行経路の必要性
- 関連:
../admin/system.mdの配信ロック・バッジ更新ロック解除
品質 / 約束事項
- 応答性: バッチは非同期、外部スケジューラの cron 設定に従う
- 信頼性: 失敗時の自動リトライは個別 UseCase 依存。バッチ層共通機構なし
- 制限値:
- タイムゾーン: JVM 全体を Asia/Tokyo 固定
- 二重起動: 外部スケジューラ側で制御
- データ保持: バッチ実行履歴は外部スケジューラのログ依存
📝 レビュー観点:
- [本機能特有] 外部スケジューラ依存のリスク: スケジューラ障害時の影響範囲
- [本機能特有] バッチ実行履歴の可視化: 運用上の確認手段
変更履歴（リリースノート候補）
v2.29.2: 2026-05-04（PSD 初版）
- [PSD 追加] 本ドキュメント初版作成。v2.29.2 時点の実装を起こし。機能追加・変更は含まない
📝 レビュー観点:
- 過去の主要変更（バッチ追加履歴 / 二重経路（monthly-payment）の整理 等）
関連ドキュメント
- 権限定義:
../user-roles.md - 用語辞書:
../terminology.md - 関連 PSD:
./delivery-engine.md— メール配信エンジン./media-pipeline.md— メディアパイプライン../admin/system.md— 運営アドミンシステム運用（緊急停止）