docs(3d): 补充首页 3D 标签可发现性根因与修复至知识卡片

Author: Aparencia

docs/knowledge/bugs/2026-08-homepage-3d-duplicate-planets-misaligned-click.md

@@ -59,6 +59,29 @@
 - **"只改状态不跳转"的点击回调是隐蔽 bug**：`enterModule` 不报错、UI 也有遮罩反馈，表面"有响应"，实则路由未变。排查"点了没到预期页面"时，先确认点击回调里是否真的调用了 `navigate`。
 - 排查此类问题的高效方法：**沿渲染链路列出所有同类可点击实体，逐个核对其点击回调**，而不是只看其中一个。
 
+## 后续演进（同一反馈的第二根因：标签可发现性）
+
+移除重复行星后内测仍反馈“3D 物体不可用”。**浏览器复现**（vite dev + Playwright 截图）发现：行星确实渲染出来了，但
+
+- **标签默认隐藏**：`showLabel={highlightAll}`，`highlightAll` 仅在新手引导某步为 true，平时只有悬浮才显示标签；
+- **功能副标题受新手期门控**：`{isNewbie && subtitle && …}`，首潜完成后“专注番茄钟/学习笔记”等直白功能名消失，只剩隐喻名（深潜/结礁…）。
+
+用户看到的是一堆**无名彩色球体**，无法对应到功能——这才是“无法对应到其功能”的直接原因。
+
+**修复**（`b605a6f`）：
+1. `SpatialNav`：概览模式（`!isInModule`）默认显示标签（`showLabel={highlightAll || !isInModule}`）；
+2. `AuroraModuleEntity`/`ModuleEntity`：功能副标题改为**常驻**（移除 `isNewbie` 门控），始终展示“隐喻名 · 功能名”（如 深潜 · 专注番茄钟）。
+
+浏览器实测：标签可见、点击行星正确跳转对应模块。
+
+> 取舍：为了让用户能把行星对应到功能，**牺牲了“新手期后才隐藏副标题”的原设计**。隐喻名保留（品牌），功能名常驻（可用性）。移动端网格/侧边栏仍按新手期门控，如需全导航面一致可后续对齐。
+
+## 教训补充
+
+- **“无法对应到功能”优先查标签可发现性**：交互对象可见 ≠ 可用。若对象本身能点击跳转，但用户仍报“不可用”，多半是**缺少可识别的标签**，而非点击逻辑坏了。
+- **复现优先于推测**：本轮首轮仅凭代码推测“重复行星”为唯一根因，未复现；直到浏览器截图才看到“无标签”这个真正根因。debug-sop 第二步“复现”不可跳。
+
 ## 相关提交
 
-- fix(3d): 移除晨曦穹顶场景中重复的行星系统，导航行星统一由 SpatialNav 渲染（待提交）
+- `ff67320` fix(3d): 移除晨曦穹顶场景重复的行星系统，导航行星统一由 SpatialNav 渲染
+- `b605a6f` fix(3d): 概览模式常驻显示模块标签与功能副标题，解决 3D 物体无法对应到功能