zfc/bindbox-game
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
bindbox-game/.trae/documents/活动级通用承诺（Commitment）体系改造方案.md
邹方成 45815bfb7d chore: 清理无用文件与优化代码结构 
refactor(utils): 修复密码哈希比较逻辑错误
feat(user): 新增按状态筛选优惠券接口
docs: 添加虚拟发货与任务中心相关文档
fix(wechat): 修正Code2Session上下文传递问题
test: 补充订单折扣与积分转换测试用例
build: 更新配置文件与构建脚本
style: 清理多余的空行与注释
2025-12-18 17:35:55 +08:00

2.3 KiB
Raw Blame History

核心原则

  • 承诺是活动级属性：所有活动均需生成并持有承诺；抽奖只能在承诺存在的活动上执行
  • 不做旧期兼容：不读取/维护期级承诺表；全量切换到活动级承诺

数据模型（仅 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 字段迁移
  • 接入生成与概览接口
  • 改造策略读取活动承诺
  • 更新前端活动管理显示与按钮
  • 移除前端/后端期级承诺路径（保留表但不访问）