vtubermini/Development-Requirements-Breakdown.md

VTuber Mini 开发需求拆解文档

1. 项目定位

VTuber Mini 是一个面向单个虚拟主播粉丝的 Android 优先 App。第一阶段目标不是做通用多主播平台，而是交付一个可运营的粉丝互动闭环：

• 粉丝每日照顾主播动物化小狗，获得积分。
• 粉丝用积分抽取主播虚拟小卡，并在卡册中收藏。
• 运营通过后台发放钻石。
• 粉丝用钻石在商城兑换实物周边。
• 粉丝记录入团时间、主播生日、开播周年和自定义纪念日。
• 运营通过后台管理资产、卡池、商城、订单、纪念日配置和审计日志。

当前项目状态：前端可交互 MVP 已搭建，业务规则目前在本地 mock service 中模拟。生产化仍需要真实后端、数据库、鉴权、权限、风控、订单履约和 Android 构建环境。

2. 开发分工建议

分工	负责范围	主要交付
A 前台基础体验	App 壳、登录、首页、我的、规则、通知	移动端主流程、导航、入口、规则和用户中心
B 宠物与积分	宠物小屋、每日任务、积分上限、积分流水	每日照顾闭环和积分可信结算接口
C 抽卡收藏	卡池、抽卡、卡册、抽卡日志、重复卡处理	抽卡体验、概率公示、卡牌资产记录
D 商城订单	钻石钱包、商品、兑换、订单、库存	钻石兑换实物周边闭环
E 纪念日	入团时间、系统纪念日、自定义纪念日、提醒	陪伴关系记录和提醒能力
F 后台与服务端	后台工坊、API、数据库、审计、风控	生产可信业务服务
G 构建交付	Capacitor、Android 环境、APK、发布说明	Android 可安装包和构建文档

3. 前台 App 需求

3.1 App 壳与登录

目标：用户能稳定进入 App，并在核心模块之间切换。

需求

• Android 优先，使用 React + Vite + TypeScript + Capacitor。
• 底部 5 个主 Tab：首页、宠物、抽卡、商城、我的。
• 二级页包括纪念日、卡册、订单、积分流水、钻石流水、抽卡记录、规则、客服、通知。
• 登录后加载用户资产、宠物状态、卡册、订单、纪念日等个人数据。

验收

• 5 个 Tab 切换不丢状态。
• 未登录用户不能进入业务主界面。
• 用户身份必须绑定资产、卡册、订单、纪念日数据。

3.2 首页

目标：让用户快速看到主播氛围、个人资产和核心入口。

需求

• 展示主播主题视觉。
• 展示积分余额和钻石余额。
• 提供宠物、抽卡、商城、纪念日、活动等快捷入口。
• 展示最近纪念日卡片和公告活动。

验收

• 资产数字与服务端返回一致。
• 所有核心入口可点击进入。
• 视觉装饰不能遮挡操作入口。

3.3 宠物小屋

目标：用户每日照顾主播小狗，形成回访和积分产出。

需求

• 展示小狗状态：饱腹、心情、清洁、活力、亲密度、亲密等级。
• 支持每日看小狗奖励。
• 支持喂食、抚摸、清洁、玩耍四类互动。
• 每日积分上限暂定 80。
• 展示今日任务进度、今日剩余可获得积分、连续照顾天数、累计照顾天数。
• 达到每日上限后，继续互动只能增加陪伴反馈或亲密度，不能继续发积分。

验收

• 每日照顾可跑满 80 分，但不能超过 80 分。
• 每类互动达到每日次数后应禁用或提示已完成。
• 积分发放必须写资产流水。
• 宠物状态不得影响抽卡概率、积分倍率、商城价格或实物兑换资格。

3.4 抽卡与卡册

目标：用户用积分抽取主播小卡，并沉淀收藏。

需求

• 展示当前卡池、卡池版本、活动时间、单抽成本、概率、保底、重复卡处理规则。
• 支持单抽和十连。
• 抽卡消耗积分。
• 抽中卡牌后写入用户卡册。
• 重复卡自动转换为碎片或积分，第一阶段可先转积分，但需要保留碎片字段。
• 抽卡记录要包含卡池版本、消耗、结果、是否重复、转换结果。
• 卡册支持按系列、稀有度、拥有状态筛选。

