邹方成
8141a47690
Some checks failed
Build docker and publish / linux (1.24.5) (push) Failing after 39s
- 新增系统称号模板与效果配置表及相关CRUD接口 - 实现用户称号分配与抽奖效果应用逻辑 - 优化抽奖接口支持用户ID参数以应用称号效果 - 新增称号管理前端页面与分配功能 - 修复Windows时区错误与JSON字段初始化问题 - 移除无用管理接口代码并更新文档说明
116 lines
5.3 KiB
Markdown
116 lines
5.3 KiB
Markdown
## 目标
|
||
- 为“抽奖后获得双倍奖励，并具备时效”的业务提供可执行的创建流程与说明文档。
|
||
- 输出一份可直接用于运营与研发的《说明文档.md》，包含：项目规划、实施方案、进度记录，以及完整的操作与集成指南。
|
||
|
||
## 核心概念
|
||
- SystemTitles：系统称号主数据，含名称、描述、获取规则、适用范围等。参考 internal/repository/mysql/model/system_titles.gen.go
|
||
- SystemTitleEffects：称号效果，含效果类型、参数、叠加策略、封顶值等。参考 internal/repository/mysql/model/system_title_effects.gen.go
|
||
- UserTitles：用户称号记录，含生效状态与过期时间，用于管控时效。参考 internal/repository/mysql/model/user_titles.gen.go
|
||
- 效果类型示例：在 admin/titles_seed.go 已内置6类，含“双倍之王（EffectType=6）”。参考 internal/api/admin/titles_seed.go:18-37
|
||
|
||
## 后端接口一览（供前后端与运维对齐）
|
||
- 系统称号（管理员）
|
||
- GET/POST/PUT/DELETE `/api/admin/system_titles`
|
||
- GET/POST/PUT/DELETE `/api/admin/system_titles/:title_id/effects`
|
||
- 用户称号分配（管理员）
|
||
- POST `/api/admin/users/:user_id/titles`（分配或更新有效期与激活状态）
|
||
- 路由参考：internal/router/router.go
|
||
- 管理端控制器参考：internal/api/admin/titles_admin.go（列表/创建/修改/删除/分配）
|
||
|
||
## 创建流程（运营页面）
|
||
1. 进入管理端：`/operations/titles`（确保菜单已存在，见 EnsureTitlesMenu）
|
||
2. 创建称号：
|
||
- 名称：例如“抽奖双倍达人”
|
||
- 描述：例如“抽奖奖励翻倍，限时24小时”
|
||
- 状态：启用
|
||
3. 配置获取规则（ObtainRulesJSON）：
|
||
- methods：`["lottery"]`
|
||
- conditions：可选，如抽奖类型 `lottery_type="normal"`
|
||
- 示例：
|
||
```json
|
||
{
|
||
"methods": ["lottery"],
|
||
"conditions": {"lottery_type": "normal"}
|
||
}
|
||
```
|
||
4. 配置适用范围（ScopesJSON）：可为空或限定品类/场次/用户等级，按需填写
|
||
5. 添加效果（SystemTitleEffects）：选择“EffectType=6（双倍概率）”，并设置参数：
|
||
- `target_prize_ids`: []（空表示所有奖品）
|
||
- `chance_x1000`: 1000（100% 双倍；或按需改为 200=20%）
|
||
- `period_cap_times`: 1（周期内最多触发次数，建议与日/活动周期对齐）
|
||
- 示例：
|
||
```json
|
||
{
|
||
"target_prize_ids": [],
|
||
"chance_x1000": 1000,
|
||
"period_cap_times": 1
|
||
}
|
||
```
|
||
6. 保存称号与效果，确认列表中显示。
|
||
|
||
## 分配与时效（运营或自动）
|
||
- 运营手动分配（页面“分配用户”对话框）：
|
||
- 选择用户，设定有效期类型：
|
||
- `permanent` 永久
|
||
- `period` 指定开始/结束时间（填写 `start_time`/`end_time`）
|
||
- `days` 按天数有效（例如 1 天）
|
||
- 勾选“覆盖现有/发送通知”按需配置，提交后生效
|
||
- 抽奖后自动分配（后端集成点）：
|
||
- 在抽奖流程成功后，调用分配接口或服务方法为用户写入 UserTitles（设置 `expires_at`）
|
||
- 建议在抽奖服务中统一封装：检查用户是否已拥有称号；若没有则分配，有则延长或保持不变（按业务策略）
|
||
|
||
## 抽奖流程应用双倍效果（后端逻辑）
|
||
- 在发奖时：
|
||
1. 读取用户当前激活且未过期的 UserTitles
|
||
2. 聚合其 SystemTitleEffects（EffectType=6），解析 `chance_x1000` 与 `period_cap_times`
|
||
3. 按概率/次数限制判断是否触发翻倍，将奖品数量或价值翻倍（或对指定 `target_prize_ids` 生效）
|
||
4. 记录一次触发（用于控制当期 `period_cap_times`）
|
||
- 注意：叠加策略（StackingStrategy）与封顶（CapValueX1000）需一并考虑，避免超限
|
||
|
||
## 配置示例（可直接复用）
|
||
- 称号获取规则（让称号只在抽奖场景下获得）
|
||
```json
|
||
{
|
||
"methods": ["lottery"],
|
||
"conditions": {"lottery_type": "normal"}
|
||
}
|
||
```
|
||
- 双倍效果参数（对所有奖品 100% 双倍，且周期内最多 1 次）
|
||
```json
|
||
{
|
||
"target_prize_ids": [],
|
||
"chance_x1000": 1000,
|
||
"period_cap_times": 1
|
||
}
|
||
```
|
||
- 用户分配有效期（按天）
|
||
```json
|
||
{
|
||
"expire_type": "days",
|
||
"days": 1,
|
||
"remark": "抽奖获得双倍称号",
|
||
"override_existing": true,
|
||
"send_notification": true
|
||
}
|
||
```
|
||
|
||
## 测试与验收
|
||
- 管理端：
|
||
- 创建称号与效果 → 列表校验 → 为测试用户分配（1天有效）
|
||
- 抽奖流程：
|
||
- 模拟用户抽奖 → 校验发奖结果是否翻倍 → 检查 period_cap_times 限制是否生效
|
||
- 到期后再次抽奖：不再翻倍（验证 `expires_at` 生效）
|
||
- 数据核查：
|
||
- 检查 UserTitles 记录及过期时间
|
||
- 检查效果触发记录（若有）与叠加/封顶逻辑
|
||
|
||
## 说明文档结构（交付内容）
|
||
- 文件：`docs/称号系统/说明文档.md`
|
||
- 项目规划：业务目标、范围、时间节点
|
||
- 实施方案：模型与接口、创建与分配流程、抽奖集成方案
|
||
- 进度记录：每次变更与验证结果
|
||
- 操作指南：页面操作步骤、配置示例、常见问题
|
||
- 验收标准：用例列表与通过条件
|
||
|
||
## 后续工作
|
||
- 我将依据上述结构生成《说明文档.md》，并补充操作截图位点与接口示例；如需我同时在抽奖服务中添加自动分配与双倍应用的集成代码，请确认后我直接实现并提交测试用例。 |