API仕様書 - 2026/04/17

データベース設計

2つのDBでソース画像と生成画像を管理

DB1: Source Image DB

事前に用意された元原稿画像の情報を管理

一覧表示、詳細表示、選択対象として利用

Read Only

フィールド	説明	いつ使う
sourceImageIdPK	元原稿画像ID	STEP1: Bubble DBに紐付け保存 / STEP4: POST時に送る
fileName	ファイル名	STEP1: 画像選択時の表示
category	分類	STEP1: 行事 or 共通印刷物でフィルタ
size	サイズ	STEP1: サイズでフィルタ（パラメータ追加が必要）
fileKey	元画像ファイル識別子	Bubble側は使わない（Brother内部用）
thumbnailKey	サムネイル識別子	Bubble側は使わない（APIがthumbnailUrlに変換）
status	状態	STEP1: 有効な画像のみ表示するフィルタ
createdAt	作成日時	用途不明
updatedAt	更新日時	用途不明
description任意	説明	用途不明
tags任意	タグ	用途不明
version任意	バージョン	用途不明

DB2: Generated Image DB

元原稿画像 + 入れ替えテキストをもとに生成された画像情報を管理

生成履歴、状態管理、再生成の管理も担当

CRUD

フィールド	説明	いつ使う
generatedImageIdPK	生成画像ID	STEP4: POSTレスポンスで受取 → Bubble DBに保存。再生成/削除時にも使用
sourceImageId	元原稿画像ID	どの背景画像から生成したか（参照用）
userId	ユーザID	どのユーザーの生成物か
replaceText	差し替えテキスト	STEP4: リクエストで送る（ただし要拡張）
fileName	ファイル名	用途不明
status	生成状態	STEP4: 生成中/完了/失敗の判定
fileKey	生成画像ファイル識別子	Bubble側は使わない（APIがimageUrlに変換）
parentGeneratedImageId	再生成元ID	再生成時の履歴追跡用
size	サイズ	どのサイズで生成したか
createdAt	作成日時	履歴管理
updatedAt	更新日時	履歴管理
deletedAt任意	削除日時	論理削除用
version任意	バージョン	用途不明

APIエンドポイント

全7エンドポイント（元原稿画像系 2 + 生成画像系 5）

元原稿画像系 (Source Images)

GET /source-images 原稿一覧取得

レスポンス

sourceImageId title thumbnailUrl status category

GET /source-images/{sourceImageId} 特定原稿詳細取得

パスパラメータ

sourceImageId

レスポンス

sourceImageId title imageUrl status

生成画像系 (Generated Images)

POST /generated-images 非同期新規生成

リクエストボディ

sourceImageId originalText replaceText

レスポンス

generatedImageId sourceImageId status

* 非同期処理 - 即座にgeneratedImageIdとstatus=RUNNINGを返却し、バックグラウンドで画像生成を実行

GET /generated-images/{generatedImageId} 生成画像詳細取得

パスパラメータ

generatedImageId

レスポンス

generatedImageId sourceImageId status imageUrl

* imageUrl は status=COMPLETED のときのみ返却

GET /generated-images 生成画像一覧取得

クエリパラメータ

userId

レスポンス

generatedImageId sourceImageId status createdAt thumbnailUrl

POST /generated-images/{generatedImageId}/regenerate 再生成

パスパラメータ + リクエストボディ

generatedImageId originalText replaceText

レスポンス

generatedImageId parentGeneratedImageId sourceImageId status

* 新しいgeneratedImageIdが発行され、元のIDはparentGeneratedImageIdとして記録

DELETE /generated-images/{generatedImageId} 生成画像削除

パスパラメータ

generatedImageId

レスポンス

generatedImageId status

シーケンス図: 原稿一覧・詳細取得

原稿一覧画面の表示から、特定原稿の詳細取得までのフロー

やっていることの流れ（かんたん解説）

1原稿一覧を表示する

ユーザ

ブラウザで原稿一覧画面を開きます。
画面（Frontend）

裏側のサーバーに「原稿の一覧をちょうだい」とリクエストを送ります。

API呼び出し: GET /source-images
サーバー（Backend API）

データベースから原稿の情報（タイトル・サムネイルのキーなど）をまとめて取得します。
サーバー → ファイルストレージ

サムネイル画像のキーをもとに、ブラウザで表示できる画像URLを生成します。

画像ファイル自体はクラウドストレージに保管されており、一時的な表示用URLを発行する仕組みです
画面（Frontend）

受け取った情報をもとに、サムネイル画像の一覧をユーザに表示します。

2原稿の詳細を見る

ユーザ

一覧の中から見たい原稿をクリックして選択します。
画面（Frontend）

サーバーに「この原稿の詳しい情報をちょうだい」とリクエストを送ります。

API呼び出し: GET /source-images/{sourceImageId}
サーバー（Backend API）

データベースからその原稿の詳細情報（タイトル・説明・画像キーなど）を取得し、ファイルストレージからフルサイズの画像URLを生成します。
画面（Frontend）

原稿の詳細情報と大きな原稿画像をユーザに表示します。

原稿一覧取得 → 特定原稿の詳細取得（シーケンス図）

sequenceDiagram
    autonumber

    actor User as ユーザ
    participant FE as Frontend
    participant API as Backend API
    participant SIDB as Source Image DB
    participant FS as File Storage

    User ->> FE: 原稿一覧画面を開く
    FE ->> API: GET /source-images

    API ->> SIDB: 原稿一覧メタ情報を取得
    SIDB -->> API: sourceImageId, title, thumbnailFileKey, status

    API ->> FS: thumbnailFileKey から表示用URLを生成
    FS -->> API: thumbnailUrl

    API -->> FE: 原稿一覧（thumbnailUrl 含む）
    FE -->> User: サムネイル画像一覧を表示

    User ->> FE: 特定原稿を選択
    FE ->> API: GET /source-images/{sourceImageId}

    API ->> SIDB: 特定原稿の詳細取得
    SIDB -->> API: title, imageFileKey, description, status

    API ->> FS: imageFileKey から表示用URLを生成
    FS -->> API: imageUrl

    API -->> FE: 原稿詳細（imageUrl 含む）
    FE -->> User: 原稿詳細・原稿画像を表示

シーケンス図: AI画像生成

特定原稿からテキスト差し替え画像を生成し、結果を取得するまでのフロー

やっていることの流れ（かんたん解説）

1元になる原稿を開く

ユーザ

テキストを差し替えたい元原稿の詳細画面を開きます。
サーバー（Backend API）

「原稿一覧・詳細取得」と同じ流れで、DBから原稿情報を取得し、ストレージから画像URLを発行して画面に返します。
画面（Frontend）

原稿の詳細と画像を表示します。ここからユーザはテキスト差し替えの操作に進めます。

2AIに画像生成を依頼する

