addashboard-cli 0.5.1 → 0.6.0

package/skills/ad-ops/scripts/plan_lint.py

@@ -0,0 +1,297 @@
+#!/usr/bin/env python3
+"""入稿計画JSONの回収・要約・lint・合意差分を1コマンドで行う。
+
+`adops.sh plan` から呼ばれる。単体でも動く:
+
+    python3 plan_lint.py [<入稿計画.json>]
+
+引数を省略すると ~/Downloads と 入稿計画/ の中で最も新しい入稿計画を拾う。
+Downloads にあったものは 入稿計画/ へリネームして移動する。
+
+やること:
+  1. 回収 — DLに落ちた計画を 入稿計画/<案件名>_<CP名>_入稿計画_<timestamp>.json へ移動
+  2. 要約 — CP > 広告グループ > 広告 を1画面の表で出す
+  3. lint — dry-run が検出しない不備（相対finalUrl・paramCode衝突など）を拾う
+  4. 差分 — サンプルプラン.json（＝合意した内容の正）と突き合わせ、違う項目だけ出す
+"""
+import glob
+import json
+import os
+import re
+import shutil
+import sys
+import urllib.parse
+
+SKILL_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+PLAN_DIR = os.path.join(SKILL_DIR, "入稿計画")
+DOWNLOADS = os.path.expanduser("~/Downloads")
+
+# 新規モードの既定 12,000円 / 既存ASC の 5〜10万円 を包含するレンジ。
+# 外れたら桁間違いを疑う（エラーではなく確認を促す）。
+BUDGET_MIN, BUDGET_MAX = 3_000, 200_000
+SUSPICIOUS_NAME = re.compile(r"テスト|test|サンプル|sample|dummy|仮", re.I)
+
+errors: list[str] = []
+warns: list[str] = []
+
+
+def err(msg: str) -> None:
+    errors.append(msg)
+
+
+def warn(msg: str) -> None:
+    warns.append(msg)
+
+
+# --------------------------------------------------------------- 1. 回収
+def newest(pattern: str) -> str | None:
+    hits = glob.glob(pattern)
+    return max(hits, key=os.path.getmtime) if hits else None
+
+
+def load_account(platform: str, account_id: str) -> dict:
+    """accountId からアカウントJSONを引く。見つからなければ空dict。
+
+    sample_account.json は雛形として実アカウントと同じ accountId を持つため、
+    実データを優先して最後に回す（先に拾うと案件名が 'sample_account' になる）。
+    """
+    paths = [
+        p for p in glob.glob(os.path.join(SKILL_DIR, "アカウント", platform, "*.json"))
+        if os.path.basename(p) != "index.json"
+    ]
+    paths.sort(key=lambda p: os.path.basename(p) == "sample_account.json")
+    for path in paths:
+        try:
+            data = json.load(open(path, encoding="utf-8"))
+        except Exception:
+            continue
+        if str(data.get("accountId", "")) == str(account_id):
+            return data
+    return {}
+
+
+def collect(path: str, plan: dict) -> str:
+    """Downloads にある計画を 入稿計画/ へリネーム移動する。移動後のパスを返す。"""
+    if os.path.dirname(os.path.abspath(path)) != os.path.abspath(DOWNLOADS):
+        return path
+
+    platform = plan.get("platform", "yda")
+    account = load_account(platform, plan.get("accountId", ""))
+    project = account.get("name") or plan.get("accountId", "plan")
+    campaigns = plan.get("campaigns") or []
+    cp = (campaigns[0].get("name") if campaigns else "") or "no-campaign"
+    stamp = re.search(r"(\d{8}-\d{6})", os.path.basename(path))
+    stamp = stamp.group(1) if stamp else "unknown"
+
+    safe = lambda s: re.sub(r"[/\\:\s]+", "_", str(s)).strip("_")
+    dest = os.path.join(PLAN_DIR, f"{safe(project)}_{safe(cp)}_入稿計画_{stamp}.json")
+    os.makedirs(PLAN_DIR, exist_ok=True)
+    shutil.move(path, dest)
+    print(f"📥 回収: ~/Downloads → 入稿計画/{os.path.basename(dest)}")
+    return dest
+
+
+def pick_plan(argv: list[str]) -> str:
+    if argv:
+        if not os.path.exists(argv[0]):
+            sys.exit(f"✗ ファイルが見つかりません: {argv[0]}")
+        return argv[0]
+    candidates = [
+        p
+        for p in (
+            newest(os.path.join(DOWNLOADS, "*入稿計画*.json")),
+            newest(os.path.join(PLAN_DIR, "*.json")),
+        )
+        if p
+    ]
+    if not candidates:
+        sys.exit("✗ 入稿計画JSONが見つかりません（~/Downloads にも 入稿計画/ にも）")
+    return max(candidates, key=os.path.getmtime)
+
+
+# ------------------------------------------------------- 共通: 値の取り出し
+def param_code_of(ad: dict, group: dict) -> str:
+    """広告グループの paramCode。export形式には無いので finalUrl の ?ad= から復元する。"""
+    if group.get("paramCode"):
+        return str(group["paramCode"])
+    url = ad.get("finalUrl") or ""
+    q = urllib.parse.parse_qs(urllib.parse.urlparse(url).query)
+    return (q.get("ad") or [""])[0]
+
+
+def image_no_of(ad: dict) -> str:
+    """creative パラメータ '<code>-1047c-45L60-<code>' から画像番号を復元する。"""
+    if ad.get("imageNo"):
+        return str(ad["imageNo"])
+    url = ad.get("finalUrl") or ""
+    q = urllib.parse.parse_qs(urllib.parse.urlparse(url).query)
+    m = re.search(r"-(\d+)[a-z]-", (q.get("creative") or [""])[0])
+    return m.group(1) if m else ""
+
+
+def ad_groups(campaign: dict) -> list:
+    return campaign.get("adGroups") or campaign.get("adSets") or []
+
+
+# --------------------------------------------------------------- 2. 要約
+def summarize(plan: dict) -> None:
+    print(f"\n── 入稿計画 ── platform={plan.get('platform', 'yda')} "
+          f"accountId={plan.get('accountId')} planVersion={plan.get('planVersion')}")
+    for ci, c in enumerate(plan.get("campaigns") or []):
+        bid = c.get("biddingStrategy", "")
+        if c.get("targetCpa"):
+            bid += f" (tCPA {c['targetCpa']:,})"
+        print(f"\n  CP[{ci}] {c.get('name')}")
+        print(f"        予算 {c.get('budget', 0):,}/日 | {bid} | status {c.get('status')} "
+              f"| 開始 {c.get('startDate', '-')}")
+        for g in ad_groups(c):
+            tg = "/".join(filter(None, [
+                ",".join(g.get("devices") or g.get("devicePlatforms") or []) or "全デバイス",
+                ",".join(g.get("ages") or []) or "全年齢",
+                ",".join(g.get("genders") or []) or "全性別",
+            ]))
+            print(f"    AG  {g.get('name')} | {tg} | status {g.get('status')}")
+            for a in g.get("ads") or []:
+                media = ",".join(a.get("mediaIds") or []) or a.get("videoId") or a.get("imageHash") or "-"
+                head = (a.get("headlines") or ["（空）"])[0]
+                print(f"      AD  media {media} | 画像No {image_no_of(a) or '-'} | {head}")
+                print(f"          {a.get('finalUrl')}")
+
+
+# --------------------------------------------------------------- 3. lint
+def lint(plan: dict) -> None:
+    platform = plan.get("platform", "yda")
+    account = load_account(platform, plan.get("accountId", ""))
+    base = account.get("baseArticleUrl") or ""
+    base_host = urllib.parse.urlparse(base).netloc if base else ""
+    known_codes = {
+        str(v.get("paramCode"))
+        for v in (account.get("refs", {}).get("adGroups") or {}).values()
+        if v.get("paramCode")
+    }
+
+    if not base:
+        warn(f"アカウントJSONに baseArticleUrl がありません（{platform}/{plan.get('accountId')}）。"
+             " finalUrl が相対パスになる原因になります")
+
+    seen_media: dict[str, str] = {}
+    for c in plan.get("campaigns") or []:
+        name = c.get("name", "")
+        budget = c.get("budget") or 0
+        if not (BUDGET_MIN <= budget <= BUDGET_MAX):
+            warn(f"CP「{name}」の日予算 {budget:,} が想定レンジ外（{BUDGET_MIN:,}〜{BUDGET_MAX:,}）。桁を確認してください")
+        if c.get("status") == "ACTIVE":
+            warn(f"CP「{name}」が ACTIVE です。初回・PoC は PAUSED（配信オフ）を推奨します")
+        if SUSPICIOUS_NAME.search(name):
+            warn(f"CP名「{name}」に検証用らしき語が残っています。本番入稿の命名か確認してください")
+
+        for g in ad_groups(c):
+            gname = g.get("name", "")
+            if SUSPICIOUS_NAME.search(gname):
+                warn(f"広告グループ名「{gname}」に検証用らしき語が残っています")
+            for a in g.get("ads") or []:
+                url = a.get("finalUrl") or ""
+                if not re.match(r"https?://", url):
+                    err(f"CP「{name}」の finalUrl が相対パスです: {url}\n"
+                        f"        → アカウントJSONの baseArticleUrl 未設定。"
+                        f"**dry-run はこれを検出しません**")
+                elif base_host and urllib.parse.urlparse(url).netloc != base_host:
+                    warn(f"CP「{name}」の finalUrl のホストがアカウントの baseArticleUrl "
+                         f"({base_host}) と違います: {urllib.parse.urlparse(url).netloc}")
+
+                media = a.get("mediaIds") or []
+                if not media and not a.get("videoId") and not a.get("imageHash"):
+                    err(f"CP「{name}」の広告にクリエイティブがありません（mediaIds が空）")
+                for m in media:
+                    if m in seen_media:
+                        warn(f"mediaId {m} が複数の広告で使われています"
+                             f"（{seen_media[m]} / {name}）。画像検証なら重複は想定外です")
+                    else:
+                        seen_media[m] = name
+
+                code = param_code_of(a, g)
+                if not code:
+                    err(f"CP「{name}」の paramCode が特定できません")
+                elif code in known_codes:
+                    err(f"paramCode {code} はアカウントの既存広告グループと重複しています"
+                        f"（{name}）。新規なら未使用の番号に変えてください")
+
+
+# --------------------------------------------------------------- 4. 差分
+def flatten(plan: dict, is_sample: bool) -> dict:
+    """サンプルプラン(schemaVersion 3)と入稿計画(planVersion 1)を同じ形に潰して比較可能にする。"""
+    out: dict[str, object] = {"CP数": len(plan.get("campaigns") or [])}
+    for ci, c in enumerate(plan.get("campaigns") or []):
+        p = f"CP[{ci}]"
+        out[f"{p}.name"] = c.get("name")
+        out[f"{p}.budget"] = c.get("budget")
+        out[f"{p}.tCPA"] = c.get("tcpa") if is_sample else c.get("targetCpa")
+        groups = ad_groups(c)
+        out[f"{p}.広告グループ数"] = len(groups)
+        for gi, g in enumerate(groups):
+            gp = f"{p}.AG[{gi}]"
+            out[f"{gp}.name"] = g.get("name")
+            ads = g.get("ads") or []
+            out[f"{gp}.広告数"] = len(ads)
+            for ai, a in enumerate(ads):
+                out[f"{gp}.AD[{ai}].paramCode"] = param_code_of(a, g)
+                out[f"{gp}.AD[{ai}].画像No"] = image_no_of(a)
+    return out
+
+
+def diff_against_sample(plan: dict) -> None:
+    platform = plan.get("platform", "yda")
+    sample_path = os.path.join(
+        SKILL_DIR, "サンプルプラン_meta.json" if platform == "meta" else "サンプルプラン.json"
+    )
+    if not os.path.exists(sample_path):
+        print("\n（サンプルプランが無いため差分比較をスキップしました）")
+        return
+    sample = json.load(open(sample_path, encoding="utf-8"))
+    if str(sample.get("accountId")) != str(plan.get("accountId")):
+        print(f"\n⚠ サンプルプランのaccountId({sample.get('accountId')})と入稿計画"
+              f"({plan.get('accountId')})が違うため差分比較をスキップしました")
+        return
+
+    a, b = flatten(sample, True), flatten(plan, False)
+    rows = [(k, a.get(k, "—"), b.get(k, "—")) for k in dict.fromkeys([*a, *b])
+            if str(a.get(k, "—")) != str(b.get(k, "—"))]
+
+    print("\n── 合意（サンプルプラン）との差分 ──")
+    if not rows:
+        print("  ✓ 差分なし（合意どおり）")
+        return
+    width = max(len(k) for k, _, _ in rows)
+    for k, want, got in rows:
+        print(f"  {k.ljust(width)}  {want} → {got}")
+    print("  ↑ この差分だけをユーザーに確認すること（全項目の読み上げはしない）")
+
+
+# ---------------------------------------------------------------- main
+def main() -> int:
+    path = pick_plan(sys.argv[1:])
+    plan = json.load(open(path, encoding="utf-8"))
+    path = collect(path, plan)
+    print(f"📄 {path}")
+
+    summarize(plan)
+    lint(plan)
+    diff_against_sample(plan)
+
+    print("\n── lint（dry-run が検出しない項目）──")
+    for m in errors:
+        print(f"  ERROR  {m}")
+    for m in warns:
+        print(f"  WARN   {m}")
+    if not errors and not warns:
+        print("  ✓ 問題なし")
+
+    if errors:
+        print(f"\n✗ ERROR {len(errors)}件。修正するまで本実行しないこと")
+        return 1
+    print(f"\n✓ ERROR なし{f'（WARN {len(warns)}件は要確認）' if warns else ''}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/ad-ops//343/202/242/343/202/257/343/203/206/343/202/243/343/203/226/343/203/227/343/203/251/343/203/263.json

@@ -0,0 +1,6 @@
+{
+ "_comment": "ad-ops スキルが書き出す『いま作業中のプラン』の指定。プランナーは起動時にこれを読み、媒体と案件（アカウント）を自動選択してサンプルプランを適用する。",
+ "platform": "meta",
+ "accountName": "act_887120717645667",
+ "samplePlanFile": "サンプルプラン_meta.json"
+}