邹方成
45815bfb7d
refactor(utils): 修复密码哈希比较逻辑错误 feat(user): 新增按状态筛选优惠券接口 docs: 添加虚拟发货与任务中心相关文档 fix(wechat): 修正Code2Session上下文传递问题 test: 补充订单折扣与积分转换测试用例 build: 更新配置文件与构建脚本 style: 清理多余的空行与注释
49 lines
2.3 KiB
Markdown
49 lines
2.3 KiB
Markdown
## 核心原则
|
||
- 承诺是活动级属性：所有活动均需生成并持有承诺；抽奖只能在承诺存在的活动上执行
|
||
- 不做旧期兼容：不读取/维护期级承诺表；全量切换到活动级承诺
|
||
|
||
## 数据模型（仅 activities）
|
||
- `activities` 新增字段：
|
||
- `commitment_algo` VARCHAR(32) 默认 `commit-v1`
|
||
- `commitment_seed_master` BLOB（活动随机种子，256位）
|
||
- `commitment_seed_hash` BLOB（`SHA256(seed_master)`）
|
||
- `commitment_state_version` INT（递增）
|
||
- `commitment_items_root` BLOB（按玩法需要可填，比如 Ichiban 的 slots 根）
|
||
- 期级承诺表不再使用（保留但不访问），所有策略仅访问活动级承诺
|
||
|
||
## 接口
|
||
- 生成承诺（活动级）：`POST /api/admin/activities/:activity_id/commitment/generate`
|
||
- 行为：生成随机种子；计算 `seed_hash`；按玩法（如 Ichiban）计算 `items_root`；版本 +1
|
||
- 承诺概览：`GET /api/admin/activities/:activity_id/commitment/summary`
|
||
- 返回：`{ seed_version, algo, has_seed, items_root(optional) }`
|
||
- 抽奖前置校验：策略入口统一校验活动承诺存在；缺失则返回 `COMMITMENT_REQUIRED`
|
||
|
||
## 策略消费
|
||
- Ichiban：
|
||
- 读取活动级 `seed_master` 作为随机源
|
||
- 根据期的奖励配置构造 slots（基于 `original_qty`）→ 使用活动种子做确定性洗牌
|
||
- 保持“位置→奖品”稳定，版本变更后整体映射更新
|
||
- 其他玩法：
|
||
- 统一读取活动承诺作为随机源或哈希链起点
|
||
|
||
## 前端改造
|
||
- 活动管理：
|
||
- 操作列显示“生成承诺”与“承诺概览”（适用于所有活动，不再区分玩法）
|
||
- 详情/期次页可显示版本号与算法
|
||
- 一番赏序号映射：只读查看映射；顶部显示当前活动 `seed_version`
|
||
|
||
## 抽奖流程
|
||
- 即时/定时调用策略前：校验活动承诺
|
||
- 抽奖回执携带：`seed_version`、`algo`
|
||
|
||
## 测试与验收
|
||
- 生成承诺版本递增与哈希一致性
|
||
- 策略在承诺存在时正常运行、缺失时明确错误
|
||
- 一番赏映射稳定性（同版本稳定）
|
||
|
||
## 上线步骤
|
||
- 执行 `activities` 字段迁移
|
||
- 接入生成与概览接口
|
||
- 改造策略读取活动承诺
|
||
- 更新前端活动管理显示与按钮
|
||
- 移除前端/后端期级承诺路径（保留表但不访问） |