要件定義 & システム設計書（実装向け）

目的：代理店が外注している「制作の一段」を、品質×速度のAI制作エンジンで白label置換する。MVPは鰻人（うなぎ専門店）を証明台に、一連の流れを実際に完結させる。素材はクライアントのテスト素材が主（我々のデフォルト素材から生成・整形はしない）。勝ち筋はリサーチ→分析でAIが仮説する（v0.2で詳細化）。

# レイヤー構成
[UI層]        承認UI / 依頼UI / ジョブ実行ビュー / オペログ    (Cloudflare Pages)
     |  REST/WebSocket
[API層]       Job API / Approval API / Webhook受信            (Workers / Container)
     |
[オーケストレーター] 司令塔 = Claude Code(現) -> Agent SDK(製品)
     |   ステージ実行・状態遷移・承認待ち・リトライ
     |--- サブエージェント（部署）: 解析 / 制作 / 多言語 / 分析
[アダプタ層]   モデル/ツール/APIを抽象化（差し替え可能）
     |--- Vision(Claude/Gemini)  --- 動画編集(Shotstack/Creatomate)
     |--- LLM(Claude)            --- 画像(GPT Image2/Nano Banana/Seedream)
     |--- TTS(ElevenLabs)        --- Meta Graph/Insights/Messaging API
[データ層]     Postgres(業務データ) / R2(メディア) / Queue(非同期) / KVS(状態)

agency(              -- 代理店（白label顧客・将来）
  id uuid pk, name text, brand_logo_url text, contact jsonb, created_at timestamptz)

client(              -- エンドクライアント（店舗）
  id uuid pk, agency_id uuid null fk->agency,
  name text, cuisine_type text,           -- 業種: 'unagi'
  google_place_id text,
  target_languages text[],                -- ['ja','en','ko','zh-Hant']
  ig_account_id text,                      -- 投稿先IGアカウント(誰名義かは未決)
  created_at timestamptz)

brand_profile(       -- ブランドの声・世界観
  id uuid pk, client_id uuid fk->client,
  brand_voice text, world_view text,
  signature_menus jsonb,                   -- 蒲焼/白焼/ひつまぶし…
  ng_list jsonb, updated_at timestamptz)

store_feature(       -- 特徴DB = 独自1割の源泉
  id uuid pk, client_id uuid fk->client,
  feature_tags jsonb,                      -- ['三度の食べ方','炭火','老舗']
  strengths jsonb, unique_elements jsonb,  -- 独自要素の候補
  discovery_gap text, updated_at timestamptz)

template(            -- 勝ち型テンプレ / WinningPattern
  id uuid pk, name text, vertical text,    -- 'unagi'/'yakiniku'…
  structure jsonb,                         -- 3幕: hook/guide/info
  shot_list jsonb,                         -- 必要ショット定義
  caption_template text, hashtag_set jsonb,
  subtitle_style jsonb, music_style text,
  performance_score numeric, scope text,   -- global/vertical/client
  client_id uuid null, updated_at timestamptz)

asset(               -- 素材（clip/photo）
  id uuid pk, client_id uuid fk->client,
  type text,                               -- 'video'/'photo'
  storage_url text, public_url text, duration_ms int,
  vision_tags jsonb,                       -- {scene, foods:['unagi'], ...}
  shot_role text, quality_score numeric,
  qc_status text,                          -- pending/ok/rejected
  created_at timestamptz)

job(                 -- 依頼（1リクエスト）
  id uuid pk, client_id uuid fk->client,
  requested_by text, target_languages text[], count int,
  template_id uuid null fk->template,
  compose_brief jsonb,                     -- 型+独自要素(9:1)
  status text,                             -- enum(下記)
  priority text, created_at, updated_at timestamptz)
  -- status enum: received|setup|analyzing|strategizing|producing|
  --   localizing|awaiting_qa|approved|publishing|published|analyzing_insights|failed

job_stage(          -- ステージ実行ログ（冪等/リトライ）
  id uuid pk, job_id uuid fk->job, stage text,
  status text,                             -- pending/running/done/failed/waiting_approval
  idempotency_key text, input jsonb, output jsonb,
  tool text, cost numeric, error text,
  started_at, finished_at timestamptz)

reel_render(        -- 言語別の完成リール
  id uuid pk, job_id uuid fk->job, language text,
  video_url text, duration_ms int, thumbnail_url text,
  subtitle_track jsonb, voiceover_url text,
  spec jsonb,                              -- {ratio:'9:16',codec:'h264'}
  status text, created_at timestamptz)

approval(           -- 承認ゲートの記録（承認者=エンドユーザー）
  id uuid pk, job_id uuid, reel_render_id uuid,
  reviewer text, reviewer_role text,       -- 'agency_staff'(A) / 'store_owner'(B)
  decision text,                           -- approve/reject/revise
  issue_codes text[],                      -- 選択肢式の指摘: looks/info_wrong/tone_strong…
  comment text,                            -- 自由記述は任意
  target_stage text, created_at timestamptz)

review_request(     -- 確認依頼（A -> B、リンク1つ）
  id uuid pk, job_id uuid, candidate_id uuid,
  sent_to text, link_token text, sent_at timestamptz,
  opened_at timestamptz, viewed_at timestamptz,
  reminder_count int, status text)         -- sent/opened/answered

candidate(           -- 複数案（1案提示にしない）
  id uuid pk, job_id uuid, reel_render_id uuid,
  variant_label text, diff_meta jsonb,     -- 案ごとの差分（フック/尺/構成）
  selected boolean, created_at timestamptz)

