zfc/bindbox-game
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
bindbox-game/docs/需求文档.md
邹方成 6ee627139c
Some checks failed
Build docker and publish / linux (1.24.5) (push) Failing after 40s
Details
feat: 新增支付测试小程序与微信支付集成 
feat(pay): 添加支付API基础结构
feat(miniapp): 创建支付测试小程序页面与配置
feat(wechatpay): 配置微信支付参数与证书
fix(guild): 修复成员列表查询条件
docs: 更新代码规范文档与需求文档
style: 统一前后端枚举显示与注释格式
refactor(admin): 重构用户奖励发放接口参数处理
test(title): 添加称号效果参数验证测试
2025-11-17 00:42:08 +08:00

11 KiB
Raw Blame History

一、业务一句话概述
你构建的是一个以“活动期”为载体的盲盒抽奖与商品售卖平台，支持用户参与抽奖、生成订单并支付，中奖/购买后产生成交与持仓记录，可进行转赠、发货，平台提供优惠券与积分体系以促进转化，同时具备邀请裂变、公会协作与玩法扩展（如 Boss 排行），形成完整的增长-交易-履约闭环。

二、用户视角的核心流程

  1. 账号与身份
    • 用户注册/登录（微信为主），维护用户基本资料与收货地址（user_members / user_addresses）。
  2. 活动参与
    • 浏览活动及分类（activity / activity_categories），在具体期（activity_issues）参与抽奖或直接购买。
    • 抽奖行为与结果记录（draw_logs），中奖奖品与参与信息可追溯。
  3. 交易与支付
    • 下单（order_headers + order_items），支持积分、优惠券抵扣（user_points / user_coupons / coupons）。
    • 支付流程（payment_preorders / payment_refunds），异常场景可退款。
  4. 资产与履约
    • 奖品持有（user_inventory）与转赠（inventory_transfers），不引入复杂状态机，使用流水记录事实与最终归属。
    • 发货（shipping_sheets，对应发货单），后续可扩展发货明细（shipping_items）。
  5. 社交与增长
    • 邀请裂变（user_invites），通过用户唯一邀请码（user_members.invite_code）建立 inviter-invitee 关系，奖励以积分或优惠券落地。
    • 公会互动（guild_main / guild_members / guild_boxes / guild_contribute_logs），支持公会玩法与贡献日志。
  6. 玩法扩展
    • Boss 排行（leaderboard_boss_players）等玩法可在活动域或独立域扩展。
  7. 平台通知
    • 系统公告（system_notices）与系统配置（system_configs），支持运营触达与配置管理。

三、运营视角的能力闭环

  1. 增长与激励
    • 邀请裂变：唯一邀请码与邀请关系，奖励结算可选积分或优惠券。
    • 积分体系：支持签到等行为积分，具备“每日一次”约束的唯一索引设计，利于并发安全。
    • 优惠券体系：券模板（coupons）支持适用范围（全局/活动/商品），用户持券与使用记录（user_coupons）清晰。
  2. 商品与内容运营
    • 商品与分类（product_main / product_categories / product_category_map），活动期配置（activity_issues / activity_reward_settings）。
    • 公告与配置（system_notices / system_configs）用于活动宣导与功能开关。
  3. 履约与服务
    • 发货单（shipping_sheets），配合订单与地址进行物流履约。
    • 转赠流水（inventory_transfers）增强用户间互动与资产流通。