ユーザ

元のテキスト（originalText）と差し替え後のテキスト（replaceText）を入力して「生成」ボタンを押します。
画面（Frontend）

サーバーに「この原稿のテキストを差し替えた画像を作って」とリクエストを送ります。

API呼び出し: POST /generated-images { sourceImageId, originalText, replaceText }
サーバー（Backend API）

すぐに「受け付けました（生成中）」と返事を返します。画面にはローディング表示が出ます。

画像生成には時間がかかるため、結果を待たずに先に「受付OK」を返す仕組み（非同期処理）です

3裏側でAIが画像を生成する（バックグラウンド）

サーバー（Backend API）

元原稿が本当に存在するかDBで確認し、生成画像DBに「処理中」のレコードを作成します。
サーバー → 生成AI

元原稿画像と差し替えテキストを生成AIに渡して、テキストが差し替わった新しい画像を作ってもらいます。
サーバー → ファイルストレージ

AIから返ってきた生成画像をストレージに保存します。
サーバー（Backend API）

生成画像DBのレコードを「完了」に更新し、画面に「生成が終わりました」と通知します。

4生成結果を確認する

ユーザ

生成完了の通知を受けて、生成結果を表示する操作をします。
画面（Frontend）

サーバーに「この生成画像の情報をちょうだい」とリクエストを送ります。

API呼び出し: GET /generated-images/{generatedImageId}
サーバー（Backend API）

生成画像DBから結果を取得し、ストレージから表示用の画像URLを発行して画面に返します。
画面（Frontend）

AIが生成したテキスト差し替え済みの画像をユーザに表示します。

特定原稿から新規生成 → 結果取得・表示（シーケンス図）

sequenceDiagram
    autonumber

    actor User as ユーザ
    participant FE as Frontend
    participant API as Backend API
    participant SIDB as Source Image DB
    participant GIDB as Generated Image DB
    participant AI as Generative AI
    participant FS as File Storage

    User ->> FE: 特定原稿詳細を開く
    FE ->> API: GET /source-images/{sourceImageId}
    API ->> SIDB: 原稿詳細を取得
    SIDB -->> API: 原稿メタ情報を返却
    API ->> FS: 原稿画像URLを取得
    FS -->> API: sourceImageUrl
    API -->> FE: 原稿詳細 + sourceImageUrl
    FE -->> User: 原稿詳細を表示

    User ->> FE: ターゲットテキストと差し替えテキストを入力し「生成」を実行
    FE ->> API: POST /generated-images { sourceImageId, originalText, replaceText }
    API -->> FE: generatedImageId, status = RUNNING
    FE -->> User: 生成受付/生成中を表示

    API ->> SIDB: sourceImageId の存在確認
    SIDB -->> API: 原稿情報を返却

    API ->> GIDB: 生成レコード作成 status = PENDING
    GIDB -->> API: generatedImageId を返却

    API ->> AI: 元原稿 + replaceText で画像生成依頼
    AI -->> API: 生成画像データを返却

    API ->> FS: 生成画像を保存
    FS -->> API: generatedFileKey を返却

    API ->> GIDB: status = COMPLETED, fileKey = generatedFileKey を更新
    GIDB -->> API: 更新完了

    API -->> FE: generatedImageId, status = COMPLETED
    FE -->> User: 生成完了を表示

    User ->> FE: 生成結果を表示
    FE ->> API: GET /generated-images/{generatedImageId}

    API ->> GIDB: generatedImageId で生成結果取得
    GIDB -->> API: status, fileKey を返却

    API ->> FS: fileKey から表示用URLを取得
    FS -->> API: generatedImageUrl

    API -->> FE: generatedImageId, status = COMPLETED, generatedImageUrl
    FE -->> User: 生成画像を表示

原稿登録〜ダウンロードの全体フロー

管理者のテンプレート登録から、ユーザーの画像生成・ダウンロードまでの一連の流れ（整理中）

0 ブラザー側がSource Image DBに画像を登録する Brother Source Image DB Design Template DB

Brother

各サイズ（A3・A4等）の元原稿画像とサムネイル画像をFile Storageにアップロードする。

アップロードにより fileKey を取得。サムネイルは公開URLとして配置
Brother

Design Template DBにデザインテンプレートを登録する。テンプレート名・代表サムネイルURL（thumbnailUrl）を設定。

designTemplateId が発行される
Brother

デザインテンプレートに紐づけてSource Image DBに各サイズの元原稿画像を登録する。designTemplateId（FK）・size・fileKey・thumbnailUrl を設定。

Bubble側からは Read Only。サイズごとに1レコード（例: A3, A4, B4 ...）

1 デザインテンプレートを登録する管理者 / GET /design-templates → Bubble DB保存 Design Template DB Bubble: デザインテンプレート

管理者

Bubbleの管理画面でデザインテンプレートを作成。開催月・テンプレート名を設定する。
Bubble → Brother API

GET /design-templates でデザインテンプレート一覧を取得し、テンプレートを選択する。
テンプレートを選ぶだけで全サイズの背景画像が自動で紐づく。

個別のsourceImageIdを選ぶ必要がなくなり、画像差し替え時もBubble側に影響なし
Bubble → Brother API

GET /design-templates/{designTemplateId}/source-images で選択したテンプレートのサイズ別画像一覧を取得し、サムネイルで内容を確認する。

A3・A4等のサイズごとの画像を一覧で確認できる
Bubble

以下をBubble DBに保存する。
・デザインテンプレート（親）: 名前・開催月・designTemplateId・thumbnailUrl
・デザインテンプレート画像（子）: 各サイズの sourceImageId・size・thumbnailUrl をリスト型で保持

使用API: GET /design-templates

ブラザー側のデザインテンプレート一覧を取得して、管理者がテンプレートを選択する

新規API

レスポンス

designTemplateId thumbnailUrl

使用API: GET /design-templates/{designTemplateId}/source-images

選択したテンプレートに含まれる全サイズの画像を取得して、サムネイルで内容を確認する

新規API

パスパラメータ

designTemplateId

レスポンス

sourceImageId size thumbnailUrl status

2 行事テンプレートを作成する管理者 / Bubble DB保存（API呼ばない） Bubble: 行事テンプレート

管理者

Bubbleの管理画面で業界（宗教法人等）を選択し、必要に応じて小分類（神社/寺院等）を選択して、行事テンプレートを作成する。
管理者

開催月・行事名・開催期間・行事詳細・プログラム・注釈などのデフォルト値を設定する。
管理者

ステップ1で作ったデザインテンプレートを最大3種紐づける（デザイン1は必須、デザイン2・3は任意）。
Bubble

すべてBubble DBに保存。Brother APIは呼ばない。

初期表示テンプレートをONにすると、新規登録ユーザーの行事一覧に自動で表示される

