企业官网建设流程全解析

• 后端
• API网关
• MCP 服务
• dsh-plugin

本文以 docs/context/architecture/ads-conversions.md 为骨架，结合 src/treg/adsconv.py 等源码实现，系统讲解 treg 如何围绕 Google 点击 ID（gclid/gbraid/wbraid）搭建一条"捕获 → 存储 → 触发 → 上传"的转化跟踪链路。读完你将掌握：第一方脚本如何以零第三方请求捕获广告点击、转化事件如何以耐久 Outbox 的方式落库并幂等去重、平台级凭据与客户 OAuth 连接如何分离、后台 Worker 如何以 6 小时延迟与指数退避把转化批量送达 Google Ads，以及该设计在原子性、货币换算与测试隔离上的取舍。

功能总览：这是一条可整体关闭的附加链路

treg 的 Google Ads 转化跟踪是一条**完全附加（additive）**的功能链路，其开关由adsconv.enabled()决定（adsconv.py）：只有当google_ads_customer_id和ads_conv_refresh_token两个配置同时存在时功能才开启。这样设计的目的，是让测试套件和自托管实例不会启动一台根本无法上传的机器——未配置时，/adtrack.js返回一个空的no-cache响应，归因 Cookie 被忽略，整个链路（捕获、排队、上传）都不会发生。

一个容易误解的细节：google_ads_developer_token不参与这个开关。Data Manager 接口根本不接受 developer-token 请求头，该配置只服务于读取侧的 Ads 目录调用（oauth_providers.GOOGLE_ADS），是另一套独立的凭据（详见下文"认证"一节）。对应地，routers/web.py 中的/adtrack.js与/gtag.js两个路由在未启用时都返回空内容，且永远带Cache-Control: no-cache——前者是为了让修复能立即生效（页面以裸<script src="/adtrack.js">引用、无版本号查询参数），后者是为了让自托管部署完全不发起任何外部 Google 请求。

与通用流量归因的边界

本文只讲Google 点击 ID 路径（treg_adCookie →Org.ad_*字段 → 转化上传）。通用的流量来源归因（赞助链接、新闻邮件、目录站的utm_*与 referrer）走的是另一条独立的treg_utm→Org.utm_*路径，实现在 web/sitetrack.js，记录在>TREG_TEST_DB_URL="sqlite+aiosqlite:///./some-other.db" uv run --frozen python -m pytest -q

得益于该架构，tests/test_adsconv.py 拥有完整覆盖：固定汇率与纯整数换算、动作 ID 覆盖、开关门槛（任一必需配置缺失即禁用）、(org_id, action)唯一性与幂等、无 gclid/禁用时的无操作、两种注册门对 cookie/braid 的持久化、首次调用只触发一次、payload 的货币换算与时间格式（naive UTC 必须戳成 RFC 3339，绝不能用.astimezone()读成本地时间——在悉尼部署目标上会把每次转化偏移 10–11 小时）、点击 ID 字段保留（braid 绝不误标为 GCLID）、批处理与去重的 destinations、经理账号按 destination 设置、整批发送、只死信被点名的行、HTTP 失败超过行尝试上限仍持续重试、死信、无requestId的 200 不确认、field warning 不影响确认、认证头不带 developer-token/login-customer-id、平台 refresh token 与 Ads 客户端赎回、令牌缓存、过期重换，以及两个全路由扫描测试。

未构建项（Not built）

文档明确列出了三件有意不做的事，保持诚实边界：

1. 无路由/自动故障转移——这里不适用（只有一个目的地：Google Ads），但为了与目录其余部分保持一致而声明：treg 不建模自动选择；
2. paid原子性缺口的对账扫描（上文）——已命名为廉价修复，未实现；
3. 真实点击的在线验证——需要真实的广告点击，无法自动化，将在本文档落定之后、任何真实花费之前运行。

• 后端
• API网关
• MCP 服务
• dsh-plugin