我现在要做一个盲盒系统小程序,数据库我已经设计好了,现在我和你说业务需求 活动(盲盒抽奖):

  1. 有活动列表: 1.1 用户可以自己点击对应的活动 1.2 每个活动都有标签: 对应的活动类型 / 活动是否 Boss挑战 标签 1.3 创建活动是: activities 创建一个记录; 然后对应的 activity_issues 创建一个记录, 记录活动的期数;这样的目的是 一个活动可以有多个期数 1.3.1 例如 对对碰 一个活动 一个期数 1.3.2 例如 一番赏 一个活动 多个期数 1.4 创建好活动的时候可以根据活动分类来设置类型 1.5 每个活动也可以配置奖品 1.6 活动也可以设置是否为 boss 活动

  2. 活动接口: 后台接口:

    1. 创建活动: /api/admin/activities
    2. 修改活动: /api/admin/activities/:activity_id
    3. 删除活动: /api/admin/activities/:activity_id
    4. 查看活动详情: /api/admin/activities/:activity_id
    5. 查看活动期数: /api/admin/activities/:activity_id/issues
    6. 创建期数奖品: /api/admin/activities/:activity_id/issues/:issue_id/rewards
    7. 查看期数奖品: /api/admin/activities/:activity_id/issues/:issue_id/rewards
    8. 创建活动期数: /api/admin/activities/:activity_id/issues
    9. 修改活动期数: /api/admin/activities/:activity_id/issues/:issue_id
    10. 删除活动期数: /api/admin/activities/:activity_id/issues/:issue_id

    app用户接口:

    1. 浏览活动列表: /api/app/activities
    2. 查看活动详情: /api/app/activities/:activity_id
    3. 查看活动期数: /api/app/activities/:activity_id/issues
    4. 查看期数奖品: /api/app/activities/:activity_id/issues/:issue_id/rewards
    5. 查看活动抽奖记录: /api/app/activities/:activity_id/issues/:issue_id/draw_logs

工会(公会):

  1. 需求: 1.1 用户可以自己点击对应的工会 1.2 每个工会都有标签: 对应的工会类型 / 工会是否公开 标签 1.3 创建工会是: guild 创建一个记录; 然后对应的 guild_members 创建一个记录, 记录工会的成员;这样的目的是 一个工会可以有多个成员 1.3.1 例如 一对情侣 一个工会 两个成员 1.3.2 例如 一个团队 一个工会 多个成员 1.3.3 创建公会的时候 默认 第一个人是会长 1.3.4 其他成员加入工会的时候, 会创建一个 guild_members 记录, 记录成员的加入时间 1.4 创建好工会的时候可以根据工会分类来设置类型 1.5 工会也可以设置是否为公开工会 1.6 用户离开公会后 24 小时不允许加入公会

  2. 工会接口: 后台接口:

    1. 创建工会: /api/admin/guilds
    2. 修改工会: /api/admin/guilds/:guild_id
    3. 删除工会: /api/admin/guilds/:guild_id
    4. 查看工会详情: /api/admin/guilds/:guild_id
    5. 查看工会成员: /api/admin/guilds/:guild_id/members

  3. app用户接口:

    1. 浏览工会列表: /api/app/guilds
    2. 查看工会详情: /api/app/guilds/:guild_id
    3. 加入工会: /api/app/guilds/:guild_id/members
    4. 离开公会: /api/app/guilds/:guild_id/members/:user_id
    5. 查看工会成员: /api/app/guilds/:guild_id/members

用户(用户):

  1. 需求: 1.1 用户可以注册登录: weixin 登录 1.2 用户可以查看自己的个人信息 1.3 用户可以修改自己的个人信息 1.4 用户可以查看自己邀请记录 1.5 可以看到自己的订单记录 1.6 用户可以看到自己的优惠券 1.7 用户可以查看自己的积分记录 和 积分余额

