主题
功能总览
探字星球功能模块文档。每篇含：功能概述、核心规则、关键文件、数据流、相关 API、规则数值引用。书写与复习系统的权威文档见顶层
/write-module与/review-system。
功能模块
| # | 功能 | 文档 | 简介 |
|---|---|---|---|
| 1 | 汉字学习 | learning.md | 汉字星际筛选、character tabs、CDN 回退 |
| 2 | 象形配对游戏 | game-pictograph.md | 动态限时、3 次错误失败、消除/冻结道具 |
| 3 | 拼图闯关游戏 | game-stroke-puzzle.md | 笔画拼块拖放、5 次错误失败、自动配对/跳过道具 |
| 4 | 汉字消消乐游戏 | game-char-match3.md | 7×7 Match-3、步数限制、锤子/洗牌/提示/加步数道具 |
| 5 | 3D 星球地图 | planet.md | Three.js、9 个 GLSL 着色器、6 颗星球、星球解锁机制 |
| 6 | 成就系统 | achievement.md | 5 大级别 × 10 小段 = 50 段、30 个徽章、自动解锁检测 |
| 7 | 商店系统 | shop.md | 积分兑换、密码保护（5 次锁定 30 分钟）、奖励管理 |
| 8 | 首页/引导 | 见下节 | onboarding 引导轮播、首页看板 + 今日推荐、HeroScene 3D 背景 |
| 9 | 墨水屏模式 | ink-screen-mode.md | 黑白灰护眼、禁动画、安卓灰度自动检测、屏蔽 3D 星球地图 |
| 10 | 工具页 | 见下节 | 设置/资料等工具类页面 |
首页/引导与 3D 背景
首页模块（
pages/onboarding/、pages/index/）共用pages/index/components/HeroScene.vue（798 行）作全屏 3D 星空背景。
- 引导页（onboarding）：首次进入由路由守卫强制跳转（检测
localStorage.tzxq_onboarded）；展示 3 个功能卡片轮播（2500ms 自动切换），点击星球 →handleStart()写入 onboarded 标记并router.replace("/index") - 首页（index）：学习统计 4 卡片（今日目标/连续天数/今日复习/正确率）+ 6 个功能入口（3×2 网格）+ 今日推荐 4 个汉字
- 今日推荐算法：按日期种子伪随机（
[...new Date().toDateString()].reduce((s, c) => s + c.charCodeAt(0), 0)），按category_id分桶各取一候选，最多 10 轮收集 4 个；同天一致、跨天不同，且watch(characters.length)兜底异步数据未就绪 - HeroScene 关键点：6 星球循环（6000ms 切换、2500ms 弧线进出过渡）、拖拽旋转、
raycaster点击检测 emitplanet-click、UnrealBloom后处理、usePlanetTheme()驱动 App.vue TabBar 主题色、内容感知定位（contentInsetTop/Bottom/targetCenterY）避开 NavBar/TabBar - Props：
clickHint/showOrbits/activePlanet等 8 个，被 onboarding（show-orbits=false）与 char-select（active-planet跟随分类）等页复用
道具配置总览
道具配置源码：
web/src/stores/game.ts→defaultPowerUps（第 51-55 行）。所有功能文档以源码为准，不沿用 AGENTS.md 过时描述。
| 游戏 | gameId | 道具配置 |
|---|---|---|
| 象形配对 | pictograph_match | { clear: 1, timeFreeze: 1 } — 1 次消除 + 1 次时间冻结 |
| 拼图闯关 | stroke_puzzle | { pair: 3, skip: 1 } — 3 次自动配对 + 1 次跳过 |
| 汉字消消乐 | char_match3 | { hammer: 3, shuffle: 2, hint: 3, extraMoves: 1 } — 锤子×3、洗牌×2、提示×3、加步数×1 |
⚠️ Mock 层
mock/modules/game/powerups.ts的兜底默认值为{ hammer: 3, shuffle: 2, hint: 3 }（不含extraMoves），仅在 Store 层未初始化时使用。实际游戏使用 Store 层的defaultPowerUps。
数值引用规范
features/ 文档中所有 EXP/积分/段位/道具等数值均链接到规则文档，不重复生成：
工具页
支撑辅助页面，无独立业务引擎，多为页面级实现。源码位于
web/src/pages/对应目录。
设置页 settings.vue
pages/settings/settings.vue（611 行），路由 /settings。三大板块：
- 通用设置：字号（small/medium/large）、墨水屏模式（
t-switch绑定settings.darkMode，护眼省电，详见 墨水屏模式） - 学习设置：每日目标（t-stepper min=5 max=50 step=5）、笔顺提示 / 自动音频 / 书写提示气泡（t-switch）、提示停留时间（1-15）、提示间隔（10-300 step=10）
- 数据管理：清除缓存 / 导出数据 / 导入数据 / 重置学习进度
- 星球解锁管理：6 颗星球手动解锁，
nature_planet固定"默认解锁"无开关
数据管理关键逻辑：
- 设置变更
watch(deep)+ 300ms 防抖自动保存 clearCache()仅清 4 个缓存键（tzxq_resource_cache/tzxq_etymology_index/tzxq_etymology_cache/tzxq_hw_cache），保留用户数据exportData()导出所有tzxq_前缀键为tzxq_backup_YYYY-MM-DD.json- 导入校验
data.keys存在且含tzxq_user_data - 重置全部三步防回写：
clearMockDb()→userStore.reset()+gameStore.reset()→ 移除所有tzxq_键，再location.reload()
个人资料页 profile.vue
pages/profile/profile.vue（852+ 行），Tab 页 /profile。展示头像 / 用户名 / 段位条、学习统计（已学汉字 / 连续天数 / 徽章）、太空舱功能菜单（成就/商店/徽章墙/复习统计/设置）、连接中心（关于）。
- 头像裁剪：Canvas 2x retina，裁剪框为 canvas 80% 居中正方形；三种输入（触摸单指拖拽 + 双指捏合缩放 + 鼠标/滚轮）；
applyScale以裁剪框中心为锚点，userScale ∈ [0.5, 5.0]；confirmCrop缩放到 ≤400×400 →toDataURL("image/jpeg", 0.85)→ 写入userData.avatar - 用户名编辑：自定义 Teleport + Transition 弹窗（tdesign Dialog Teleport 到 body 后 scoped 样式无法穿透），
--dialog-color跟随useActivePlanetColor，弹窗样式在文件末尾非 scoped<style>块定义
关于页 about.vue
pages/about/about.vue（185 行），路由 /about。数据全部来自静态 @/data/about.json（header/intro/sections/footer），无 Store 依赖。版本号 __APP_VERSION__ 由 Vite define 构建时注入（来自 package.json version）。
获取说明页（earn-guide / exp-guide / points-guide）
三个页面共享全局组件 EarnGuide.vue（components/EarnGuide.vue，271 行），数据来自 @/data/reward-guide.json：
earn-guide.vue：双 Tab 可切换，v-model:mode+router.replace同步 URLexp-guide.vue/points-guide.vue：固定mode，无 Tab 切换交互EarnGuide积分模式过滤points === "—"条目；主题色经usePlanetTheme预计算（Tab/图标/数值随 bgColor/planetColor 更新，背景亮度 <128 用白色文字）