Add purchase integrity health checks

Author: owensky-dev

.github/workflows/ci.yml

@@ -0,0 +1,36 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+
+      - name: Set up Python
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: dtc-growth-data-report/scripts/template/requirements.txt
+
+      - name: Install dependencies
+        run: python -m pip install -r dtc-growth-data-report/scripts/template/requirements.txt
+
+      - name: Run regression tests
+        run: python -m unittest discover -s tests -p 'test_*.py'

README.en.md

@@ -16,6 +16,7 @@ This skill helps Codex set up and customize a local data pipeline for ecommerce
 - Weekly comparison report generator with current week vs previous week.
 - Operator-ready weekly report modules: business conclusions, revenue bridge, funnel health, Google Ads budget actions, page actions, SEO intent clusters, anomaly alerts, next-week owners, and data health checks.
 - Weekly funnel comparisons use dated GA4 add-to-cart and checkout events instead of a 90-day proxy total.
+- Purchase-integrity health compares aligned Shopify orders/revenue with GA4 purchases/revenue, escalates count gaps to transaction-level BigQuery reconciliation, and never auto-sends recovery events.
 - Boss-facing HTML dashboard generator.
 - Configuration and data contract references.
 

README.md

@@ -20,6 +20,7 @@
 - 数据统一转换：输出标准 processed CSV。
 - 周报模板：自动生成“本周 vs 上周”的老板版 HTML 和 Markdown 周报。
 - 操盘手增强周报：包含经营判断、收入归因、漏斗健康、广告预算动作、页面优化动作、SEO 意图分组、异常提醒、下周行动清单和数据健康检查。
+- Purchase 完整性告警：对比同一周 Shopify 订单/收入与 GA4 purchase/收入；出现单量差异时置顶提示并要求 BigQuery `transaction_id` 逐单核验，本技能不会自动补发事件。
 - 周报漏斗按本周与上周分别统计加购和开始结账，不再用 90 天事件总量代替周度数据。
 - 独立站增长诊断看板：输出老板可读的本地 HTML dashboard。
 - 配置参考、数据字段说明和报告工作流说明。

README.zh-CN.md

@@ -20,6 +20,7 @@
 - 数据统一转换：输出标准 processed CSV。
 - 周报模板：自动生成“本周 vs 上周”的老板版 HTML 和 Markdown 周报。
 - 操盘手增强周报：包含经营判断、收入归因、漏斗健康、广告预算动作、页面优化动作、SEO 意图分组、异常提醒、下周行动清单和数据健康检查。
+- Purchase 完整性告警：对比同一周 Shopify 订单/收入与 GA4 purchase/收入；出现单量差异时置顶提示并要求 BigQuery `transaction_id` 逐单核验，本技能不会自动补发事件。
 - 周报漏斗按本周与上周分别统计加购和开始结账，不再用 90 天事件总量代替周度数据。
 - 独立站增长诊断看板：输出老板可读的本地 HTML dashboard。
 - 配置参考、数据字段说明和报告工作流说明。

dtc-growth-data-report/SKILL.md

@@ -72,6 +72,9 @@ When customizing reports:
 
 - Use Shopify as the default source of truth for revenue and orders.
 - Use GA4 for sessions, engagement, landing page behavior, and funnel events.
+- Compare aligned-period Shopify orders/revenue with GA4 `ecommercePurchases`/`totalRevenue` as a purchase-integrity health signal. Persist the count gap, revenue gap, and tracking rate in weekly JSON and show the result in data health.
+- Treat an aggregate gap as an alert, not proof of a specific missing order. Require BigQuery `transaction_id` versus Shopify paid-order reconciliation before naming affected orders or handing recovery to `$ga4-data-analysis`.
+- Keep this reporting skill read-only. Never send Measurement Protocol events or repair tracking automatically.
 - Fetch GA4 `add_to_cart` and `begin_checkout` with the `date` dimension so weekly funnel stages use the same current and previous periods as the rest of the report.
 - Use Google Ads for spend, clicks, conversions, conversion value, ROAS, CPA, search terms, and ad landing URLs.
 - Use campaign-level daily Google Ads facts for totals and weekly campaign decisions so Performance Max is included; keep ad-group data only for compatible campaign detail.