验收

• 积分不足不能抽卡。
• 卡池下架不能抽卡。
• 抽卡结果、扣积分、发卡、重复转换、日志必须同事务完成。
• 概率、成本、保底和重复规则在页面明确展示。

3.5 钻石商城与订单

目标：用户用后台发放的钻石兑换实物周边。

需求

• 展示商品图片、名称、规格、库存、钻石价格、发货周期、兑换规则、售后说明。
• 用户提交收货人、手机号、地址后兑换。
• 兑换时校验钻石余额、库存、商品状态、收货信息。
• 成功后扣钻石、锁定或扣减库存、生成订单、写钻石流水。
• 订单展示待发货、已发货、已完成、售后中、已取消、已退款等状态。

验收

• 钻石不足、库存不足、地址缺失时不能提交。
• 兑换成功后余额、库存、订单、流水同步更新。
• 前台不出现充值、购买钻石、提现、转赠、用户间交易入口。

3.6 纪念日

目标：记录粉丝和主播的陪伴关系。

需求

• 支持设置入团时间，并展示已陪伴天数和下一次入团周年倒计时。
• 展示系统纪念日：主播生日、开播周年。
• 支持用户自定义纪念日：名称、日期、是否每年重复、提醒开关、提前提醒天数、备注。
• 纪念日列表按即将到来排序。
• 纪念日提醒可以先做站内模拟，后续接推送。

验收

• 用户能新增、编辑、删除自己的自定义纪念日。
• 系统纪念日和用户纪念日视觉分区清楚。
• 纪念日默认不直接发积分或钻石，奖励必须走活动配置或后台资产发放。

3.7 我的、规则、客服、通知

目标：用户能查账、查规则、查看通知并提交问题。

需求

• 我的页展示账号信息、积分余额、钻石余额。
• 入口包括积分流水、钻石流水、抽卡记录、卡册、订单、纪念日、规则、客服、通知。
• 规则页包含积分规则、钻石规则、抽卡概率、商城兑换、隐私政策、未成年人提示。
• 客服申诉覆盖资产异常、抽卡异常、兑换异常、风控申诉。
• 通知中心展示抽卡结果、钻石到账、兑换成功、订单状态、纪念日提醒。

验收

• 所有入口可达。
• 资产流水可追溯来源、金额、时间和业务编号。
• 规则信息与实际业务规则一致。

4. 后台工坊需求

4.1 用户与资产管理

需求

• 查看用户基础信息和资产余额。
• 给指定用户发放积分、钻石或卡牌。
• 发放必须填写原因。
• 发放必须写资产流水和后台审计日志。

验收

• 无原因不能发放。
• 普通用户不能调用后台发放接口。
• 审计日志包含操作人、时间、对象、原因、业务编号和状态。

4.2 卡牌与卡池管理

需求

• 管理卡牌：名称、系列、稀有度、图片、上下架状态。
• 管理卡池：版本、活动时间、成本、概率、保底、重复卡规则、上下架状态。
• 概率或卡牌范围变更时创建新版本，不覆盖历史版本。

验收

• 历史抽卡记录能追溯到当时卡池版本。
• 卡池不能为空奖。
• 概率配置必须可公示。

4.3 商城与订单管理

需求

• 管理商品：图片、名称、规格、钻石价格、库存、上下架、发货周期、售后规则。
• 管理订单：待发货、已发货、已完成、售后中、已取消、已退款。
• 后台可填写物流信息和处理售后状态。

验收

• 下架商品不能兑换。
• 库存不能超卖。
• 订单状态变更有审计记录。

4.4 纪念日配置

需求

• 配置主播生日、开播周年、主题图、祝福文案、活动入口。
• 系统纪念日用户不可直接编辑。

验收

• 前台能读取后台配置。
• 系统纪念日和用户自定义纪念日权限隔离。

5. 服务端与数据需求

5.1 核心 API

建议保持当前服务响应结构：

interface ServiceResponse<T> {
  ok: boolean
  data?: T
  error?: {
    code: string
    message: string
  }
}

核心接口：

