AIインスタ担当 v2 — 設計書

Version 2.0（完成系） | 2026-04-17 | AI経営共創パートナーズ

プロジェクト名

AIインスタ担当 v2

対象業界

飲食店

ステータス

完成・デプロイ済み

プラン

Standard / Premium

このドキュメントの位置づけ

Phase 2として定義されていた機能（F-01 予約投稿 / F-02 投稿履歴 / F-03 店舗設定）に加え、投稿メソッドモード・投稿承認フローの2つの新機能を盛り込んだ v2 完成版の設計書。本ドキュメントが最新の正。

📝 2026-04-17 実コード確認による修正

本設計書の改善提案（12章）作成後、v2の実リポジトリ（~/projects/insta-auto-v2/）を確認した結果、以下の提案はv2で既に実装済みだった。設計書記述を現実に合わせて修正した。

提案1（post_approvals分離） → approval_requests テーブルとして既に独立実装（token / expires_at / status カラム付き）
提案3（承認者固定化） → stores.approver_name カラムが既に存在
提案2（tokenエントロピー） → generateSecureToken() で256bit (32byte) crypto.getRandomValues を使用。128bit以上要件は既にクリア

v3で追加実装する必要があるのは 提案4（プロンプトバージョニング）/ 提案5（二重実行防止）/ 提案6（運用監視） の3件のみ。詳細は 05_v3実装計画書.html。

1. デプロイ情報

対象	URL / 情報
フロントエンド	https://insta-auto-v2.pages.dev/
バックエンド API	`https://insta-auto-v2-api.yuya-takagi0520.workers.dev/api`
デモアカウント	storeId: `demo_store` / password: `demo`（プラン: premium）
デモ店舗名	デモ焼肉店

2. 技術スタック

要素	技術	備考
フロントエンド	React + Vite + TailwindCSS	SPA、Cloudflare Pages
バックエンド	Cloudflare Workers + Hono	エッジ実行
DB	Cloudflare D1 (SQLite)	v1から継承
画像一時保管	Cloudflare KV	TTL: 即時投稿=短期／予約投稿=scheduledAt+1h
AI	Claude API (Sonnet 4)	画像分析 + キャプション生成 + メソッド適用
Instagram投稿	Instagram Graph API v21.0	単一 + カルーセル
認証	JWT (HS256) + PBKDF2	24時間有効
トークン暗号化	AES-GCM (Web Crypto API)	IGトークン保護
Cron Triggers	`/5 * * `（予約投稿実行）／ `0 2 * *`（IGトークン更新）

3. 画面構成

3.1 画面一覧

投稿作成（3ステップ）

画像選択 → 編集 → 完了。ステップインジケータ付き。

予約投稿一覧

タブ: 予約済み / 承認待ち / すべて。キャンセル可能。

店舗設定

プラン表示・メソッドモード ON/OFF・承認フロー ON/OFF。

承認画面

/approve/{token}。承認 or 却下（コメント必須）。

3.2 共通ヘッダー

ロゴ（IA）＋店舗名／右側に 「予約一覧」「設定」「ログアウト」 の3ボタン。

3.3 投稿作成フロー

① 画像選択
最大10枚 / JPEG・PNG・WebP・GIF

→

② 編集
AI生成結果の確認・修正・再生成

→

③ 完了
即時投稿 or 予約投稿 or 承認依頼

ステップ	主要UI要素
① 画像選択	ドラッグ&ドロップエリア（「タップまたはドラッグで画像を選択」）／「新しい投稿を作成」ボタン
② 編集	キャプション・ハッシュタグ表示／「再生成」「コピー」「クリア」ボタン／「適用されるルール」サマリ表示（メソッドモードON時）
③ 完了	「即時投稿」「今すぐ投稿」／「予約投稿」→日付・時間選択／承認フローON時は「承認URL発行」

3.4 予約投稿一覧

タブ: 予約済み / 承認待ち / すべて
カード表示（キャプション抜粋・店舗名・予約日時・ステータスバッジ）
「キャンセル」ボタンで予約削除
空状態文言: 「投稿はまだありません」「承認待ちの投稿はありません」

