# 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

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

```ts
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`