addashboard-cli 0.3.0 → 0.4.0

package/skills/ad-ops/SKILL.md

@@ -142,9 +142,57 @@ open "https://ads-display.yahoo.co.jp/campaign/detail?accountId=<accountId>&camp
 | キャンペーン一覧            | `npx -y addashboard-cli@latest list --platform <媒体> --resource campaigns --account-id <id>`                   |
 | 汎用入稿 (JSON) dry-run | `npx -y addashboard-cli@latest submit --platform <媒体> --json-file <path>`                                     |
 | 汎用入稿 (JSON) 実入稿     | `npx -y addashboard-cli@latest submit --platform <媒体> --json-file <path> --no-dry-run --yes`                  |
+| 入稿計画 順次入稿 dry-run | `npx -y addashboard-cli@latest submit-plan --plan-file <入稿計画.json>`（現状 yda のみ）                       |
+| 入稿計画 順次入稿 実入稿   | `npx -y addashboard-cli@latest submit-plan --plan-file <入稿計画.json> --no-dry-run --yes`（1CPずつ・再開可能） |
+| チーム週次レビュー取得       | `npx -y addashboard-cli@latest review --team <伊藤T\|松井T> [--week <YYYY-MM-DD>]`                              |
+| 「予実」「予実管理」「今月の予実」「着地予測」「予実サマリ」 | `npx -y addashboard-cli@latest pl summary`（月指定は `pl summary --month YYYY-MM`） |
+| 「案件別の予実」「案件ごとの損益」 | `npx -y addashboard-cli@latest pl projects`（`--month` / `--status` / `--platform` で絞り込み可） |
 
 汎用入稿 (JSON ボディ直渡し) は yda / meta / google / smartnews / bytedance の 5 媒体対応。fixtures の雛形は tarball 同梱の `fixtures/*_poc.json`、各媒体の必須フィールドは `fixtures/README.md`。
 
+**結果の要約**: `pl summary` / `pl projects` が返す JSON はそのまま貼らず、金額(円)・当月/指定月・着地予測を踏まえて人間向けに要約して提示すること（CLI の役割はデータ取得までで、要約はここで行う）。
+
+***
+
+## チーム週次レビュー取得（review コマンド）
+
+チーム × 週で **全案件の週次レビュー（課題・今週のアクションプラン）を 1 回でまとめて取得** し、LLM（このセッション）が案件ごとに要約するためのコマンド。CLI の役割は JSON 取得までで、要約は LLM が行う。
+
+### 自然言語 → コマンド マッピング
+
+以下のような依頼で発火する:
+
+- 「伊藤T（松井T）の先週の課題とアクションプラン（を案件ごとに要約して）」
+- 「チームの週次レビュー（を見せて／まとめて）」
+- 「先週の課題まとめ」「先週のアクションプランまとめ」
+
+→ 実行するコマンド（**先週がデフォルト**）:
+
+```bash
+npx -y addashboard-cli@latest review --team 伊藤T
+```
+
+特定週を指定する場合は、その週の月曜（JST）を `--week` で渡す:
+
+```bash
+npx -y addashboard-cli@latest review --team 松井T --week 2026-07-13
+```
+
+- `--team` は `伊藤T` または `松井T` のいずれか（必須）
+- `--week` 省略時は **先週の月曜（JST）** を自動採用（例: 実行日が 2026-07-23(水) なら 2026-07-13）
+- 出力は JSON（`team` / `weekStart` / `teamProjectCount` / `reviewCount` / `reviews[]`）
+
+### 結果の要約（LLM 側の必須整形）
+
+`review` の JSON は **そのまま貼らない**。案件ごとに次の形で要約する:
+
+- **案件名（clientName / platform があれば併記）**
+  - 課題: `issue` を要約
+  - 今週のアクションプラン: `thisWeekPlan` を要約
+  - 数値実績（`actualCpa` / `actualCtr` / `actualCvr` 等）があれば補足。目標（`goalCpa` 等）と併記できると良い
+
+冒頭または末尾で **`reviewCount`（レビュー記入のあった案件数）/ `teamProjectCount`（チームの総案件数）** に触れ、「N 件中 M 件にレビュー記入あり」といった全体像を示す。`reviews` が空（`reviewCount: 0`）の場合は「該当週の週次レビュー記入はありませんでした」と伝える。
+
 ***
 
 ## YDA入稿プランナー（HTML DOCS / JSON入稿・レスポンシブ画像固定型）
@@ -152,16 +200,37 @@ open "https://ads-display.yahoo.co.jp/campaign/detail?accountId=<accountId>&camp
 動画の API 入稿とは別に、**レスポンシブ(画像)・固定型の一括入稿** を計画・確認するためのシングルHTMLツール。2026-07-16 / 07-21 定例フィードバックを反映。**2026-07-23 に CSV 書き出しを廃止し、保存・入稿受け渡しを JSON に統一**。
 
 - **ファイル**: 本スキル同梱の [`yda-planner.html`](./yda-planner.html)（ローカルで開くだけ・依存なし。実データ同梱: タイトル999 / 画像633 / グループ96）
