Add synthetic end-to-end example

SKILL.md

@@ -43,6 +43,10 @@ The helper recomputes ratios from aggregate numerators and denominators:
 
 Return `null`/`N/A` when a denominator is zero. Never average row-level ratios.
 
+## Example
+
+For a synthetic end-to-end example, read [examples/README.md](examples/README.md). It includes a sample `creative_breakdown` response, deterministic product aggregation, and a rendered Script Daily Report in HTML and PNG. Use it to understand the workflow and artifact shape only; never reuse its example scripts or metrics in a live report.
+
 ## Interpretation
 
 - Treat TikTok orders and GMV as platform-attribution evidence, not causal incrementality.

examples/README.md

@@ -0,0 +1,27 @@
+# Synthetic Script Daily Report example
+
+This example shows the complete artifact shape without using a real account, credentials, customer names, or live campaign data.
+
+## Files
+
+- `query.json` — synthetic `creative_breakdown` response. It deliberately includes one product-card row so the helper's video-only exclusion is observable.
+- `report-data.json` — deterministic output from the aggregation helper with `--top 2`.
+- `script-daily-report.html` — self-contained example report with exactly three cross-product scripts.
+- `script-daily-report.png` — rendered primary deliverable.
+
+## Reproduce the aggregation
+
+From the repository root:
+
+```bash
+python3 scripts/aggregate_video_products.py examples/query.json --top 2 > /tmp/swads-example-output.json
+diff -u examples/report-data.json /tmp/swads-example-output.json
+```
+
+An empty diff confirms that product-card delivery was excluded and the aggregate ratios were recomputed from numerators and denominators.
+
+## Expected interpretation
+
+- The demo pot has the stronger CTR and ROAS at useful but still limited scale; preserve its visible specification proof and test controlled variants.
+- The demo jug has positive attributed revenue, but the capacity/leak proof version has clicks without orders; strengthen proof and product-page alignment.
+- The three example scripts are derived from these synthetic patterns. Live reports must derive new scripts from the requested reporting window and must not copy these scripts by default.

examples/query.json

@@ -0,0 +1,27 @@
+{
+  "columns": [
+    {"name": "external_creative_id", "type": "string", "role": "dimension"},
+    {"name": "external_creative_name", "type": "string", "role": "dimension"},
+    {"name": "creative_identity_kind", "type": "string", "role": "dimension"},
+    {"name": "creative_creator_name", "type": "string", "role": "dimension"},
+    {"name": "creative_product_id", "type": "string", "role": "dimension"},
+    {"name": "spend", "type": "number", "role": "metric"},
+    {"name": "gross_revenue", "type": "number", "role": "metric"},
+    {"name": "orders", "type": "number", "role": "metric"},
+    {"name": "product_impressions", "type": "number", "role": "metric"},
+    {"name": "product_clicks", "type": "number", "role": "metric"}
+  ],
+  "rows": [
+    ["video-pot-proof", "304 material + 24cm visible proof", "item", "Demo Shop", "demo-pot-001", 20, 50, 2, 1000, 50],
+    ["video-pot-usecase", "One pot for soup, noodles, and hotpot", "item", "Demo Shop", "demo-pot-001", 10, 0, 0, 500, 20],
+    ["video-jug-family", "1.5L jug + four cups for the family", "item", "Demo Shop", "demo-jug-002", 12, 24, 1, 800, 24],
+    ["video-jug-proof", "Capacity and leak test", "item", "Demo Shop", "demo-jug-002", 8, 0, 0, 400, 16],
+    ["product_card:demo-pot-001", "", "product_card", "", "demo-pot-001", 100, 240, 8, 9000, 300]
+  ],
+  "row_count": 5,
+  "query_meta": {
+    "date_from": "2026-08-13",
+    "date_to": "2026-08-21",
+    "synthetic": true
+  }
+}

examples/report-data.json

