邹方成
87ad4177b1
Some checks failed
Build docker and publish / linux (1.24.5) (push) Failing after 39s
feat(抽奖动态): 修复抽奖动态未渲染问题并优化文案展示 fix(用户概览): 修复用户概览无数据显示问题 feat(新用户列表): 在新用户列表显示称号明细 refactor(待办事项): 移除代办模块并全宽展示实时动态 feat(批量操作): 限制为单用户操作并在批量时提醒 fix(称号分配): 防重复分配称号的改造计划 perf(接口性能): 优化新用户和抽奖动态接口性能 feat(订单漏斗): 优化订单转化漏斗指标计算 docs(测试计划): 完善盲盒运营API核查与闭环测试计划
72 lines
5.9 KiB
Markdown
72 lines
5.9 KiB
Markdown
## 目标
|
||
- 补齐工作台 4 个模块的真实数据接口与前端对接：订单转化漏斗、活动中奖分析、用户概述、抽奖动态文案完善。
|
||
|
||
## 后端接口设计（统一前缀 `/api/admin/dashboard`）
|
||
### 1) 订单转化漏斗 `GET /order_funnel`
|
||
- 入参：`rangeType=today|7d|30d|custom`，`start/end`（custom 时必填）
|
||
- 出参：`FunnelData[]`（与 `web/admin/src/api/operations.ts` 定义一致）
|
||
- 统计口径：
|
||
- 访问用户：优先取 `log_request` 中 `path LIKE '/api/app/%'` 的唯一访问（去重 `tid` 或 IP/UA），范围时间内（`internal/repository/mysql/model/log_request.gen.go:13-27`）
|
||
- 下单用户：`orders.created_at` 范围内下单的唯一用户数（`orders.status` 任意）（`internal/repository/mysql/model/orders.gen.go:13-33`）
|
||
- 支付用户：`orders.status=2`（已支付）范围内唯一用户数
|
||
- 完成订单：订单完成的判定（二选一并取并集）：`orders.status=2 AND is_consumed=1` 或存在 `shipping_records.status IN (2,3)`（已发货/已签收）（`internal/repository/mysql/model/shipping_records.gen.go:13-31`）
|
||
- 返回各阶段 `count`，并计算 `rate`（相对上一阶段）与 `lostCount`。
|
||
|
||
### 2) 活动中奖分析 `GET /activity_prize_analysis`
|
||
- 入参：`activity_id`（必填），可选 `rangeType`
|
||
- 出参：`ActivityPrizeAnalysis`（`activity` + `prizes[]` + `summary`，与前端类型一致）
|
||
- 统计口径：
|
||
- 奖品模板：`activity_reward_settings`（`issue_id` 归属同活动的期）（`internal/repository/mysql/model/activity_reward_settings.gen.go:13-27`）
|
||
- 中奖统计：`activity_draw_logs` 按 `reward_id` 分组统计 `winCount`（`is_winner=1`），`drawCount` 为期内抽奖总次数（`internal/repository/mysql/model/activity_draw_logs.gen.go:13-24`）
|
||
- 概率（设置）：`weight/Σweight*100`（模板无显式概率字段，采用权重归一化）
|
||
- 概率（实际）：`winCount/drawCount*100`
|
||
- 成本：若模板 `product_id` 非空，关联 `products.price` 作为单件成本（`internal/repository/mysql/model/products.gen.go:13-25`）；否则成本为 0 或采用等级默认表（可配置）
|
||
- 活动信息：`activities` + `activity_issues` 组合（名称、时间范围、参与人数=distinct `user_id`，总抽奖次数）
|
||
|
||
### 3) 用户概述 `GET /user_overview`
|
||
- 入参：`rangeType`
|
||
- 出参：包含：
|
||
- `chart`: 最近 N 个时间桶（默认 9 个月）用户注册量序列（来源 `users.created_at`）
|
||
- `metrics`: `totalUsers`（系统总量）、`totalVisits`（`log_request` 中 `/api/app/%` 请求计数）、`dailyVisits`（当天 `/api/app/%`）、`weeklyGrowth`（近 7 天 vs 上 7 天访问增幅）
|
||
- 说明：若实际“访问”定义需更严格，可后续改为埋点表；当前采用请求日志近似。
|
||
|
||
### 4) 抽奖动态增强 `GET /draw_stream`（已有）
|
||
- 增加字段：`activityName`、`issueNumber`、`prizeName`（中奖时）
|
||
- 数据来源：`activity_issues`、`activities`、`activity_reward_settings.name`
|
||
- 现有实现位置：`internal/api/admin/dashboard_admin.go:270-317`（将补充字段）
|
||
|
||
### 5) 通用
|
||
- 时间范围工具沿用：`parseRange/previousWindow/daysBetween`（`internal/api/admin/dashboard_admin.go:365-417`），对 `custom` 做 30 天上限；趋势分桶工具已实现（`normalizeGranularity/buildBuckets`）。
|
||
- 路由注册：在 `adminAuthApiRouter` 添加新端点（参考 `internal/router/router.go:63` 附近已有 dashboard 路由）。
|
||
|
||
## 前端改动
|
||
- 文件：`web/admin/src/api/operations.ts`
|
||
- `fetchOrderFunnel(range)` → `GET admin/dashboard/order_funnel`
|
||
- `fetchActivityList()` → `GET admin/dashboard/activities`（返回 `id,name,type,start,end,status,totalDraws,totalParticipants`；也可直接用现有 `GET /api/admin/activities` 的列表按需映射）
|
||
- `fetchActivityPrizeAnalysis(activityId)` → `GET admin/dashboard/activity_prize_analysis`
|
||
- `fetchUserOverview(range)`（新增） → `GET admin/dashboard/user_overview`
|
||
- 组件对接：
|
||
- `order-funnel.vue` 已调用 `fetchOrderFunnel`（`web/admin/src/views/dashboard/console/modules/order-funnel.vue:148-153`），直接切换数据源即可。
|
||
- `activity-prize-analysis.vue` 使用 `fetchActivityList/fetchActivityPrizeAnalysis`（`web/admin/src/views/dashboard/console/modules/activity-prize-analysis.vue:219-225`、`344-357`、`367-375`），切换到真实 API。
|
||
- `active-user.vue` 当前为静态数据（`web/admin/src/views/dashboard/console/modules/active-user.vue:31-46`），改为使用 `fetchUserOverview` 渲染条形图与 4 个指标。
|
||
- `dynamic-stats.vue` 增强显示中奖文案：“用户在【活动-期】中奖【奖品名】”（使用新增字段），保留参与与中奖标签（`web/admin/src/views/dashboard/console/modules/dynamic-stats.vue`）。
|
||
|
||
## 返回示例
|
||
- `GET /api/admin/dashboard/order_funnel`：`[{"stage":"访问用户","count":12580,"rate":100,"lostCount":0}, ...]`
|
||
- `GET /api/admin/dashboard/activity_prize_analysis`：结构与前端定义一致，概率为权重归一化。
|
||
- `GET /api/admin/dashboard/user_overview`：`{"chart":[{"date":"2025-03","value":1200},...],"metrics":{"totalUsers":12345,"totalVisits":45678,"dailyVisits":1234,"weeklyGrowth":"+8%"}}`
|
||
- `GET /api/admin/dashboard/draw_stream`：增加 `activityName/issueNumber/prizeName` 字段。
|
||
|
||
## 验收
|
||
- 工作台四模块均显示真实数据；各接口性能在默认范围（≤30 天）内响应合理。
|
||
- 环比与趋势计算准确；异常/空数据有合理降级。
|
||
|
||
## 后续可选优化
|
||
- 为 `log_request.created_at`、`orders.created_at`、`shipping_records.status`、`activity_draw_logs.created_at` 增加索引。
|
||
- 活动奖品“成本”可从商品资料或运营配置独立维护，避免 0 值。
|
||
|
||
确认后我将：
|
||
1. 补充 3 个新端点与 `draw_stream` 字段；注册路由；
|
||
2. 替换 `operations.ts` 的 Mock 为真实请求；
|
||
3. 调整前端 3 个模块的渲染逻辑；
|
||
4. 进行构建与联调，提供验证指令与预览链接。 |