3.5 店舗設定

セクション	項目	説明
店舗	店舗名 / プラン表示	読み取り専用（現在はSQL直投入）
投稿メソッド	メソッドモードトグル	「飲食店向けInstagram投稿ノウハウを適用」
投稿承認フロー	投稿前に承認を必要にするトグル	「ONにすると、投稿前に上長の承認が必要になります」
保存	「設定を保存」ボタン	PUT /api/store/settings

4. 投稿メソッドモード v2 新規

トグルONで、飲食店向けInstagram投稿ノウハウをAI生成に自動適用する。UIに「適用されるルール」として以下が表示される。

4.1 適用ルール

軸	ルール
キャプション構造	冒頭1行目で興味を引くタイトル
訴求方針	コト訴求（体験・シーン描写）
ハッシュタグ戦略	3軸選定（ジャンル・ニーズ・テイスト）
CTA	自社メンション + CTA誘導文
禁止事項	地域単体タグ・店舗名タグの禁止

実装上の位置づけ

v1で想定していた「SNSメソッド（上位プランのみ）」を、トグル切替式の可視化された機能として実装したもの。Claude APIへのプロンプトに動的に付加される。

5. 投稿承認フロー v2 新規

投稿前に上長の承認を必須化する機能。設定でONにすると、投稿時に承認用URLが発行される。

5.1 フロー

スタッフが投稿作成

→

承認URL発行
/approve/{token}

→

承認者へ共有
手動コピー／将来LINE連携

→

承認 or 却下

→

承認時のみIG投稿

5.2 承認画面（`/approve/{token}`）

投稿内容（画像・キャプション・ハッシュタグ）のプレビュー
入力欄: 承認者名（例: 店長田中）
入力欄: コメント（却下時は必須）
既処理の場合: 「この承認リクエストは既に処理されています。」

5.3 将来拡張

LINE通知（準備中）

現状は承認URLを手動共有。UI文言に「承認リクエストをLINEで通知する機能は現在開発中です。リリース後、ここでLINEアカウントを連携できるようになります。」と明記されている。

6. API 仕様

ベースURL: https://insta-auto-v2-api.yuya-takagi0520.workers.dev/api

6.1 認証系

Method	Path	認証	説明
POST	`/auth/login`	不要	JWT発行（24h有効） / レートリミット 5回/15分

6.2 投稿系

Method	Path	認証	説明
POST	`/upload`	JWT	画像1〜10枚アップロード（MIME+マジックバイト検証）
POST	`/generate`	JWT	Claude APIでキャプション＋ハッシュタグ生成（メソッドモード反映）
POST	`/publish`	JWT	Instagram Graph API で投稿（即時 or 予約登録）

6.3 店舗設定系

Method	Path	認証	説明
GET	`/store/settings`	JWT	店舗名・プラン・メソッドモード・承認フロー設定を取得
PUT	`/store/settings`	JWT	設定更新

6.4 承認系 v2 新規

Method	Path	認証	説明
GET	`/approval/{token}`	token	承認対象の投稿内容を取得
POST	`/approval/{token}`	token	承認 / 却下を記録。Body: `{ action, approverName, comment }`

承認URLは https://insta-auto-v2.pages.dev/approve/{token} 形式。token は推測困難なランダム文字列。

7. DBスキーマ（v1からの差分）

v1の stores / posts テーブルを拡張。

7.1 `stores` 追加カラム

カラム	型	説明
`method_mode_enabled`	BOOLEAN	メソッドモード ON/OFF
`approval_required`	BOOLEAN	投稿承認フロー ON/OFF

7.2 `posts` 追加カラム / ステータス

カラム	値	説明
`status`	`draft` / `pending_approval` / `scheduled` / `published` / `rejected` / `failed`	`pending_approval` と `rejected` を v2 で追加
`approval_token`	TEXT	承認URL用トークン（推測困難）
`approver_name`	TEXT	承認者名
`approval_comment`	TEXT	承認 / 却下コメント
`approved_at`	TEXT	承認日時

