项目印记

panel.addEventListener('mousedown', () => { suppress = true; });   // 拖动开始
window.addEventListener('mouseup', () => {
  if (suppress) { suppress = false; return; }                      // 松手不点选
  pickSceneAt(mouse.x, mouse.y);
});

规则 7：小图标状态渲染只保留一个函数；小字号禁配半透明/缩放

问题现象：工具栏部分开关图标状态不更新；图标发虚。
根因：同名的状态刷新函数被声明了两次，后加载的覆盖先加载的（JS 静默行为，不报错）；12px 小字配 opacity<1 再经 transform 缩放会亚像素糊化。
通用规则：每个状态渲染函数全项目唯一（代码评审时 grep 函数名计数）；小图标固定整数字号 + 不透明度 100%。

规则 8：Fullscreen API 必须是真实用户手势

问题现象：导览模式想自动全屏，JS 调 .click() 触发被拒。
根因：浏览器安全策略——requestFullscreen 只认真实用户手势事件（trusted event）。
通用规则：入口做成真按钮；自动化测试用 selenium ActionChains 物理点击而非 .click()；监听 fullscreenchange 刷新图标状态。全屏与退出成对（导览开始全屏、结束退出）。

规则 9：文档入库检索——先删旧块再插入（幂等），HTML 用白名单清洗

问题现象：子文章在站内知识中心搜不到。
根因：入库管线只覆盖了主文章，子文章（CKEditor HTML）这类源从未纳入索引。
通用规则（Flask 通用，可移植）：新增一类文档源时，① 切块函数复用现有"Markdown/HTML 白名单清洗"；② 重编入索引采用先按 (source_type, source_id) 删旧块、再插新块，保证重复执行幂等；③ 路由层在创建/编辑保存时同步增量入库，别依赖手动重建；④ 检索默认源白名单显式列出新类型。

def index_document(doc_id, title, html, url, source_type):
    # 幂等：先清旧块
    Chunk.query.filter_by(source_type=source_type, source_path=str(doc_id)).delete()
    clean = strip_html_whitelist(html)      # 去标签脚本样式，留纯文本
    return add_chunks(source_type, str(doc_id), title, clean, url)

外部语料抓取陷阱：MediaWiki API 一次传多个 title 会命中 continue 分页，只返回第一页造成数据残缺——必须逐条请求，带 User-Agent，间隔 0.8–1.5s 限速；注意版权协议（维基为 CC BY-SA，须署名+回链原条目）。

回归基线与提交

88 星座全量搜索回归通过（搜索→点击→对准→稳定；唯一"失败"是批量测试相机转场 2.2s 不够，属测试节奏非功能问题）。天王星贴图换旅行者号真实照片（+2.2 倍对比度）。相关提交：63b15f5（已推 gitee master）。测试脚本当时存于本机 /tmp（临时目录，重启即失），复现请按本文代码段重写。

2026-11-11 · 资料卡「🔭 发现与传承」板块（四类数据源全覆盖）

需求：每张悬停/点击弹出的资料卡补充四项人文字段——发现时间、发现技术、主要神话、文章或诗词。

通用规则（可复制）：卡片组件采用「可选数据块」模式——渲染函数只认 d.hist 键，数据层各来源自行组装；无值的行在渲染时过滤（h[1] && h[1] !== '—'），空数组不输出板块头，做到「无资料不显示、有资料必完整」。内容准确性策略：古典天体写"史前即知+最早文献出处"，近代天体写"发现者+年份+仪器/方法"，无神话/诗词的天体（球状星团、矮星系）宁可缺行也不编造。

数据源与填充方式：行星×9、太阳、月球——手写 4 行（史实均为主流天文史共识）；近邻恒星×14——按标签名匹配，比邻星 1915 英尼斯照相底片、天狼 B 1862 克拉克折射镜等；球状星团×16、伴星系×3、电离氢区×4——与渲染数组按下标/名字一一对应；24 主星座——手写（托勒密 48 体系 + 希腊神话 + 中国最权威出典，如"七月流火""动如参与商"）；63 生成星座——从故事文本正则提取创立者与年代（拉卡伊/普朗修斯/赫维留），未命中再查托勒密 48 英文名白名单，兜底"近代星图创立"——新增星座零手工录入。

验证：node --check 语法过；selenium 11 项断言全绿（行星/日/月/近邻星/球状星团/伴星系/HII/主星座/生成星座各抽 1）；最满卡片（地球，含 4 行）高 498px 不溢出；截图目检板块样式（紫色左边条与既有蓝/金块区分）。

2026-11-11 · 全 88 星座"不占位置"显示方案（索引面板 + 3D 弱显）

问题：88 个星座要全部可及，但 3D 天球塞 88 个名牌必然互相遮挡（24 主星座已是贪心防重叠上限）。
方案（核心规则可复制）：名牌全量显示与访问入口必须解耦——天上"全都在"（弱显），名字"一个不多"（只在悬停/搜索时出现），浏览入口收进折叠 UI 面板。三件事：

