運用設計¶
実行時の挙動・運用フローを定義する。
全体システム構成 (Phase 1b)¶
5 レーン (関係者 / テーマリポ / Backlog / AWS / SaaS) の 構造図 (関連性のみ、方向付きフローは下の各セクション参照):
レーン構成¶
| レーン | 内容 |
|---|---|
| 関係者 | メディア運営者 (spin-dd 運営担当) / automedia 開発者 (spin-dd エンジニアリング) |
テーマリポ <key>-hubspot-theme |
コントロールプレーン (Claude Code セッション + .automedia/ + HubSpot テーマ) |
| Backlog | 業務 SoT (TTRTAGSPIN、3 新規 status + カスタムフィールド) |
| automedia AWS 中央サービス | spindd account (ap-northeast-1)。API Gateway / Lambda 群 / EventBridge / Storage / Claude Platform |
| External SaaS | LINE Platform / Backlog SaaS / HubSpot / GitHub |
設計原則・役割境界は コントロールプレーンと責務分担 を参照。
① コンテンツ起票 → 承認 → 配信予約¶
メディア運営者が Backlog 課題を承認し、automedia が EventBridge Schedule に予約するまでの流れ。
| Step | 主アクター | 動作 |
|---|---|---|
| ① 課題起票 | メディア運営者 (spin-dd 運営担当、テーマリポ Claude Code または Backlog UI) | 「コンテンツ運用」issueType で課題を作成、配信メタ (チャネル / 投稿日時 / テンプレ) を記入 |
| ② 内容確認 → 承認の意思 | メディア運営者 | プレビューを確認 (read 系 endpoint で automedia preview <issue> 可) |
③ status を automedia承認 に変更 |
メディア運営者 (チーム内レビュー後) | Backlog UI で status 遷移 = 承認の意思表示。承認者・日時は Backlog の status 変更履歴に組み込みで残る (チーム内 4-eyes 運用にするかは別途定義) |
| ④ Webhook 配信 | Backlog SaaS | IssueUpdated を POST /backlog/webhook に送信 |
| ⑤ webhook-backlog Lambda 受理 | システム | status === 'automedia承認' を検証、それ以外なら 400 (not-approved) |
| ⑥ Schedule 登録 | webhook-backlog Lambda | 即時送信も予約も常に EventBridge Schedule 経由。at(max(投稿日時, now+5s)) で登録 → 5 秒以内に deliver が起動。経路統一で監査ログ・取り消し動線を一貫化 |
不変条件:
- automedia承認 未満の status での write 要求は 400 (not-approved) で拒否
- automedia承認 状態で本文・投稿日時・テンプレ参照が変更されたら、Lambda が自動で status を 1 つ戻す + Schedule 削除 (= invalidate、Invalidate ルール)
詳細は コンテンツワークフロー を参照。
② 配信実行 → 結果書き戻し¶
EventBridge Schedule 到達時点で deliver Lambda が Claude Platform 経由で配信を実行し、結果を Backlog に書き戻すまで。
| Step | 主アクター | 動作 |
|---|---|---|
| ① Schedule 到達 | EventBridge Schedule | at(投稿日時) 秒精度で deliver Lambda を invoke |
| ② Claude 呼び出し | deliver Lambda | Claude Platform on AWS (IAM 統合) を Claude Agent SDK で呼ぶ、tool 実行で各 SaaS API に到達 |
| ③ 配信実行 | deliver Lambda | LINE Messaging API / HubSpot CMS / CRM / Email へ送信 |
| ④a 成功時 | deliver Lambda | Backlog 課題の status を automedia実行済み に更新 + コメント [automedia] dispatched at <iso> + カスタムフィールド「自動配信実行日時」更新 |
| ④b 失敗時 / retry 尽き | deliver Lambda | Backlog 課題の status を automediaエラー に更新 + コメント [automedia] failed: <reason> |
冪等性: DynamoDB deliver-locks テーブルで <tenant>:<issueKey> ロックを取得してから配信実行。同一課題の二重実行を防止。
リトライ規則 (deliver Lambda 内部):
| 失敗種別 | 自動 retry |
|---|---|
| 5xx / Timeout | 指数バックオフ (30s, 2m, 10m, 30m, 1h) 最大 5 回 → リトライ尽き automediaエラー |
| 認証失敗 (401/403) | なし (token 更新が必要) → 即時 automediaエラー |
| 422 (ペイロード不正) | なし → 即時 automediaエラー |
automediaエラー に遷移したら 人手介入が前提 (自動再実行なし)。詳細は コンテンツワークフロー: 失敗時のリトライ規則。
③ read 系問い合わせ (preview / status / audience-query)¶
テーマリポ Claude Code セッションが副作用なしで automedia の情報を取得する経路。Backlog 課題を起票せずに呼び出せる。
| Step | 主アクター | 動作 |
|---|---|---|
| ① read リクエスト | テーマリポ Claude Code (.claude/skills/automedia-*) |
OIDC → テナント単位の read-only IAM Role で短期クレデンシャル取得 → GET/POST |
| ② API Gateway → read API Lambda | システム | 認証通過後、内部処理 (将来追加実装) |
| ③ 必要に応じて参照 | read API Lambda | S3 (templates) / Backlog API (課題情報) / HubSpot CRM API (リード抽出) などを read のみで叩く |
| ④ JSON で応答 | テーマリポ Claude Code | preview 内容 + 承認状態 / audience サイズなどを取得 |
現状の実装状況: read API Lambda は 未実装。Phase 1b の追加スコープとして別 Issue で着手予定 (08-control-plane.md の追加実装スコープ)。
④ LINE follow → welcome reply + HubSpot リード upsert¶
LINE ユーザーが友だち追加 / ブロック解除した瞬間のフロー。webhook-line Lambda が welcome reply を 5 秒以内に返し、並列で HubSpot に upsert する。
| Step | 主アクター | 動作 |
|---|---|---|
| ① 友だち追加 | ユーザー | LINE 公式アカウントをブロック解除 / 新規追加 |
| ② follow event | LINE Platform | POST /line/webhook/{channel_id} |
| ③ welcome.json 取得 | webhook-line Lambda | S3 の <tenant>/templates/line/welcome.json を読む |
| ④ welcome reply (≤5s) | webhook-line Lambda | LINE Reply API でメッセージ送信 |
| ⑤ HubSpot upsert (並列) | webhook-line Lambda | line_user_id で search-first、line_follow_count インクリメント + line_last_followed_at 更新 |
redelivery 対応: LINE は約 62 秒後に同 event を再配信することがあり、deliveryContext.isRedelivery=true を検知して skip する (PR #102)。
詳細は LINE follow フロー (welcome + HubSpot upsert) を参照。
⑤ テナント設定同期 (.automedia/ Push)¶
テーマリポの .automedia/** (project.yml / templates / rules) が GitHub に push されたら、S3 cache にミラーするフロー。
| Step | 主アクター | 動作 |
|---|---|---|
| ① git push | メディア運営者 (テーマリポ Claude Code) | PR レビュー → main へ merge → push |
| ② Push Webhook | GitHub | POST /github/webhook |
| ③ sync Lambda | システム | HMAC 検証 → .automedia/** を s3://spin-dd-automedia-tenants/<tenant>/ にミラー |
二重審査: 設定変更は GitHub PR レビュー に加え、配信時に Backlog 承認 が必要 (= GitHub と Backlog の両方で承認が要る)。
⑥ 日次セーフティネット (Scan Lambda)¶
Backlog Webhook 配信の取りこぼしを救済する最終防衛線。通常運用では検知件数 0 を期待。
| Step | 主アクター | 動作 |
|---|---|---|
| ① rate(1 day) 起動 | EventBridge Scheduler | scan Lambda を 1 日 1 回起動 |
| ② 取りこぼし課題の検索 | scan Lambda | 全テナント Backlog をスキャン: status = automedia承認 + 投稿日時 ≤ now() + 自動配信実行日時 IS NULL |
| ③a 検知 → 救済 | scan Lambda | deliver Lambda を invoke (= 通常経路と同じ実行) |
| ③b 検知 → アラート | scan Lambda | CloudWatch Alarm に通知 → Backlog Webhook 設定の問題として調査対象 |
通常は 0 件。検知が継続するようなら Backlog Webhook の配信失敗 / シークレット期限切れなどを示すシグナル。
⑦ 開発者の force 経路 (トラブル対応)¶
automedia 開発者が本番 write エンドポイント (Backlog 承認必須) を バイパス する経路。緊急時の最後の手段として位置付け。
| Step | 主アクター | 動作 |
|---|---|---|
| ① 認証 | automedia 開発者 | AWS SSO (spindd profile) でログイン |
| ② CLI 起動 | automedia 開発者 | aws lambda invoke で対象 Lambda を直接呼ぶ |
| ③ Lambda invoke | システム | 本番経路と同じコードだが、payload を自由指定可能 |
| ④ 履歴記録 | システム | CloudTrail に全 invoke 履歴が残る (監査は維持) |
原則: - 本番 write エンドポイント (webhook-backlog 経由) は 厳格に承認必須、例外なし - 開発者の force 経路はそれと 完全に別経路。本番フローを汚さないため分離 - CloudTrail で全 invoke が記録されるため監査は維持される - 通常運用では使わない (Issue #104 確定事項)
各論ページ¶
- コンテンツワークフロー — Backlog 課題のライフサイクル詳細 + 3 status の仕様 + リトライ規則
- トリガー・スケジューラ — EventBridge Schedule の詳細
- ターゲティング・タグ付け — オーディエンス管理
- 効果測定・フィードバック — 配信後の集計・分析
- メディア運営者ハンドブック — 利用開始 / 日次運用 / コンテンツ運用 / チャネル追加 / テナント切替 / FAQ を運営者視点で一気通読