# 广寒任务 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`。