8. v1 → v2 差分サマリ

機能	v1 ステータス	v2 ステータス	備考
F-01 予約投稿	未着手	実装済み	日時指定・キャンセル対応
F-02 投稿履歴画面	未着手	実装済み	予約済み / 承認待ち / すべての3タブ
F-03 店舗設定 GUI	未着手	一部実装	メソッドモード・承認フローのみ。ブランドボイス等の詳細設定はまだSQL直投入
F-04 フィードバック学習	未着手	未着手	データ蓄積後に実装予定
F-05 助っ人API連携	未着手	未着手	カプセル社API提供待ち
F-06 IGトークン自動更新	未着手	実装済み	Cron毎日2:00で60日延長
投稿メソッドモード	—	v2新規	飲食店向けノウハウ自動適用
投稿承認フロー	—	v2新規	承認URL発行・却下コメント・LINE連携は準備中

9. 未完成・今後の課題

項目	ステータス	内容
店舗設定GUIの拡充	一部実装	ブランドボイス / ハッシュタグ固定タグ / キャプション文字数 / 禁止表現などのGUI化
LINE通知連携	準備中	承認URLの自動通知
F-04 フィードバック学習	未着手	engagement_rate上位20%を分析しプロンプト自動改善
F-05 助っ人API連携	未着手	カプセル社API仕様確定待ち

10. 運用情報

10.1 デモ用アクセス

URL:      https://insta-auto-v2.pages.dev/
storeId:  demo_store
password: demo
プラン:    premium（メソッドモード・承認フロー 両方利用可）

10.2 Cron スケジュール

Cron式	頻度	機能
`/5 * * *`	5分ごと	予約投稿の実行チェック（F-01）
`0 2 * * *`	毎日 AM 2:00	IGトークン自動更新（F-06）
`0 3 * * 1`	毎週月曜 AM 3:00	フィードバック学習バッチ（F-04・未実装）

11. 子安氏への依頼事項

⚠ まず依頼したいこと：本設計自体の妥当性レビュー

開発着手の前に、本設計書に書かれている内容そのものの見直しが必要か精査してほしい。現状はユーザー側（高木悠哉）が手を動かしながら作り上げた設計であり、本職エンジニア視点でのレビューを受けていない。以下の観点で所見をいただきたい。

11.1 レビュー観点とCC所見

この表の見方

各観点について、設計したAI（Claude Code）側で「現状OKと考える理由」を添える。子安氏にはこの判断根拠を踏まえた上で、見落としや別視点がないかを見てほしい。信号: 🟢 OK / 🟡 懸念あり / 🔴 要変更提案あり（13章に改善提案を別途記載）