验证：selenium 断言全绿——面板 88/88 项、弱显 54/54 可见且连线透明度 0.1、弱显名牌隐藏、真点击 ♈ 展开/点项飞往（goConstellation 路径 soloOn=true）面板自动关、Esc 后弱显 53/53 重放；截图目检分组面板与飞行画面。FPS 25（headless 基线正常范围）。

2026-11-11 · 人类探索进程演示：足迹图层 + 「探索之旅」导览（范围球膨胀隐喻）

需求：演示人类探索宇宙的进程与活动范围扩张。核心视觉隐喻——以太阳为中心不断膨胀的"人类活动范围球"。

通用规则（可复制）：①图层组必须挂 scene 并每帧拷贝太阳位置——不能挂太阳 sprite 节点下，太阳 farDim 缩放剧烈（0.00005–0.06），子节点会跟着变形；②"活动范围随时间膨胀"用目标半径+每帧 6% 平滑逼近实现，导览只需改目标值，任何引擎可移植；③跨 10⁸ 量级（400 km→162 AU）的演示不要追真实比例——用分级圈表达，每圈独立标注真实数值；④图层标签只在相关视距窗口显示（dSun<1.2），银河视角自动隐藏防糊屏。

2026-11-11 · 探索之旅增强：历史照片卡 + 巡视器/着陆器标记

需求：①导览站点配真实历史照片；②月球/火星上的巡视器此前不存在于场景，需新增标记。

验证：selenium 全绿——月球 2/2 标记+标签、火星 4/4、阿波罗卡含 hist、探索之旅 1969 站照片卡显示且 credit=NASA；截图目检月球双旗标与导览照片卡同屏。工作模式补充：NASA 图片 API 逐条请求有效，搜索词给 NASA ID（如 as11-40-5878）命中率最高。

2026-11-11 · 三项修复与收尾：抖动、遮挡、照片补全

同日对探索之旅功能的三个打磨，均为高频交互病，规则可复制。

当日全量：资料卡「发现与传承」四字段（8 类数据源）、工作文档写作规范（docs/ 三文档 + AGENTS.md）、88 星座索引面板 + 3D 弱显、人类足迹图层 + 探索之旅 14 站导览、12→15 张历史照片、6 个巡视器/着陆器标记、抖动/遮挡两项修复。探索之旅现全长 14 站 × 8 秒 ≈ 2 分钟，站站有真实照片，月球/火星站有着陆点旗标，可直接录屏。

2026-11-11 下午场 · 文章页排版型故障修复（500 / 非法栅格类 / 模板分支写反）

问题现象：/sub_article/64 打开即 AttributeError 整页报错（未登录访问 500）；登录后正文栏只剩约 340px 宽，表格一列一个字竖排，右侧大片空白。curl 验证：匿名 200 但 body 是调试错误页；登录态 DOM 量得 .mailbox-right 仅 465px（设计应为容器 83%）。

根因（5 个，链式暴露）：① views.py:252 对未登录用户直接取 current_user.id——AnonymousUser 无 id 属性必崩，是用户看到的"排版不正常"真身；② 修复①后立刻 NameError: markdown——生成 content_html 的分支从未被执行过（存量数据 content_html 早已存在），import 缺失潜伏至今；③ bleach 白名单缺 blockquote/img，引用块与配图会被过滤；④ 模板两个渲染分支写反（有 content_html 时渲染原始 content、没有时渲染 content_html）；⑤ 左侧栏用非法 Bootstrap 栅格类 col-md-1.3（主文章页是 col-md-1.2）——Bootstrap 无此类，左栏掉出栅格流，右栏 col-md-10 被挤压。主文章页 /main_article/23 与用户截图确认同病。

通用规则：1）任何取 current_user.id 的视图必须先过 is_authenticated（本站 7 处旧代码均为此写法，新增代码必须照抄）；2）"从未执行过的分支"等于没有代码——改完触发路径必须实测一次；3）HTML 白名单要跟着内容资产走（引用块/配图是文章系统一等公民）；4）Bootstrap 栅格类只有整数 1–12，"col-md-1.3" 不是"1.3 列"而是"无此类"；5）调试渲染类页面（debug toolbar）会被用户误认为"排版坏了"——先 curl 看 HTTP 状态再谈 CSS。

可复制实现：

is_author = current_user.is_authenticated and current_user.id == current_sub.author_id
from markdown import markdown   # 潜伏 NameError 的补法：分支级 import 与视图同文件头
allowed_tags += ['blockquote', 'img']; allowed_attrs['img'] = ['src','alt','style','width','height']
# 模板：{% if content_html %}{{ content_html|safe }}{% else %}{{ content|markdown|safe }}{% endif %}
# 栅格：<div class="col-md-2 mailbox-left">（左栏）+ col-md-10（右栏），左栏 max-width:180px 由行内样式约束

验证：匿名 curl 200、blockqu­ote/img 保留（重建 content_html）、selenium 登录态 1843px 窗口两页正文栏 1215px、表格全宽。提交 d28a9bd。

