fix(wiki): restore GHC-05 image lightbox

Document the shared Wikipedia-style mission page format and the required Wiki.js script extraction workflow. Co-Authored-By: OpenAI Codex <codex@openai.com>
2026-07-15 18:06:37 +08:00
parent 1b6c599a89
commit da2d01a5aa
4 changed files with 353 additions and 0 deletions
@@ -0,0 +1,343 @@
+# 广寒任务 Wiki 页面 Wikipedia 化格式规范
+
+## 1. 目的与基准
+
+本文档用于指导其他团队将广寒计划任务页面统一为当前 GHC-05 的 Wikipedia 风格。
+
+- 旧版对照：线上 GHC-04；
+- 新版基准：线上 GHC-05；
+- 基准源码：`data/wiki/guanghan_ghc05_zh.html`；
+- 核对日期：2026-07-15。
+
+工作区里的 GHC-04 源文件已经吸收了一部分新版样式，但线上 GHC-04 仍是旧版。本文的页面差异对比以线上实际渲染为准。
+
+## 2. 关于图片灯箱的更正
+
+GHC-04 的图片灯箱是正确基准，GHC-05 不应重新设计图片打开方式。GHC-05 曾出现“点击图片无反应”，原因不是灯箱 HTML、CSS 或 JavaScript 的设计错误，而是发布时只提取了页面 CSS，没有把正文中的 `<script>` 提取到 Wiki.js 的页面 JavaScript 字段。Wiki.js 渲染正文时不会可靠执行正文内联脚本，因此图片没有绑定点击事件。
+
+修复后的 GHC-05 已恢复与 GHC-04 一致的行为：
+
+- 点击图片打开居中的全屏灯箱；
+- 背景使用深色遮罩，并锁定页面滚动；
+- 图片按原比例完整显示；
+- 灯箱底部显示图注；
+- 支持右上角按钮、点击遮罩和 `Esc` 关闭；
+- 关闭后恢复页面滚动和触发图片的焦点。
+
+图片灯箱属于“保留并正确发布的既有能力”，不是 GHC-05 相对 GHC-04 的视觉改造项。
+
+## 3. 线上格式对照
+
+| 项目 | 线上 GHC-04 | 当前 GHC-05 | 统一要求 |
+| --- | --- | --- | --- |
+| 页面主标题 | Wiki.js 外层标题和正文 H1 同时显示 | 隐藏外层标题，只保留正文 H1 | 每页只显示一个主标题 |
+| 正文目录 | 页面内部另有“目录”框 | 已删除 | 只使用 Wiki.js 左侧“页面内容” |
+| 左侧页面导航 | 与面包屑区域距离不足 | 桌面端固定在 `top: 118px` | 滚动时不得遮挡面包屑 |
+| 正文容器 | 页面结构较松散 | 最大宽度 1180px、居中 | 使用统一阅读宽度 |
+| 标题排版 | Wiki.js 默认标题 | Wikipedia 风格衬线标题和细分隔线 | H1/H2 使用百科条目样式 |
+| Infobox | 线上实测宽 330px、左间距 0 | 宽 360px、左间距 48px | 正文与信息框必须明显分离 |
+| Infobox 内部 | 普通表格感较强 | 31%/69% 标签数据列，分组标题 | 使用 Wikipedia 信息框层级 |
+| 章节避让 | 表格可能掉到信息框下方突然全宽 | 重叠章节作为整体保持左栏宽度 | 标题、正文和表格不得分裂 |
+| 普通数据表 | Wiki.js 默认表格 | `wikitable` 灰色表头、细边框 | 使用紧凑百科表格 |
+| 移动端 | 基础响应式 | 信息框转单栏、表格可横向滚动 | 页面本身不得横向溢出 |
+| 图片灯箱 | 正确 | 修复后与 GHC-04 一致 | 保留同一套灯箱并正确发布脚本 |
+| 基地拓扑图 | 无 | 响应式 iframe 图框 | 仅有拓扑图的页面使用 |
+
+## 4. 页面骨架与导航
+
+正文必须放在统一容器中：
+
+```html
+<article class="mw-parser-output wiki-article">
+  <h1 id="top">广寒基地建设任务-XX</h1>
+  <!-- infobox、导语和正文 -->
+</article>
+```
+
+隐藏 Wiki.js 自动生成的重复外层标题：
+
+```css
+body:has(.wiki-article) .page-header-section {
+  display: none !important;
+}
+
+.wiki-article {
+  max-width: 1180px;
+  margin: 0 auto;
+  padding: 24px 32px 48px;
+  color: #202122;
+  background: #fff;
+  font-family: sans-serif;
+  font-size: 15px;
+  line-height: 1.65;
+}
+```
+
+正文里不得再添加 `<nav class="toc">`。Wiki.js 左侧“页面内容”已经负责当前条目的章节导航。
+
+桌面端给顶部面包屑留出空间：
+
+```css
+@media (min-width: 1264px) {
+  body:has(.wiki-article) .page-col-sd {
+    top: 118px !important;
+  }
+}
+```
+
+## 5. 标题与颜色
+
+```css
+.wiki-article h1,
+.wiki-article h2 {
+  color: #202122 !important;
+  font-family: "Linux Libertine", Georgia, "Noto Serif SC", "Songti SC", serif;
+  font-weight: normal;
+  border-bottom: 1px solid #a2a9b1;
+}
+```
+
+统一使用 Wikipedia 常见色值：
+
+- 主要文字：`#202122`；
+- 次要文字：`#54595d`；
+- 边框：`#a2a9b1`；
+- 浅背景：`#f8f9fa`；
+- 分组背景：`#eaecf0`；
+- 链接：`#36c`。
+
+## 6. Infobox 规范
+
+### 6.1 桌面尺寸与间距
+
+```css
+.wiki-article table.infobox {
+  float: right;
+  clear: right;
+  width: 360px;
+  margin: 0 0 24px 48px !important;
+  border: 1px solid #a2a9b1 !important;
+  border-collapse: separate !important;
+  border-spacing: 0 !important;
+  table-layout: fixed;
+  background: #f8f9fa;
+  font-size: 84%;
+  line-height: 1.45;
+}
+```
+
+`48px` 左外边距是明确要求，不得压缩为 0。
+
+### 6.2 推荐结构
+
+```html
+<table class="infobox">
+  <caption>
+    GHC-XX
+    <span>广寒计划 · 任务副标题</span>
+  </caption>
+  <tbody>
+    <tr>
+      <td class="infobox-image" colspan="2">
+        <img src="/asset/path.png"
+             data-wiki-asset="/asset/path.png"
+             alt="准确的图片替代文字">
+        <div class="thumbcaption">图片说明</div>
+      </td>
+    </tr>
+    <tr class="infobox-section"><th colspan="2">任务概况</th></tr>
+    <tr>
+      <th class="infobox-label" scope="row">任务编号</th>
+      <td class="infobox-data">GHC-XX</td>
+    </tr>
+  </tbody>
+</table>
+```
+
+标签列占 31%，数据列占 69%。普通数据行只使用淡灰色横向分隔线，不给每个单元格画完整方框。任务概况、发射与着陆、任务纪录等使用 `.infobox-section` 分组。
+
+## 7. 与 Infobox 重叠的章节必须整体避让
+
+凡是与信息框垂直重叠的章节，必须把标题、段落、列表和表格包进同一个区块：
+
+```html
+<section class="infobox-overlap-section" aria-labelledby="crew">
+  <h2 id="crew">乘组</h2>
+  <table class="wikitable">
+    <!-- 完整表格 -->
+  </table>
+</section>
+```
+
+```css
+.wiki-article .infobox-overlap-section {
+  min-width: 0;
+  overflow: hidden;
+}
+
+.wiki-article .infobox-overlap-section .wikitable {
+  table-layout: fixed;
+  overflow-wrap: anywhere;
+}
+```
+
+不能只给 H2 或表格单独设置宽度，也不能使用 `clear` 把表格推到信息框下方。只要章节与信息框发生垂直重叠，整个章节必须保持同一左栏宽度。GHC-05 当前对“任务背景”和“乘组”应用了这一规则。
+
+## 8. 普通数据表
+
+所有任务数据表使用 `class="wikitable"`：
+
+```css
+.wiki-article .wikitable {
+  width: 100%;
+  margin: 1em 0;
+  border: 1px solid #a2a9b1;
+  border-collapse: collapse;
+  background: #f8f9fa;
+  font-size: 90%;
+}
+
+.wiki-article .wikitable th,
+.wiki-article .wikitable td {
+  padding: 6px 8px;
+  border: 1px solid #a2a9b1;
+  text-align: left;
+  vertical-align: top;
+}
+
+.wiki-article .wikitable th {
+  background: #eaecf0;
+  font-weight: bold;
+}
+```
+
+## 9. 图片灯箱与发布要求
+
+### 9.1 图片标记
+
+需要打开灯箱的图片必须同时保留 `src` 和 `data-wiki-asset`：
+
+```html
+<img src="/asset/path.png"
+     data-wiki-asset="/asset/path.png"
+     alt="图片内容说明">
+```
+
+灯箱优先读取图片所在容器中的 `.thumbcaption`；找不到图注时才使用 `alt`。
+
+### 9.2 正确发布命令
+
+```powershell
+.\.venv\Scripts\python.exe scripts\wiki_update_page.py `
+  --path 'home/mission/Guanghan_Program/GHC-XX' `
+  --content-file 'data/wiki/guanghan_ghcXX_zh.html' `
+  --locale 'zh' `
+  --extract-style-to-script-css `
+  --extract-script-to-script-js `
+  --temporary-manage-system
+```
+
+`--extract-script-to-script-js` 不可遗漏。只提取 CSS 会造成页面样式正常、鼠标可能仍显示放大光标，但点击图片没有反应。
+
+发布输出必须同时出现：
+
+```text
+script_css_extracted=True
+script_js_extracted=True
+```
+
+### 9.3 灯箱验收
+
+1. 图片节点存在 `data-lightbox-bound="1"`；
+2. 页面中存在且仅存在一个 `.wiki-image-lightbox`；
+3. 点击图片后灯箱可见；
+4. 原图地址和图注正确；
+5. 打开时 `body` 包含 `wiki-image-lightbox-open`；
+6. 右上角按钮可以关闭；
+7. 点击遮罩可以关闭；
+8. `Esc` 可以关闭；
+9. 关闭后页面滚动恢复。
+
+## 10. 移动端
+
+```css
+@media (max-width: 600px) {
+  .wiki-article {
+    padding: 18px 14px 36px;
+    font-size: 14px;
+  }
+
+  .wiki-article h1 { font-size: 1.8em; }
+
+  .wiki-article table.infobox {
+    float: none;
+    width: 100%;
+    margin: 0.75em 0 1em !important;
+  }
+
+  .wiki-article .wikitable {
+    display: block;
+    overflow-x: auto;
+    white-space: nowrap;
+  }
+}
+```
+
+移动端允许表格自身横向滚动，但不允许整个页面产生横向溢出。
+
+## 11. GHC-05 专属拓扑图
+
+拓扑图不是每个任务页面的必选项。有拓扑图时使用 `figure.topology-embed-shell` 包裹 iframe 和图注，并针对桌面、平板和手机设置不同比例。iframe 必须：
+
+- 携带当前任务编号，例如 `mission=GHC-05`；
+- 使用访问端可到达的公网或同源代理地址；
+- 提供准确的 `title`；
+- 设置必要的 `sandbox` 权限；
+- 提供“在新窗口打开”的回退链接；
+- 不得给页面带来横向滚动条。
+
+完整实现参考 GHC-05 源文件中的 `.topology-embed-*` 和 `<figure class="topology-embed-shell">`。
+
+## 12. 推荐迁移顺序
+
+1. 备份原页面内容和 Wiki.js 页面元数据；
+2. 增加 `.wiki-article` 页面容器；
+3. 隐藏重复的 Wiki.js 外层标题；
+4. 删除正文内部目录；
+5. 套用统一标题、正文、链接和色彩规则；
+6. 重构 Infobox，保留 360px 宽度和 48px 左间距；
+7. 找出所有与 Infobox 垂直重叠的章节；
+8. 用 `.infobox-overlap-section` 包裹每个完整重叠章节；
+9. 将普通数据表改为 `.wikitable`；
+10. 保留 GHC-04 式图片灯箱源码；
+11. 使用同时提取 CSS 与 JavaScript 的命令发布；
+12. 在 1920px、1290px 和 390px 视口下分别截图；
+13. 点击图片并验证全部关闭方式；
+14. 有拓扑图时再测试 iframe、任务切换和移动端缩放。
+
+## 13. 最终验收清单
+
+- [ ] 页面只有一个可见主标题；
+- [ ] 正文没有重复目录；
+- [ ] Wiki.js 左侧导航不遮挡面包屑；
+- [ ] 桌面端 Infobox 宽 360px；
+- [ ] Infobox 与正文保留 48px 布局间距；
+- [ ] Infobox 信息分组明确；
+- [ ] 与 Infobox 重叠的章节整体保持左栏宽度；
+- [ ] 普通表格使用 `wikitable`；
+- [ ] 390px 视口下页面横向溢出为 0；
+- [ ] 图片灯箱行为与 GHC-04 一致；
+- [ ] 灯箱原图和图注正确；
+- [ ] 关闭按钮、遮罩和 `Esc` 均可关闭灯箱；
+- [ ] 发布日志同时显示 CSS 和 JavaScript 提取成功；
+- [ ] 拓扑 iframe 不引入额外页面滚动条。
+
+## 14. 参考文件
+
+- 页面基准：`data/wiki/guanghan_ghc05_zh.html`；
+- 发布工具：`scripts/wiki_update_page.py`；
+- 灯箱验证工具：`scripts/wiki_verify_lightbox.py`；
+- GHC-04 正确灯箱截图：`output/playwright/ghc05_lightbox_fix_2026-07-15/reference_ghc04_open.png`；
+- GHC-05 修复后截图：`output/playwright/ghc05_lightbox_fix_2026-07-15/after_ghc05_open.png`；
+- 宽屏章节避让截图：`output/playwright/ghc05_layout_collision_fix_2026-07-15/crew_section_1920.png`；
+- 移动端截图：`output/playwright/ghc05_layout_collision_fix_2026-07-15/mobile_390.png`。
@@ -47,5 +47,15 @@ class WikiTopologyProxyTests(unittest.TestCase):
        self.assertIn("舱段外围没有环形加压走道", html)


+    def test_ghc05_preserves_the_shared_image_lightbox(self):
+        html = GHC05_PATH.read_text(encoding="utf-8")
+
+        self.assertIn(".wiki-image-lightbox", html)
+        self.assertIn("img[data-wiki-asset]", html)
+        self.assertIn("dataset.lightboxBound", html)
+        self.assertIn("wiki-image-lightbox-open", html)
+        self.assertIn("event.key === 'Escape'", html)
+
+
 if __name__ == "__main__":
    unittest.main()