3 行事を新規作成する任意 - スキップ可ユーザー / Bubble DB保存（API呼ばない） Bubble: 行事データ

ユーザー

行事テンプレートを選択して行事を作成できる（テンプレートの情報がデフォルト値として入る）。
ユーザー

テンプレートを選択しないで行事を作成することも可能。この場合、すべて手入力。
Bubble

行事データをBubble DBに保存。Brother APIは呼ばない。

これどうするの？

テンプレートなしで行事を作成した場合、デザインテンプレート（背景画像）が紐づいていない。
この状態で「生成」ボタンを押したらどうなる？sourceImageId がないので生成できないはず。

→ 要確認

4 原稿を生成するユーザー / POST /generated-images → GET /generated-images/{generatedImageId} でポーリング Generated Image DB Bubble: 生成画像

ユーザー

行事一覧から行事を選択する。初期表示では原稿は何も表示されない（未生成状態）。
ユーザー

右上の「生成」ボタンを押下する。
Bubble → Brother API

POST /generated-images で行事情報をAPIに渡して原稿を生成する。
Bubble DBに保存済みの行事データ（行事名・期間・プログラム等）を展開してリクエストに含める。
Brother（バックグラウンド）

Source Image DBから背景画像を取得 → AIで背景画像にテキストを配置した原稿を生成 → File Storageに保存。
Bubble → Brother API

GET /generated-images/{generatedImageId} をポーリングして生成完了を待つ。
status=COMPLETED になったら fileKey + thumbnailUrl を取得し、Bubble DBに保存する。
Bubble

生成完了後、7サイズ分の生成結果が一覧表示される。

使用API: POST /generated-images

行事情報を渡して原稿画像を生成する（非同期）

既存API リクエスト・レスポンスの拡張が必要

色付き= キー項目（DB保存）

理想のリクエスト

sourceImageId eventName period details program notes

sourceImageIdを直接指定。STEP1で取得済みのBubble DB.デザインテンプレート画像から取得

理想のレスポンス

generatedImageId sourceImageId status fileKey thumbnailUrl

fileKey（DL用・永続識別子）+ thumbnailUrl（表示用・公開URL）を返却しBubble DBに保存。DL時のみ GET /files/{fileKey}/url で一時URLを取得

呼び出し方針

ユーザーがサイズを選択してから生成する（1サイズずつ）
7サイズ分を並列に最大7回POSTする
各POSTのレスポンスで受け取った generatedImageId を使ってポーリングを開始する
レート制限の有無はブラザーに要確認

使用API: GET /generated-images/{generatedImageId}

生成状態をポーリングし、完了後に fileKey + thumbnailUrl を取得する

既存API レスポンスの拡張が必要

パスパラメータ

generatedImageId

POST /generated-images のレスポンスで取得したIDを使用

レスポンス

generatedImageId sourceImageId status fileKey thumbnailUrl

status=COMPLETED のとき fileKey + thumbnailUrl が返却される。Bubble DBに保存する

ポーリング方針

7つの生成リクエストそれぞれに対してポーリングを行う
ポーリング間隔・最大リトライ回数はブラザーに要確認
status=COMPLETED → fileKey + thumbnailUrl をBubble DBに保存しポーリング終了
status=FAILED → エラー表示しポーリング終了

生成失敗時のリカバリーフロー

7サイズ中の一部が失敗した場合、成功した他のサイズはそのまま保持する
失敗したデザインには「再試行」ボタンを表示し、同じパラメータで新規POSTし直す
失敗した generatedImageId に対して /regenerate は呼ばない（FAILEDの画像は再生成の起点にしない）
新規POSTで新しい generatedImageId が発行されるため、Bubble DBには新しいレコードとして保存し、失敗レコードは削除する

※ Webhook方式の場合はこのAPIは不要

ブラザー側が生成完了時にBubbleへWebhookで通知する方式を採用する場合、ポーリング用のこのGETエンドポイントは不要になる。Webhookペイロードに generatedImageId + fileKey + thumbnailUrl を含めれば、Bubble側はそのまま保存するだけでよい。
どちらの方式にするかはブラザーに要確認。

5 評価・ダウンロードするユーザー / 評価はBubble DB / DLはfileKeyからURL取得 Bubble: 生成画像 / 評価

ユーザー

3種類のデザインテンプレートそれぞれに五段階評価をつける。

例: A3のデザイン2をDLしたい場合、A3のデザイン1,2,3すべてを評価する必要がある
Bubble

評価データはBubble DBに保存する。Brother APIは呼ばない。
ユーザー

3種類すべて評価すると「この原稿をダウンロード」ボタンが活性化される。
ユーザー

「この原稿をダウンロード」を押して画像をダウンロードする。

API呼び出しフロー

タイミング	やること	API
初回生成時（STEP4）	POSTで生成開始 → GETポーリングで完了後に fileKey + thumbnailUrl を取得し、Bubble DBに保存	POST /generated-images → GET /generated-images/{id}
一覧表示時（毎回）	Bubble DBの thumbnailUrl で直接表示（APIコール不要）	APIは呼ばない
ダウンロード時	Bubble DBの fileKey で一時DL用URLを取得	GET /files/{fileKey}/url
行事情報を変更した時	再生成が必要 → STEP6へ	POST /generated-images/{generatedImageId}/regenerate（STEP6で詳述）

使用API: GET /files/{fileKey}/url

fileKeyから一時的な署名付きURLを取得する（ダウンロード用）

新規API

パスパラメータ

fileKey

レスポンス

url expiresAt

一時的な署名付きURL（有効期限付き）を返却。期限が切れたら再度呼び出すだけでOK

6 行事情報を変更して再生成するユーザー / POST /generated-images/{generatedImageId}/regenerate → GET /generated-images/{generatedImageId} でポーリング Generated Image DB Bubble: 生成画像

ユーザー

行事情報（行事名・期間・プログラム等）を編集して保存する。
ユーザー

「再生成」ボタンを押下する。
Bubble → Brother API

POST /generated-images/{generatedImageId}/regenerate で変更後の行事情報を渡して再生成する。
既存の generatedImageId をパスに指定し、更新された行事データをリクエストボディに含める。
Brother API

新しい generatedImageId を発行し、元のIDを parentGeneratedImageId として記録。
バックグラウンドで画像を再生成する。
Bubble → Brother API

STEP4と同様、GET /generated-images/{generatedImageId} をポーリングして再生成完了を待つ。
status=COMPLETED になったら新しい fileKey + thumbnailUrl を取得する。
Bubble

Bubble DBの生成画像レコードを新しい generatedImageId・fileKey・thumbnailUrl で更新する。画面に再生成結果が表示される。

使用API: POST /generated-images/{generatedImageId}/regenerate

既存の生成画像を起点に、変更後の行事情報で再生成する（非同期）

既存API リクエスト・レスポンスの拡張が必要