@@ -96,6 +99,7 @@ Before final handoff:
 - Confirm HTML/Markdown reports exist and are non-empty.
 - Confirm conversion rates and CTR are percentages, not decimals.
 - Confirm GA4 funnel rows compare dated `add_to_cart` and `begin_checkout` values for the current and previous aligned weeks.
+- Confirm the report compares Shopify orders with GA4 `ecommercePurchases`, leads with the risk when counts differ, and explicitly requires transaction-level reconciliation before recovery.
 - Confirm Google Ads cost is in account currency units, not micros.
 - Confirm campaign-level Google Ads coverage includes Performance Max and that account totals are not derived only from `ad_group` rows.
 - Confirm sitewide ROI equals Shopify revenue divided by Google Ads spend, and GSC clicks appear in the core KPI table.

dtc-growth-data-report/references/data-contract.md

@@ -57,6 +57,8 @@ The transform step should produce:
 - SEO impressions, clicks, CTR, average position: GSC.
 - Store conversion rate: Shopify orders divided by GA4 sessions.
 - Sitewide ROI: Shopify revenue divided by total Google Ads cost for the same aligned period.
+- Purchase tracking rate: GA4 `ecommercePurchases` divided by Shopify orders for the same aligned period. When both are zero, report 100% coverage rather than a divide-by-zero error.
+- Purchase count gap: Shopify orders minus GA4 `ecommercePurchases`. Purchase revenue gap: Shopify revenue minus GA4 `totalRevenue`. These aggregate fields are health signals only; exact missing orders require Shopify paid-order IDs versus BigQuery `transaction_id` reconciliation.
 - Add-to-cart rate: GA4 `add_to_cart` events divided by GA4 sessions for the same report period.
 - Cart-to-checkout rate: GA4 `begin_checkout` events divided by GA4 `add_to_cart` events for the same report period.
 - ROAS: Google Ads conversion value divided by Google Ads cost.

dtc-growth-data-report/references/report-workflows.md

@@ -26,6 +26,7 @@ Required sections:
 - Top KPI cards: Shopify revenue, orders, store conversion rate, sitewide ROI (`Shopify revenue / Google Ads spend`), and Google Ads ROAS.
 - Revenue bridge: split revenue movement into traffic, conversion rate, and AOV effects.
 - Funnel health: show GA4 Sessions, dated `add_to_cart`, dated `begin_checkout`, Shopify purchases, and ad click-to-conversion efficiency. Compare GA4 funnel events for the current and previous aligned weeks; do not substitute a 90-day event total when dated data is available.
+- Data health: compare Shopify orders/revenue with GA4 `ecommercePurchases`/`totalRevenue` for the same aligned week. Put a count gap in the Executive Summary and P0 actions, but do not identify or repair orders until BigQuery `transaction_id` reconciliation confirms them. Hand authorized recovery to `$ga4-data-analysis`; this report remains read-only.
 - Daily Google Ads spend and weekly spend total
 - Core KPI table: current week, previous week, and change, including GSC clicks alongside impressions and CTR.
 - Channel traffic changes

dtc-growth-data-report/scripts/template/generate_weekly_comparison_template.py