-- **役割**: 動画=`addashboard-cli submit`（API入稿）、**画像=このプランナーで計画 → 「入稿JSON書き出し」→ 同じ `submit --platform yda` に流す**（Yahoo管理画面CSVインポートは廃止）。
-- **基本思想（定例）**: AIで生成できる部分は **AIに生成させ（JSON読込）**、絶対に人が確定する部分（クリエイティブ選定・確認）を **スプシ的コピペ・一括入力・複製** で楽にする。プランナーで確認・修正して **OK なら 入稿JSON書き出し（=GO）→ `submit` dry-run → 本実行**。
+- **役割**: 動画=`addashboard-cli submit`（API入稿）、**画像まとめ入稿=このプランナーで計画 → 「入稿JSON書き出し」（入稿計画JSON planVersion:1）→ `submit-plan` に流す**（Yahoo管理画面CSVインポートは廃止）。
+- **基本思想（定例）**: AIで生成できる部分は **AIに生成させ（JSON読込）**、絶対に人が確定する部分（クリエイティブ選定・確認）を **スプシ的コピペ・一括入力・複製** で楽にする。プランナーで確認・修正して **OK なら 入稿JSON書き出し（=GO）→ `submit-plan` dry-run一括検証 → 本実行**（1キャンペーンずつ入稿・進捗書き戻しで再開可能）。
 - **ビュー**: `媒体要件`（YDA/Meta タブの仕様・使い方ページ）/ `プラン`（戦略メモ → 案件設定 → シート/ツリー切替。シートは1広告=1行の表＋広告/広告グループ/キャンペーンのネストタブ、ツリーは開閉・複製・量産）/ `参照データ`（タイトル&説明一覧・登録画像一覧の閲覧+新規登録）/ `履歴`（保存バージョン一覧）。同一 state を投影し切替。
 
+### 起点フロー（戦略壁打ち → サンプルプラン.json → 入稿）
+
+ヘッダーの **「❓使い方」ボタン** を押すと、この流れとプロンプト例（戦略壁打ち用・アカウント取込用）をモーダルで表示できる。全体像は「AIで作れる部分はAIに、人が確定するクリエイティブ選定・確認をプランナーで」。
+
+1. **戦略を壁打ちする**: AI（Claude Code）に商材・目的・予算・訴求点を伝え、ターゲティング方針・キャンペーン/広告グループ構成・訴求軸を提案させる。
+2. **OK → `サンプルプラン.json` へ書き出し**: 壁打ちで OK が出たら、その戦略を本スキル同梱の `サンプルプラン.json`（保存先: `.claude/skills/ad-ops/サンプルプラン.json`、フォーマット: `{"schemaVersion":3, "accountId":"<ID>", "campaigns":[ キャンペーン>広告グループ(paramCode)>広告 ]}`）に **上書き** する。
+3. **プランナーに反映**: プランナーを開き直す／リロードすると、起動時に `サンプルプラン.json` が読み込まれ、キャンペーン > 広告グループ > 広告として表示される（accountId が現アカウントと不一致なら読み込まない安全弁あり）。
+4. **確認・編集**: 見て、AI に再指示してもよいし、プランナー内で追加・複製・文言/画像/パラメータ編集（セル選択コピペ可）してもよい。
+5. **保存 → 入稿**: 「バージョン保存」（履歴に v1, v2…）と「✅完成→保存して入稿」（入稿計画JSON書き出し）。保存後に表示されるプロンプトを AI に貼ると入稿（dry-run→本実行）まで進む。
+
+**初回セットアップ**: 初めて使うアカウントは、先に「アカウント取込プロンプト」で登録画像・見出し・既存キャンペーン/広告グループを取り込み、`アカウント/<名前>.json`（refs）を用意する（アカウント名は日本語で可）。
+
+### 入稿手順：未知の画像・キャンペーン/広告グループは先に登録
+
+入稿は「**未知のアセットを先に登録 → アカウントJSONに反映 → 広告を入稿**」の順で行う。`submit-plan` 本実行がこれを自動化する:
+
+1. **未知の画像を登録**: 広告の `imagePaths[]`（ローカル画像）を `/yda/upload-image` で自動アップロードして mediaId を解決。解決結果は計画ファイルに書き戻され、再開時の再アップロードを防ぐ。
+2. **未知のキャンペーン/広告グループを作成**: 計画に既存IDが無い CP/AG は backend が新規作成し、応答から campaignId を回収（進捗に書き戻し）。
+3. **アカウントJSONへ反映**: 解決した mediaId・新規作成した CP/AG のID（`【paramCode】↔ID`）を `アカウント/<名前>.json` の `refs`（media / campaigns / adGroups / groups）へ反映し、次回以降は再利用する（未解決を避ける）。
+4. **広告を入稿**: アセット解決済みの状態で 1 キャンペーンずつ入稿。`submitted` 済みはスキップ（再開・二重入稿防止）。
+
 ### 保存とバージョン履歴（2026-07-23〜）
 
 - **バージョン保存**: 保存のたびに **常に新バージョン**（v1, v2…）。JSON は `schemaVersion:2` で `meta`（バージョンID・作成/更新日時・作成者・対象媒体・名称・メモ）を持つ。旧 v1 JSON も読込時に自動マイグレーション。**履歴本体はブラウザ内（localStorage）に自動保存**されるため、フォルダ設定なしで一覧・再読込・削除が完結する。