パスパラメータ

generatedImageId

再生成元の生成画像ID（Bubble DBに保存済み）

リクエストボディ

eventName period details program notes

テンプレート・サイズは元の生成結果から引き継ぐため指定不要

レスポンス

generatedImageId parentGeneratedImageId sourceImageId status fileKey thumbnailUrl

新しい generatedImageId が発行される。元のIDは parentGeneratedImageId として記録

呼び出し方針

STEP4と同じく、7サイズ分を並列に7回POSTする
各POSTのレスポンスで新しい generatedImageId を受け取り、ポーリングを開始する
完了後、Bubble DBの既存レコードを新しい generatedImageId・fileKey・thumbnailUrl で上書きする

使用API: GET /generated-images/{generatedImageId}（ポーリング）

再生成の完了をポーリングし、新しい fileKey + thumbnailUrl を取得する

既存API STEP4と同じAPI

パスパラメータ

generatedImageId

POST /regenerate のレスポンスで取得した新しいIDを使用

レスポンス

generatedImageId sourceImageId status fileKey thumbnailUrl

ポーリング方針

STEP4と同じ方式・間隔でポーリングする
status=COMPLETED → 新しい fileKey + thumbnailUrl でBubble DBの既存レコードを上書きしポーリング終了
status=FAILED → エラー表示しポーリング終了（元の生成画像はそのまま残す）

※ Webhook方式の場合はこのAPIは不要

STEP4と同様、Webhook方式を採用する場合はポーリング不要。

共通印刷物フロー

AI生成なし・サイズ指定なし。Brother DBから画像グループを選択して、そのままユーザーに配布する

前提条件

共通印刷物は行事用とは別のCommon Print Group DB + Common Print DBで管理する。
行事のデザインテンプレートと同じパターン: Brother側がグルーピング、Bubble側が業界紐付けを管理。
サイズ指定はないため、1グループ = N枚の印刷物（行事の「7サイズ」とは構造が異なる）。

行事フローとの違い

	行事	共通印刷物
テキスト入力	あり（行事名・期間等）	なし
AI生成	あり	なし
サイズ展開	7サイズ	なし（1画像 = 1印刷物）
Brother側グルーピング	Design Template DB → Source Image DB	Common Print Group DB → Common Print DB
Bubble側管理	行事テンプレート（業界紐付け）	共通印刷物グループ（業界紐付け）
画像の出処	Brother DB → AI生成	Brother DBからそのまま配布
DL方式	fileKey → GET /files/{fileKey}/url	同じ
使用API	GET /design-templates + POST /generated-images 等	GET /common-print-groups + GET /files/{fileKey}/url

0 Brother側が共通印刷物グループ・画像を登録する Brother Common Print Group DB Common Print DB

Brother

Common Print Group DBにグループを登録する。グループ名（name）を設定。

commonPrintGroupId が発行される
Brother

グループに紐づけてCommon Print DBに各印刷物画像を登録する。commonPrintGroupId（FK）・fileName・fileKey・thumbnailUrl を設定。

1グループにN枚の印刷物。サイズ概念はない

1 共通印刷物グループを登録する管理者 / GET /common-print-groups → Bubble DB保存 Common Print Group DB Bubble: 共通印刷物グループ

管理者

Bubbleの管理画面でグループ名を入力し、業界・小分類を選択する。
Bubble → Brother API

GET /common-print-groups でBrother側の共通印刷物グループ一覧を取得し、グループを選択する。
グループを選ぶだけで全印刷物が自動で紐づく。

デザインテンプレート登録（行事STEP1）と同じパターン
Bubble → Brother API

GET /common-print-groups/{commonPrintGroupId}/prints で選択したグループの印刷物一覧を取得し、サムネイルで内容を確認する。
Bubble

以下をBubble DBに保存する。
・共通印刷物グループ（親）: グループ名・業界・小分類・commonPrintGroupId
・共通印刷物（子）: 各印刷物の commonPrintId・fileName・thumbnailUrl・fileKey をリスト型で保持

使用API: GET /common-print-groups

Brother側の共通印刷物グループ一覧を取得して、管理者がグループを選択する

新規API

レスポンス

commonPrintGroupId name

使用API: GET /common-print-groups/{commonPrintGroupId}/prints

選択したグループに含まれる全印刷物を取得して、サムネイルで内容を確認する

新規API

パスパラメータ

commonPrintGroupId

レスポンス

commonPrintId fileName thumbnailUrl fileKey

commonPrintId・thumbnailUrl・fileKeyをBubble DBに保存。thumbnailUrlは一覧表示用、fileKeyはDL用

2 ユーザーが閲覧・ダウンロードするユーザー / 表示はBubble DB / DLはGET /files/{fileKey}/url Bubble: 共通印刷物

ユーザー

サイドバーの「共通印刷物」から、自分の業界に紐づくグループを選択して印刷物一覧を閲覧する。
Bubble

Bubble DBの thumbnailUrl で印刷物一覧を表示する。Brother APIは呼ばない。
ユーザー

DLしたい印刷物を選択する。
Bubble → Brother API

Bubble DBの fileKey で GET /files/{fileKey}/url を呼び出し、一時DL用URLを取得してダウンロードを実行する。

API呼び出しフロー

タイミング	やること	API
グループ登録時（STEP1）	グループ選択 → 全印刷物のcommonPrintId・fileKey・thumbnailUrl をBubble DBに保存	GET /common-print-groups GET /common-print-groups/{id}/prints
一覧表示時（毎回）	Bubble DBの thumbnailUrl で直接表示	APIは呼ばない
ダウンロード時	Bubble DBの fileKey で一時DL用URLを取得	GET /files/{fileKey}/url

使用API

使用するAPI

API	使用箇所	備考
GET /common-print-groups	STEP1: グループ一覧取得・選択	新規API
GET /common-print-groups/{id}/prints	STEP1: グループ内の印刷物一覧取得	新規API
GET /files/{fileKey}/url	STEP2: ユーザーDL時に一時URLを取得	行事と共通で使用

設計概要

ブラザー提供のAPI仕様をベースに、実運用に合わせた理想設計の概要

設計の概要

本システムは行事原稿（AI生成）と共通印刷物（既存画像配布）の2つの機能を持つ。
どちらも「Brother側がグルーピング・画像管理」「Bubble側が業界紐付け・ユーザー管理」という同一パターンで設計。

行事原稿

STEP0 Brotherがデザインテンプレート・元原稿画像を登録

STEP1 管理者がテンプレートを選択・業界を紐付け

STEP2 管理者が行事テンプレートを作成しデザインテンプレートを紐付け

STEP3 ユーザーが行事を新規作成（テンプレートから or 手入力）

STEP4 AI生成（API送信 → ポーリング → 結果保存）

STEP5 ユーザーが生成結果を確認・ダウンロード