translation_pair(   -- 原文↔訳の対応（多言語の確認）
  id uuid pk, reel_render_id uuid, language text,
  source_text text, translated_text text,
  verified boolean, verified_by text, verified_at timestamptz)

post(                -- 公開投稿
  id uuid pk, job_id uuid, reel_render_id uuid,
  ig_account_id text, ig_media_id text, permalink text,
  caption text, scheduled_at, published_at timestamptz, status text)

insight(            -- 投稿実績（日次）
  id uuid pk, post_id uuid fk->post, captured_at timestamptz,
  reach int, plays int, saves int, avg_watch_ms int,
  profile_visits int, overseas_reach_ratio numeric, dm_count int)

knowledge_rule(     -- 学習ルール（勝ち型の根拠）
  id uuid pk, scope text, vertical text, client_id uuid null,
  language text, rule jsonb, evidence_post_ids uuid[],
  confidence numeric, updated_at timestamptz)

operation_log(      -- 監査ログ
  id uuid pk, job_id uuid, actor text, action text,
  tool text, payload jsonb, ts timestamptz)

# R1 shot-list（templateから）: 必要ショットと役割
required_shots = [exterior, dish_closeup, sizzle, pour/plating, reaction]
# R2 clip解析: asset.vision_tags と shot_role をマッチング（不足は警告）
# R3 自動編集(動画API): テンプレJSONにclipを流し込む
timeline = {
  ratio:'9:16', fps:30,
  scenes:[ {role:'sizzle', clip:asset_a, dur:1800, text_overlay:hook},
           {role:'guide',  clip:asset_b, dur:6000, captions:lang},
           {role:'info',   clip:asset_c, dur:3000, text:reserve+map} ],
  music: template.music_style, brand: client.logo }
render(timeline) -> mp4(9:16, h264/aac, 5-90s)
# R4 多言語: 字幕トラック＋TTSを言語ごとに差し替えて再レンダ
for lang in ['ja','en','ko','zh-Hant']:
    subtitles = translate(script, lang)         # Claude(文化適応)
    voiceover = tts(script, lang)               # ElevenLabs(任意)
    reel_render[lang] = render(timeline + subtitles + voiceover)
# R5 人QA -> 承認後に確定・書き出し

# 入力: client, vertical, store_feature, 勝ちtemplate候補
def build_compose_brief(client, vertical):
    tmpl = pick_template(vertical, scope in [client, vertical, global])  # 9割=型
    # 独自1割: 特徴DBから、その店ならではの要素を1-2個レコメンド/抽出
    originals = recommend_originals(          # Claude
        store_feature.unique_elements + store_feature.feature_tags,
        constraint = "テンプレの3幕を壊さず、hook/captionに1割だけ差し込む")
    return {template_id: tmpl.id,
            base_structure: tmpl.structure,   # 90%そのまま
            applied_originals: originals,      # 10%差し込み
            ratio: "9:1"}
# 学習ループ: 投稿実績 -> スコア更新 -> 店舗専用の勝ち型が育つ
on insight_captured(post):
    update template.performance_score (by reach/save/来店反応)
    upsert knowledge_rule(scope='client', client_id, rule=勝ち要因)
    # 次回 pick_template は client scope を優先 = その店専用に賢くなる

# 投稿（Reels）
1) POST /{ig_user_id}/media
     { media_type:'REELS', video_url:, caption, share_to_feed:true }
   -> { id: creation_id }
2) poll GET /{creation_id}?fields=status_code   # 指数バックオフ, FINISHEDまで
3) POST /{ig_user_id}/media_publish { creation_id }  -> { id: media_id }   # 承認後のみ
4) GET /{media_id}/insights?metric=reach,plays,saved,total_interactions,...

# 制約
- 動画: 9:16 / 5-90秒 / H.264+AAC / 公開URL必須
- レート: ~100投稿/24h/アカウント（新規は低め）→ 1日1-3本推奨
- 要件: Business/Creator + FBページ + アプリ審査(instagram_content_publish)
- DM(後): 24h枠 / ~200件/時 / Webhookはレート非消費

POST   /jobs                      # 依頼作成
       req: {client_id, target_languages[], count, template_id?}
       res: {job_id, status:'received'}
POST   /jobs/{id}/assets          # 素材添付（署名付きURLでアップロード）
GET    /jobs/{id}                 # 状態＋stages＋reel_renders
       res: {status, stages:[{stage,status,...}], renders:[{language,video_url}]}
POST   /jobs/{id}/approve         # 承認ゲート（承認者=A または B）
       req: {candidate_id, decision:'approve|revise|reject', issue_codes[], comment?, target_stage?}
POST   /jobs/{id}/review-requests # A -> B へ確認依頼（リンク1つ）
       req: {candidate_id, send_to}
       res: {review_request_id, link_url}
GET    /review/{token}            # B用・未ログインで即再生できる確認画面
       res: {video_url, store_name, is_prepublish:true, issue_options[]}
POST   /review/{token}/answer     # B の2択回答
       req: {decision:'ok|issue', issue_codes[], comment?}
GET    /jobs/{id}/candidates      # 複数案と差分
GET    /jobs/{id}/translations    # 原文↔訳の対応・確認済み状態
POST   /trials                    # 契約前トライアル（登録を挟まない入口）
POST   /jobs/{id}/publish         # 承認済のみ許可。予約可
       req: {reel_render_ids[], scheduled_at?}
GET    /jobs/{id}/insights        # 実績
POST   /webhooks/meta             # コメント/DM受信（後）
POST   /webhooks/render           # 動画レンダ完了通知