@rk911/tracker-register

埋点注册 CLI 工具 — 自动扫描 Vue 文件、生成 track-id、注入埋点属性、批量注册到后端。

面向 uni-app Vue 项目的埋点自动化工具，提供交互式 Web 面板和命令行两种模式，支持扫描 .vue 文件中的交互元素，智能生成 data-track-* 属性并注入源码，最终批量注册到后端 dd_action_config 表。

安装

npm install @rk911/tracker-register -g

或作为项目开发依赖：

npm install @rk911/tracker-register -D

快速开始

模式一：交互式 Web 面板（推荐）

# 设置认证 token
export TRACKER_TOKEN=<admin-token>

# 启动本地服务
tracker-register --serve --project store-manager --env test

浏览器打开 http://localhost:5178 即可使用可视化面板进行埋点审查、注入和注册。

模式二：命令行模式

# 仅注入（修改 .vue 文件，不注册到后端）
tracker-register --apply confirmed.json --inject-only

# 仅注册（不修改文件）
tracker-register --apply confirmed.json --register-only

# 完整流程（注入 + 注册）
tracker-register --apply confirmed.json --env prod --yes

命令参数

| 参数 | 默认值 | 说明 | | ------------------ | ---------------- | ------------------------------------ | | --serve | — | 启动交互式 Web 面板 | | --apply <file> | — | 应用 confirmed.json 文件 | | --project <name> | store-manager | 项目名称（对应 project-config.json） | | --dir <path> | 配置的 scanDir | 扫描目录 | | --file <path> | — | 扫描单个文件 | | --env <env> | test | 环境（test / prod） | | --port <n> | 5178 | 服务端口 | | --inject-only | false | 仅注入，跳过注册 | | --register-only | false | 仅注册，跳过注入 | | --yes | false | 确认注册（实际调用 API 必需） | | --verbose | false | 详细输出 |

Web 面板功能

• 按模块/目录组织的文件浏览器
• 状态过滤：未埋点 / 已埋点 / 已注册
• 类型过滤：简单 / 复杂 / 清晰
• 每个元素的代码上下文、track-id、注入预览
• 动态参数配置面板（v-for 元素）
• 批量注入/注册，差异预览
• 三种主题（绿色、蓝色、暗色）
• 路由确认 UI（多来源组件）

API 接口（面板模式）

| 路由 | 方法 | 说明 | | -------------------- | ---- | ------------------------------- | | / | GET | 交互式面板页面 | | /api/scan | GET | 实时扫描分析项目 | | /api/inject | POST | 注入 data-track-* 到 .vue 文件 | | /api/register | POST | 批量注册埋点到后端 | | /api/feedback | POST | 保存用户反馈 | | /api/route-confirm | POST | 持久化路由确认 | | /api/field-config | POST | 持久化字段配置 |

项目配置

支持在目标项目根目录创建配置文件（推荐 tracker.config.js），工具启动时会自动加载本地配置，无需修改 npm 包源码或重新发包。

加载优先级

1. 目标项目根目录 tracker.config.js
2. 目标项目根目录 tracker.config.json
3. 目标项目根目录 package.json 中的 "trackerConfig"
4. npm 包内置默认配置

配置文件示例 (tracker.config.js)

// 在目标项目根目录下创建 tracker.config.js
module.exports = {
  // 1. 支持单 AppID 或多 AppID (双端/多端同步注册)
  appId: [12, 13], // 或单个 1，或对象 { default: 12, ios: 13 }

  // 2. 扫描目录：设为 'auto' 或不填时，会自动解析 pages.json 读取主包及所有分包目录
  scanDir: "auto", // 也可手动指定数组: ["pages", "pagesA", "live"]

  // 3. 环境域名配置
  api: {
    test: "https://teststate.renruikeji.cn",
    prod: "https://state.renruikeji.cn",
  },

  registerPath: "/api/point/task/batchRegister",
  configListPath: "/api/point/task/getConfigList",
  registeredStateSource: "backend",
  excludeDirs: [
    "components",
    "node_modules",
    "static",
    "uview-ui",
    "uni_modules",
  ],
  excludeFilePatterns: ["副本", "备份", "-old"],
};