2026-11-11 下午场 · 导览相机准确性核验（24 站全量实拍 + 4 处修复）

方法：无头 Chrome 把十站银河（10 站）与探索之旅（14 站）完整跑一遍，每站等相机补间收敛 3.5s 后截图逐站目检——共 24 张。导览引擎每站 8s，相机目标在站点表 run() 里改 view.tDist/tPan/tPitch。

问题现象 → 根因 → 修复：

通用规则：1）双坐标系项目里，跨层传坐标必须写明"局部 or 世界"——本模块 skyGroup/galaxy/humanGroup 三个组各有局部系，世界坐标一律用 o.v（每帧 applyMatrix4 刷新）而不是 o.rel；2）跟随运动目标的视觉元素必须与渲染链同频（每帧），异步事件（全屏切换/图片加载）只做"重定位触发器"，单次定位必竞态；3）教学类视角要为主角清场：多层叠加场景（星场/尘埃/光晕/碎片带）做"特写站"时，用系数压光 + 中央复位比逐站写还原代码可靠——系数集中在 step() 里先复位默认值、run() 自行覆盖；4）判定相机准确与否的金标准：截图目检画面内容与站点文案是否相符，坐标数字对了不等于画面对。

可复制实现：

// 压光四系数（导览态）
let sunGlareK = 1, localGainK = null, beltGainK = null, orbitBoostK = 1;
// step() 开头：sunGlareK = 1; localGainK = null; beltGainK = null; orbitBoostK = 1;   // 中央复位
// stopTour() 同样复位，防残留到手动浏览
// animate 内：localGainUniform.value = localGainK != null ? localGainK : (1.0 - 0.95*t);
//   beltGainUniform.value = beltGainK != null ? beltGainK : 1;
//   for (const p of planetObjs) if (p.orbitRing) p.orbitRing.material.opacity = 0.3 * orbitBoostK;
// 需要压光的站点 run()：sunGlareK = 0.3; localGainK = 0.12; beltGainK = 0.15; orbitBoostK = 3;

验证：修复后 4 站重拍截图确认（比邻星：太阳+行星+★标记同框；俯瞰：同心轨道圈清晰；hm1：照片卡稳定显示）。提交 8e08ce1。

2026-11-11 下午场 · 知识入库管道落地：P0 三项 + P1 三项（方案见 /artcles/256）

架构：文章 = 知识本体，模块 = 交互界面，中间加一层结构化 JSON——app/galaxy/data/kb/<topic>.json，Flask 通用端点 /galaxy/api/kb/<name>（正则 [a-z0-9_]+ 白名单防路径穿越），前端按需 fetch。galaxy.html 已 3900+ 行，知识内容绝不硬编码进页面；文章修订后重生成 JSON 即同步。

通用规则：1）JSON 里禁止裸 ASCII 双引号内嵌——中文内容内嵌引号一律用『』/“”，否则 json.load 直接炸（本次 spiralarms.json 踩过：字符串里 "恒星产房" 未成对转义）；2）面板/卡片 z-index 生态：infoCard z1300 > 浮层 z1210 > 底框 z1200——开浮层必须先 hideInfoCard()，fixed 定位面板必须显式给 inset（缺 top/right 会落到静态定位处，视口外不可见）；3）双向闭环验收：模块每个入口回链 /sub_article/xx，文章开头插「配套交互」blockquote（入库前清 content_html 强制重生成，过 bleach 新白名单）；4）数据分级原则：真实比例模块不画压缩示意圈——超出尺度的量（3000 万光年/红移）进知识卡文字，不进 3D。

可复制实现（Flask 通用管道端点）：

@galaxy.route('/api/kb/<name>')
def api_kb(name):
    if not re.fullmatch(r'[a-z0-9_]+', name or ''): abort(404)
    data = _load_json(os.path.join('kb', name + '.json'))
    if data is None: return jsonify({'error': 'kb topic not found'}), 404
    resp = jsonify(data); resp.cache_control.max_age = 3600
    return resp

验证：7 份 kb JSON 全部合法、端点 200/404 正确、浏览器逐项实测（球壳/标签/卡片/三态切换/演化时间轴/月面板/导览条回链）；sub72/76/77/81/85 五篇配套交互指引已入库索引。底框图标现 14 个：🔍♈👣🛰📐🌈🔭⤳⊙🚀🪐🏷🎵⛶。build v20261111-04。

2026-11-12 · 知识文库扩建：2 篇新增 + 2 篇扩写 + 全系列重排（27 篇定版）

背景：六线盘点发现三个缺口——宇宙学本体无专篇、多信使只有一句、"做中学"任务层缺失。当日全部补齐。

方法：DB 直写脚本（先断言幂等再写入），页面 curl grep 关键词核验渲染；主文章 23 同步补"11-10~11-12 迭代补记"并更新星座节表述（八大→全天 88）。本次为数据层变更，未涉及模块代码。