観点	見てほしいこと	CC所見（OKと考える理由 / 懸念）
アーキテクチャ	CF Workers + D1 + KV構成のスケール耐性／SQLite(D1)選定の妥当性	🟢 OK。10〜30店舗想定ならD1（SQLite）で十分。エッジ実行で低レイテンシ・月$55〜106という低コストはこの規模の最適解。100店舗超に達した時点でPostgres移行を検討すれば良く、現時点の前倒し投資は不要。
DBスキーマ	`stores`/`posts`拡張方針・`approval_token`の持たせ方・正規化	🟡 概ねOKだが1点懸念。`posts`に`approval_token`を直接持つ現設計は、将来「承認の再発行」「多段承認」を入れる時に破綻する。現規模ならYAGNIで許容だが、想定する拡張があるなら `post_approvals` に分離が無難（→12章提案1）。
API設計	RESTパス粒度（`/approval/{token}` vs `/posts/{id}/approval`）／冪等性	🟢 OK。承認者はpostIdを知らずtokenのみ持つため、`/approval/{token}` を独立リソース化する現設計が実装上自然。冪等性は「既処理エラー」で担保されている（UI文言「この承認リクエストは既に処理されています」）。
セキュリティ	JWT運用・AES-GCM暗号化・承認tokenエントロピー／レート制限	🟡 ベースはOK、設計書に未記載の明文化が必要。JWT HS256+PBKDF2+AES-GCMは業界標準。ただし承認tokenのエントロピー（128bit以上）と有効期限（例: 7日）が本書に書かれていないので明記する必要あり（→12章提案2）。
投稿承認フロー	URL手動共有のまま拡張するか／LINE前提に組み直すか／多段承認	🟡 段階移行の方針はOK、承認者固定化が未設計。現状は投稿ごとに承認者が可変だが、実運用では「店長が常に承認者」の想定のはず。`stores.approver_name / approver_line_id` で固定化する方が運用UXが良い（→12章提案3）。多段承認は現段階でYAGNI。
投稿メソッドモード	プロンプト動的生成のアプローチ／評価・改善ループの持たせ方	🟡 OKだがバージョン管理が欲しい。5軸ルールの明文化＋プロンプト動的生成は柔軟性が高い。ただし改善ループを回すには `posts.method_version` カラムでどのプロンプト版で生成されたかを記録すべき（→12章提案4）。A/Bテストもこれで可能になる。
Cron設計	5分間隔チェックの耐性／失敗時リトライ／冪等性	🟡 原則OK、二重実行防止の明記が必要。CF Cron Triggersは安定、5分ズレは投稿UXとして許容範囲。ただし5分ごとの処理で重複実行を防ぐため `posts.processing_started_at` をロックとして使う設計を明示すべき（→12章提案5）。
運用・監視	障害検知・ログ・アラート／IGトークン失効検知の多層化	🔴 現設計書では不足。監視設計が本書にない。Cloudflare Logpush + Sentry + Slack Webhookでのアラート方針、およびIGトークン失効48h前の事前通知が最低限必要（→12章提案6）。
コード品質	リポジトリ `~/projects/insta-auto/` の技術的負債・テスト・CI/CD	⚪ CC側からは未評価。本書は設計レベルの整理に留まっており、実装品質は子安氏に直接確認いただきたい。テストカバレッジ目標・CI/CDパイプライン・型安全性の状況を所見としてほしい。

11.2 期待するアウトプット

Go/No-Go判断: 現設計のまま拡張して良いか／大きく見直すべきか
修正提案リスト: 見直すべき箇所と代替案（重要度付き）
修正後の残タスク工数再見積もり: 下記「13. 残タスク」の工数が変わるかの所見

進め方イメージ

Step 1: 本設計書＋リポジトリを読んだ上で 1〜2時間でクイックレビュー（重大な設計ミスがないかだけ確認）
Step 2: 問題なさそうなら「13. 残タスク」に着手／問題があれば再設計の方針だけ合意してから実装

12. CCからの改善提案

このセクションの位置づけ

11.1の🟡🔴マークに紐づく、Claude Code側から見た具体的な改善提案。子安氏レビューで「採用／不要／別案」を判断してほしい。採用された提案は本文設計（6・7章）に反映する。

提案1: 承認情報を `post_approvals` テーブルに分離

現状	`posts.approval_token / approver_name / approval_comment / approved_at` を生で保持
提案	別テーブル `post_approvals` に切り出し、1:N構造にする
メリット	承認URL再発行・却下→再承認のやり直し・多段承認への拡張が破綻しない／履歴が追える
デメリット	テーブル1つ増える・JOINが必要／現規模ではオーバーエンジニアリングの可能性
CC推奨	🟡 採用推奨。コスト小・将来柔軟性大。

CREATE TABLE post_approvals (
  id              TEXT PRIMARY KEY,
  post_id         TEXT NOT NULL REFERENCES posts(id),
  token           TEXT UNIQUE NOT NULL,      -- 128bit以上のランダム
  token_expires_at TEXT NOT NULL,            -- 発行から7日
  status          TEXT NOT NULL,             -- pending / approved / rejected / expired
  approver_name   TEXT,
  comment         TEXT,
  processed_at    TEXT,
  created_at      TEXT NOT NULL
);

提案2: 承認tokenのエントロピー・有効期限を明記