JSON 方式 (tracker.config.json)

{
  "appId": [12, 13],
  "scanDir": "auto",
  "api": {
    "test": "https://teststate.renruikeji.cn",
    "prod": "https://state.renruikeji.cn"
  }
}

认证方式

方式一：Token 文件（推荐）

在目标项目根目录创建 .tracker-register-token.json：

{
  "orgToken": "...",
  "rsbToken": "..."
}

修改后实时生效，无需重启。

方式二：环境变量

| 变量 | 说明 | | ------------------- | ---------------------- | | TRACKER_TOKEN | 默认认证 token | | TRACKER_ORG_TOKEN | 组织 token（高优先级） | | TRACKER_RSB_TOKEN | RSB token |

自定义规则

customize/ 目录支持按项目扩展规则：

// customize/modules/store-manager.js
module.exports = {
  textMapping: { 删除: "delete", 编辑: "edit" },
  handlerKeywords: { goDetail: "view_detail" },
  extraNavHandlers: ["navigateToDetail"],
  extraSkipHandlers: ["onScroll"],
  pageNameOverrides: { "pages/index/index": "home" },
  refineTrackId(defaultId, ctx) {
    return defaultId;
  },
  refineReason(defaultReason, ctx) {
    return defaultReason;
  },
};

| 字段 | 说明 | | ------------------- | ---------------------------------- | | textMapping | 中文文本 → 动作映射 | | handlerKeywords | 事件处理函数名 → 动作映射 | | extraNavHandlers | 额外的导航处理函数（跳过自动埋点） | | extraSkipHandlers | 完全跳过的处理函数 | | pageNameOverrides | 强制指定页面名称 | | refineTrackId | trackId 自定义 hook | | refineReason | reason 自定义 hook |

核心流程

扫描 .vue 文件 → 提取交互元素 → 生成 track-id + reason
    → 人工审核确认 → 注入 data-track-* 属性 → 批量注册到后端

1. Scanner — 解析 <template>，提取带 @click、@tap、@change 等事件的元素
2. Analyzer — 生成语义化 trackId（格式：{pageName}_{action}）和中文描述
3. Injector — 将 data-track-id 等属性写入 .vue 源文件
4. Registerer — 调用后端 batchRegister API，支持重试和降级单条注册
5. Route Resolver — 构建组件导入图，确定运行时真实路由
6. Uniquify — 全局 trackId 去重，冲突时自动加前缀

项目结构

tracker-register/
├── index.js              # 入口：CLI 参数解析、模式分发
├── register-demo.js      # 独立 demo，生成 HTML 报告
├── package.json
├── config/
│   └── project-config.json   # 项目配置
├── core/
│   ├── scanner.js        # Vue template 扫描
│   ├── analyzer.js       # track-id 生成、reason 生成
│   ├── injector.js       # 源码注入
│   ├── param-gen.js      # B 路由解析器代码生成
│   ├── registerer.js     # 后端 API 注册
│   ├── collect.js        # 文件收集 + pages.json 标题 + 编排
│   ├── route-resolver.js # 组件导入图 → 真实路由
│   ├── state.js          # 本地状态持久化
│   └── uniquify.js       # 全局 trackId 去重
├── server/
│   ├── index.js          # HTTP 服务
│   └── app-render.js     # SPA 面板渲染
├── customize/
│   ├── index.js          # 规则分发
│   └── modules/
│       ├── common.js     # 公共 uni-app 规则
│       └── store-manager.js  # 店掌项目规则
└── docs/
    ├── TRACK_ID_SPEC.md          # track-id 命名规范
    └── REGISTER_SCRIPT_DESIGN.md # 架构设计文档

本地状态

工具会在目标项目根目录生成 .tracker-register-state/ 目录：

| 文件 | 说明 | | ----------------------------- | -------------- | | registered-{project}.json | 已注册埋点清单 | | feedback-{project}.json | 用户反馈记录 | | routes-{project}.json | 路由确认记录 | | field-config-{project}.json | 字段配置记录 |

License

MIT