zfc/bindbox-game
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
bindbox-game/docs/需求文档.md
邹方成 42e7cb5f12
Some checks failed
Build docker and publish / linux (1.24.5) (push) Failing after 31s
Details
feat(interceptor): 添加APP端token验证接口并实现用户私有数据鉴权 
refactor(api/user): 重构用户相关接口使用token验证替代user_id路径参数

docs: 更新API文档规范，明确私有接口需携带token及返回字段要求

fix(service/user): 避免写入未使用字段的零值导致MySQL校验错误

style: 统一格式化部分代码缩进和导入顺序

chore: 更新DS_Store等IDE配置文件
2025-11-15 00:49:53 +08:00

170 lines
10 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

一、业务一句话概述
你构建的是一个以“活动期”为载体的盲盒抽奖与商品售卖平台，支持用户参与抽奖、生成订单并支付，中奖/购买后产生成交与持仓记录，可进行转赠、发货，平台提供优惠券与积分体系以促进转化，同时具备邀请裂变、公会协作与玩法扩展（如 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. 代办事项: 显示用户需要完成的任务; 比如 绑定手机号 绑定邮箱 绑定工会
Reference in New Issue View Git Blame Copy Permalink