mkadri85/relay-marketing-console

# Relay 控制台 一款面向消费服务类移动应用的生产级营销与互动控制台： 批量 WhatsApp 活动、带 AI 辅助的实时操作员收件箱、浏览器内的广告创意工作室、每小时数据同步 pipeline，以及带有基于预测的异常警报的分析层。它作为单个容器化的 Node 服务在 Cloud Run 上运行，由测试门控的 Cloud Build pipeline 进行部署。 ## 功能说明 | 功能 | 简介 | |---|---| | **WhatsApp 活动引擎** | 批量模板/轮播发送，支持并行扇出、每个活动的 media-id 缓存以及 Cloud Tasks 调度器。吞吐量比原始的顺序循环高出约 10 倍。 | | **实时聊天 + AI 辅助** | 基于 WhatsApp Cloud API 的操作员收件箱。多提供商 AI（以 Claude 为主，OpenAI 为备选，基于规则的兜底机制），带有针对单用户的速率限制，并可自动转接给人工。 | | **创意工作室** | 浏览器内的分层广告编辑器。通过提供商网关（Imagen / gpt-image / Flux）进行 AI 图像生成，通过 headless Chromium 进行服务端渲染，使用带签名的 URL 访问私有 GCS 存储桶，并配有针对每个组织的成本防护。 | | **数据同步 pipeline** | 每小时执行 ETL，将 Meta Ads、GA4 和 Firestore 数据提取至 BigQuery，使用基于幂等 load job 的 upsert 操作，并通过 BigQuery ML 异常检测写入警报。 | | **通知** | 事件驱动的 Cloud Functions，响应 Firestore 变更（优惠券/订阅/安全/互动），并带有退订、静默时间、每日上限和去重防护。 | | **Cloud Run 上的 CI/CD** | 推送至 main 分支会运行测试、构建镜像、进行部署，并将流量固定至最新修订版本。 | ## 可视化流程演示 独立的 HTML 图表（在浏览器中打开）： - [`docs/index.html`](docs/index.html) - 导航主页 / 从这里开始 - [`docs/architecture.html`](docs/architecture.html) - 全系统映射图 - [`docs/flow-campaign-send.html`](docs/flow-campaign-send.html) - WhatsApp 发送 pipeline - [`docs/flow-data-sync.html`](docs/flow-data-sync.html) - ETL + 异常检测 - [`docs/flow-chat-ai.html`](docs/flow-chat-ai.html) - 聊天 + AI 兜底 + 人工转接 - [`docs/flow-creative-studio.html`](docs/flow-creative-studio.html) - 生成 / 组合 / 发布 - [`docs/flow-cicd-deploy.html`](docs/flow-cicd-deploy.html) - Cloud Build 至 Cloud Run ## 架构 ``` Cloudflare -> console.relay.example.com | +--v--+ | Cloud Run (Node/Express) | | EJS + Alpine.js UI | +--+--+--+ WhatsApp Cloud API <--+ | | +--+--+--+ | | | | BigQuery MongoDB (Atlas) Cloud Tasks GCS (private) analytics + read replica scheduled creative assets campaign log (campaign audience) campaigns + signed URLs ^ | hourly ETL (Cloud Scheduler) +-- Meta Ads API / GA4 Data API / Firestore Firestore document changes -> Cloud Functions -> FCM / HMS push ``` 控制台使用单个 Cloud Run 服务；通知作为独立的 Cloud Functions 运行。读取活动受众的数据来自 Mongo 只读副本（而不是庞大的数据仓库镜像），从而避免了活动的重复扣费。 ## 技术栈 - **运行时：** Node.js 18、Express、EJS 服务端渲染视图、Alpine.js 群岛 - **数据：** BigQuery（分析与 ML）、MongoDB（受众）、Firestore（移动端事件）、GCS（资产） - **消息传递：** WhatsApp Cloud API（Meta Graph）、Cloud Tasks（调度） - **AI：** Anthropic Claude、OpenAI、Google Imagen / Gemini、Flux（FAL） - **渲染：** Playwright headless Chromium（每次渲染一个子进程） - **基础设施：** Cloud Run、Cloud Build、Secret Manager、Cloud Scheduler、Cloud Functions ## 仓库布局 ``` src/ whatsapp/ campaign-engine, media-cache, scheduler (Cloud Tasks) chat/ multi-provider AI gateway + rate-limit-to-human handoff creative-studio/ provider gateway, render pipeline, GCS, cost guard marketing/ ETL (meta/ga4/firestore), BigQuery ML anomaly detection lib/ GA4 Measurement Protocol functions/ event-driven notification Cloud Functions docs/ HTML flow diagrams cloudbuild.yaml test -> build -> deploy -> pin-traffic pipeline Dockerfile Debian-slim + Playwright Chromium ``` ## 工程亮点 几个值得阅读代码的决定： 1. **Media-id 缓存 (`src/whatsapp/media-cache.js`)** - 向 2,200 名接收者发送 4 张卡片的轮播广告时，会重复上传相同的 4 张图片达 8,800 次。通过针对每个数据源缓存 `media_id` 并结合进行中请求的合并（in-flight coalescing），将上传次数减少到 4 次，并去除了约 95% 的活动运行时间。 2. **并行扇出 (`src/whatsapp/campaign-engine.js`)** - 以并发组的形式发送，组间有可调的暂停时间，在保持低于 Meta 速率限制的同时，将发送速度从约 33 条消息/分钟提升至约 355 条消息/分钟。 3. **预留后结算的成本防护 (`src/creative-studio/lib/quotaGuard.js`)** - 原子化的消费预留解决了并发竞争问题，并附带了一条坦诚的注释，说明了为什么单进程 mutex 在自动扩缩的副本中只能作为软警报，以及真正的上限在哪里。 4. **幂等的 BigQuery upsert (`src/marketing/lib/bq.js`)** - 使用 load job + MERGE 代替流式插入，这样每小时的 ETL 就可以安全地重新运行同一个时间窗口（流式插入的行在约 90 分钟内无法进行 MERGE）。 5. **异常检测 (`src/marketing/etl/anomaly.js`)** - 针对每个指标使用 BigQuery ML ARIMA_PLUS，仅将标记的日期写入警报表。 6. **跨环境签名的 URL (`src/creative-studio/lib/gcs.js`)** - 在 Cloud Run 上进行原生 v4 签名，对于本地用户凭据则使用 IAM `signBlob` 作为兜底。 ## 本地运行 ``` cp .env.example .env # fill in your own keys + project npm install npm test # jest npm run dev # nodemon ``` 该服务需要其专属的 GCP 项目、BigQuery 数据集和提供商密钥。 本仓库中的任何内容均未指向原始的生产后端。 ## 许可证 MIT。请参见 [LICENSE](LICENSE)。

标签：AI图像生成, AI对话, BigQuery, MITM代理, 特征检测, 自定义脚本, 营销自动化