STEP6 必要に応じて再生成

共通印刷物

STEP0 Brotherがグループ・印刷物画像を登録

STEP1 管理者がグループを選択・業界を紐付け

STEP2 ユーザーが閲覧・そのままDL

	Brother側（API提供）	Bubble側（フロント + DB）
画像・グルーピング	Design Template DB / Common Print Group DB でグルーピング管理。画像はFile Storageに保存	`designTemplateId` / `commonPrintGroupId` を参照するのみ
業界・業種	関知しない	行事テンプレート / 共通印刷物グループに業界・小分類を紐付け
サムネイル表示	`thumbnailUrl`（公開URL・期限なし）を返却	Bubble DBに保存して直接 `<img src>` に使用。APIコール不要
ダウンロード	`fileKey`（永続識別子）を返却。DL時に `GET /files/{fileKey}/url` で一時URL発行	`fileKey` をBubble DBに保存。DL時にAPIコール

設計思想

Design Template DB / Common Print Group DB の新設

✗ ブラザー設計の課題

Bubble側が sourceImageId を直接保持する設計。Brother側が画像を差し替えるとIDが変わり、Bubble側の参照が壊れる。画像の追加・削除のたびにBubble側の同期が必要になる

✓ 理想設計の解決策

グループID（designTemplateId / commonPrintGroupId）で管理。Brother側が裏で画像を差し替えてもグループIDは不変なのでBubble側に影響なし。画像の実体管理はBrother側に閉じる

サムネイル表示の最適化

✗ ブラザー設計の課題

生成画像のレスポンスに thumbnailUrl がなく、imageUrl（署名付き一時URL）のみ。一覧表示のたびにAPIコールが必要になるか、期限切れURLで画像が表示されなくなるリスクがある

✓ 理想設計の解決策

生成画像にも thumbnailUrl（公開URL・期限なし）を追加。Bubble DBに保存して直接 <img src> で表示するだけ。APIコール不要で、期限切れの心配もない

DL用URLの期限管理と共通化

✗ ブラザー設計の課題

imageUrl（署名付き一時URL）を直接保存する設計。期限が切れるとDLできなくなり、GET /generated-images/{id} でリソース全体を再取得してURLを取り出す必要がある。また共通印刷物にはDL用APIすら存在しない

✓ 理想設計の解決策

fileKey（永続識別子）をBubble DBに保存し、DL時に GET /files/{fileKey}/url で一時URLを都度発行。期限切れても再発行するだけ。行事の生成画像も共通印刷物もこのAPI 1本でDL可能で、ファイル種別を意識する必要がない

行事情報はBubble側で管理

✗ ブラザー設計の課題

originalText / replaceText という汎用フィールドのみ。行事名・期間・プログラムなどの構造化データを表現できない。Brother側Generated Image DBにテキストを保持する設計のため、データの二重管理になる

✓ 理想設計の解決策

行事情報はBubble DBで一元管理し、生成・再生成時にリクエストパラメータとして都度送信。Brother側は画像生成に使うだけで保持しない。ユーザーが行事情報を編集→再生成すれば常に最新データが反映される

行事と共通印刷物で同じパターン

✗ ブラザー設計の課題

共通印刷物の概念自体がなく、行事原稿のみを前提としたAPI設計。共通印刷物を追加する場合、別の仕組みを一から設計する必要がある

✓ 理想設計の解決策

Brother側がグルーピング（テンプレート/グループ）を管理し、Bubble側が業界紐付けを管理する同一パターンを行事・共通印刷物で共通化。管理者は「グループを選ぶだけ」で全画像が自動紐付け。APIの構造も同形にすることで実装・学習コストを削減

ブラザー設計との差分

画像のグルーピング画像差し替え時のID変更リスク回避

ブラザー提供

なし（Source Image DBはフラット）

→

理想設計

Design Template DB を新設し、designTemplateId でグルーピング

画像選択方式テンプレート経由で体系的に取得

ブラザー提供

sourceImageId を直接指定（全画像から個別選択）

→

理想設計

sourceImageId を直接指定（Design Template経由で7サイズ分を一括取得済み）

生成リクエスト構造化されたテキストデータを渡す設計に

ブラザー提供

sourceImageId + originalText + replaceText

→

理想設計

sourceImageId + 行事情報（eventName, period, details, program, notes）

サムネイル表示生成画像にthumbnailUrlを追加し、APIコール不要に

ブラザー提供

元原稿は thumbnailUrl あり。生成画像は imageUrl（一時URL）のみでサムネイル専用URLがない

→

理想設計

生成画像にも thumbnailUrl（公開URL・期限なし）を追加。Bubble DBに保存して直接表示

DL用URL 期限切れを根本解決 + 行事・共通印刷物で共通化

ブラザー提供

imageUrl（一時URL）を直接保存。期限切れ時は GET /generated-images/{id} で全体再取得が必要

→

理想設計

fileKey（永続）を保存し、GET /files/{fileKey}/url で都度一時URL発行。行事・共通印刷物で共通利用

共通印刷物行事と統一した設計パターンで管理

ブラザー提供

対応なし

→

理想設計

Common Print Group DB + Common Print DB を新設。行事と同パターン

不要になったAPI 理想設計では廃止

API	機能	廃止理由
`GET /source-images`	元原稿の一覧取得	テンプレート方式に移行。`GET /design-templates` で代替
`GET /source-images/{id}`	元原稿の詳細取得	テンプレート配下の画像一覧で代替。個別IDでの取得が不要に
`GET /generated-images`	生成画像の一覧取得	生成画像はBubble DBで管理。Brother側に一覧を問い合わせる必要がない
`DELETE /generated-images/{id}`	生成画像の削除	再生成で上書きする運用のため、個別削除はスコープ外

残論点（ブラザー側への確認事項）

対応可否 — 理想設計の提案をブラザーが受けられるか

#	論点	詳細	関連フロー
1	Design Template DB / Common Print Group DB の新設は対応可能か	理想設計ではBrother側にグルーピング用DBの新設を提案している。対応可否を確認	STEP0, STEP1 / 共通STEP0, STEP1
2	リクエスト構造の拡張は対応可能か	現行の `originalText` / `replaceText` → `eventName`, `period`, `details`, `program`, `notes` の複数フィールド対応。理想設計の構造をこちらから提案する形で良いか	STEP4
3	生成画像への thumbnailUrl 追加は対応可能か	現行の生成画像レスポンスは `imageUrl` のみ。元原稿（`GET /source-images`）には既に `thumbnailUrl` があるため、生成画像にも同様に公開URL（期限なし）のサムネイルを追加できるか	STEP4, STEP5
4	fileKey + GET /files/{fileKey}/url 方式は対応可能か	DL用に `fileKey`（永続識別子）を返却し、`GET /files/{fileKey}/url` で署名付き一時URLを都度発行する新規API。行事の生成画像・共通印刷物で共通利用する想定	STEP5 / 共通STEP2
5	バッチ生成エンドポイントは対応可能か	現状は7サイズ分を個別に `POST /generated-images` × 7回並列送信している。行事情報（eventName等）が毎回重複するため、`POST /generated-images/batch` で複数 `sourceImageId` をまとめて送信し1回で済ませたい。Bubble側の並列制御が不要になり、部分失敗時のハンドリングもBrother側で完結する	STEP4, STEP6

