邹方成
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核查与闭环测试计划
64 lines
4.1 KiB
Markdown
64 lines
4.1 KiB
Markdown
## 目标
|
||
- 为运营提供可控的批量操作能力：批量增加积分、批量发送优惠券、批量发放奖励。
|
||
- 满足权限、配额、上限、幂等与审计要求，闭环验证整个盲盒系统运营流程。
|
||
|
||
## 问题与现状
|
||
- 现有单用户接口：`POST /api/admin/users/:user_id/points/add`、`/coupons/add`、`/item_cards`、`/rewards/grant`；缺少批量维度与风控保护。
|
||
- 已加固：优惠券发放需超管（internal/api/admin/users_admin.go:596-616）、发放配额与持有上限（internal/service/user/coupon_add.go）、道具卡数量与持有上限（internal/service/user/item_card_add.go）。
|
||
- 仍缺：批量接口、幂等、审计与限流。
|
||
|
||
## API 设计
|
||
- 批量积分：`POST /api/admin/users/batch/points/add`
|
||
- Body：`{ users: number[], amount: number, reason?: string, idempotency_key?: string }`
|
||
- 校验：超管；`amount > 0`；`users.length <= 5000`；可选日累计上限（防爆刷）。
|
||
- 行为：逐用户执行加分（重用现有服务层），支持幂等（按 `op_type+idempotency_key+users+amount` 去重）。
|
||
- 返回：`{ success: number, failed: number, details: Array<{user_id,status,msg}> }`。
|
||
|
||
- 批量优惠券：`POST /api/admin/users/batch/coupons/add`
|
||
- Body：`{ users: number[], coupon_id: number, quantity_per_user?: number, idempotency_key?: string }`
|
||
- 校验：超管；模板启用与有效期；配额与单用户持有上限（已在服务层）；`quantity_per_user` 上限（<=5）。
|
||
- 行为：逐用户发券（重用 `AddCoupon`），事务分片（每批 100~200），记录逐项状态；幂等去重。
|
||
- 返回：同上。
|
||
|
||
- 批量奖励：`POST /api/admin/users/batch/rewards/grant`
|
||
- Body：`{ users: number[], reward_id: number, quantity?: number, idempotency_key?: string }` 或按活动期：`POST /api/admin/activities/:activity_id/issues/:issue_id/rewards/batch_grant` `{ users: number[], reward_id: number, quantity?: number }`
|
||
- 校验：超管；奖励模板/库存；单用户持有上限（可与道具卡同策略）；数量上限（<=10）。
|
||
- 行为：逐用户入库，事务分片，幂等去重。
|
||
- 返回：同上。
|
||
|
||
## 权限与风控
|
||
- 仅超管可调用批量接口；非超管拒绝。
|
||
- 限流：每分钟调用次数限制（可在拦截器或中间件层实现）。
|
||
- 上限：请求用户数上限（5000），单用户数量上限；模板配额检查；用户持有上限（已存在的加固沿用）。
|
||
- 幂等：支持 `idempotency_key`；服务层保存批次指纹，重复提交直接返回历史结果。
|
||
- 审计：记录批量操作日志（操作者、时间、对象数量、成功/失败明细摘要与请求指纹）。
|
||
|
||
## 后端改造点
|
||
- 路由：`internal/router/router.go`
|
||
- 新增：`POST /api/admin/users/batch/points/add`、`/batch/coupons/add`、`/batch/rewards/grant`
|
||
- 处理器：`internal/api/admin/users_admin.go`
|
||
- 新增批量处理 Handler（结构体 Request/Response、超管校验、参数绑定、分片循环、调用服务层、汇总返回）。
|
||
- 服务层：`internal/service/user/*`
|
||
- 新增批量方法或在 Handler 中循环调用现有单个方法（推荐服务层添加批量封装，带事务与幂等指纹）。
|
||
- 中间件：可选全局限流与审计记录入口（日志/Audit DAO）。
|
||
|
||
## 前端（管理端）
|
||
- 称号运营页或用户管理页新增“批量操作”入口，支持：
|
||
- 用户选择（列表多选/CSV导入）
|
||
- 操作类型（积分/优惠券/奖励）与参数（金额/模板/数量）
|
||
- 幂等键（可选自动生成）
|
||
- 执行后展示分项结果与失败原因下载。
|
||
|
||
## 测试与验收
|
||
- Postman 集合扩展三条批量接口；注入 admin 令牌后按顺序回归。
|
||
- 验收标准：
|
||
- 权限校验：非超管拒绝。
|
||
- 配额/上限：超量拒绝；成功/失败计数正确。
|
||
- 幂等：重复提交返回相同结果，不重复写入。
|
||
- 审计：生成批次日志记录（至少在系统日志中可查）。
|
||
|
||
## 交付
|
||
- 批量接口与处理器实现、服务层封装、路由挂载。
|
||
- 集合/脚本更新与验收报告（问题清单与修复项）。
|
||
|
||
确认后我将开始实现并提交对应代码与测试集合更新。 |