現状	設計書に仕様記載なし
提案	エントロピー 128bit以上（`crypto.randomUUID()` または32byteランダム+base64url）／有効期限 7日／期限切れは `expired` ステータスで識別
CC推奨	🟢 必須。セキュリティ監査観点でも明文化しておくべき。

提案3: 承認者の固定化

現状	投稿ごとに承認者名を都度入力（都度可変）
提案	`stores` に `approver_name / approver_email / approver_line_id` を持たせ、既定承認者を固定化。必要に応じて個別投稿で上書き可。
メリット	LINE通知機能（提案6・未実装）と直結／承認者ミスマッチの防止／運用オペレーションの簡略化
CC推奨	🟢 採用推奨。LINE連携着手と同時に入れるのが自然。

提案4: プロンプトバージョニング

現状	投稿メソッドモードのプロンプトに版管理なし
提案	`posts.method_version`（例: `"method-v1"`, `"method-v2"`）を保存。プロンプト本体は `prompts.json` 等でバージョン別に管理。
メリット	F-04 フィードバック学習の精度計測に必須／A/Bテスト可能／プロンプト改善のロールバック可能
CC推奨	🟢 採用推奨。F-04着手前に必ず入れる。

提案5: 予約投稿の二重実行防止

現状	5分ごとCronで予約投稿を実行する仕様はあるが、二重実行防止の明記なし
提案	`posts.processing_started_at` をロックカラムとして使用。Cron開始時に `WHERE status='scheduled' AND processing_started_at IS NULL` で取得→即座にタイムスタンプをセット→投稿成功で `status='published'` に更新／失敗で `processing_started_at=NULL` に戻してリトライ。最大3回まで。
CC推奨	🟢 必須。分散環境でなくても、Cron重なり・手動再実行時の二重投稿事故を防ぐ基本装備。

提案6: 運用監視の最低ライン整備

現状	監視・アラート設計が本書に未記載
提案	Cloudflare Logpush → R2 or 外部SIEMへ／Workers実行ログ保全 Sentry 導入（Frontend + Workers両方） Slack Webhook アラート: 投稿失敗・Cron失敗・ログイン失敗スパイクの3種 IGトークン失効の事前通知: F-06の自動更新が失敗した場合に48h前に通知
工数追加	8〜12h（初期セットアップ）
CC推奨	🔴 最優先。商用提供する以上、監視なしは事故時の対応不能。子安氏に依頼する最初のブロックに含めるべき。

12.7 採否まとめと影響

#	提案	CC推奨	工数影響	着手タイミング
1	post_approvals テーブル分離	🟡 推奨	+4〜6h	店舗設定GUI拡充と同時
2	承認tokenの仕様明記	🟢 必須	±0h（既実装なら文書化のみ）	即時
3	承認者の固定化	🟢 推奨	+4〜6h	LINE連携と同時
4	プロンプトバージョニング	🟢 推奨	+2〜4h	F-04着手前
5	予約投稿の二重実行防止	🟢 必須	+2〜4h	即時
6	運用監視の整備	🔴 最優先	+8〜12h	最初のブロックに含める
追加合計（全採用時）			+20〜32h

13. 残タスク（上記レビュー後に着手）

#	タスク	規模	想定工数	備考
1	店舗設定GUI拡充（ブランドボイス／固定ハッシュタグ／キャプション文字数・CTA／禁止表現）	中	16〜24h	4タブ追加＋バリデーション＋API拡張
2	LINE通知連携（承認URL自動通知）	小	8〜12h	LINE Messaging API・Webhook・トークン保存
3	F-04 フィードバック学習	大	24〜40h	IG Insights取得＋engagement分析＋prompt_patch生成＋Cron
4	F-05 助っ人API連携	中	16〜24h	カプセル社API仕様確定後
合計			64〜100h（約8〜12人日）

優先着手順の提案: ①店舗設定GUI拡充 → ②LINE通知連携 → ③F-04 → ④F-05。まず小さく始めるなら①+②の 24〜36h が最初の依頼ブロック。

14. 関連ドキュメント

リポジトリ: ~/projects/insta-auto/