AdHunter（软广猎手）

一个基于 React、TypeScript 和 Vite 的图片找茬小游戏。玩家在场景图中寻找软广植入点；全部找出后进入下一关。

当前能力

• 从腾讯云 CloudBase levels 集合读取关卡。
• 云端不可用时自动切换到本地 content/levels.json。
• 对关卡、坐标、半径和重复 ID 做运行时校验，避免坏数据进入渲染层。
• 支持热点命中、重复查看提示、通关和自动切换下一关。
• 内置标注模式，可新增、选择、移动、调整半径、修改文案、删除热点，并导出完整 JSON。

本地运行

npm ci
npm run dev

生产构建与类型检查：

npm run check

标注模式

按 Ctrl + Shift + D；macOS 使用 Command + Shift + D。

进入后：

1. 点击已有红色热点，编辑面板会选中它。
2. 点击图片空白处创建新热点。
3. 修改名称、吐槽文案、坐标和判定半径。
4. 点击“导出全部 JSON”，下载新的 levels.json。

标注结果只存在于当前浏览器会话，不会直接写入 CloudBase。导出的 JSON 需要人工审核；确认无误后用它覆盖 content/levels.json，如需同步云端再单独导入 CloudBase。

目录结构

AdHunter/
├─ content/
│  └─ levels.json          # 唯一的本地关卡数据
├─ shared/
│  ├─ types.ts             # 共享数据类型
│  ├─ hitTest.ts           # 热点命中算法
│  └─ levelValidation.ts   # 关卡数据校验
├─ src/
│  ├─ main.tsx             # React 启动入口
│  ├─ App.tsx              # 页面状态与模块编排
│  ├─ game/                # 游戏显示和交互
│  ├─ editor/              # 标注工具
│  └─ data/                # CloudBase 与本地数据加载
└─ public/                 # 关卡图片

数据结构

{
  "levelId": 1,
  "title": "关卡标题",
  "imageUrl": "/level1.png",
  "ads": [
    {
      "id": "ad_unique_id",
      "x": 50,
      "y": 50,
      "radius": 5,
      "name": "商品或品牌",
      "sarcasmText": "命中后的提示文案"
    }
  ]
}

x、y 和 radius 均使用相对于图片容器的百分比坐标。

环境变量

复制 .env.example 为 .env.local，可覆盖 CloudBase 环境：

VITE_CLOUDBASE_ENV_ID=your-env-id

CloudBase 环境 ID 不是密钥。真正的数据安全边界仍由数据库权限规则决定。

工程约束

• content/levels.json 是仓库内唯一的本地关卡数据，也是 CloudBase 读取失败时的离线兜底。
• 标注器导出的 levels.json 经人工审核后，可直接覆盖上述文件。
• shared/ 只存放可跨平台复用的纯 TypeScript，不得依赖 React、DOM、CloudBase SDK 或微信 API。
• Pull Request 会自动执行 TypeScript 检查和 Vite 构建。

后续开发顺序见 ROADMAP.md。