@@ -185,6 +185,8 @@ def summarize_period(
     gsc_week = period_filter(gsc, "parsed_date", start, end)
 
     sessions = metric_sum(ga4_week, "sessions")
+    ga4_purchases = metric_sum(ga4_week, "ecommercePurchases")
+    ga4_purchase_revenue = metric_sum(ga4_week, "totalRevenue")
     orders = metric_sum(shopify_week, "orders")
     revenue = metric_sum(shopify_week, "total_sales")
     ad_spend = metric_sum(ads_week, "cost")
@@ -197,6 +199,11 @@ def summarize_period(
     return {
         "revenue": revenue,
         "orders": orders,
+        "ga4_purchases": ga4_purchases,
+        "ga4_purchase_revenue": ga4_purchase_revenue,
+        "purchase_count_gap": orders - ga4_purchases,
+        "purchase_revenue_gap": revenue - ga4_purchase_revenue,
+        "purchase_tracking_rate": safe_divide(ga4_purchases, orders) if orders else (1.0 if ga4_purchases == 0 else 0.0),
         "sessions": sessions,
         "conversion_rate": safe_divide(orders, sessions),
         "aov": safe_divide(revenue, orders),
@@ -635,7 +642,19 @@ def anomaly_rows(current: dict[str, float], previous: dict[str, float]) -> list[
 
 def data_health_rows(current: dict[str, float], coverage: dict[str, Any], funnel: list[dict[str, str]]) -> list[dict[str, str]]:
     ads_vs_shopify_gap = current["ad_value"] - current["revenue"]
+    purchase_count_gap = current.get("purchase_count_gap", 0.0)
+    ga4_purchases = current.get("ga4_purchases", 0.0)
+    ga4_purchase_revenue = current.get("ga4_purchase_revenue", 0.0)
     has_dated_funnel = any(row.get("metric") == "GA4 开始结账" for row in funnel)
+    if purchase_count_gap > 0:
+        purchase_status = "高风险"
+        purchase_gap_text = f"GA4 比 Shopify 少 {number(purchase_count_gap)} 单"
+    elif purchase_count_gap < 0:
+        purchase_status = "异常"
+        purchase_gap_text = f"GA4 比 Shopify 多 {number(abs(purchase_count_gap))} 单"
+    else:
+        purchase_status = "通过"
+        purchase_gap_text = "订单数一致"
     rows = [
         {
             "check": "四源周期",
@@ -647,6 +666,15 @@ def data_health_rows(current: dict[str, float], coverage: dict[str, Any], funnel
             "status": "通过" if current["orders"] >= 0 else "异常",
             "detail": f"本周 Shopify 订单 {number(current['orders'])}，收入 {money(current['revenue'])}。",
         },
+        {
+            "check": "Shopify vs GA4 purchase",
+            "status": purchase_status,
+            "detail": (
+                f"Shopify {number(current['orders'])} 单 / {money(current['revenue'])}；"
+                f"GA4 purchase {number(ga4_purchases)} 单 / {money(ga4_purchase_revenue)}；"
+                f"{purchase_gap_text}。聚合差异只用于告警，需用 BigQuery transaction_id 对账后确认。"
+            ),
+        },
         {
             "check": "GA4 周度漏斗",
             "status": "通过" if has_dated_funnel else "待修复",
@@ -669,6 +697,14 @@ def next_action_rows(data: dict[str, Any]) -> list[dict[str, str]]:
     top_page = pages[0] if pages else None
     top_seo = seo[0] if seo else None
     rows = []
+    if data.get("current", {}).get("purchase_count_gap", 0) > 0:
+        rows.append({
+            "priority": "P0",
+            "task": "核对 Shopify paid order 与 GA4 BigQuery transaction_id",
+            "owner": "数据/追踪",
+            "target": "确认 GA4 purchase 漏记数量和收入影响",
+            "done": "完成逐单核验；不在本报告流程自动补发，需交给受控 GA4 recovery 流程。",
+        })
     if top_budget:
         rows.append({"priority": "P0", "task": f"{top_budget['action']}：{top_budget['campaign']} / {top_budget['ad_group']}", "owner": "投放", "target": "降低无效花费，观察 CPA/ROAS", "done": "预算动作完成并在 3 天后复盘。"})
     if top_page:
@@ -797,12 +833,18 @@ def build_summary(data: dict[str, Any]) -> list[str]:
     roas_delta = delta_value(current["roas"], previous["roas"])["display"]
     seo_ctr_delta = pp_delta(current["seo_ctr"], previous["seo_ctr"])
     top_action = data["next_actions"][0]["task"] if data.get("next_actions") else "先处理最大经营杠杆。"
-    return [
+    summary = [
         f"本周 Shopify 收入 {money(current['revenue'])}，订单 {number(current['orders'])}，较上周收入变化 {revenue_delta}；转化率 {pct(current['conversion_rate'])}，较上周 {cvr_delta}。",
         f"Google Ads 本周花费 {money(current['ad_spend'])}，ROAS {current['roas']:.2f}，较上周 {roas_delta}；广告转化价值 {money(current['ad_value'])}。",
         f"GSC 本周曝光 {number(current['seo_impressions'])}、点击 {number(current['seo_clicks'])}，CTR {pct(current['seo_ctr'])}，较上周 {seo_ctr_delta}。",
         f"下周第一动作：{top_action}",
     ]
+    if current.get("purchase_count_gap", 0) != 0:
+        summary.insert(
+            0,
+            f"数据风险：Shopify {number(current['orders'])} 单，GA4 purchase {number(current['ga4_purchases'])} 单；先按 BigQuery transaction_id 逐单核验，再做渠道或预算判断。",
+        )
+    return summary
 
 
 def build_markdown(data: dict[str, Any]) -> str:

tests/test_purchase_integrity.py

@@ -0,0 +1,94 @@
+from __future__ import annotations
+
+import sys
+import unittest
+from datetime import date
+from pathlib import Path
+
+import pandas as pd
+
+
+TEMPLATE_DIR = Path(__file__).resolve().parents[1] / "dtc-growth-data-report" / "scripts" / "template"
+sys.path.insert(0, str(TEMPLATE_DIR))
+
+import generate_weekly_comparison_template as weekly  # noqa: E402
+
+
+class PurchaseIntegrityTests(unittest.TestCase):
+    def source_frames(self, *, shopify_orders: int, ga4_purchases: int):
+        report_date = pd.Timestamp("2026-08-16")
+        ga4 = pd.DataFrame(
+            [
+                {
+                    "parsed_date": report_date,
+                    "sessions": 100,
+                    "ecommercePurchases": ga4_purchases,
+                    "totalRevenue": ga4_purchases * 100,
+                }
+            ]
+        )
+        shopify = pd.DataFrame(
+            [
+                {
+                    "parsed_date": report_date,
+                    "orders": shopify_orders,
+                    "total_sales": shopify_orders * 100,
+                }
+            ]
+        )
+        ads = pd.DataFrame([{"parsed_date": report_date}])
+        gsc = pd.DataFrame([{"parsed_date": report_date}])
+        return ga4, shopify, ads, gsc
+
+    def test_period_summary_persists_shopify_vs_ga4_purchase_gap(self) -> None:
+        summary = weekly.summarize_period(
+            *self.source_frames(shopify_orders=3, ga4_purchases=2),
+            date(2026, 8, 16),
+            date(2026, 8, 16),
+        )
+
+        self.assertEqual(summary["ga4_purchases"], 2)
+        self.assertEqual(summary["purchase_count_gap"], 1)
+        self.assertEqual(summary["purchase_tracking_rate"], 2 / 3)
+        self.assertEqual(summary["purchase_revenue_gap"], 100)
+
+    def test_data_health_flags_missing_ga4_purchases_without_auto_recovery(self) -> None:
+        summary = weekly.summarize_period(
+            *self.source_frames(shopify_orders=3, ga4_purchases=2),
+            date(2026, 8, 16),
+            date(2026, 8, 16),
+        )
+        health = weekly.data_health_rows(
+            summary,
+            {"sources": {"GSC": {"last_date": "2026-08-16"}}},
+            [{"metric": "GA4 开始结账"}],
+        )
+        integrity = next(row for row in health if row["check"] == "Shopify vs GA4 purchase")
+
+        self.assertEqual(integrity["status"], "高风险")
+        self.assertIn("少 1 单", integrity["detail"])
+        self.assertIn("BigQuery transaction_id", integrity["detail"])
+
+        actions = weekly.next_action_rows({"current": summary, "funnel": []})
+        self.assertEqual(actions[0]["priority"], "P0")
+        self.assertIn("核对 Shopify paid order", actions[0]["task"])
+        self.assertIn("不在本报告流程自动补发", actions[0]["done"])
+
+    def test_matching_zero_order_week_is_healthy(self) -> None:
+        summary = weekly.summarize_period(
+            *self.source_frames(shopify_orders=0, ga4_purchases=0),
+            date(2026, 8, 16),
+            date(2026, 8, 16),
+        )
+        health = weekly.data_health_rows(
+            summary,
+            {"sources": {"GSC": {"last_date": "2026-08-16"}}},
+            [{"metric": "GA4 开始结账"}],
+        )
+        integrity = next(row for row in health if row["check"] == "Shopify vs GA4 purchase")
+        self.assertEqual(summary["purchase_tracking_rate"], 1.0)
+        self.assertEqual(integrity["status"], "通过")
+
+
+if __name__ == "__main__":
+    unittest.main()