-- **保存フォルダ連携（入稿計画/）**: 履歴ビューの「📁 保存フォルダに接続」で本スキル同梱の `入稿計画/` フォルダを**初回に1回だけ**選ぶと、以後は開くだけで自動接続され、保存のたびにファイルにも書き出される（File System Access API / Chrome系のみ。非対応環境・未接続時はダウンロード動作）。
+- **保存フォルダ連携（入稿計画/）**: 履歴ビューの「📁 保存フォルダに接続」で本スキル同梱の `入稿計画/` フォルダ（`.claude/skills/ad-ops/入稿計画/`）を**初回に1回だけ**選ぶと、以後は開くだけで自動接続され、保存のたびにファイルにも書き出される（File System Access API / Chrome系のみ。非対応環境・未接続時はダウンロード動作）。
 - **履歴ビュー**: バージョン・日時・媒体・名称・メモ・作成者の一覧。`読込`（過去バージョン復元）/ `編集`（名称・メモ）/ `削除`。
-- **入稿JSON書き出し**: 設定ダイアログなしの**ワンクリック**。アカウントID・目的(goal)・開始日は案件設定チップ、入札はキャンペーン行（tCPA→`MAXIMIZE_CONVERSIONS`+targetCpa）、ターゲティングは広告グループ行の列（日本語ラベル→API enum 自動変換）から `*_submit-body_*.json` を生成。手入稿バナー・参照未解決の広告は自動除外。accountId 未入力・0件なら書き出し中止（空入稿防止）。
+- **入稿JSON書き出し**: 設定ダイアログなしの**ワンクリック**。アカウントID・目的(goal)・開始日は案件設定チップ、入札はキャンペーン行（tCPA→`MAXIMIZE_CONVERSIONS`+targetCpa）、ターゲティングは広告グループ行の列（日本語ラベル→API enum 自動変換）から `*_入稿計画_*.json`（planVersion:1、広告は IMAGE 形式: mediaIds/headlines/descriptions/principal）を生成。手入稿バナー・参照未解決の広告は自動除外。accountId 未入力・0件なら書き出し中止（空入稿防止）。
 
 ### 量産構造（媒体要件の核）
 
@@ -177,7 +246,7 @@ open "https://ads-display.yahoo.co.jp/campaign/detail?accountId=<accountId>&camp
 
 ### 発火時の案内
 
-「YDA入稿プランナー」「入稿シート」「タイトル/画像一覧」「まとめ入稿の確認用シート」等を求められたら、このHTMLを案内・オープンする（`open <path>`）。入稿JSONは書き出し後 `webgram submit --platform yda --json-file <submit-body>` で **dry-run → 本実行** にかける。
+「YDA入稿プランナー」「入稿シート」「タイトル/画像一覧」「まとめ入稿の確認用シート」等を求められたら、このHTMLを案内・オープンする（`open <path>`）。入稿計画JSONは書き出し後 `webgram submit-plan --plan-file <入稿計画.json>` で **dry-run一括検証 → `--no-dry-run --yes` 本実行** にかける（1CPずつ・進捗書き戻しで途中失敗後も再開可、`submitted` 済みはスキップ）。
 
 ## ログイン情報の取り扱い
 
@@ -204,7 +273,7 @@ open "https://ads-display.yahoo.co.jp/campaign/detail?accountId=<accountId>&camp
 
 ### 入稿プランナー関連ロードマップ（2026-07-16 定例 / 2026-07-23 更新）
 
-- ~~CSVを介さない直接入稿~~ → **完了（2026-07-23）**: プランナーの「入稿JSON書き出し」が submit-body.json を生成し、そのまま `submit --platform yda` に流せる。CSV書き出しは廃止。
+- ~~CSVを介さない直接入稿~~ → **完了（2026-07-23）**: プランナーの「入稿JSON書き出し」が入稿計画JSON（planVersion:1）を生成し、`submit-plan` が dry-run一括検証→1CPずつ入稿（`/yda/upload-image` で新規画像の mediaId 解決・進捗書き戻し・再開可）。backend は `createImageAd`（RESPONSIVE_AD+IMAGE）対応。CSV書き出しは廃止。
 - **キャンペーン/広告グループID の自動取得**: 管理画面からの手コピペ（`【paramCode】`↔ID の突合）を、API/MCP で自動取得して置き換える。新規CPは払出し後にID解決。
 - **新規画像のメディア登録自動化**: ドライブ格納画像を YDA メディアに登録し、プランナーの参照データ（画像番号→mediaID）へ反映。
 - **命名規則の統一**: `【】内の数字`のみ共通で、キャンペーン名/広告名は担当者差がある → システム命名に寄せられるようにする。