仕様確認 — 現行仕様の不明点

#	論点	詳細	関連フロー
6	thumbnailUrl は公開URLか、署名付き一時URLか	元原稿（`GET /source-images`）が返す `thumbnailUrl` は期限なしの公開URLか、それとも `imageUrl` と同様に署名付き一時URLか。理想設計ではサムネイルを公開URL前提でBubble DBに保存する設計のため、期限の有無で方針が変わる	STEP1, STEP5
7	imageUrl の有効期限と期限切れ時の挙動	現行の `imageUrl`（署名付き一時URL）の有効期限は何分/何時間か。期限切れ時のHTTPレスポンス（403？リダイレクト？）も確認したい	STEP4, STEP5
8	認証方式と userId の受け渡し	API認証はAPIキー方式かBearer Token方式か。Generated Image DBに `userId` があるが、POSTリクエストのパラメータには含まれていない。認証トークンから取得する想定か、リクエストボディに追加が必要か	全API共通
9	生成完了の通知方式	Webhook / ポーリングのどちらか。7サイズ並列POST時に完了をどう検知するか。ポーリングの場合、推奨間隔・最大リトライ回数も確認	STEP4, STEP6
10	レート制限の有無	最大7リクエストを並列POSTする。レート制限はあるか。バッチAPI（#5）が実現すればこの問題は解消される	STEP4
11	sizeの表現方法	A3 / A4 等のラベル指定か、px / mm 指定か。Bubble側からリクエストに含める値の形式	STEP4
12	生成と再生成APIを分ける必要があるか	`POST /generated-images` と `POST /generated-images/{id}/regenerate` が別APIである理由。内部処理が異なるのか。統合する場合、オプショナルな `parentGeneratedImageId` で初回/再生成を区別する方式を想定	STEP4, STEP6
13	ポーリングのバッチ取得は可能か	現状は `GET /generated-images/{id}` を7件分個別にポーリングしている。`GET /generated-images?ids=gi_001,gi_002,...,gi_007` のようにクエリパラメータで複数件を一括取得できるとポーリングループが1本で済む	STEP4, STEP6
14	テンプレートなし行事で「生成」を押した場合の挙動	ユーザーがテンプレートを選ばずに行事を作成した場合、`sourceImageId` がないため生成APIを呼べない。UI側で生成ボタンを非活性にする対応で良いか、そもそもテンプレート必須にするか	STEP3

理想DB設計

今日の議論を踏まえた理想的なDB構造。現行のDB設計タブは既存API仕様ベース、こちらは理想状態

Brother側

Design Template DB新規

デザインテンプレートのグルーピング情報。Read Only（Bubble側から）

フィールド	説明	備考
designTemplateIdPK	デザインテンプレートID	ブラザーが画像登録時に付与
name	テンプレート名	Brother内部の管理用。APIレスポンスには含めない
thumbnailUrl	代表サムネイルURL	テンプレート一覧表示用。公開URL（期限なし）で返却。Bubble DBに保存して再利用
createdAt	作成日時
updatedAt	更新日時

Source Image DB拡張

元原稿画像。designTemplateIdでグルーピング。Read Only（Bubble側から）

フィールド	説明	備考
sourceImageIdPK	元原稿画像ID
designTemplateIdFK	デザインテンプレートID	★追加 — Design Template DBへの参照
fileName	ファイル名
size	サイズ	A3, A4 等のラベルを想定（px/mm指定かはブラザーに要確認）
fileKey	元画像ファイル識別子	Brother内部のFile Storage用キー。Bubble側は使わない
thumbnailUrl	サムネイルURL	公開URL（期限なし）。Bubble DBに保存して再利用可
status	状態	有効/無効のフィルタ用。具体的な値はブラザーに要確認
createdAt	作成日時
updatedAt	更新日時

なぜDesign Template DBを作るのか：Bubble側が sourceImageId を直接保持していると、ブラザーが画像を差し替えた際にIDが変わり、Bubble DBとの整合性が壊れる。designTemplateId で管理すれば、ブラザーが裏で画像を差し替えてもBubble側は影響を受けない。

Generated Image DB拡張

AI生成された画像の情報

フィールド	説明	備考
generatedImageIdPK	生成画像ID
sourceImageId	元原稿画像ID
userId	ユーザID
status	生成状態	PROCESSING / COMPLETED / FAILED
fileKey	生成画像ファイル識別子	永続的な識別子。Bubble側に返却し、DL時に `GET /files/{fileKey}/url` でURL発行
thumbnailUrl	サムネイルURL	公開URL（期限なし）。一覧表示用にBubble DBに保存して直接使用
parentGeneratedImageId	再生成元ID	再生成時の履歴追跡。ブラザー内部の用途（品質分析等）か要確認
createdAt	作成日時
updatedAt	更新日時

Common Print Group DB新規

共通印刷物のグルーピング情報。Design Template DBと同じパターン。Read Only（Bubble側から）

フィールド	説明	備考
commonPrintGroupIdPK	共通印刷物グループID	ブラザーがグループ登録時に付与
name	グループ名	Brother内部の管理用
createdAt	作成日時
updatedAt	更新日時

Common Print DB新規

共通印刷物画像。commonPrintGroupIdでグルーピング。Read Only（Bubble側から）

フィールド	説明	備考
commonPrintIdPK	共通印刷物ID
commonPrintGroupIdFK	共通印刷物グループID	★追加 — Common Print Group DBへの参照
fileName	ファイル名
fileKey	画像ファイル識別子	永続的な識別子。DL時は GET /files/{fileKey}/url で一時URL取得
thumbnailUrl	サムネイルURL	公開URL（期限なし）。Bubble DBに保存して再利用可
status	状態
createdAt	作成日時
updatedAt	更新日時

Bubble側

デザインテンプレート

Brother側のdesignTemplateIdを参照。画像リストをリスト型で保持

カラム	備考
`designTemplateId`	Brother側のdesignTemplateIdを参照
名前
開催月
`thumbnailUrl`	GET /design-templatesのレスポンスから保存
デザインテンプレート画像（リスト型）	子テーブルへの参照。Search for不要

デザインテンプレート画像

デザインテンプレートの子テーブル。サイズごとに1レコード