@@ -0,0 +1,74 @@
+{
+  "products": [
+    {
+      "product_id": "demo-pot-001",
+      "video_count": 2,
+      "spend": 30.0,
+      "gross_revenue": 50.0,
+      "orders": 2.0,
+      "product_impressions": 1500.0,
+      "product_clicks": 70.0,
+      "video_ctr": 0.04666666666666667,
+      "order_conversion_rate": 0.02857142857142857,
+      "roas": 1.6666666666666667,
+      "cost_per_order": 15.0,
+      "top_videos": [
+        {
+          "external_creative_id": "video-pot-proof",
+          "external_creative_name": "304 material + 24cm visible proof",
+          "creative_creator_name": "Demo Shop",
+          "spend": 20,
+          "gross_revenue": 50,
+          "orders": 2,
+          "product_impressions": 1000,
+          "product_clicks": 50
+        },
+        {
+          "external_creative_id": "video-pot-usecase",
+          "external_creative_name": "One pot for soup, noodles, and hotpot",
+          "creative_creator_name": "Demo Shop",
+          "spend": 10,
+          "gross_revenue": 0,
+          "orders": 0,
+          "product_impressions": 500,
+          "product_clicks": 20
+        }
+      ]
+    },
+    {
+      "product_id": "demo-jug-002",
+      "video_count": 2,
+      "spend": 20.0,
+      "gross_revenue": 24.0,
+      "orders": 1.0,
+      "product_impressions": 1200.0,
+      "product_clicks": 40.0,
+      "video_ctr": 0.03333333333333333,
+      "order_conversion_rate": 0.025,
+      "roas": 1.2,
+      "cost_per_order": 20.0,
+      "top_videos": [
+        {
+          "external_creative_id": "video-jug-family",
+          "external_creative_name": "1.5L jug + four cups for the family",
+          "creative_creator_name": "Demo Shop",
+          "spend": 12,
+          "gross_revenue": 24,
+          "orders": 1,
+          "product_impressions": 800,
+          "product_clicks": 24
+        },
+        {
+          "external_creative_id": "video-jug-proof",
+          "external_creative_name": "Capacity and leak test",
+          "creative_creator_name": "Demo Shop",
+          "spend": 8,
+          "gross_revenue": 0,
+          "orders": 0,
+          "product_impressions": 400,
+          "product_clicks": 16
+        }
+      ]
+    }
+  ]
+}

examples/script-daily-report.html

