Files

km2023 4ad8e7cbec chore: 初始化仓库,配置 Git LFS 管理大素材

- git init (分支 main) + remote origin → gitea comi-logic/vtubermini
- 根级 .gitignore 排除 node_modules/dist/android-build/releases(APK)/日志/.codex-logs
- .gitattributes 用 Git LFS 跟踪 *.png/*.mp4 等媒体(141 个文件)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

2026-06-29 11:19:40 +08:00

23 KiB

Raw Permalink Blame History

Development Plan — VTuber Mini

本文件记录 VTuber Mini 的开发阶段划分、当前进度和剩余工作。新 session 启动时应首先阅读此文件，了解项目状态后再继续开发。

当前状态

产品规格已完成：Product-Spec.md
设计规范已完成：Design-Brief.md
设计交付已存在：design/vtubermini-mvp-v1.pen、design/vtubermini-mvp-v1-preview.png、design/vtubermini-mvp-v1-export.png
代码项目已创建：vtubermini/
Phase 1 已实现并通过 npm.cmd run lint、npm.cmd run build、本地 dev server 访问验证。
Phase 2 已实现并通过 npm.cmd run lint、npm.cmd run build、本地 dev server 访问验证，等待用户确认视觉和交互效果。
Phase 3 已实现并通过 npm.cmd run lint、npm.cmd run build、本地 dev server 访问验证，等待用户确认宠物互动体验。
Phase 4 的小游戏实现已从当前 App 入口和代码中移除，宠物积分回到每日照顾闭环。
Phase 5 已实现并通过 npm.cmd run lint、npm.cmd run build、本地 dev server 访问验证，等待用户确认抽卡和卡册体验。
Phase 6 已实现并通过 npm.cmd run lint、npm.cmd run build、本地 dev server 访问验证，等待用户确认商城兑换和订单体验。
Phase 7 已实现并通过 npm.cmd run lint、npm.cmd run build、本地 dev server 访问验证，等待用户确认纪念日记录和提醒体验。
Phase 8 已实现并通过 npm.cmd run lint、npm.cmd run build、本地 dev server 访问验证，等待用户确认我的页面、流水、规则、客服和通知体验。
Product Spec 已更新至 v1.2，新增宠物玩法目标、积分产出模型、长期养成、情绪反馈和玩法边界。
Product Spec 已更新至 v1.3，小游戏从当前宠物积分闭环中移除；宠物每日照顾满勤仍可获得 80 积分。
当前本机可用：Node.js、npm.cmd、npx.cmd
当前本机不可用或未加入 PATH：Git、Java/JDK、Android SDK、Gradle

Phase 1: React + Capacitor App 骨架

交付内容：

搭建 vtubermini/ 子目录下的 React、TypeScript、Vite、Capacitor 项目骨架。
配置 Tailwind CSS 设计 token，落地 dream-blue、crystal-blue、moon-white、deep-blue、rose-gold。
实现移动端 390px 设计宽度的 App Shell、底部 5 Tab、页面路由和基础页面容器。
创建模拟数据层，提供用户资产、宠物状态、卡池、卡册、商城商品、订单、纪念日数据。
实现首页、宠物、抽卡、商城、我的 5 个 Tab 的静态入口和纪念日二级页入口。

关键文件：

vtubermini/package.json — 项目脚本和依赖声明。
vtubermini/vite.config.ts — Vite 配置。
vtubermini/capacitor.config.ts — Capacitor App 配置。
vtubermini/src/main.tsx — React 入口。
vtubermini/src/App.tsx — App 路由和页面装配。
vtubermini/src/styles/index.css — Tailwind 引入、全局样式和设计 token。
vtubermini/src/components/app-shell.tsx — 移动端应用壳、底部 Tab 和安全区布局。
vtubermini/src/lib/mock-data.ts — MVP 模拟数据源。
vtubermini/src/lib/types.ts — 用户、资产、宠物、卡牌、商品、订单、纪念日类型。

验收标准：

npm.cmd run build 编译通过。
npm.cmd run dev -- --host 127.0.0.1 能启动并显示移动端 App 壳。
浏览器打开本地地址后能切换 5 个底部 Tab，首页能进入纪念日页面。

Phase 2: 首页与基础导航体验

交付内容：

实现深蓝沉浸式首页，展示主播主题视觉、积分余额、钻石余额、活动公告和快捷入口。
实现首页纪念日卡片，展示最近纪念日、倒计时、入团陪伴天数和查看全部入口。
实现公告与活动模块，展示活动规则入口和兑换提醒。
实现空状态、加载状态和错误提示组件的基础样式，供后续页面复用。

关键文件：

vtubermini/src/pages/home-page.tsx — 首页页面。
vtubermini/src/components/home/hero-scene.tsx — 首页深蓝主视觉和主播信息区。
vtubermini/src/components/home/asset-summary.tsx — 积分和钻石资产摘要。
vtubermini/src/components/home/quick-actions.tsx — 宠物、抽卡、商城、纪念日快捷入口。
vtubermini/src/components/home/anniversary-card.tsx — 最近纪念日卡片。
vtubermini/src/components/common/state-block.tsx — 空、加载、错误状态展示。

验收标准：

首页信息层级符合 Design Brief：深蓝主视觉清楚，操作入口不被装饰遮挡。
首页能从纪念日卡片跳转到纪念日页面。
npm.cmd run build 编译通过，底部 Tab 切换不破坏首页状态。

Phase 3: 宠物小屋与积分上限规则

交付内容：

实现宠物小屋页面，展示小狗形象占位、饱腹、心情、清洁、活力、亲密度状态。
实现喂食、抚摸、清洁、玩耍四类互动，更新模拟状态、任务进度和积分流水。
实现每日积分上限 80 分、每日操作次数限制和超限提示。
实现积分钱包摘要和宠物相关积分流水列表。

关键文件：

vtubermini/src/pages/pet-page.tsx — 宠物小屋页面。
vtubermini/src/components/pet/pet-stage.tsx — 小狗主视觉和状态表现。
vtubermini/src/components/pet/pet-stats.tsx — 宠物状态值展示。
vtubermini/src/components/pet/pet-actions.tsx — 宠物互动按钮。
vtubermini/src/components/pet/daily-task-panel.tsx — 今日任务和积分上限。
vtubermini/src/lib/pet-rules.ts — 宠物互动、次数限制、积分上限计算。
vtubermini/src/lib/asset-ledger.ts — 积分流水写入和余额计算。

验收标准：

用户点击宠物互动后能看到状态变化、任务进度变化和积分余额变化。
达到每日次数或每日积分上限后，系统展示明确提示并不再增加积分。
npm.cmd run build 编译通过，首页资产摘要能反映宠物互动后的模拟资产变化。

Phase 4: 小狗小游戏（已退役）

交付内容：

原小游戏方案已从当前 App 入口、路由、类型、服务契约和代码文件中移除。
当前宠物积分来源改为每日看小狗、喂食、抚摸、清洁、玩耍和全部照顾完成奖励。
每日满勤仍受 80 积分上限控制。

关键文件：

vtubermini/src/pages/pet-page.tsx — 当前宠物日常照顾闭环。
vtubermini/src/lib/pet-rules.ts — 当前宠物积分、次数、成长和每日完成奖励规则。
vtubermini/src/services/contracts.ts — 当前服务契约不再包含小游戏结算接口。

验收标准：

App 内无小游戏入口和小游戏可导航路由。
用户通过每日宠物照顾即可拿满 80 积分。
npm.cmd run lint 和 npm.cmd run build 编译通过。

Phase 5: 抽卡、卡池与卡册

交付内容：

实现抽卡页，展示当前卡池、活动时间、单抽成本、稀有度概率、保底进度、重复卡处理规则。
实现单抽和十连抽模拟流程，扣减积分、生成结果、写入抽卡日志。
实现重复卡转积分和预留碎片字段，结果弹窗清楚显示新卡或重复转换。
实现卡册页面，按系列、稀有度、已拥有/未拥有筛选卡牌。

关键文件：

vtubermini/src/pages/gacha-page.tsx — 抽卡页面。
vtubermini/src/pages/album-page.tsx — 卡册页面。
vtubermini/src/components/gacha/pool-summary.tsx — 卡池信息和概率公示。
vtubermini/src/components/gacha/gacha-actions.tsx — 单抽和十连抽操作。
vtubermini/src/components/gacha/gacha-result-modal.tsx — 抽卡结果弹窗。
vtubermini/src/components/album/card-grid.tsx — 卡册网格。
vtubermini/src/lib/gacha-rules.ts — 卡池版本、权重抽取、保底和重复卡规则。

验收标准：

积分不足时不能抽卡，并展示明确原因。
抽卡后积分、卡册、抽卡日志和重复卡转换结果同步更新。
抽卡页清楚展示概率、成本、保底和重复处理规则，npm.cmd run build 编译通过。

Phase 6: 钻石商城与兑换订单

交付内容：

实现钻石商城页面，展示商品图片、名称、规格、库存、钻石价格、发货周期和兑换规则。
实现商品详情和兑换确认流程，校验钻石余额、库存和收货信息必填项。
实现兑换成功后扣减钻石、锁定库存、生成订单和写入钻石流水。
实现订单列表，展示待发货、已发货、已完成、售后中、已取消、已退款状态。

关键文件：

vtubermini/src/pages/shop-page.tsx — 钻石商城页面。
vtubermini/src/pages/product-detail-page.tsx — 商品详情页面。
vtubermini/src/pages/order-list-page.tsx — 兑换订单列表。
vtubermini/src/components/shop/product-card.tsx — 商品卡片。
vtubermini/src/components/shop/exchange-form.tsx — 兑换确认和收货信息表单。
vtubermini/src/components/orders/order-card.tsx — 订单状态卡片。
vtubermini/src/lib/shop-rules.ts — 库存、钻石余额和订单生成规则。

验收标准：

钻石不足、库存不足、收货信息缺失时不能提交兑换，并展示明确原因。
兑换成功后钻石余额、库存、订单记录和钻石流水同步更新。
商城页面不出现充值、购买、提现或用户间交易入口，npm.cmd run build 编译通过。

Phase 7: 纪念日记录与提醒

交付内容：

实现纪念日页面，区分入团时间、系统纪念日和用户自定义纪念日。
实现入团时间设置，展示已陪伴天数和下一次入团周年倒计时。
实现自定义纪念日新增、编辑、删除，支持一次性日期、每年重复、提醒开关和提前提醒天数。
实现站内提醒模拟列表，关联抽卡或商城活动时展示活动规则入口。

关键文件：

vtubermini/src/pages/anniversary-page.tsx — 纪念日页面。
vtubermini/src/components/anniversary/join-date-panel.tsx — 入团时间和陪伴天数。
vtubermini/src/components/anniversary/system-anniversary-list.tsx — 主播生日和开播周年。
vtubermini/src/components/anniversary/custom-anniversary-list.tsx — 用户自定义纪念日列表。
vtubermini/src/components/anniversary/anniversary-edit-modal.tsx — 添加和编辑弹窗。
vtubermini/src/lib/anniversary-rules.ts — 倒计时、周年、重复日期和提醒计算。

验收标准：

用户能设置入团时间，并看到已陪伴天数和周年倒计时。
用户能新增、编辑、删除自定义纪念日，页面排序按即将到来优先。
系统纪念日和用户纪念日视觉分区清楚，npm.cmd run build 编译通过。

Phase 8: 我的页面、资产流水与规则页

交付内容：

实现我的页面，展示账号信息、积分余额、钻石余额和常用入口。
实现积分流水、钻石流水、抽卡记录、规则与协议页面。
实现客服与申诉入口的静态表单，覆盖资产异常、抽卡异常、兑换异常和风控申诉类型。
实现消息通知中心，展示抽卡结果、钻石到账、兑换成功、订单状态和纪念日提醒。

关键文件：

vtubermini/src/pages/my-page.tsx — 我的页面。
vtubermini/src/pages/points-ledger-page.tsx — 积分流水页面。
vtubermini/src/pages/diamond-ledger-page.tsx — 钻石流水页面。
vtubermini/src/pages/gacha-log-page.tsx — 抽卡记录页面。
vtubermini/src/pages/rules-page.tsx — 积分、钻石、抽卡、商城和隐私规则。
vtubermini/src/pages/support-page.tsx — 客服与申诉表单。
vtubermini/src/pages/notifications-page.tsx — 消息通知中心。

验收标准：

我的页面能跳转到资产流水、抽卡记录、订单、纪念日、规则和客服入口。
规则页包含积分规则、钻石规则、概率公示、商城兑换规则、隐私政策和未成年人提示。
所有资产流水能追溯来源、金额、时间和关联业务编号，npm.cmd run build 编译通过。

Phase 9: 后台工坊基础管理

交付内容：

实现桌面宽度的后台工坊入口，使用清晰管理端布局，不沿用前台重玻璃视觉。
实现用户与资产管理，支持查看用户资产、发放积分、发放钻石并填写原因。
实现卡牌与卡池管理，支持查看卡牌、稀有度、概率、保底规则和卡池版本。
实现商城商品与兑换订单管理，支持查看库存、上下架状态和订单发货状态。
实现纪念日配置管理，支持配置主播生日、开播周年、主题图说明和活动入口。
实现操作审计日志列表，记录操作人、时间、对象、原因和审批状态。

关键文件：

vtubermini/src/admin/admin-app.tsx — 后台工坊入口。
vtubermini/src/admin/admin-layout.tsx — 后台布局、导航和页面容器。
vtubermini/src/admin/pages/admin-dashboard.tsx — 后台概览。
vtubermini/src/admin/pages/user-assets-page.tsx — 用户与资产管理。
vtubermini/src/admin/pages/card-pool-page.tsx — 卡牌与卡池管理。
vtubermini/src/admin/pages/shop-orders-page.tsx — 商品与订单管理。
vtubermini/src/admin/pages/anniversary-config-page.tsx — 纪念日配置管理。
vtubermini/src/admin/pages/audit-log-page.tsx — 操作审计日志。

验收标准：

浏览器能在移动端 App 和后台工坊之间切换入口。
后台资产发放必须要求填写原因，并写入模拟资产流水和操作审计。
后台表格、筛选和日志信息可读，npm.cmd run build 编译通过。

Phase 10: 服务端接口契约与本地可信规则模拟

交付内容：

抽离前端模拟业务规则，定义服务端接口契约和请求/响应类型。
实现本地 API 适配层，把积分、钻石、抽卡、订单、纪念日和后台发放统一改为异步服务调用。
创建服务端可信规则文档，明确前端不能自行决定积分、钻石、抽卡结果或订单状态。
增加错误路径：网络失败、余额不足、库存不足、卡池下架、重复提交和表单校验失败。

关键文件：

vtubermini/src/services/api-client.ts — 前端 API 客户端。
vtubermini/src/services/contracts.ts — API 请求和响应类型。
vtubermini/src/services/mock-server.ts — 本地内存服务端模拟。
vtubermini/src/services/service-errors.ts — 业务错误码和错误文案。
vtubermini/docs/api-contract.md — 服务端接口契约。
vtubermini/docs/trusted-rules.md — 服务端可信规则说明。

验收标准：

前端页面不再直接调用规则函数修改资产，统一通过服务层请求。
所有核心业务错误有明确错误码和用户可读文案。
npm.cmd run build 编译通过，宠物、抽卡、商城、后台发放的主流程仍可用。

Phase 11: Android 工程接入与打包准备

交付内容：

初始化 Capacitor Android 工程，配置 App 名称、包名、图标占位和启动页占位。
补充 Android 构建环境检查脚本，检测 JDK、Android SDK、Gradle 和 adb。
编写 APK 打包说明，明确本机缺少 JDK/Android SDK 时的安装前置条件。
在 Android 构建环境可用后执行 Web 构建、Capacitor 同步和 Android Debug APK 构建。

关键文件：

vtubermini/android/ — Capacitor Android 工程。
vtubermini/scripts/check-android-env.mjs — Android 构建环境检查脚本。
vtubermini/docs/android-build.md — Android 打包和环境配置说明。
vtubermini/capacitor.config.ts — Android App 名称、包名和 Web 输出路径。

验收标准：

npm.cmd run build 成功生成 Web 构建产物。
npm.cmd run cap:sync 在 Android 工程存在且依赖可用时同步成功。
本机安装 JDK 和 Android SDK 后，能按 docs/android-build.md 构建 Debug APK。

Phase 12: 宠物玩法 v2 补强

交付内容：

按 Product Spec v1.3 调整宠物积分模型：登录看小狗 10 分、喂食 20 分、抚摸 21 分、清洁 10 分、玩耍互动 14 分、全部照顾完成奖励 5 分，总上限仍为每日 80 分。
补齐每日照顾闭环：今日登录看小狗、全部照顾完成状态、连续照顾天数、累计照顾天数、今日推荐动作和积分接近单抽成本时的抽卡提示。
增加轻量亲密等级：根据亲密度展示 Lv.1-Lv.10、当前等级称号和下一等级进度；不影响抽卡概率、积分倍率或商城兑换。
优化宠物页情绪体验：主视觉展示状态短句，互动成功反馈同时包含陪伴文案和积分变化，达到上限后明确提示继续互动只增加亲密度。
优化交互状态：达到每日次数的操作按钮禁用并显示“已完成”，今日任务区显示全部照顾完成态，底部展示今日积分进度和抽卡入口。

关键文件：

vtubermini/src/lib/types.ts — 扩展宠物状态字段：亲密等级、每日登录、全部照顾完成、连续照顾、累计照顾。
vtubermini/src/lib/pet-rules.ts — 宠物互动、登录看小狗、全部照顾完成奖励、推荐动作和亲密等级计算。
vtubermini/src/lib/mock-data.ts — 补齐宠物 v2 初始模拟数据。
vtubermini/src/components/pet/pet-stage.tsx — 主视觉状态短句、今日推荐动作和亲密等级展示。
vtubermini/src/components/pet/pet-actions.tsx — 按钮禁用态和已完成文案。
vtubermini/src/pages/pet-page.tsx — 宠物页抽卡轻提示和整体信息顺序。
vtubermini/src/pages/rules-page.tsx — 更新积分规则文案。
vtubermini/docs/api-contract.md、vtubermini/docs/trusted-rules.md — 同步宠物 v2 服务端可信规则。

验收标准：

用户进入宠物页即可触发或展示“登录看小狗”进度，今日积分模型能跑满但不超过 80 分。
四项每日照顾全部完成后，只发放一次完成奖励；达到积分上限后不再增加积分，但仍可展示亲密度或陪伴反馈。
亲密等级、连续照顾、今日推荐动作、全部照顾完成态和抽卡轻提示能在宠物页清楚展示。
宠物状态不影响抽卡概率、积分倍率、商城价格或实物兑换资格。
npm.cmd run lint 和 npm.cmd run build 编译通过。

技术栈

层级	技术	版本	说明
运行时	Node.js	24.16.0	当前本机已安装版本，用于开发和构建。
包管理	npm	11.13.0	当前本机 `npm.cmd` 可用；PowerShell 中避免直接调用 `npm.ps1`。
前端框架	React	19.x	构建移动 App 和后台工坊界面。
构建工具	Vite	8.x	React + TypeScript 开发服务器和生产构建。
类型系统	TypeScript	5.x	开启 strict mode，禁止业务代码使用 `any`。
样式	Tailwind CSS	4.x	设计 token、响应式布局和组件样式。
移动壳	Capacitor	8.x	Web App 打包为 Android 工程和 APK。
图标	lucide-react	0.x	按钮、Tab、状态和入口图标。
本地数据	内存模拟服务	项目内实现	Phase 1-9 使用，Phase 10 抽象为服务接口，后续可替换云端 API。
Android 构建	Android SDK + JDK + Gradle	系统环境	当前本机缺失；Phase 11 前必须安装并配置。

数据库表

表名	所属 Phase	用途
`users`	Phase 10	用户身份、昵称、头像、登录状态和账号基础信息。
`user_assets`	Phase 10	用户积分余额、钻石余额和碎片余额。
`asset_ledger`	Phase 10	积分、钻石、碎片的获得、消耗、退回和后台发放流水。
`pet_states`	Phase 10 / Phase 12	饱腹、心情、清洁、活力、亲密度、亲密等级、连续照顾天数、累计照顾天数、装备状态和回忆节点。
`daily_task_states`	Phase 10 / Phase 12	每日积分获得量、每日积分上限、登录看小狗状态、全部照顾完成状态、互动次数和重置日期。
`pet_items`	Phase 12 后续	宠物装饰配置，包括头饰、颈饰、小窝背景、来源、解锁条件和上下架状态。
`pet_memories`	Phase 12 后续	宠物回忆节点配置，包括触发条件、标题、文案、关联纪念日或抽卡事件。
`cards`	Phase 10	卡牌编号、系列、稀有度、名称、图片和上下架状态。
`card_pools`	Phase 10	卡池标识、版本、活动时间、消耗积分、保底规则和重复规则。
`card_pool_entries`	Phase 10	卡池版本内的卡牌范围、稀有度权重和概率配置。
`owned_cards`	Phase 10	用户拥有的卡牌、获取时间、来源和重复次数。
`gacha_logs`	Phase 10	每次抽卡的卡池版本、消耗、结果、重复转换和业务流水编号。
`shop_products`	Phase 10	商城商品、规格、图片、钻石价格、库存、发货周期和售后规则。
`exchange_orders`	Phase 10	兑换订单、收货信息、库存锁定、物流状态和售后状态。
`anniversaries`	Phase 10	入团时间、主播生日、开播周年和用户自定义纪念日。
`notifications`	Phase 10	站内通知、纪念日提醒、钻石到账、兑换和订单状态消息。
`support_tickets`	Phase 10	资产异常、抽卡异常、兑换异常和风控申诉记录。
`admin_audit_logs`	Phase 10	后台操作人、时间、对象、原因、审批状态和业务流水编号。

开发规则

代码放在 vtubermini/ 子目录，根目录保留规划文档和设计资产。
每个 Phase 开始前先读取本文件、Product-Spec.md 和 Design-Brief.md 中对应章节。
每完成一个 Phase 执行四步走：Code Review → 测试完整性 → 编译验证 → 功能测试。
四步走全部通过后才能确认 Phase 完成。
Commit message 格式：phase-N: 简要描述；当前本机 Git 不可用时先跳过提交并记录原因。
包管理器使用 npm.cmd。
业务资产规则必须逐步收敛到服务层；前端页面不能长期直接决定积分、钻石、抽卡结果或订单状态。
毛玻璃仅用于容器背景，关键数字、概率、价格、库存和订单状态必须保持高对比度可读。
MVP 不实现充值、提现、用户间交易、卡牌转卖、多主播入驻、多只宠物、复杂会员体系。

23 KiB Raw Permalink Blame History Unescape Escape

Development Plan — VTuber Mini

当前状态

Phase 1: React + Capacitor App 骨架

Phase 2: 首页与基础导航体验

Phase 3: 宠物小屋与积分上限规则

Phase 4: 小狗小游戏（已退役）

Phase 5: 抽卡、卡池与卡册

Phase 6: 钻石商城与兑换订单

Phase 7: 纪念日记录与提醒

Phase 8: 我的页面、资产流水与规则页

Phase 9: 后台工坊基础管理

Phase 10: 服务端接口契约与本地可信规则模拟

Phase 11: Android 工程接入与打包准备

Phase 12: 宠物玩法 v2 补强

技术栈

数据库表

开发规则

最新进度补充

23 KiB

Raw Permalink Blame History