## 产品需求文档
### 1. 产品概述
- **app名称**：Rvix
- **产品描述**：Rvix 是一款轻量级「物品归位」益智游戏。玩家将打乱的生活用品拖拽到正确分类区，通过名称、外观与用途判断归属；正确得分并触发 Combo，错误扣分或增加耗时。支持多主题关卡、限时挑战、干扰辨别与图鉴解锁，适合休闲益智与轻度脑力挑战。
- **英文描述**：Rvix is a light sorting puzzle game. Drag everyday items into the right category by name, look, and use. Score points, build Combos, beat timed challenges, and unlock new items and themes as you clear stages.
---
### 2. 功能需求
- **整体框架设计**：原生 Swift（UIKit）单机应用，本地持久化，无账号、无云同步、无 AI / 生成式能力。核心闭环为「选关 → 拖拽分类 → 结算 → 解锁图鉴/主题」。底部 Tab 承载主入口，游戏页以全屏 Modal / Push 进入，避免与 Tab 抢焦点。
#### 整体框架与模块
- **导航栏模式**：`UITabBarController`（4 Tab）
1. **Home（首页）**：开始游戏、每日挑战、最高分与快捷入口
2. **Collection（图鉴）**：已解锁物品与主题浏览（对应「记录/收集」）
3. **Shop（商店）**：消耗本地金币解锁主题皮肤 / 装饰（非付费 IAP 一期不做）
4. **Settings（设置）**：音效、难度偏好、隐私协议、关于我们、数据重置
- **主页内容**：
- 品牌标题 + 简短 Slogan
- 「Play」进入关卡选择
- 「Daily Challenge」当日固定种子关卡（本地日期）
- 展示 Best Score、当前 Combo 纪录、今日挑战状态
- 次要入口：Achievements（成就列表，可从首页 Push）
- **记录页面（图鉴 Collection）**：
- 按主题分组展示物品卡片（锁定 / 解锁）
- 解锁条件：通关对应关卡或累计正确分类次数
- 点击查看物品英文名、所属分类、简要用途说明
- **商店页面**：
- 展示本地 Currency（Coins）余额
- 可兑换：主题背景、分类区装饰框、拖拽拖尾特效（纯视觉，不影响判定）
- 一期仅用游戏内金币，不上架 IAP，降低审核与合规复杂度
- **设置页面内容**：
- Sound / Haptics 开关
- 默认难度（Easy / Normal / Hard）
- Privacy Policy、Terms of Use（内嵌 WebView 或本地 HTML）
- About（版本号、开发者说明）
- Reset Progress（二次确认）
#### 2.1 功能模块
##### 1. 首页（Home）
- **功能描述**
- **目的与实现方式**：聚合核心入口与成绩展示，降低上手成本。用本地 `UserDefaults` / 轻量 JSON 读取最高分与每日挑战状态。
- **技术依赖**：`HomeViewController`、`ScoreStore`、`DailyChallengeService`（按本地日期生成固定关卡种子）
- **用户场景**
- **触发条件**：冷启动进入 App，或从其他 Tab 切回 Home
- **操作流程**：
1. 查看最高分 / 每日挑战完成状态
2. 点击 Play → 关卡页
3. 或点击 Daily Challenge → 直接进入当日关卡游戏页
4. 可进入 Achievements 查看成就
- **界面与UI要求**
- 顶部品牌区 + 渐变背景
- 中部大按钮 Play（主 CTA），下方 Daily Challenge
- 底部成绩卡片：Best Score / Best Combo / Coins
- 色彩跟随全局主题（见第 4 节），按钮需明确触控反馈
##### 2. 关卡选择（Level Select）
- **功能描述**
- **目的与实现方式**：选择主题、难度与游戏模式后进入对局。关卡数据以本地配置表（plist/json）驱动，避免硬编码散落。
- **技术依赖**：`LevelCatalog`、`LevelSelectViewController`
- **用户场景**
- **触发条件**：Home → Play
- **操作流程**：
1. 横向/网格选择主题（Kitchen、Desk、Toolbox…）
2. 选择难度 Easy / Normal / Hard
3. 选择模式 Classic / Timed / Distractor / Memory / Endless（一期可先上 Classic + Timed + Endless，其余二期）
4. 点击 Start → 游戏页
- **界面与UI要求**
- 主题卡片带示意插画（自制扁平图标，禁止使用第三方品牌 Logo）
- 未解锁主题显示锁态与解锁条件文案（英文）
- 难度与模式使用 Segmented Control 或 Chip，避免信息过载
##### 3. 核心游戏（Play）
- **功能描述**
- **目的与实现方式**：随机打乱物品，玩家拖拽至分类区；根据物品 `categoryId` 判定对错，更新分数、Combo、时间。
- **技术依赖**：`GameSession`、`ItemCatalog`、`DragDropController`、`ComboEngine`、`TimerService`
- **用户场景**
- **触发条件**：关卡选择 Start，或每日挑战
- **操作流程**：
1. （Memory 模式）先展示分类规则 N 秒，再开始
2. 顶部 HUD：Time / Score / Combo
3. 中部待整理物品区（可叠放或队列出现）
4. 底部/侧边分类投放区
5. 正确：+分，Combo+1，播放轻反馈
6. 错误：扣分或加罚时，Combo 清零
7. 物品清空或时间结束 → 结果页
- **界面与UI要求**
- 物品卡片：图标 + 英文短名，尺寸适合手指拖拽（建议 ≥ 64pt）
- 分类区：色块区分 + 英文标签，投放高亮
- 干扰物品视觉上接近正确类，但标签/用途不同
- 暂停按钮；暂停时遮罩，禁止继续拖拽
- **判定与数值（一期建议）**
| 项目 | Easy | Normal | Hard |
| --- | --- | --- | --- |
| 物品数 | 8 | 12 | 16 |
| 分类数 | 3 | 4 | 5 |
| 限时（Timed） | 90s | 75s | 60s |
| 正确得分 | +10 | +10 | +12 |
| Combo ≥3 额外 | +5 | +5 | +8 |
| 错误 | -5 | -5 且 +3s 罚时（Timed） | -8 且 +5s |
##### 4. 结果结算（Result）
- **功能描述**
- **目的与实现方式**：展示得分、正确率、用时、星级评价；发放金币；解锁物品/主题；检测成就。
- **技术依赖**：`ResultViewController`、`UnlockService`、`AchievementService`、`CurrencyStore`
- **用户场景**
- **触发条件**：关卡完成或失败（超时 / 放弃）
- **操作流程**：
1. 展示 Score / Accuracy / Time / Max Combo / Stars（1–3）
2. 展示新解锁物品或主题（若有）
3. Retry / Next Level / Home
- **界面与UI要求**
- 成绩数字动效（短暂计数动画即可）
- 解锁弹层简洁，避免堆叠过多弹窗
- 失败态文案鼓励重试，不羞辱玩家
##### 5. 图鉴（Collection）
- **功能描述**
- **目的与实现方式**：收集驱动复玩。物品解锁写入本地存储，图鉴只读展示。
- **技术依赖**：`CollectionViewController`、`ItemCatalog`、`ProgressStore`
- **用户场景**
- **触发条件**：Tab → Collection；或结果页「View Unlocked」
- **操作流程**：选主题 → 浏览格子 → 点开详情
- **界面与UI要求**
- 网格卡片；锁定项灰阶 + 锁图标
- 详情：图标、Name、Category、Short tip（英文）
##### 6. 成就（Achievements）
- **功能描述**
- **目的与实现方式**：通关与挑战里程碑，增强留存。成就定义本地配置，进度本地累计。
- **技术依赖**：`AchievementService`、`AchievementsViewController`
- **用户场景**
- **触发条件**：Home 入口 Push，或达成时 Toast / Banner
- **操作流程**：列表查看已完成 / 未完成与进度条
- **界面与UI要求**
- 列表行：图标、标题、描述、进度
- 示例成就：First Clear、Combo x10、Daily 7-Day Streak、Clear All Themes（Easy）
##### 7. 商店（Shop）
- **功能描述**
- **目的与实现方式**：用通关金币兑换视觉主题，形成轻度目标感；一期不做真实货币交易。
- **技术依赖**：`ShopViewController`、`CurrencyStore`、`ThemeStore`
- **用户场景**
- **触发条件**：Tab → Shop
- **操作流程**：查看余额 → 选择装饰 → Confirm 扣币装备
- **界面与UI要求**
- 顶部余额组件（全局可复用）
- 商品卡片：预览图、价格、Owned / Equip 状态
##### 8. 设置与合规（Settings）
- **功能描述**
- **目的与实现方式**：满足 App Store 隐私与透明度要求；提供基础偏好。
- **技术依赖**：本地 HTML / URL、`SettingsViewController`、可选 ATT（若无广告/追踪则一期不集成 ATT）
- **用户场景**
- **触发条件**：Tab → Settings
- **操作流程**：开关音效；打开 Privacy / Terms；查看 About；确认后 Reset
- **界面与UI要求**
- 分组 `UITableView` / `UICollectionView` list
- 协议页英文正文；关于页含 App 名、版本、联系邮箱（可选）
##### 9. 每日挑战（Daily Challenge）
- **功能描述**
- **目的与实现方式**：用日期作为随机种子生成固定关卡，保证同日可重试、跨日刷新。
- **技术依赖**：`DailyChallengeService`
- **用户场景**
- Home → Daily Challenge → 游戏页 → 结果写入「今日最佳」
- **界面与UI要求**：Home 上显示 Completed / Not Completed；结果页标注 Daily 标识
---
### 3. 关卡主题与模式（内容范围）
#### 3.1 一期落地主题（建议先做 4 个，降低素材量）
| 主题 | 分类示例（英文） | 物品示例方向 |
| --- | --- | --- |
| Kitchen Sort | Seasonings / Tableware / Cookware / Snacks | salt shaker, spoon, pan, chips bag（通用造型，无品牌） |
| Desk Sort | Stationery / Documents / Gadgets | pen, folder, USB cable |
| Toolbox | Tools / Tape & Fix / Measuring | hammer, duct tape, tape measure |
| Garden Corner | Pots / Seeds / Garden Tools | clay pot, seed pack, trowel |
二期可扩展：Bathroom、Travel Pack、Kids Room。
#### 3.2 游戏模式落地优先级
| 模式 | 一期 | 说明 |
| --- | --- | --- |
| Classic | ✅ | 清完物品即过关 |
| Timed | ✅ | 倒计时结束结算 |
| Endless | ✅ | 持续出题，打最高分 |
| Distractor | 二期 | 增加易混淆物品比例 |
| Memory | 二期 | 开局短暂展示规则后隐藏标签 |
#### 3.3 合规与侵权规避（必须遵守）
- 物品名称与图标均为原创通用造型，**禁止**使用可识别的真实品牌、商标外观、IP 角色。
- App 名称、图标、文案避免模仿已上架「整理/收纳」热门 App 的专有命名与强相似 UI 模板，降低 Guideline **4.3** 风险。
- 不收集无关个人数据；无账号体系；无第三方追踪 SDK（一期）。若后续加广告再评估 ATT（Guideline **5.1**）。
- 儿童可玩内容需健康：无暴力、无赌博、无诱导消费；一期无 IAP，避免 **3.1** / 未成年人付费争议。
- 所有面向用户文案使用 **英文**；开发文档可用中文。
- 不提供「AI 记忆 / 云端个性化推荐」等能力，避免无关权限与 **5.6** 类误导性声明。
---
### 4. UI/UX设计要求
- **主题色调**：清爽收纳感 — 主色 `#2BBBAD`（Teal），辅色 `#FFB703`（暖黄强调 CTA），文字主色 `#1F2A37`，成功 `#34C759`，错误 `#FF5A5F`
- **设计总体背景色组件**：`AppGradientBackgroundView` — 竖向浅青到米白渐变；游戏页可切换为当前主题的浅色纹理层（仍用自绘 / 本地资源，不用照片拼贴侵权素材）
- **动效**：物品投放成功轻弹缩放；Combo 数字短促上浮；结果分数字滚动。动效克制，服务反馈，不遮挡操作
- **图标**：使用外部图标库插件（如 **SF Symbols** 作系统辅助图标；物品与主题主视觉使用自制 Asset / 可向量图标资源，避免直接复制商业图标包的品牌款）。推荐引入 **Swift Package** 管理的开源图标集时，确认 License（MIT/Apache）并在 About 致谢
- **布局**：优先 **SnapKit** 约束，保证不同机型安全区适配
- **无障碍**：重要按钮保留可读 `accessibilityLabel`（英文）
**页面线框示意（文字）**
```
[Home]
┌─────────────────────┐
│ Rvix │
│ Sort. Score. Flow. │
│ [ Best 1280 ] [🪙] │
│ [ PLAY ] │
│ [ Daily Challenge ]│
│ Achievements → │
└─────────────────────┘
[Play]
┌─────────────────────┐
│ ⏱ 62s ★ 240 x4 │
│ [Item][Item] │
│ │
│ [CatA][CatB][CatC] │
└─────────────────────┘
[Result]
┌─────────────────────┐
│ Stage Clear │
│ Score 240 ★★★ │
│ Acc 92% Combo 6 │
│ [Retry][Next][Home] │
└─────────────────────┘
```
---
### 5. 技术实现建议
#### 5.1 架构建议
- **模式**：UIKit + MVC / 轻量 MVP；单机无复杂状态树
- **目录建议**：
- `App/`（AppDelegate、SceneDelegate、TabBar）
- `Features/Home|Level|Game|Result|Collection|Shop|Settings|Achievements`
- `Core/Models`（Item、Category、Level、Achievement）
- `Core/Services`（Score、Currency、Progress、Daily、Unlock、Audio）
- `Core/UI`（GradientBackground、CoinBadge、PrimaryButton）
- `Resources/Levels.json`、`Items.json`、Legal HTML
- **状态管理**：对局内用 `GameSession` 可变状态；跨页进度用 `ProgressStore`（Codable + File / UserDefaults）
#### 5.2 可抽离全局组件 / 服务
| 组件/服务 | 职责 |
| --- | --- |
| `AppGradientBackgroundView` | 全局渐变/主题背景 |
| `CoinBadgeView` + `CurrencyStore` | 金币展示与增减、持久化 |
| `ScoreStore` | 最高分、模式分、每日最佳 |
| `ProgressStore` | 关卡星级、解锁物品/主题 |
| `AudioHapticsService` | 音效与触感统一开关 |
| `ItemCatalog` / `LevelCatalog` | 只读内容配置 |
| `ComboEngine` | Combo 计数与加分规则 |
| `LegalDocumentViewController` | 隐私协议 / 用户协议 |
| `ToastBanner` | 成就解锁轻提示 |
#### 5.3 隐私、协议与关于我们
- **Privacy Policy**：说明数据仅本地存储、不采集 IDFA（一期）、无账号
- **Terms of Use**：使用条款、免责声明
- **About Us**：App 简介、版本、致谢（图标许可）
- Info.plist：仅声明实际用到的权限；一期预期 **无** 相册/相机/麦克风/追踪
- 首次启动可展示简短欢迎 + 可链到 Privacy（非强制弹窗堆叠）
#### 5.4 一期 MVP 范围（快速落地）
**必须有**：Home、Level Select（4 主题）、Classic / Timed / Endless、Game 拖拽判定、Result、Collection、基础 Achievements、Coins + Shop 视觉兑换、Settings（音效/协议/关于/重置）
**明确不做（一期）**：IAP、登录、排行榜联网、广告、AI、UGC、社交分享强依赖、Distractor/Memory 完整模式、全部 7 主题素材
#### 5.5 页面交互示例场景
1. **新用户首次**：打开 Home → Play → 选 Kitchen / Easy / Classic → 拖拽完成 → Result 获 ★ 与 Coins → Collection 见新解锁物品
2. **每日挑战**：Home → Daily Challenge → 限时关 → 提交今日分 → 成就进度 +1
3. **商店兑换**：通关攒币 → Shop → 购买 Desk Theme Frame → 下次游戏页应用装饰
4. **失败重试**：Timed 超时 → Result（未三星）→ Retry → 回到同关配置重新开局
---
### 6. 验收标准（初期）
- 可在真机/模拟器完成一局 Classic 并正确结算分数与 Combo
- 错误分类会断 Combo 并按规则扣分/罚时
- 进度、最高分、金币、解锁状态杀进程后仍保留
- 图鉴锁定/解锁状态与通关一致
- Privacy / Terms / About 可打开且为英文
- 无崩溃的基础拖拽（取消拖拽回弹、越界投放判定）
- 素材与命名无明显商标侵权风险
---
### 7. 版本规划建议
| 版本 | 内容 |
| --- | --- |
| v1.0 | MVP：4 主题 + 3 模式 + 图鉴 + 成就 + 金币商店（无 IAP） |
| v1.1 | Distractor、Memory；Bathroom / Travel 主题 |
| v1.2 | Kids Room、更多成就、可选 Game Center 本地排行（仍可不联网账号） |