カラム	備考
`sourceImageId`	GET /design-templates/{id}/source-imagesのレスポンスから保存
`size`	A3, A4 等
`thumbnailUrl`	サイズ別サムネイル

行事テンプレート

管理者が作成。業界・デザインテンプレートを紐付け

カラム	備考
名前
業界
小分類	任意。業界の中の細分類（神社/寺院等）
開催月
行事名（デフォルト）	ユーザーが行事作成時に初期値として使用
開催期間（デフォルト）	同上
行事詳細（デフォルト）	同上
プログラム（デフォルト）	同上
注釈（デフォルト）	同上
デザインテンプレ×3（1必須+2任意）
初期表示フラグ	ONの場合、新規ユーザーの行事一覧に自動表示

行事データ

ユーザーが作成する行事情報。API生成時にリクエストパラメータとして送信

カラム	備考
行事テンプレートID
行事名
期間
プログラム
詳細
注釈

生成画像

fileKey（DL用）+ thumbnailUrl（表示用）をPOSTレスポンスから保存

カラム	備考
`generatedImageId`	POSTレスポンスから取得
行事ID
designTemplateId
designIndex
size
fileKey	DL用。GET /files/{fileKey}/urlで一時URL取得
thumbnailUrl	一覧表示用。公開URLなので直接img srcに使用
status
評価

共通印刷物グループ

Brother側のcommonPrintGroupIdを参照。業界紐付けはBubble側で管理

カラム	備考
`commonPrintGroupId`	Brother側のcommonPrintGroupIdを参照
グループ名
業界	Bubble側で管理（行事テンプレートと同パターン）
小分類
共通印刷物（リスト型）	子テーブルへの参照。1グループにN枚

共通印刷物

共通印刷物グループの子テーブル。GET /common-print-groups/{id}/printsから取得した情報を保存

カラム	備考
`commonPrintId`	GET /common-print-groups/{id}/printsのレスポンスから保存
印刷物名	管理者が入力（「立入禁止」「土足厳禁」等）
`thumbnailUrl`	一覧表示用。公開URLなので直接img srcに使用
`fileKey`	DL用。GET /files/{fileKey}/urlで一時URL取得

現行との主な違い

Design Template DB 新設 — ブラザー側でデザインのグルーピングを管理。Bubbleはdesign TemplateId + sourceImageIdを保持
sourceImageId直接指定 — 生成リクエストでsourceImageIdを直接指定。STEP1で取得済みのため、Brother側の内部解決が不要でシンプル
行事情報はBubble側で管理 — Brother側Generated Image DBには行事データを持たない。生成・再生成時にBubbleからリクエストパラメータとして都度送信
fileKey + thumbnailUrl の使い分け — サムネイルは thumbnailUrl（公開URL・期限なし）で直接表示。DL用フルサイズ画像は fileKey（永続識別子）を保存し、DL時に GET /files/{fileKey}/url で一時URLを取得
Common Print DB 新設 — 共通印刷物を行事用Source Imageと分離

理想APIエンドポイント

今日の議論を踏まえた理想的なAPI設計。現行APIエンドポイントタブは既存仕様ベース、こちらは理想状態。画像はfileKey（永続識別子）で管理し、表示・DL時に一時URL取得

色付き= キー項目（Bubble DBに保存）

デザインテンプレート系（新規）

GET /design-templates 新規デザインテンプレート一覧取得

レスポンス

designTemplateId thumbnailUrl

* STEP1: デザインテンプレート登録時にテンプレ一覧を取得。designTemplateIdを選ぶだけで全サイズの画像が紐づく。thumbnailUrlは代表サムネイルの公開URL（期限なし）。Bubble DBに保存して再利用可

