邹方成
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核查与闭环测试计划
4.1 KiB
4.1 KiB
目标
- 为运营提供可控的批量操作能力：批量增加积分、批量发送优惠券、批量发放奖励。
- 满足权限、配额、上限、幂等与审计要求，闭环验证整个盲盒系统运营流程。
问题与现状
- 现有单用户接口：
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}> }。
- Body：
-
批量优惠券：
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），记录逐项状态；幂等去重。 - 返回：同上。
- Body：
-
批量奖励：
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）。
- 行为：逐用户入库，事务分片，幂等去重。
- 返回：同上。
- Body：
权限与风控
- 仅超管可调用批量接口；非超管拒绝。
- 限流：每分钟调用次数限制（可在拦截器或中间件层实现）。
- 上限：请求用户数上限（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 令牌后按顺序回归。
- 验收标准：
- 权限校验：非超管拒绝。
- 配额/上限：超量拒绝；成功/失败计数正确。
- 幂等：重复提交返回相同结果，不重复写入。
- 审计：生成批次日志记录（至少在系统日志中可查）。
交付
- 批量接口与处理器实现、服务层封装、路由挂载。
- 集合/脚本更新与验收报告（问题清单与修复项）。
确认后我将开始实现并提交对应代码与测试集合更新。