## 目标
- 为“抽奖后获得双倍奖励，并具备时效”的业务提供可执行的创建流程与说明文档。
- 输出一份可直接用于运营与研发的《说明文档.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》，并补充操作截图位点与接口示例；如需我同时在抽奖服务中添加自动分配与双倍应用的集成代码，请确认后我直接实现并提交测试用例。