Response { "designTemplates": [ { "designTemplateId": "dt_001", // Design Template DB.designTemplateId "thumbnailUrl": "https://cdn.example.com/thumbnails/dt_001.png" // Design Template DB.thumbnailUrl }, { "designTemplateId": "dt_002", "thumbnailUrl": "https://cdn.example.com/thumbnails/dt_002.png" } ] }

GET /design-templates/{designTemplateId}/source-images 新規テンプレートのサイズ別画像一覧

パスパラメータ

designTemplateId

レスポンス

sourceImageId size thumbnailUrl status

* テンプレートに含まれる全サイズの画像を返却。サムネイル確認用

Response { "sourceImages": [ { "sourceImageId": "si_001", // Source Image DB.sourceImageId "size": "A3", // Source Image DB.size "thumbnailUrl": "https://cdn.example.com/thumbnails/dt_001_a3.png", // Source Image DB.thumbnailUrl "status": "active" // Source Image DB.status }, { "sourceImageId": "si_002", "size": "A4", "thumbnailUrl": "https://cdn.example.com/thumbnails/dt_001_a4.png", "status": "active" } ] }

生成画像系（既存拡張）

POST /generated-images 非同期拡張新規生成

リクエストボディ

sourceImageId eventName period details program notes

sourceImageIdを直接指定。STEP1で取得済みのBubble DB.デザインテンプレート画像から取得

レスポンス

generatedImageId sourceImageId status fileKey thumbnailUrl

fileKey（DL用・永続識別子）+ thumbnailUrl（一覧表示用・公開URL）を返却。Bubble DBに保存。DL時のみ GET /files/{fileKey}/url で一時URL取得

* 非同期処理。ユーザーがサイズを選択後、7サイズ分を並列に最大7回POSTする

Request { "sourceImageId": "si_001", // Bubble DB.デザインテンプレート画像.sourceImageId "eventName": "春季例大祭", // Bubble DB.行事データ.行事名 "period": "2026年4月20日（日）〜4月22日（火）", // Bubble DB.行事データ.期間 "details": "境内にて神事・奉納行事を執り行います", // Bubble DB.行事データ.詳細 "program": "10:00 神事 / 11:00 奉納舞 / 13:00 餅まき", // Bubble DB.行事データ.プログラム "notes": "雨天時は社務所にて執り行います" // Bubble DB.行事データ.備考 }

Response { "generatedImageId": "gi_001", // Generated Image DB.generatedImageId（新規発行） "sourceImageId": "si_001", // Source Image DB.sourceImageId（リクエストで指定した値） "status": "PROCESSING", // Generated Image DB.status（非同期処理中） "fileKey": null, // 非同期のため、完了後にGETで取得（DL用） "thumbnailUrl": null // 非同期のため、完了後にGETで取得（一覧表示用・公開URL） }

GET /generated-images/{generatedImageId} 生成状態確認・fileKey取得

パスパラメータ

generatedImageId

レスポンス

generatedImageId sourceImageId status fileKey thumbnailUrl

* ポーリング用。完了後 fileKey + thumbnailUrl をBubble DBに保存

Response（処理中） { "generatedImageId": "gi_001", // Generated Image DB.generatedImageId "sourceImageId": "si_001", // Generated Image DB.sourceImageId "status": "PROCESSING", // Generated Image DB.status（処理中） "fileKey": null, // まだ生成中 "thumbnailUrl": null // まだ生成中 }

Response（完了） { "generatedImageId": "gi_001", // Generated Image DB.generatedImageId "sourceImageId": "si_001", // Generated Image DB.sourceImageId "status": "COMPLETED", // Generated Image DB.status "fileKey": "gi_001", // Generated Image DB.fileKey（DL用・永続識別子） "thumbnailUrl": "https://cdn.example.com/thumbnails/gi_001_thumb.png" // 一覧表示用（公開URL・期限なし） }

POST /generated-images/{generatedImageId}/regenerate 再生成

パスパラメータ + リクエストボディ

generatedImageId eventName period details program notes

レスポンス

generatedImageId parentGeneratedImageId sourceImageId status fileKey thumbnailUrl

* 新しいgeneratedImageIdが発行。元のIDはparentGeneratedImageIdとして記録

Request { "eventName": "春季例大祭", // Bubble DB.行事データ.行事名 "period": "2026年4月20日（日）〜4月23日（水）", // Bubble DB.行事データ.期間 "details": "境内にて神事・奉納行事を執り行います", // Bubble DB.行事データ.詳細 "program": "10:00 神事 / 11:00 奉納舞 / 13:00 餅まき / 15:00 閉会", // Bubble DB.行事データ.プログラム "notes": "雨天時は社務所にて執り行います" // Bubble DB.行事データ.備考 }

Response { "generatedImageId": "gi_002", // Generated Image DB.generatedImageId（新規発行） "parentGeneratedImageId": "gi_001", // Generated Image DB.parentGeneratedImageId（再生成元） "sourceImageId": "si_001", // Generated Image DB.sourceImageId "status": "PROCESSING", // Generated Image DB.status（非同期処理中） "fileKey": null, // 非同期のため、完了後にGETで取得（DL用） "thumbnailUrl": null // 非同期のため、完了後にGETで取得（一覧表示用） }

ファイルURL取得（新規）

GET /files/{fileKey}/url 新規署名付き一時URL取得

パスパラメータ

fileKey

レスポンス

url expiresAt

* 生成画像のDL・共通印刷物のDLで使用。fileKeyは永続、URLは一時的（有効期限付き）。サムネイル表示はthumbnailUrl（公開URL）を直接使うためこのAPIは不要

Response { "url": "https://storage.example.com/files/gi_001.png?token=xxx&expires=1713600000", // 署名付き一時URL "expiresAt": "2026-04-22T12:00:00Z" // URL有効期限 }

共通印刷物系（新規）

GET /common-print-groups 新規共通印刷物グループ一覧取得

レスポンス

commonPrintGroupId name

* STEP1: 管理者がグループを選択する際に使用。デザインテンプレート一覧（GET /design-templates）と同パターン

Response { "commonPrintGroups": [ { "commonPrintGroupId": "cpg_001", // Common Print Group DB.commonPrintGroupId "name": "安全標識セット" // グループ名 }, { "commonPrintGroupId": "cpg_002", "name": "店舗案内セット" } ] }

GET /common-print-groups/{commonPrintGroupId}/prints 新規グループ内印刷物一覧取得

パスパラメータ

commonPrintGroupId

レスポンス

commonPrintId fileName thumbnailUrl fileKey

commonPrintId・thumbnailUrl・fileKeyをBubble DBに保存。thumbnailUrlは一覧表示用、fileKeyはDL用

* GET /design-templates/{id}/source-images と同パターン。グループ選択で全印刷物が自動紐付け

Response { "prints": [ { "commonPrintId": "cp_001", // Common Print DB.commonPrintId "fileName": "立入禁止_01.png", // Common Print DB.fileName "thumbnailUrl": "https://cdn.example.com/thumbnails/cp_001.png", // 一覧表示用（公開URL・期限なし） "fileKey": "cp_001" // DL用（永続識別子） }, { "commonPrintId": "cp_002", "fileName": "土足厳禁_01.png", "thumbnailUrl": "https://cdn.example.com/thumbnails/cp_002.png", "fileKey": "cp_002" } ] }

現行APIとの対応

現行API	理想	変更点
`GET /source-images`	`GET /design-templates`	個別画像選択 → テンプレート単位の選択に変更
`GET /source-images/{id}`	不要	テンプレートのサイズ別画像一覧で代替
`POST /generated-images`	`POST /generated-images`	リクエスト拡張 + fileKey（DL用）/ thumbnailUrl（表示用）をレスポンスに追加
`GET /generated-images/{id}`	`GET /generated-images/{id}`	ポーリング用。完了後fileKey + thumbnailUrlを取得
`GET /generated-images`	不要	Bubble DBで管理
`POST /generated-images/{id}/regenerate`	`POST /generated-images/{id}/regenerate`	リクエスト拡張
`DELETE /generated-images/{id}`	不要	今回スコープ外
—	`GET /files/{fileKey}/url`	DL用の署名付き一時URL取得。新設
—	`GET /common-print-groups`	共通印刷物グループ一覧。GET /design-templatesと同パターン
—	`GET /common-print-groups/{id}/prints`	グループ内印刷物一覧。GET /design-templates/{id}/source-imagesと同パターン

Brother API 仕様書

データベース設計

DB1: Source Image DB

DB2: Generated Image DB

APIエンドポイント

シーケンス図: 原稿一覧・詳細取得

やっていることの流れ（かんたん解説）

原稿一覧取得 → 特定原稿の詳細取得（シーケンス図）

シーケンス図: AI画像生成

やっていることの流れ（かんたん解説）

特定原稿から新規生成 → 結果取得・表示（シーケンス図）

原稿登録〜ダウンロードの全体フロー

使用API: GET /design-templates

使用API: GET /design-templates/{designTemplateId}/source-images

使用API: POST /generated-images

使用API: GET /generated-images/{generatedImageId}

API呼び出しフロー

使用API: GET /files/{fileKey}/url

使用API: POST /generated-images/{generatedImageId}/regenerate

使用API: GET /generated-images/{generatedImageId}（ポーリング）

共通印刷物フロー

行事フローとの違い

使用API: GET /common-print-groups

使用API: GET /common-print-groups/{commonPrintGroupId}/prints

API呼び出しフロー

使用API

使用するAPI

設計概要

設計の概要

設計思想

ブラザー設計との差分

残論点（ブラザー側への確認事項）

理想DB設計

Brother側

Design Template DB新規

Source Image DB拡張

Generated Image DB拡張

Common Print Group DB新規

Common Print DB新規

Bubble側

デザインテンプレート

デザインテンプレート画像

行事テンプレート

行事データ

生成画像

共通印刷物グループ

共通印刷物

現行との主な違い

理想APIエンドポイント

現行APIとの対応