hesu-JT/docs/superpowers/specs/2026-08-15-hesu-wordpress-theme-design.md

# HESU WordPress 主题设计文档

- 日期：2026-08-15
- 状态：已获用户批准（三轮设计审查修正后）
- 来源：`d:\wp\demojt` 下 10 页静态 HTML 模板 → WordPress 经典主题

## 1. 目标与约束

把现有静态站（HESU，外贸企业站，暗色+橙色主题，英文）1:1 迁移为 WordPress 主题：

- **固定模板**：页面结构锁死，编辑者在后台只能改内容（文字/图片/数字），不能增删或调换板块。
- **公共板块可复用**：抽为原生自定义 Gutenberg 区块（`block.json` + PHP `render.php`），内容存在 `post_content` 区块标记中（非 post meta）。
- **内容后台填充**：区块编辑器可视化编辑；新闻走完整文章系统。
- **不依赖 ACF / 付费插件**：唯一插件依赖 Contact Form 7（联系表单）。
- **严格复刻设计稿**：前端输出 HTML 与静态站逐字节对齐（项目既定原则）。
- 交付位置 `d:\wp\demojt\hesu-theme\hesu\`（zip 后即为标准主题包）。
- 环境：本机无 PHP、无 WP；验证采用"便携 PHP + WordPress + SQLite 插件"一次性测试站（用户已确认）。

## 2. 关键决策记录

| 决策 | 结论 | 备选与理由 |
|---|---|---|
| 主题形态 | 经典主题（PHP 模板）+ 原生自定义区块 | FSE 全区块主题需重写全部 JS 交互（fullpage/pinned/时间线），风险高，弃 |
| 区块实现 | 原生 Gutenberg 区块，无构建工具链（编辑器脚本用原生 `wp.element`，非 JSX） | ACF Pro 区块被用户排除；无 npm 依赖，交付即用 |
| 内容存储 | 区块标记写入 `post_content` | 所见即所得、导入导出原生支持 |
| 结构锁定 | 页面包裹区块 `InnerBlocks templateLock:"all"` + 全部区块实例级 `lock:{move:true,remove:true}` | 见 §5 锁定机制 |
| 新闻 | CPT `news` + 分类法 `news_cat`，Tab 用**分类归档地址**（非自定义 query var） | 原生分页/高亮/canonical 免费获得 |
| 联系表单 | Contact Form 7，seed 时程序化创建默认表单 | 未装 CF7 时显示引导占位 |
| 资产加载 | `has_block()` 判断内容区块条件加载 CSS/JS | 与 slug/模板解耦，编辑者改 slug 不影响 |
| Header/Footer | WP 菜单（自定义渲染）+ Customizer，不做区块 | 见 §6 |
| Seed | `after_switch_theme` 一次性播种（幂等守卫 + 管理员手动重跑按钮） | |

## 3. 主题目录结构

```
wp-content/themes/hesu/
├── style.css              # 主题头信息 + 站点基础样式（原 style.css）
├── functions.php          # 入口，require inc/ 各模块
├── inc/
│   ├── setup.php          # 主题支持、菜单注册、add_post_type_support('page','excerpt')
│   ├── assets.php         # has_block() 映射表条件加载 + 编辑器样式
│   ├── blocks.php         # 扫描 blocks/ 注册区块
│   ├── cpt-news.php       # CPT news + 分类法 news_cat
│   ├── customizer.php     # 社交链接、页脚标语、版权、Mega Menu 左侧文案
│   ├── seed.php           # 激活播种 + 主题设置页（重新创建预置页面按钮）
│   └── walker-mega.php    # Mega Menu 自定义渲染
├── header.php / footer.php
├── page.php               # 所有以区块组成的页面共用（唯一渲染入口）
├── archive-news.php       # 新闻列表（Tab + 分页）
├── single-news.php        # 新闻详情
├── css/ js/ fonts/ image/ # 静态站资产原样迁移（保持相对路径结构）
├── editor-style.css       # 编辑器预览样式（含页面级 class 场景）
└── blocks/                # 每区块一个目录：block.json / render.php / index.js
```

无构建步骤；PHP 目标 7.4+，WP 6.0+（用到区块实例锁）。输出一律转义（`esc_html/esc_attr/esc_url`）。

**前端 body class 注入（关键）**：各页面基底 CSS 挂在 `body.is-*` 上（如 `body.is-bp { background:#fff; ... }` 切换浅色主题），page-shell 只在 `<main>` 上输出 class 覆盖不到 body。静态站实际只有 3 种 body 钩子：`is-bp`（4 个业务页**和发展历程页**，main 同为 `bp`）、`is-news`、`is-contact`；首页/全球布局/关于我们三页 `<body>` 无 class。方案：`page.php` 经 `body_class` 过滤器解析当前 `post_content` 中 page-shell 的变体，注入 `is-bp`（含发展历程）/ `is-contact`（main 为 `ct`）/ `is-gp` / `is-au`（后两者 CSS 无对应钩子，仅为语义标记）；`archive-news.php` / `single-news.php` 直接注入 `is-news`。编辑器侧则由 page-shell 的容器 class 提供同场景（§10）。

## 4. 区块清单（`hesu/` 命名空间，22 个）

> *勘误（2026-08-17）：标题的 22 为早期概数，下表实列 33 个；实现最终为 37 个（补充 brand-card/cap/caps/partner-slide 以对应真实静态 DOM）。以实现与 readme 为准。*

### 通用
| 区块 | 属性/结构 |
|---|---|
| `hesu/hero` | 背景图(ID)、标题、副标题(RichText)、CTA(文字+链接)、SCROLL 指示器开关、对齐变体(左/居中/home/dh/ct)；home 变体内置锁定 InnerBlocks 槽位放 stats-bar（DOM 与静态站一致：stats 在 hero section 内） |
| `hesu/stats-bar` → 子块 `hesu/stat` | 子项：图标图(可选)、数字、后缀、标签；输出 `data-count` |
| `hesu/business-intro` | 固定两栏：左(标题+RichText 段落+stats-bar) 右(图片) |
| `hesu/section-heading` | 标题(+副文+可选外框按钮) |
| `hesu/view-more` | 文字+链接 |
| `hesu/page-shell` | 页面级锁定容器：`templateLock:"all"`，class 由 seed 写死(如 `is-bp`/`page-content`)，渲染为语义化 `<main>`(home 的 `page-content` 为 div，与静态站一致)，无编辑 UI |

### 首页专属
| 区块 | 说明 |
|---|---|
| `hesu/bento-grid` → `hesu/banner-cell` + `hesu/media-card` | 四大业务磁贴，4 卡结构锁死 |
| `hesu/presence` | 标题+副文(含加粗)+按钮+世界地图图 |
| `hesu/hub-carousel` → `hesu/hub-card` | 区域轮播卡(图+区域名+链接) |
| `hesu/partner` | 轮播 slide(图) + 橙色覆盖层(标题+4 特性项:图标+词) |
| `hesu/news-grid` | 动态查询块：自动拉最新 4 篇新闻(图=特色图、分类+年份自动)，仅"查看更多"链接可配 |

所有带锚点目标的区块（`gp-screen` 的 `gp-1..gp-5`、产品区 `#products` 等）的 `id` 为可配置属性，seed 沿用静态站原值，保证页脚锚点链接（如 `global-presence#gp-2`）不失效。

### 业务页专属
| 区块 | 说明 |
|---|---|
| `hesu/large-image` | 全宽大图框(bm-stock/gl-port 共用) |
| `hesu/product-cards` → `hesu/product-card` | 产品分类卡：主题内置 SVG 图标集选择(或自定义图)+名称 |
| `hesu/feature-cards` → `hesu/feature-card` | 统一"图标+标题+描述"卡片组，变体 class 区分 as-services / ae-region / as-region / gl-services 四处样式 |
| `hesu/showcase` / `hesu/brand-wall` / `hesu/model-list` | 汽车出口页专属 |

### 特殊页面
| 区块 | 说明 |
|---|---|
| `hesu/timeline` → `hesu/timeline-item` | 发展历程横向时间线(年份/标题/描述) |
| `hesu/gp-shell` → `hesu/gp-screen` | 全球布局 fullpage。容器含 `.gp-pagebg` 背景层；每屏变体(概览/区域，id `gp-1..gp-5` 可配)；**概览屏内部含 `gp-nav-list` 链接列表（屏内容的一部分，非独立导航）**——列表项为锁定子区块(文案+`#gp-N` 锚点+`data-i`)。global-presence.js **零适配**原样迁移（它只做 active 高亮，按 `data-i` 匹配） |
| `hesu/au-stage` → `hesu/au-screen-1` / `hesu/au-screen-2` | 关于我们 pinned 视屏：内部结构(背景图/角图/遮罩/标语层/缩放图/大 logo)固定，开放文案+图片编辑。注意 au-screen-1 背景为 style 内联 background-image |
| `hesu/au-gps` | 关于我们底部区，**内部 4 层锁定结构**：① head(标题+文案) ② 4 图一行 ③ 宽幅图 ④ 左右分栏——左侧数据轮播(`au-gps__data-card`: 图+标题+描述 ×3，圆点由 about-us.js 驱动) + 右侧图文覆盖卡(图+overlay 标题+文案) |
| `hesu/contact-form` | CF7 表单下拉选择器+容器样式；CF7 未装显示安装引导占位 |
| `hesu/contact-map` | 总部地图：默认嵌入静态站的 OpenStreetMap iframe（URL 可配置） |

### 编辑器脚本与渲染约定
- 主文案内联 RichText；数字/后缀/链接等用右侧栏 TextControl（控制代码量）。
- **RichText 属性存储（关键陷阱）**：本主题区块全部为动态渲染（render.php、无 save 函数），RichText 属性**禁止用 `source:'html'`**（无保存标记可解析会丢内容），一律普通 string 属性 + `value`/`onChange`。
- **stat-num DOM 微结构（关键）**：main.js 计数器以 `el.firstChild.nodeValue` 写数字——`<span class="stat-num" data-count="20">20<span class="plus">+</span></span>` 中数字文本节点必须是 firstChild，render.php 输出不得多包元素。
- 容器类动态区块 render.php 必须输出 `$content`（InnerBlocks 内容）。
- 不做 inserter `example` 配置（页面锁死，无人手动插入区块）。
- 共享 helper（createElement 包装、公共 Inspector）提为 `blocks/editor/helpers.js` 单 handle。

## 5. 结构锁定机制（核心）

1. **页面级**：每个页面 = `page-shell`（或首页 = `hero(home)` + `page-shell` 两个顶层块，因静态站 DOM 中 hero 在 `page-content` 之外）。顶层块带实例锁 `lock:{move:true,remove:true}`。
2. **容器级**：`page-shell` 内 `InnerBlocks templateLock:"all"`——不能增删/移动子板块，只能进入编辑内容。
3. **编辑器加固**：非管理员隐藏区块插入器与解锁入口（editor settings 过滤）。
4. **残余风险（已向用户说明）**：WP 核心无法阻止管理员手动解锁破坏结构；文档注明"解锁=破坏页面"。

## 6. Header / Footer 内容来源（不用区块）

| 部位 | 配置方式 |
|---|---|
| Logo | 原生 Custom Logo |
| 主导航 | WP 菜单；Mega Menu 用 `wp_get_nav_menu_items()` 自定义渲染：卡片 = 菜单项，卡片图 = 目标页特色图片（无图回退主题占位图，如指向归档/锚点的 News 卡），卡片文案 = 页面摘要（页面启用 excerpt）或菜单项描述 |
| Mega Menu 左侧文案 × 2 组 | Customizer 文本字段 |
| Contact Us 按钮 | 指向联系页 |
| Footer 5 栏 | 1 个 WP 菜单(4 个一级项=4 栏) + 标语走 Customizer |
| 社交图标 4 个 | Customizer(平台+URL) |
| 版权 / Privacy / Terms / Sitemap | Customizer |
| 菜单高亮 | `nav_menu_css_class` 过滤器补 `active` 类(静态 CSS 认 `.active`，WP 原生输出 `.current-menu-item`) |

Mega Menu 卡片恰好 4 张是布局约束，seed 保证初始 4 项；文档说明增删项会改变布局。

## 7. 页面编排（seed 写死顺序）

| 页面 | 组成 |
|---|---|
| 首页 Home | `hero(home,含stats)` + `page-shell(page-content)` → bento-grid → presence → hub-carousel → partner → news-grid |
| 建材出口 | `page-shell(is-bp)` → hero → business-intro(+stats，4 项 data-count) → large-image → product-cards → view-more |
| 汽车出口 | `page-shell(is-bp)` → hero(居中) → business-intro(无 stats，静态站此页没有) → showcase → brand-wall → model-list → feature-cards(region) → view-more |
| 售后改装 | `page-shell(is-bp)` → hero → business-intro(无 stats，静态站此页没有) → feature-cards(services) → feature-cards(region) |
| 国际物流 | `page-shell(is-bp)` → hero → business-intro(+stats，4 项 data-count) → large-image(port) → feature-cards(services) |
| 全球布局 | `page-shell(main 为 gp-main)` → gp-shell(1 概览屏+4 区域屏) |
| 关于我们 | `page-shell(main 为 au-main)` → au-stage(2 pinned 屏) → au-gps |
| 发展历程 | `page-shell(is-bp，静态站此页 body 即 is-bp)` → hero(dh) → timeline |
| 联系我们 | `page-shell(is-contact，main 为 ct)` → hero(ct) → contact-form → contact-map |
| 新闻列表/详情 | PHP 模板渲染，不用区块 |

## 8. 新闻系统

- CPT `news`：支持标题/编辑器/特色图片/摘要；归档 `/news/`（**不建 News 页面，避免 URL 冲突**；导航 News 链接指向 `get_post_type_archive_link('news')`）。
- 分类法 `news_cat`（非层级）：seed 建 4 词——Company News / Delivery Cases / Exhibition Info / Global Network（第 4 个供首页卡片 meta 与页脚 News 栏使用；Tab 自动列出全部词，初始即 4 个，较静态站多出 Global Network 一项为有意取舍）。Tab = 全部分类词的**归档地址链接**；分页原生。
- `archive-news.php`：新闻 Hero → Tab → **左文右图行列表（`.nw-row`，与静态站一致，非卡片网格）** → 分页（每页 5 条，与静态 news.js 的 PER_PAGE 一致）。行内 `[data-reveal]`/`.nw-row` 默认 `opacity:0`，reveal 逻辑并入 main.js（见 §10）。**Hero 背景图来源**：Customizer 新增"新闻 Hero 图"设置（theme mod，默认主题资产 `image/carexport/export-bg.jpg`），归档与详情共用。
- `single-news.php`（按 `demo-html/新闻详情1.jpg` 已读图确认）：新闻 Hero+面包屑 → 分类标签+日期+标题 → 特色图 → 正文（核心区块编辑器，零自定义区块）→ 上一篇/下一篇 → 返回列表。
- 首页 `news-grid` 自动拉最新 4 篇。
- 静态 `news.js`（207 行，客户端渲染 15 篇硬编码数据 + Tab 过滤 + 分页）服务端化后大部分作废，不迁移；仅 reveal 行为由 main.js 承接。

## 9. Seed 流程

```
守卫(option hesu_seeded) → 图片入库(image/ 内容图经临时文件 + media_handle_sideload)
→ 建 9 个页面(锁定区块标记，引用图片附件 ID；9 页全部设置特色图片，供 Mega Menu 卡片使用)
→ 设 show_on_front/page_on_front → 建 4 个分类词
→ 建 15 篇示例新闻(迁移 news.js 内置的全部 15 篇数据，保证分页可见 3 页)
→ 建主菜单+页脚菜单并绑定卡位 → CF7 已激活时创建默认表单(字段=静态表单)
→ 写入 hesu_seeded
```

- CF7 晚于主题激活的场景：另挂 `activated_plugin` 钩子，检测到 CF7 启用且默认表单缺失时补建；主题设置页"重新创建预置页面"按钮作为最终兜底。
- Mega Menu 卡片无特色图时的占位：复刻静态站 `ph-*` 占位样式（底色 + "Photo" 标签的 div），不使用裸 `<img>`。

- 主题设置页提供管理员"重新创建预置页面"按钮（幂等重跑）。
- 若在已有内容的站点激活：seed 仍会创建预置页面并设置首页，文档说明预期用于全新安装。

## 10. 资产加载

| 层级 | 策略 |
|---|---|
| 全站 | `style.css` + `fonts.css` + `main.js`(footer 加载，与静态站 body 尾一致；扩展：新增对 `[data-reveal]` 与 `.nw-row` 的 IntersectionObserver reveal——业务页 `[data-reveal]` 与新闻行默认 `opacity:0`，无 JS 则内容不可见) |
| 按区块 CSS | `business-intro→business.css`、`hero→business.css`、`product-cards→building-materials.css`、`brand-wall/showcase/model-list→auto-export.css`、`feature-cards→after-sales.css+auto-export.css+global-logistics.css`(交叉装载无害：各文件选择器以自身变体 class 作用域)、`timeline→development-history.css+js`、`gp-shell→global-presence.css+js`、`au-stage→about-us.css+js`、`news-grid→news.css`、`contact-form→contact.css+js` |
| 按区块 JS | 出现任一业务页区块（hero/business-intro/product-cards/brand-wall/showcase/model-list/feature-cards/large-image）→ 加载 4 个业务页 JS（building-materials.js / auto-export.js / after-sales.js / global-logistics.js，共约 6KB）。理由：各文件自带选择器守卫（无目标即 return），其中 data-count 计数（建材/物流两页的 bp-stats）与部分 reveal 由它们驱动，main.js 的 `.stat-num` 计数器不覆盖 `bp-stat__num` 结构 |
| news.js | 不迁移（客户端渲染/过滤/分页已服务端化），reveal 逻辑由 main.js 扩展承接 |
| 模板直载 | archive/single-news 直接 enqueue `news.css` |
| 编辑器 | 编辑器侧加载 `fonts.css` + `style.css` + **全部页面 CSS**（约 130KB，仅后台开销，无法按页条件）；page-shell 输出页面级 class(如 `is-bp`)使作用域 CSS 在编辑器 iframe 生效 |
| 行为边界 | 交互(计数/轮播/fullpage)仅在.front 前端运行，编辑器内为静态预览——WP 服务端渲染区块的固有限制 |

### CF7 与静态表单的样式映射

静态表单是自绘结构（`ct-form/ct-field/ct-label/ct-input/ct-selectwrap` + `#ctForm` 客户端校验 + `#ctNote` 成功态）；CF7 输出 `form.wpcf7-form` + `span.wpcf7-form-control-wrap` 包裹。约定：

- seed 建表单时为每个字段 shortcode 挂静态 class（如 `[text* your-name class:ct-input]`）。
- `contact.css` 增补桥接规则：以 CF7 实际 DOM（`.wpcf7-form` / `.wpcf7-form-control-wrap` / `.wpcf7-not-valid` / 响应元素 `.wpcf7-response-output`）为目标复刻 ct-* 视觉。CF7 6.x 起状态类（`invalid` / `sent` / `failed` / `aborted` / `unaccepted` / `spam`）挂在 form 元素上（如 `form.wpcf7-form.sent`），响应元素仅保留 `.wpcf7-response-output`，桥接规则按 `form.{invalid,sent,...} .wpcf7-response-output` 匹配；校验与提交反馈全部交给 CF7 原生状态 class，`contact.js` 的表单分支不迁移。

JS 依赖事实：静态站全部 JS 为原生手写（无 GSAP/fullpage 库），**全部原样迁移、零适配**（global-presence.js 的 active 高亮依赖 `gp-nav-list a[data-i]` 标记，由概览屏锁定子区块保证）。main.js 的 network 无限轮播克隆逻辑要求 `.network-card` 为 `.network-track` 直接子元素，hub-carousel 渲染须保持该层级。

## 11. 验证方案（用户已确认搭一次性环境）

1. 下载便携版 PHP（≥7.4，含 pdo_sqlite）解压至项目临时目录（不入库）。
2. WordPress + SQLite drop-in（如 wp-sqlite-db）搭建一次性站点，安装主题与 CF7。
3. 实跑验收清单（§12）。
4. 测完删除临时站点；若用户后续装正式环境可复用清单。

## 12. 验收清单

1. 干净 WP 激活 → 页面/菜单/示例新闻自动生成，首页即成型。
2. 10 个路由与静态站逐页对照：板块顺序、数字滚动、Mega Menu、轮播拖拽、fullpage 翻屏、pinned 视屏、时间线横滑全部工作（含 `.reveal` 滚动动画）。
3. 以"编辑"角色打开任意页面：结构不可增删/移动，文字图片可改；尝试删除被锁区块被拒绝。
4. 新闻：各类别发文 → 归档 Tab 过滤 + 分页 + 首页卡片自动更新。
5. 联系表单：样式按 §10 桥接规则还原静态视觉；测试环境将 CF7 邮件设为 dummy（便携 PHP 无邮件服务），验收标准为**提交成功态/校验态正确展示**，不要求真实发信。
6. 导航高亮、Customizer 各字段生效。
7. `php -l` 全过、输出转义审查、控制台无报错、本地字体正常加载。
8. CF7 缺失时联系页显示引导提示而非报错。

## 13. 设计审查修正记录（三轮）

| # | 级别 | 问题 | 修正 |
|---|---|---|---|
| 1 | 漏洞 | `templateLock` 锁不到顶层区块 | 全部区块实例级 `lock:{move,remove}` |
| 2 | 漏洞 | News 页面与 CPT 归档 `/news/` URL 冲突 | 不建 News 页面 |
| 3 | 漏洞 | 按 slug 条件加载资产脆弱 | 改 `has_block()` |
| 4 | 漏洞 | 页面级 CSS 依赖 body class，编辑器不生效 | page-shell 输出等价 class |
| 5 | 漏洞 | 首页 hero 与 page-content 的 DOM 层级套不进单容器 | 两个顶层锁死块；hero(home) 内嵌 stats 槽位 |
| 6 | 缺口 | Mega Menu News 卡片无特色图/摘要 | 占位图+菜单描述兜底 |
| 7 | 缺口 | 菜单高亮 `.active` vs `.current-menu-item` | nav_menu_css_class 过滤器 |
| 8 | 缺口 | wp_nav_menu 输出不了 mega 结构 | wp_get_nav_menu_items 自定义渲染 |
| 9 | 缺口 | 新闻 Tab 分页保参易错 | 改用分类归档地址，原生分页 |
| 10 | 缺口 | seed 无重跑出口 | 主题设置页按钮 |
| 11 | 缺口 | News 卡用 query_var 方案繁琐 | 改原生归档 URL |
| 12 | 矛盾 | 验收清单需实机 vs 本机无 PHP | 便携 PHP + SQLite 一次性测试站 |
| 13 | 漏洞 | 页面基底 CSS 挂在 `body.is-*`（如 body.is-bp 浅色主题），page-shell 的 main class 覆盖不到 body | `body_class` 过滤器按 page-shell 变体注入前端 body class（spec 审查发现） |
| 14 | 漏洞 | 4 个业务页 JS（data-count 计数/reveal）未纳入资产映射；`[data-reveal]` 默认 opacity:0，JS 缺失内容不可见 | has_block 命中业务区块即加载 4 个业务 JS；main.js 扩展承接 news reveal（spec 审查发现） |
| 15 | 错误 | 汽车出口/售后改装两页静态站没有 stats，编排误写 business-intro(+stats) | 改为无 stats（spec 审查发现） |
| 16 | 错误 | 新闻列表实为左文右图行、每页 5 条、news.js 内置 15 篇，spec 误写 3 列卡片/9 条/4 篇 | 按静态站修正；Tab 有意保留 4 词（spec 审查发现） |
| 17 | 缺口 | CF7 DOM 与静态表单差异未定义、CF7 晚激活无法补建表单、seed 未设页面特色图、锚点 id 保留未覆盖、测试环境无法真实发信 | §10 桥接规则、activated_plugin 补建、seed 设特色图+ph-* 占位、区块 id 可配置、验收措辞调整（spec 审查发现） |
| 18 | 错误 | body 变体名臆造：静态 CSS 只有 is-bp/is-news/is-contact 三种钩子；发展历程页实为 is-bp+main.bp，联系页为 is-contact+main.ct，不存在 is-dh/is-ct | §3/§7 按静态站事实改注 is-bp / is-contact（二审发现） |
| 19 | 错误 | gp"圆点导航由 JS 从 data-nav-title 生成"系错误假设：gp-nav-list 实为概览屏内部链接列表（屏内容），js 仅做 active 高亮，无需任何适配；导航文案与屏标题在静态站本就不一致，不应自动生成 | §4 改为概览屏锁定子区块，global-presence.js 零适配（四轮源码核查发现） |
| 20 | 不足 | au-gps 实为 4 层结构（head/4 图行/宽图/数据轮播+图文卡分栏），spec 仅一句带过 | §4 细化内部结构（四轮源码核查发现） |
| 21 | 缺口 | 动态区块 RichText 用 source:html 会丢内容；stat-num 的 firstChild 文本节点微结构未约定；编辑器 CSS 加载范围未明确；新闻 Hero 图来源未定义；contact-map 实为 OSM iframe | 编辑器约定补两条关键约定、§10 明确全量页面 CSS、§8 Customizer 新闻 Hero 图、contact-map 改 iframe（四轮源码核查发现） |

**内容备注（非缺陷）**：静态站 gp-3（Africa）屏的 lead 文案讲的是 Minsk/Belarus（静态站自身的复制粘贴错误）。迁移按原文保留，seed 后可在后台修正。

## 14. 范围外（明确不做）

- 多语言（结构不阻碍后续接多语言插件，内容在 post_content 中天然可翻译）。
- Classic Editor 插件兼容（文档注明必须使用区块编辑器）。
- 性能优化超出 §10 所列（CDN、缓存策略交由宿主环境）。

## 15. v2 同步记录（2026-08-17）

静态站改版 v2（commit a68ff43）后的主题同步：mega 精简（Business 只留 title/About 空 left 2 卡）、footer 社交 img 化（LinkedIn→Instagram）、hero scroll 全删、bp-stats→bp-caps（含物流双 label）、SVG 图标全面 img 化、as-loc 简化、ae-models 去 tags、ae-map 去 markers、au-gps 重构（img 化+4 数据卡+feature-copy）、au-zoom-mask 新增、ct-map 三层结构、新闻系统重做（4 篇/nd-* 详情页/nw-empty 空态）、news-banner 新图。详见 `plans/2026-08-17-static-v2-sync-report.md` 与验收日志。已接受偏差：footer 按正确闭合（不复刻旧页嵌套错误）；"Four Core Businessesk"与"99% Awards Winner"原样复刻。