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)
This commit is contained in:
commit
02762400fb
174 files changed
+28059
No files matched your search
@@ -0,0 +1,271 @@
|
||||
# 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%)自动标注并推送。
|
||||
|
||||
|
||||
Reference in new issue
Block a user