@@ -0,0 +1,28 @@
+<!doctype html>
+<html lang="zh-CN">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>SW Ads 脚本日报 · 合成示例</title>
+<style>
+:root{--ink:#153b33;--green:#0f5a48;--mint:#24b47e;--pale:#eef8f4;--line:#c9ddd6;--muted:#65756f;--warn:#fff1dd}
+*{box-sizing:border-box}body{margin:0;background:#edf3f1;color:var(--ink);font-family:Inter,"Noto Sans SC","Microsoft YaHei",Arial,sans-serif}.page{width:1120px;margin:28px auto;background:white;padding:38px 42px 44px;border-radius:22px;box-shadow:0 12px 36px #153b3317}.top{display:flex;justify-content:space-between;gap:24px}.brand{font-size:12px;font-weight:800;color:var(--green);letter-spacing:.08em}.tag{font-size:11px;padding:7px 10px;border-radius:99px;background:var(--warn)}h1{font-size:31px;margin:8px 0 4px}h2{font-size:19px;margin:26px 0 10px}.sub{font-size:12px;color:var(--muted)}.kpis{display:grid;grid-template-columns:repeat(5,1fr);gap:9px;margin:18px 0}.kpi{padding:13px;border:1px solid var(--line);border-radius:12px;background:linear-gradient(180deg,#fff,var(--pale))}.kpi span{display:block;font-size:10px;color:var(--muted)}.kpi b{display:block;font-size:21px;margin-top:3px}.note{padding:11px 13px;border-left:4px solid var(--mint);border-radius:8px;background:var(--pale);font-size:12px;line-height:1.5}table{width:100%;border-collapse:separate;border-spacing:0;border:1px solid var(--line);border-radius:12px;overflow:hidden;font-size:11px}th{padding:8px 9px;background:var(--green);color:white;text-align:left}td{padding:8px 9px;border-top:1px solid var(--line);vertical-align:top}tr:nth-child(even) td{background:#f8fbfa}.num{text-align:right;white-space:nowrap}.scripts{display:grid;gap:10px}.script{padding:14px;border:1px solid var(--line);border-radius:14px}.script h3{margin:0 0 7px;font-size:15px}.why{padding:8px 10px;border-radius:8px;background:var(--pale);font-size:10.5px;line-height:1.45}.beats{display:grid;grid-template-columns:repeat(4,1fr);gap:7px;margin-top:8px}.beat{padding:8px;border:1px solid var(--line);border-radius:8px;font-size:10px;line-height:1.45}.footer{display:flex;justify-content:space-between;margin-top:22px;padding-top:12px;border-top:1px solid var(--line);font-size:9px;color:var(--muted)}
+</style>
+</head>
+<body><main class="page">
+<div class="top"><div><div class="brand">SW ADS · SYNTHETIC EXAMPLE</div><h1>脚本日报</h1><div class="sub">2026.08.13–08.21 · 两个演示商品 · 所有数据均为合成示例</div></div><div class="tag">只读工作流 · 非真实账户数据</div></div>
+<div class="kpis"><div class="kpi"><span>视频消耗</span><b>50.00</b></div><div class="kpi"><span>商品曝光</span><b>2,700</b></div><div class="kpi"><span>商品点击</span><b>110</b></div><div class="kpi"><span>综合CTR</span><b>4.07%</b></div><div class="kpi"><span>归因订单 / ROAS</span><b>3 / 1.48×</b></div></div>
+<div class="note"><b>示例结论：</b>锅具的规格证明同时带来较高点击与订单；水壶的生活场景带来订单，但容量/防漏证明仍需加强。本示例不代表任何真实账户结果。</div>
+<h2>商品视频对比</h2>
+<table><thead><tr><th>商品</th><th class="num">视频</th><th class="num">曝光 / 点击</th><th class="num">CTR</th><th class="num">订单 / CVR</th><th class="num">消耗 / ROAS</th><th>诊断与建议</th></tr></thead><tbody>
+<tr><td><b>304不锈钢24cm汤锅</b><br><span class="sub">demo-pot-001</span></td><td class="num">2</td><td class="num">1,500 / 70</td><td class="num"><b>4.67%</b></td><td class="num">2 / 2.86%</td><td class="num">30 / 1.67×</td><td>“304材质＋24cm”可见证明最强；保留承诺，只改变开头与证明顺序。</td></tr>
+<tr><td><b>1.5L水壶＋4杯套装</b><br><span class="sub">demo-jug-002</span></td><td class="num">2</td><td class="num">1,200 / 40</td><td class="num">3.33%</td><td class="num">1 / 2.50%</td><td class="num">20 / 1.20×</td><td>家庭场景有订单；容量与防漏版本有点击无订单，需加强可见证明和商品页承接。</td></tr>
+</tbody></table>
+<h2>本周三套通用脚本</h2><div class="scripts">
+<section class="script"><h3>脚本1｜规格限时证明</h3><div class="why"><b>依据：</b>锅具规格证明视频贡献2单、CTR 5.00%。<br><b>假设：</b>把[核心规格]放在首屏，并立即完成[可见证明]，可提高合格点击。</div><div class="beats"><div class="beat"><b>0–3s</b><br>“[时间]内验证[核心规格]。”</div><div class="beat"><b>3–8s</b><br>近景展示刻度、材质或尺寸。</div><div class="beat"><b>8–14s</b><br>完成容量/受热/防漏测试。</div><div class="beat"><b>14–18s</b><br>展示[结果]，CTA“先看规格”。</div></div></section>
+<section class="script"><h3>脚本2｜生活场景＋整套价值</h3><div class="why"><b>依据：</b>水壶家庭场景视频贡献1单、ROAS 2.00×。<br><b>假设：</b>先展示多人真实使用，再解释件数和容量，可增强整套价值感。</div><div class="beats"><div class="beat"><b>0–3s</b><br>先给出聚会/家庭使用结果。</div><div class="beat"><b>3–8s</b><br>字幕：[容量]＋[件数]。</div><div class="beat"><b>8–14s</b><br>多人或多菜式连续使用。</div><div class="beat"><b>14–18s</b><br>CTA“看看是否适合你家”。</div></div></section>
+<section class="script"><h3>脚本3｜购买疑虑逐项验证</h3><div class="why"><b>依据：</b>水壶证明版本有16次点击但0单，说明兴趣之后仍缺成交证据。<br><b>假设：</b>依次回应[核心疑虑]、价格与清洁/耐用问题，可改善点击后转化。</div><div class="beats"><div class="beat"><b>0–3s</b><br>评论回复：“真的[核心疑虑]吗？”</div><div class="beat"><b>3–9s</b><br>无剪切完成一次真实测试。</div><div class="beat"><b>9–14s</b><br>展示清洁、容量或耐用细节。</div><div class="beat"><b>14–19s</b><br>给出规格/价格，低压力CTA。</div></div></section>
+</div>
+<h2>字段替换</h2><table><thead><tr><th>商品</th><th>[核心规格/痛点]</th><th>[可见证明]</th><th>[结果]</th></tr></thead><tbody><tr><td>汤锅</td><td>304材质、24cm、多用途</td><td>受热、容量、清洗</td><td>一锅完成日常烹饪</td></tr><tr><td>水壶套装</td><td>1.5L、4杯、家庭使用</td><td>刻度、倒水、防漏</td><td>多人饮水更完整</td></tr></tbody></table>
+<div class="footer"><span>示例数据：合成，不对应任何客户或账户。</span><span>Requires human confirmation：预算、投放状态、发布与商品锚点均未执行。</span></div>
+</main></body></html>