接口	用途
GET /api/me/state	获取用户首页聚合状态
POST /api/pet/visit	每日看小狗奖励
POST /api/pet/actions	宠物互动与积分结算
POST /api/gacha/draw	积分抽卡
POST /api/shop/exchange	钻石兑换商品
POST /api/admin/assets/grants	后台资产发放
PATCH /api/anniversaries/join-date	设置入团时间
POST /api/anniversaries/custom	新增或编辑自定义纪念日
DELETE /api/anniversaries/custom/{id}	删除自定义纪念日

5.2 数据表

表	用途
users	用户身份、昵称、生日、基础资料
user_assets	积分、钻石、碎片余额
asset_ledger	所有资产变更流水
pets	宠物状态、亲密度、连续照顾
pet_daily_states	每日任务、次数、每日积分上限
cards	卡牌配置
user_cards	用户持卡与重复次数
gacha_pools	卡池版本与规则
gacha_pool_rates	卡池概率配置
gacha_logs	抽卡主日志
gacha_log_items	抽卡结果明细
shop_products	商城商品
exchange_orders	兑换订单
anniversaries	系统和用户纪念日
notifications	站内通知
support_tickets	客服申诉
admin_audit_logs	后台操作审计

5.3 服务端可信规则

• 前端不能决定积分、钻石、碎片余额。
• 前端不能生成抽卡结果。
• 前端不能决定订单最终状态。
• 宠物奖励、抽卡、兑换、后台发放必须由服务端事务处理。
• 所有资产变更必须写流水。
• 抽卡扣款、发卡、重复转换、日志、保底进度必须同事务完成。
• 商城扣钻、锁库存、生成订单必须同事务完成。
• 后台发放必须鉴权、记录原因、写审计。

6. 合规与风控要求

• 抽卡页必须展示概率、成本、卡池范围、保底、重复卡处理规则。
• 卡池概率变更必须创建新版本。
• 不允许空奖。
• MVP 不开放钻石充值、转赠、提现、二级交易。
• 实物兑换涉及姓名、手机号、地址，必须做权限控制、日志脱敏和数据保留策略。
• 需要预留未成年人提示、隐私政策和活动规则展示。
• 需要处理重复提交、库存并发、余额并发、抽卡重复扣款、每日奖励多端重复领取。

7. Android 构建交付

当前状态

• Capacitor Android 工程已存在。
• 当前本机缺 JDK、Android SDK、adb、Gradle，无法直接完成 Debug APK 构建。

需求

• 补齐 Android 构建环境。
• 执行 Web 构建和 Capacitor 同步。
• 输出可安装 Debug APK。
• 保留构建文档和环境检查脚本。

验收

• npm.cmd run lint 通过。
• npm.cmd run build 通过。
• npm.cmd run check:android 不再报关键缺项。
• npm.cmd run cap:sync 成功。
• 生成 Android Debug APK。

8. 第一阶段不做

• 多主播入驻。
• 用户充值钻石。
• 付费抽卡。
• 用户间交易、卡牌转卖、提现、二级市场。
• 多只宠物、宠物繁殖、战斗、开放地图。
• 社区动态、评论、私信。
• 复杂会员体系。
• AI 能力接入。

9. 开发前必须确认的问题

问题	影响
宠物奖励到底发积分还是钻石？每日 80 上限约束哪种资产？	影响宠物规则、资产流水、经济系统
商城兑换到底扣钻石还是积分？diamondPrice 字段是否修正？	影响商城、订单、资产表设计
喂食是否和其他互动一样受每日次数和每日上限限制？	影响宠物风控和刷资产风险
抽卡是否需要真实随机、种子审计、概率快照和保底继承？	影响抽卡后端实现和合规
商品是否有每账号限购？	影响商城订单规则
订单是否需要取消、退款、售后、物流单号、地址修改窗口？	影响订单状态机和后台
后台发放是否需要审批流？	影响后台权限、审计和运营流程
纪念日提醒是否需要真实推送？提醒时间是否按用户时区处理？	影响通知服务和定时任务
碎片资产是否保留第一阶段可见入口？	影响重复卡处理和后续兑换

10. 关联文件

• 产品需求：Product-Spec.md
• 设计规范：Design-Brief.md
• 开发计划：DEV-PLAN.md
• 需求关系图：Requirement-Breakdown.mmd
• API 契约：vtubermini/docs/api-contract.md
• 可信规则：vtubermini/docs/trusted-rules.md
• Android 构建说明：vtubermini/docs/android-build.md