Files
Sisyphus (主代理) 02762400fb chore: 项目基线提交 - 拼豆图纸生成器 V1.0 核心代码
- 前端: React+Vite 首页/AI专区, 算法库(MARD色板/量化/背景去除), API对接
- 后端: Express+SQLite, 兑换码/订单/支付/chibi生成, 风控+云端同步
- CI/CD: GitHub Actions + Docker + nginx 配置
- 文档: PRD/DESIGN/LAUNCH/ROADMAP/E2E/竞品对照等 15 份
- 工程: 任务看板(taskboard) + 健康巡检(agent-health) + Git流程(gitflow)
2026-08-13 21:40:27 +08:00

272 lines
14 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# PERLER LAB 数据分析与事件埋点规范(ANALYTICS.md)
> 版本: 1.0 | 关联: LAUNCH.md(§5 运营指标)· PRD.md
> 说明: 本规范定义全站事件埋点、转化漏斗、上报方式与关键指标看板,所有目标值对齐 LAUNCH.md §5.1/§5.2/§5.3。
---
## 1. 数据口径与用户标识
| 字段 | 类型 | 说明 |
|---|---|---|
| `device_id` | `string` (uuid) | 存于 `localStorage._pl_device_id`,首次访问生成,永久复用。权益与回访均按此维度统计(与兑换权益的本地存储机制一致) |
| `session_id` | `string` (uuid) | 存于 `sessionStorage._pl_session_id`,一次会话一个,关闭标签页即失效 |
| `page` | `"/"` \| `"/chibi"` | 事件发生时所在页面 |
| `ts` | `number` (ms) | 事件时间戳(`Date.now()`) |
**去重规则**:漏斗与转化率类指标按 `device_id` 去重,且同一 `session_id` 内同一环节只计首次命中,避免重复点击抬高转化率。
---
## 2. 事件总表(38 个事件)
> 命名约定:全小写 snake_case;每行含 事件名 / 触发时机 / 参数(全部标注类型)/ 页面。
### 2.1 访问 / 页面浏览(5 个)
| 事件名 | 触发时机 | 参数 | 页面 |
|---|---|---|---|
| `session_start` | 页面首次加载(会话开始) | `referrer: string`(来源页), `landing_page: "/"\|"/chibi"`, `utm_source: string?` | / /chibi |
| `page_view` | 每次页面浏览(SPA 路由切换同样触发) | `page: "/"\|"/chibi"`, `referrer: string` | / /chibi |
| `home_view` | 首页完成渲染 | `-` | / |
| `chibi_view` | /chibi 专区完成渲染 | `-` | /chibi |
| `first_visit` | 无 `device_id` 记录时首次访问 | `landing_page: "/"\|"/chibi"`, `referrer: string` | / /chibi |
### 2.2 图片上传(5 个)
| 事件名 | 触发时机 | 参数 | 页面 |
|---|---|---|---|
| `upload_start` | 用户点击/选择文件 | `file_type: "jpg"\|"png"\|"webp"`, `file_size_bytes: number` | / |
| `upload_success` | 图片读取并校验通过 | `file_type: string`, `file_size_bytes: number`, `width_px: number`, `height_px: number`, `aspect_ratio: number`(宽/高,保留 2 位) | / |
| `upload_fail` | 读取/解析失败 | `file_type: string`, `file_size_bytes: number`, `error_code: "read_error"\|"parse_error"\|"corrupt"` | / |
| `upload_size_exceed` | 文件超过 12MB 被拦截 | `file_size_bytes: number`, `limit_mb: 12` | / |
| `upload_type_invalid` | 文件格式不受支持 | `file_type: string`, `allowed: ["jpg","png","webp"]` | / |
### 2.3 参数调整(4 个)
| 事件名 | 触发时机 | 参数 | 页面 |
|---|---|---|---|
| `param_change` | 任意参数变更(通用兜底) | `param: "size"\|"colors"\|"bg_removal"\|"style"`, `value: string\|number\|boolean`, `prev_value` | / /chibi |
| `param_size_change` | 图纸尺寸变更 | `size: "32x32"\|"48x48"\|"64x64"` | / |
| `param_color_change` | 色数变更 | `colors: 12\|24\|36` | / |
| `param_bg_removal_toggle` | 背景去除开关切换 | `value: boolean` | / /chibi |
### 2.4 重新生成(1 个)
| 事件名 | 触发时机 | 参数 | 页面 |
|---|---|---|---|
| `regenerate_click` | 点击"重新生成"按钮 | `trigger: "auto"\|"manual"`, `size: string`, `colors: number` | / |
### 2.5 兑换码(5 个)
| 事件名 | 触发时机 | 参数 | 页面 |
|---|---|---|---|
| `redeem_modal_open` | 打开兑换弹窗 | `entry: "download_lock"\|"nav"\|"banner"\|"limit_hit"` | / |
| `redeem_submit` | 提交兑换码(调用 `/api/codes/redeem`) | `code_length: number`, `code_prefix: string`(脱敏,仅取前 4 位) | / |
| `redeem_success` | 兑换成功(redeem 返回成功) | `balance_added: number`, `total_balance: number`, `channel: "personal"\|"agent"` | / |
| `redeem_fail` | 兑换失败 | `error_code: "invalid"\|"used"\|"expired"\|"rate_limited"`, `channel: "personal"\|"agent"` | / |
| `redeem_balance_checked` | 用户查看剩余次数 | `balance: number` | / |
### 2.6 订单 / 支付(5 个)
| 事件名 | 触发时机 | 参数 | 页面 |
|---|---|---|---|
| `order_create` | 创建订单(调用 `/api/orders`) | `order_id: string`, `package: "experience"\|"standard"\|"pro"`, `price_yuan: 4.9\|12.9\|29.9`, `times: 3\|10\|30` | / |
| `order_pay_method_select` | 选择支付方式 | `order_id: string`, `method: "wechat"\|"alipay"\|"mock"` | / |
| `order_pay_success` | 支付成功 | `order_id: string`, `package: string`, `price_yuan: number`, `method: string`, `pay_amount: number` | / |
| `order_pay_fail` | 支付失败 | `order_id: string`, `error_code: string`, `method: string` | / |
| `order_pay_cancel` | 用户取消支付 | `order_id: string`, `duration_ms: number`(从创建到取消) | / |
### 2.7 下载(3 个)
| 事件名 | 触发时机 | 参数 | 页面 |
|---|---|---|---|
| `download_click` | 点击下载图纸 | `work_id: string`, `size: string`, `colors: number`, `is_chibi: boolean` | / /chibi |
| `download_success` | 下载完成(触发 `/api/codes/consume` 扣次成功) | `work_id: string`, `size: string`, `colors: number`, `consume_used: boolean` | / /chibi |
| `download_fail` | 下载失败 | `work_id: string`, `error_code: "blob_error"\|"browser_blocked"\|"consume_fail"` | / /chibi |
### 2.8 AI 生成(6 个)
| 事件名 | 触发时机 | 参数 | 页面 |
|---|---|---|---|
| `ai_generate_start` | 开始 AI 生成(调用 `/api/chibi/generate`) | `source: "photo"\|"chibi"`, `size: string`, `colors: number`, `style: string?`(仅 chibi 源) | / /chibi |
| `ai_generate_success` | 生成成功 | `source: string`, `size: string`, `colors: number`, `latency_ms: number`, `cost_yuan: number` | / /chibi |
| `ai_generate_fail` | 生成失败 | `source: string`, `error_code: "model_error"\|"timeout"\|"rate_limit"`, `latency_ms: number` | / /chibi |
| `ai_generate_retry` | 用户点击重试生成 | `source: string`, `retry_count: number`, `prev_error_code: string` | / /chibi |
| `generation_limit_hit` | 剩余次数不足被拦截 | `balance: number`, `required: 1` | / |
| `chibi_convert_click` | 将 AI 结果转为正式图纸 | `size: string`, `colors: number` | /chibi |
### 2.9 代理合作(2 个)
| 事件名 | 触发时机 | 参数 | 页面 |
|---|---|---|---|
| `agent_modal_open` | 打开代理合作弹窗 | `entry: "footer"\|"banner"\|"faq"` | / |
| `agent_consult_click` | 点击"咨询/领取价目表" | `contact_channel: "wechat"\|"qq"`, `package_interest: "entry"\|"standard"\|"core"` | / |
### 2.10 分享 / 增长(2 个)
| 事件名 | 触发时机 | 参数 | 页面 |
|---|---|---|---|
| `share_click` | 点击分享 / 晒图纸 | `channel: "xiaohongshu"\|"douyin"\|"wechat"\|"copy_link"`, `work_id: string` | / |
| `refer_link_click` | 通过代理推广链接进入 | `agent_id: string`, `page: "/"\|"/chibi"` | / /chibi |
---
## 3. 转化漏斗定义
对齐 LAUNCH.md §5.1:`访问 → 上传图片 → 生成预览 → 兑换解锁 → 下载完成`(100% / 45% / 25% / 8% / 6%)。
| 步骤 | 名称 | 事件口径(去重) | 计算 | 目标 |
|---|---|---|---|---|
| 1 | 访问 | `page_view`(当日去重 `device_id` 数) | 分母 = 100% | - |
| 2 | 上传 | `upload_success`(同一 session 首次) | 上传转化率 = 步骤2 / 步骤1 | ≥45% |
| 3 | 生成 | `ai_generate_success`(同一 session 首次) | 生成转化率 = 步骤3 / 步骤1 | ≥25% |
| 4 | 兑换 | `redeem_success`(同一 session 首次) | 兑换率 = 步骤4 / 步骤1 | ≥8%(付费转化,对齐 §5.2 目标 5%) |
| 5 | 下载 | `download_success`(同一 session 首次) | 下载完成率 = 步骤5 / 步骤4 | ≥75% |
**漏斗细分口径**:
- 上传→生成转化率 = 步骤3 / 步骤2,用于衡量生成功能本身的流失(含次数不足拦截 `generation_limit_hit`)。
- 兑换→下载转化率 = 步骤5 / 步骤4,异常时应排查 `download_fail` 与浏览器下载拦截。
- 分渠道查看(小红书 / 抖音 / 代理链接 / 直接访问):以 `session_start.referrer` 与 `utm_source`、`refer_link_click.agent_id` 为维度拆分,T+7 复盘按渠道对齐。
---
## 4. 埋点实现建议
### 4.1 前端事件采集(window.__analytics 全局函数)
采用轻量全局函数方案,不引入第三方 SDK。业务代码只需一行调用:
```js
// 埋点调用示例
window.__analytics('ai_generate_success', { source: 'photo', size: '64x64', colors: 24, latency_ms: 1823 });
```
实现骨架(建议放于公共 bundle 首位):
```js
(function () {
var DKEY = '_pl_device_id', SKEY = '_pl_session_id', QUEUE = '_pl_queue';
function uuid() {
return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function (c) {
var r = Math.random() * 16 | 0;
return (c === 'x' ? r : (r & 0x3 | 0x8)).toString(16);
});
}
function get(key, gen) {
var v = localStorage.getItem(key);
if (!v) { v = gen(); localStorage.setItem(key, v); }
return v;
}
var deviceId = get(DKEY, uuid);
var sessionId = sessionStorage.getItem(SKEY) || (sessionStorage.setItem(SKEY, uuid()), sessionStorage.getItem(SKEY));
function flush() {
var batch = [];
try { batch = JSON.parse(localStorage.getItem(QUEUE) || '[]'); localStorage.removeItem(QUEUE); } catch (e) {}
if (!batch.length) return;
var body = new Blob([JSON.stringify(batch)], { type: 'application/json' });
// 优先 sendBeacon,降级 fetch keepalive
if (navigator.sendBeacon) { navigator.sendBeacon('/api/analytics/collect', body); return; }
fetch('/api/analytics/collect', { method: 'POST', body: body, keepalive: true, headers: { 'Content-Type': 'application/json' } }).catch(function () {});
}
window.__analytics = function (event, properties) {
properties = properties || {};
var payload = {
event: event,
ts: Date.now(),
device_id: deviceId,
session_id: sessionId,
page: location.pathname,
properties: properties
};
var queue = [];
try { queue = JSON.parse(localStorage.getItem(QUEUE) || '[]'); } catch (e) {}
queue.push(payload);
localStorage.setItem(QUEUE, JSON.stringify(queue));
if (queue.length >= 10) flush();
document.addEventListener('visibilitychange', function () {
if (document.visibilityState === 'hidden') flush();
});
window.addEventListener('pagehide', flush);
};
})();
```
### 4.2 上报方式
| 项 | 方案 | 说明 |
|---|---|---|
| 上报通道 | `navigator.sendBeacon` | 页面关闭不丢包,优先使用;不支持时降级 `fetch(..., { keepalive: true })` |
| 聚合 | 本地 `localStorage` 队列批量上报 | 满 10 条立即上报;`pagehide` / `visibilitychange(hidden)` 兜底刷新 |
| 接口 | `POST /api/analytics/collect` | 后端仅落库,返回 204,不参与业务逻辑;失败静默不重试(防阻塞主流程) |
| 采样 | 全量采集 | MVP 规模小,全量采集便于调试;日事件量超过 20 万再引入采样 |
### 4.3 上报数据结构示例
单事件:
```json
{
"event": "ai_generate_success",
"ts": 1755090000000,
"device_id": "9f1c3a2e-7b84-4d2e-9f1c-3a2e7b844d2e",
"session_id": "b3d2f5a1-6c9e-4f30-b3d2-f5a16c9e4f30",
"page": "/",
"properties": {
"source": "photo",
"size": "64x64",
"colors": 24,
"latency_ms": 1823,
"cost_yuan": 0.03
}
}
```
批量上报(sendBeacon body):
```json
[
{ "event": "page_view", "ts": 1755089999000, "device_id": "9f1c...", "session_id": "b3d2...", "page": "/", "properties": { "referrer": "https://www.xiaohongshu.com" } },
{ "event": "upload_start", "ts": 1755090001000, "device_id": "9f1c...", "session_id": "b3d2...", "page": "/", "properties": { "file_type": "png", "file_size_bytes": 2097152 } }
]
```
### 4.4 埋点与后端接口对照
| 事件 | 关联接口 | 触发说明 |
|---|---|---|
| `redeem_success` / `redeem_fail` | `/api/codes/redeem` | 按接口返回结果上报,`channel` 取返回值 |
| `download_success` / `download_fail` | `/api/codes/consume` | `consume_used=true` 表示本次首次下载扣次 |
| `order_create` / `order_pay_success` | `/api/orders` | 支付回调确认成功后再上报 `order_pay_success`,金额以订单为准 |
| `ai_generate_start` / `ai_generate_success` / `ai_generate_fail` | `/api/chibi/generate` | 开始即上报 `start`,结束按结果上报成功/失败,`cost_yuan` 由后端返回或按模型单价估算 |
---
## 5. 关键指标看板(每日 10 指标)
> 数据源:事件表聚合 + 订单表。所有比率按「去重用户数」计算,统计窗口为自然日(UTC+8)。首月目标值引用 LAUNCH.md §5.1/§5.2。
| # | 指标 | 计算公式 | 首月目标 |
|---|---|---|---|
| 1 | 日活 UV | `COUNT(DISTINCT device_id)`(当日有任意事件) | 300 |
| 2 | 新增用户 | `COUNT(first_visit)`(当日) | 观察值,随渠道投入变化 |
| 3 | 上传转化率 | `COUNT(DISTINCT upload_success.device_id) / COUNT(DISTINCT page_view.device_id)` | ≥45% |
| 4 | 生成转化率 | `COUNT(DISTINCT ai_generate_success.device_id) / COUNT(DISTINCT page_view.device_id)` | ≥25% |
| 5 | 兑换率(付费转化) | `COUNT(DISTINCT redeem_success.device_id) / COUNT(DISTINCT page_view.device_id)` | ≥8%(首月按 5% 起步) |
| 6 | 下载完成率 | `COUNT(DISTINCT download_success.device_id) / COUNT(DISTINCT redeem_success.device_id)` | ≥75% |
| 7 | AI 生成失败率 | `COUNT(ai_generate_fail) / (COUNT(ai_generate_success) + COUNT(ai_generate_fail))` | ≤5%(超线告警,§5.3) |
| 8 | 次日回访率 | `COUNT(昨日UV ∩ 今日UV) / COUNT(昨日UV)` | ≥15% |
| 9 | 日均营收(GMV) | `SUM(order_pay_success.pay_amount)`(当日) | 首月约 ¥1,900/月 |
| 10 | 客单价 | `SUM(order_pay_success.pay_amount) / COUNT(DISTINCT order_pay_success.device_id)` | ¥12.9(以常用包为主) |
**辅助指标**(非每日必看,周度复盘):
- AI 生成成本 = `SUM(ai_generate_success.cost_yuan)` / `COUNT(ai_generate_success)`,单张目标 ¥0.02–0.05(§5.3)。
- 复购率 = 当月发生过 ≥2 次 `redeem_success` 的 device_id / 当月兑换用户数,T+7/T+30 复盘用。
- 分渠道转化率 = 各渠道漏斗第 4 步 / 第 1 步,评估投放 ROI 与代理链接效果。
**看板展示建议**:首页放指标 1/3/4/5/7/9,第二屏放 2/6/8/10 及辅助指标;每日 09:00 生成前一日报告,异常指标(失败率>5%、兑换率低于 4%)自动标注并推送。