qr-code-scanner-tracking

由 TippyEntertainment 提供

https://github.com/tippyentertainment/skills.git

此技能专为 Tasking.tech Agent 平台（https://tasking.tech）设计，也兼容接受技能式处理程序的助手运行时，例如 .claude、.openai 和 .mistral。此技能可用于 Claude code 和 Tasking.tech Agent 源代码。

qr-code-scanner-tracking

概要

设计、构建和改进基于二维码的追踪系统。此技能可帮助生成二维码、定义扫描后的行为，并追踪扫描事件（扫描者、地点、时间、方式），适用于营销、运营、产品流程或内部工具。

---

适用场景

当用户希望执行以下操作时，请使用此技能：

• 创建指向动态追踪 URL 的二维码。
• 追踪传单、包装、活动、屏幕或内部资产带来的扫描和转化。
• 通过二维码开展活动级或按用户／资产划分的追踪。
• 实现“扫描 → 路由 → 记录”流程（扫描后打开页面、触发分析并记录元数据）。
• 将二维码扫描集成到 Web 或移动应用中（例如内部应用、自助服务终端、现场工具）。

此技能侧重于二维码生成和扫描追踪相关的架构、数据建模和代码脚手架。

---

需收集的信息

助手应询问：

业务背景

• 主要用途
  • 示例：营销活动追踪、活动签到、产品包装、资产追踪、登录／设备配对、店内标识。
• 扫描后应执行的操作
  • 重定向到着陆页、打开应用深层链接、显示动态屏幕、启动流程（例如注册）。
• 追踪目标
  • 需要衡量：扫描总数、独立扫描者数量、位置、注册／购买转化率、各渠道表现等。

技术背景

• 现有技术栈
  • 前端：React、Next.js、Vue、Svelte、SPA、原生应用。
  • 后端：Node、Deno、Python、Cloudflare Workers、AWS Lambda 等。
• 托管／平台
  • Cloudflare（Workers/Pages/D1）、AWS、GCP、本地部署等。
• 预期规模
  • 二维码的大致数量以及预计的每日扫描次数。

数据与隐私

• 每次扫描需采集的数据
  • 至少包括：时间戳、二维码 ID、活动／渠道。
  • 可选：IP／地理位置（匿名化）、设备类型、用户 ID／会话 ID、引荐来源。
• 隐私／合规
  • 关于同意、匿名化和数据保留的要求。

如果缺少关键信息，请在提出解决方案前先询问 2–4 个澄清问题。

---

预期行为

1. 明确需求

• 用几个要点概述使用场景（例如：“追踪会议胸牌上的扫描，并将注册归因到具体展位／二维码”）。
• 明确：
  • 追踪粒度（按活动、媒介、资产、个人）。
  • 对离线使用或印刷的限制。

2. 提出架构方案

将系统拆分为清晰的组件：

二维码生成服务

• 职责：
  • 创建包含唯一令牌／ID的二维码。
  • 将每个令牌关联到：
    • 目标 URL 或应用深层链接。
    • 活动／渠道元数据（例如 utm_source、utm_medium）。
    • 可选的按资产或用户划分的标签。
• 设计：
  • 用于生成和存储二维码定义的后端 API 或 CLI。
  • 可选的管理界面，供非技术用户创建和管理二维码。
• 选项：
  • 支持静态目标 URL 或动态规则（例如 A/B 测试、根据地理位置确定目标）。

扫描处理程序／重定向端点

• 路由模式：
  • 例如：https://app.example.com/q/{token} 或自定义域名 /r/{token}。
• 职责：
  • 从 URL 中解析令牌。
  • 在数据库中查找二维码定义。
  • 记录包含元数据的扫描事件。
  • 重定向到目标 URL（或呈现动态页面）。
• 错误处理：
  • 令牌无效／未知 → 显示友好的错误页面。
  • 二维码已停用／过期 → 显示备用／过期提示。

跟踪与存储

• 数据模型（示例）：

  • qr_codes

    • id
    • token（唯一）
    • campaign_id（可选）
    • destination_url
    • label（易读的名称）
    • metadata_json（可选）
    • is_active（布尔值）
    • created_at
    • expires_at（可选）

  • qr_scan_events

    • id
    • qr_code_id
    • scanned_at
    • ip_hash or ip_truncated（可选，兼顾隐私）
    • user_agent
    • referrer
    • geo_region（可选，平台提供粗略区域信息时使用）
    • user_id or session_id（可选）
    • meta_json（额外上下文：渠道、设备、应用信息）

• 存储选项：

  • 轻量级数据库（Cloudflare D1、DynamoDB、Postgres 等）。
  • 如有需要，可选择导出到分析数据仓库（BigQuery/Redshift/ClickHouse）。

分析与报告

• 查询和指标：
  • 按活动、日期、渠道统计扫描次数。
  • 表现最佳的二维码。
  • 与下游事件（例如注册）关联时的转化指标。
• 仪表板构想：
  • 时间序列图表。
  • 显示活动和扫描次数的表格。
  • 设备/浏览器细分。
  • 显示大致区域的地图（如跟踪地理位置）。

扫描器集成（可选）

• 基于浏览器的扫描器：
  • 在内部工具或自助终端中使用 getUserMedia 和 JavaScript 二维码解码器。
• 原生应用集成：
  • 使用平台扫描器，并将结果直接发送到相同的 /q/{token} 端点或自定义深层链接。
• 决定：
  • 扫描器仅供内部使用，还是通过应用向最终用户开放。

---

3. 生成实现脚手架

该技能应根据用户的技术栈，生成可直接用于实现的脚手架。示例：

扫描处理程序示例（TypeScript / Cloudflare Worker 风格）

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const url = new URL(request.url);
    const segments = url.pathname.split('/').filter(Boolean);
    const token = segments[segments.length - 1]; // /q/{token}

    if (!token) {
      return new Response('Invalid QR code', { status: 400 });
    }

    // Look up QR code
    const qr = await env.DB.prepare(
      'SELECT id, destination_url, campaign_id, is_active FROM qr_codes WHERE token = ?'
    ).bind(token).first();

    if (!qr || !qr.is_active) {
      return new Response('QR code not found or inactive', { status: 404 });
    }

    // Collect metadata
    const ua = request.headers.get('user-agent') ?? '';
    const ip = request.headers.get('cf-connecting-ip') ?? '';
    const now = new Date().toISOString();

    // Persist scan event (with hashed/truncated IP if required)
    await env.DB.prepare(
      'INSERT INTO qr_scan_events (qr_code_id, scanned_at, user_agent, ip_hash) VALUES (?, ?, ?, ?)'
    ).bind(qr.id, now, ua, hashIp(ip)).run();

    // Redirect to destination URL
    return Response.redirect(qr.destination_url, 302);
  },
};