用户在登录的时候: 判断如果 链接里面有 code=这个参数; 那么代表是被邀请用户; 需要登录的时候携带这个参数; 后台会判断这个参数(是否可以根据这个参数找到邀请人), 然后在 邀请表中写入一个记录, 如果已经邀请了则不下发积分奖励; 如果没有邀请过, 则下发积分奖励 用户可以编辑修改自己的用户信息: 昵称 + 头像 当用户加入工会后是可以看到自己的工会成员的 用户可以在订单中 找到自己的订单记录(来源是 活动抽奖得到的) 现在帮我完成这个需求; 一定需要记住: 这个是app端的接口; api 和 service 需要 遵守拆分规则 , 然后需要协商接口文档; 同时注意 req / res 这个需要在自己的代码中定义好; 接口: 1. 修改用户信息: /api/app/users/:user_id 2. 查看用户订单记录: /api/app/users/:user_id/orders 3. 查看用户优惠券: /api/app/users/:user_id/coupons 4. 查看用户积分记录: /api/app/users/:user_id/points 5. 查看用户积分余额: /api/app/users/:user_id/points/balance 6. 微信登录: /api/app/users/weixin/login 7. 查看用户邀请记录: /api/app/users/:user_id/invites

用户(admin管理端)

  1. 查看所有用户列表: /api/admin/users
  2. 可以查看到用户邀请列表: /api/admin/users/:user_id/invites
  3. 可以查看到用户订单列表: /api/admin/users/:user_id/orders
  4. 可以查看到用户优惠券列表: /api/admin/users/:user_id/coupons
  5. 可以查看到用户积分记录列表: /api/admin/users/:user_id/points
  6. 可以查看到用户积分余额: /api/admin/users/:user_id/points/balance
  7. 可以给用户添加积分: /api/admin/users/:user_id/points/add
  8. 可以给用户添加优惠券: /api/admin/users/:user_id/coupons/add

商品管理:(product_categories / products)

  1. 后台管理: 1.1 创建商品分类: /api/admin/product_categories 1.2 修改商品分类: /api/admin/product_categories/:category_id 1.3 删除商品分类: /api/admin/product_categories/:category_id 1.4 查看商品分类列表: /api/admin/product_categories 1.5 创建商品: /api/admin/products 1.6 修改商品: /api/admin/products/:product_id 1.7 删除商品: /api/admin/products/:product_id 1.8 查看商品列表: /api/admin/products

@6A 现在有以下问题需要修改

  1. 用户查看自己的优惠券 接口有问题: 'http://127.0.0.1:9991/api/app/users/12/coupons?page=1&page_size=20' 这里不应该用 user_id 来查询; 应该用 token 来查询; 因为用户可以查看自己的优惠券, 但是其他用户不能查看; 所以这里应该用 token 来查询;
  2. 优惠券返回的信息中; 应该包含 优惠券的名称, 优惠券的金额, 优惠券的有效期, 优惠券的使用规则;
  3. 用户邀请记录也是 接口有问题: 'http://127.0.0.1:9991/api/app/users/12/invites?page=1&page_size=20' 这里不应该用 user_id 来查询; 应该用 token 来查询; 因为用户可以查看自己的邀请记录, 但是其他用户不能查看; 所以这里应该用 token 来查询;
  4. 其他的 接口都存在这个问题 修复一下

仪表盘数据分析:

  1. 总访问次数 在线访客数 点击量 新用户 : 这一块我想改成:道具卡销量 / 活动抽奖次数 / 新用户注册数 用户总积分

  2. 用户概述: 想统计出 用户增长趋势 访问量: 改成活动抽奖量统计

  3. 新用户:这里面可以放用户 积分 资产等数据

  4. 动态: 显示实时抽奖数据

  5. 代办事项: 显示用户需要完成的任务; 比如 绑定手机号 绑定邮箱 绑定工会

现在帮我检查一下go的代码规范:

  1. api: 规范是这样的: 1.1 必须要有 接口文档 注释 1.2 入参出参: req / res 例如 req := new(modifyActivityRequest) res := new(simpleMessageResponse) 1.3 api 只做 路由和参数控制 1.4 必须分层次; 例如 活动: curd 需要按照activity_xxx
  2. service 2.1 做业务处理 配合 api调用 2.2 所有的代码都需要注释 2.3 必须分层次; 例如 活动: curd 需要按照activity_xxx 和 api 对应