邹方成
8141a47690
Some checks failed
Build docker and publish / linux (1.24.5) (push) Failing after 39s
- 新增系统称号模板与效果配置表及相关CRUD接口 - 实现用户称号分配与抽奖效果应用逻辑 - 优化抽奖接口支持用户ID参数以应用称号效果 - 新增称号管理前端页面与分配功能 - 修复Windows时区错误与JSON字段初始化问题 - 移除无用管理接口代码并更新文档说明
55 lines
5.3 KiB
Markdown
55 lines
5.3 KiB
Markdown
## 目标与范围
|
||
- 设计并梳理六类头衔效果：1领取优惠券、2抽奖折扣、3签到双倍积分、4领取道具卡、5概率加成、6奖励双倍。
|
||
- 输出参数规范、叠加与封顶策略、作用域策略，以及标准化新建流程（管理端接口与数据约束）。
|
||
|
||
## 效果类型与参数规范
|
||
- 1 领取优惠券：`template_id`(券模板ID)、`frequency.period`(day|week|month)、`frequency.times`(周期次数)。示例：`{"template_id":123,"frequency":{"period":"day","times":1}}`（种子示例 `internal/api/admin/titles_seed.go:31`）。
|
||
- 2 抽奖折扣：`discount_type`(percentage|fixed)、`value_x1000`(千分比或固定额)、`max_discount_x1000`(折扣封顶)。示例：`{"discount_type":"percentage","value_x1000":100,"max_discount_x1000":300}`（`internal/api/admin/titles_seed.go:32`）。
|
||
- 3 签到双倍积分：`multiplier_x1000`(如2000表示x2)、`daily_cap_points`(每日积分上限)。示例：`{"multiplier_x1000":2000,"daily_cap_points":3000}`（`internal/api/admin/titles_seed.go:33`）。
|
||
- 4 领取道具卡：`template_id`、`frequency.period/times`（同“领券”频控）。示例：`{"template_id":456,"frequency":{"period":"week","times":2}}`（`internal/api/admin/titles_seed.go:34`）。
|
||
- 5 概率加成：`target_prize_ids[]`(目标奖品ID)、`boost_x1000`(加成千分比)、`cap_x1000`(单项封顶，可选)。示例：`{"target_prize_ids":[1,2],"boost_x1000":100,"cap_x1000":300}`；应用参考 `internal/service/activity/draw_with_effects.go:104-131`。
|
||
- 6 奖励双倍：`target_prize_ids[]`、`chance_x1000`(命中概率千分比)、`period_cap_times`(期内命中上限，可选)。示例：`{"target_prize_ids":[3],"chance_x1000":150}`；命中判定参考 `internal/service/activity/draw_with_effects.go:197-208`。
|
||
|
||
## 叠加与封顶策略
|
||
- `StackingStrategy`：
|
||
- `0` max_only：取效果最大值。
|
||
- `1` sum_with_cap：累加并按封顶值限制（优先使用效果内的 `cap_x1000`，否则用 `CapValueX1000`）。
|
||
- `2` first_match：首个命中后忽略后续。
|
||
- 默认：累加并按 `CapValueX1000` 封顶（抽奖已实现 `internal/service/activity/draw_with_effects.go:117-131`、`internal/service/activity/draw_with_effects.go:146-149`）。
|
||
- 封顶单位统一为 `x1000` 千分比，避免浮点误差。
|
||
|
||
## 作用域策略（ScopesJSON）
|
||
- 字段：`activity_ids/issue_ids/category_ids` 与 `exclude` 子段；解析与匹配参考 `internal/service/title/effects_resolver.go:59-69`、`internal/service/title/effects_resolver.go:133-155`。
|
||
- 生效原则：先排除再包含；未配置视为全局生效。
|
||
|
||
## 新建流程（管理端）
|
||
- 步骤1：创建称号模板
|
||
- `POST /api/admin/system_titles`（`internal/router/router.go:128`；处理 `internal/api/admin/titles_admin.go:81-103`）。
|
||
- 请求体：`name/description/status/obtain_rules_json/scopes_json`（空JSON默认填 `{}`）。
|
||
- 步骤2：为称号模板添加效果
|
||
- `POST /api/admin/system_titles/:title_id/effects`（`internal/router/router.go:132-133`；处理 `internal/api/admin/titles_admin.go:183-213`）。
|
||
- 请求体：`effect_type/params_json/stacking_strategy/cap_value_x1000/scopes_json/sort/status`。
|
||
- 步骤3：分配给用户（可选，含有效期）
|
||
- `POST /api/admin/users/:user_id/titles`（`internal/router/router.go:127`；处理 `internal/api/admin/titles_admin.go:291-353`）。
|
||
- 请求体：`title_id/expires_at(RFC3339)/remark`。
|
||
- 步骤4：校验
|
||
- 列表查询与检查：`GET /api/admin/system_titles`、`GET /api/admin/system_titles/:title_id/effects`（`internal/router/router.go:126`、`internal/router/router.go:131`；处理 `internal/api/admin/titles_admin.go:27-59`、`internal/api/admin/titles_admin.go:156-171`）。
|
||
|
||
## 数据与规则约束
|
||
- 名称唯一与幂等：同名不重复创建（`internal/api/admin/titles_seed.go:41-48`）。
|
||
- 状态控制：模板与效果需同时启用才会生效（抽奖过滤 `internal/service/activity/draw_with_effects.go:46-49`、`internal/service/activity/draw_with_effects.go:80-83`）。
|
||
- 有效期与激活：仅激活且未过期的用户称号参与计算（`internal/service/activity/draw_with_effects.go:54-67`）。
|
||
- 参数校验：`params_json` 必填（`internal/api/admin/titles_admin.go:195-206`）。
|
||
|
||
## 示例：新增“签到双倍积分”称号
|
||
- 创建模板：`name=签到达人`、`status=1`、`scopes_json={}`。
|
||
- 添加效果：`effect_type=3`、`params_json={"multiplier_x1000":2000,"daily_cap_points":3000}`、`stacking_strategy=1`、`cap_value_x1000=3000`、`status=1`。
|
||
- 分配给用户：设置 `expires_at`（如7天后）并激活。
|
||
|
||
## 示例：新增“抽奖折扣”称号
|
||
- 创建模板：`name=折扣官`、`status=1`、`scopes_json={"activity_ids":[1001]}`。
|
||
- 添加效果：`effect_type=2`、`params_json={"discount_type":"percentage","value_x1000":150,"max_discount_x1000":500}`、`stacking_strategy=1`、`cap_value_x1000=500`、`status=1`。
|
||
|
||
## 后续实施建议
|
||
- 在签到与购票模块接入统一解析器与效果计算器，实现(2)(3)的实际应用；领取型(1)(4)接入 `UserTitleEffectClaims` 做周期限流与资产发放；抽奖效果写入审计日志。
|
||
- 你确认后，我将按上述流程与参数规范为每种类型提供可执行的创建脚手架（接口调用示例与测试用例），并补齐未接入业务的效果逻辑。 |