zfc/bindbox-game
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
bindbox-game/docs/需求文档.md
邹方成 1ab39d2f5a
Some checks failed
Build docker and publish / linux (1.24.5) (push) Failing after 25s
Details
refactor: 重构项目结构并重命名模块 
feat(admin): 新增工会管理功能
feat(activity): 添加活动管理相关服务
feat(user): 实现用户道具卡和积分管理
feat(guild): 新增工会成员管理功能

fix: 修复数据库连接配置
fix: 修正jwtoken导入路径
fix: 解决端口冲突问题

style: 统一代码格式和注释风格
style: 更新项目常量命名

docs: 添加项目框架和开发规范文档
docs: 更新接口文档注释

chore: 移除无用代码和文件
chore: 更新Makefile和配置文件
chore: 清理日志文件

test: 添加道具卡测试脚本
2025-11-14 21:10:00 +08:00

8.8 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