# 代码清理方案

> 项目：B2B Trade 主题（fragrance-trade）
> 基准：2026-07-24 全量代码扫描
> 原则：分阶段、可回滚、每步可验证

---

## 清理范围总览

| 类别 | 数量 | 风险 | 说明 |
|------|------|------|------|
| 死模板文件 | 7 个 | 低 | 多页面重构后遗留，无任何 `get_template_part()` 引用 |
| 死 JS 库 | 4 个 | 中 | plugins.js 中 6 个库仅 1 个实际使用 |
| 死 CSS 样式 | ~60% vendor.css | 低 | Jarallax + AOS 样式，对应功能未使用 |
| 死图片资源 | 13 个 | 极低 | 旧模板遗留素材，全项目零引用 |
| 死表单处理器 | 1 个 | 中 | inquiry.php 仍挂在 admin_post 但无表单提交 |
| CDN 安全缺失 | 2 处 | 中 | Bootstrap 无 SRI 完整性校验 |
| jQuery 冗余依赖 | 1 处 | 中 | 仅为 Colorbox 一个函数加载整个 jQuery |

---

## 阶段一：死代码删除（零风险）

> 删除后不影响任何已上线页面。每步删完刷新全站确认无报错。

### 1.1 删除 7 个死模板文件

| 文件 | 原用途 | 替代方案 |
|------|--------|----------|
| `template-parts/home/products.php` | 旧 B2B 产品展示 | 已被 CPT `service` + `service-teaser.php` 替代 |
| `template-parts/home/services.php` | 旧服务总览 | 已被 `service-teaser.php` 替代 |
| `template-parts/home/quality.php` | 旧质检流程 | 首页不再展示，内容可在关于页补充 |
| `template-parts/home/process.php` | 旧施工流程 | 首页不再展示 |
| `template-parts/home/projects.php` | 旧项目案例 | 已被 CPT `case` + `case-teaser.php` 替代 |
| `template-parts/home/customization.php` | 旧定制服务 | 首页不再展示 |
| `template-parts/home/rfq.php` | 旧预约表单 | 联系页已改为联系方式卡片，无表单 |

**验证方法**：删除后逐页访问首页 / 关于 / FAQ / 联系页 / 服务列表 / 案例列表，确认无 500 错误、无模板缺失警告。

### 1.2 删除 13 个死图片资源

| 文件 | 说明 |
|------|------|
| `assets/images/main-logo.png` | 旧 logo，已用 `placeholder-logo.svg` + WP custom-logo |
| `assets/images/product-item1.jpg` | 旧产品图 ×3 |
| `assets/images/product-item2.jpg` | |
| `assets/images/product-item3.jpg` | |
| `assets/images/insta-item1.jpg` | 旧 Instagram 展示图 ×6 |
| `assets/images/insta-item2.jpg` | |
| `assets/images/insta-item3.jpg` | |
| `assets/images/insta-item4.jpg` | |
| `assets/images/insta-item5.jpg` | |
| `assets/images/insta-item6.jpg` | |
| `assets/images/single-image1.png` | 旧单图素材 |
| `assets/images/factory-workflow-illustration.webp` | 旧流程插图 |

**验证方法**：全项目 grep 这些文件名，确认零引用（已验证）。

---

## 阶段二：JS 依赖瘦身（中等风险）

> 当前 plugins.js 拼接了 6 个库，但只有 Colorbox 真正在用。
> AOS 虽然在 theme.js 中初始化，但没有任何模板使用 `data-aos` 属性，属于空转。

### 2.1 库使用情况核实

| 库 | plugins.js 中 | theme.js 调用 | 模板中使用 | 结论 |
|----|--------------|---------------|-----------|------|
| jQuery Easing | 有 | 无 | 无 | **删除** |
| Jarallax v2.0.2 | 有 | 无 | 无 | **删除** |
| Colorbox 1.6.4 | 有 | `$.fn.colorbox()` | `class="youtube"` 在 video.php | **保留** |
| AOS | 有 | `AOS.init()` | 无 `data-aos` 属性 | **删除** |
| anime.js | 有 | 无 | 无 | **删除** |
| HC-Sticky | 有 | 无 | 无 | **删除** |

### 2.2 操作步骤

**步骤 A — 清理 theme.js 中的 AOS 调用**

删除 `initAnimations()` 函数及其调用（第 19-22 行、第 42 行）。AOS 在空转，删了不影响任何可见效果。

**步骤 B — 重写 plugins.js**

将 plugins.js 从 6 库拼接缩减为仅保留 Colorbox 1.6.4（约 4KB）。其余 5 个库全部移除。

**步骤 C — 清理 vendor.css**

删除 vendor.css 中的 Jarallax 样式（第 6-36 行）和 AOS 样式（第 89 行至文件末尾的大段压缩 CSS）。仅保留 Colorbox 样式（第 39-85 行）。

**步骤 D — 评估 jQuery 去留**

Colorbox 依赖 jQuery。两个选项：

| 方案 | 改动量 | 效果 |
|------|--------|------|
| **A. 保留 jQuery**（推荐当前阶段） | 无 | 维持现状，Colorbox 正常工作 |
| B. 用原生 lightbox 替代 Colorbox | 中等 | 彻底去掉 jQuery 依赖，减少 ~90KB 加载 |

> 方案 B 需要找一个不依赖 jQuery 的 lightbox 库（如 GLightbox）并改写 theme.js 的 `initVideoLightbox()`。建议放到独立迭代中做，不在本次清理范围内。

**验证方法**：
1. 打开关于门店页，点击施工视频缩略图，确认 Colorbox 弹窗正常弹出
2. 检查浏览器控制台无 JS 报错
3. 对比清理前后页面加载时间（预计减少 ~80KB JS 传输）

---

## 阶段三：死表单处理器处理（中等风险）

### 3.1 现状

`inc/inquiry.php` 注册了 `admin_post_fragrance_rfq` 和 `admin_post_nopriv_fragrance_rfq` 两个 hook，但联系页已无表单，这些 hook 永远不会被触发。

### 3.2 两个选项

| 方案 | 操作 | 理由 |
|------|------|------|
| **A. 保留但标注弃用**（推荐） | 在文件头加 `@deprecated` 注释，保留 hook 注册 | 未来可能恢复预约表单功能，代码本身安全合规，留着不碍事 |
| B. 完全删除 | 删除 inquiry.php + 从 functions.php 移除加载 | 彻底清理，但未来恢复需重写 |

> 推荐 A：inquiry.php 的安全实现（nonce + honeypot + 速率限制 + 邮件头注入防护）是项目中的优秀范例，删了可惜。标注弃用即可。

---

## 阶段四：CDN 安全加固（中等风险）

### 4.1 现状

`inc/setup.php` 第 47-54 行从 `cdn.bootcdn.net` 加载 Bootstrap CSS/JS，无 `integrity` 属性（SRI），无本地回退。如果 CDN 被劫持，攻击者可注入恶意代码。

### 4.2 操作步骤

**步骤 A — 添加 SRI 完整性校验**

为 Bootstrap CSS 和 JS 添加 `integrity` + `crossorigin` 属性。需要从 [BootCDN](https://www.bootcdn.cn/) 获取对应版本的 SRI 哈希。

```php
// 修改前
wp_enqueue_style( 'fragrance-bootstrap', 'https://cdn.bootcdn.net/ajax/libs/twitter-bootstrap/5.3.0-alpha3/css/bootstrap.min.css', array(), '5.3.0-alpha3' );

// 修改后（需填入实际哈希）
wp_enqueue_style( 'fragrance-bootstrap', 'https://cdn.bootcdn.net/ajax/libs/twitter-bootstrap/5.3.0-alpha3/css/bootstrap.min.css', array(), '5.3.0-alpha3' );
// WP 的 wp_enqueue_style 不直接支持 integrity，需用 style_loader_tag 过滤器追加属性
```

由于 WordPress 的 `wp_enqueue_*` 函数不直接支持 `integrity` / `crossorigin` 属性，需要通过 `style_loader_tag` 和 `script_loader_tag` 过滤器注入：

```php
// 在 inc/setup.php 中添加
function fragrance_trade_resource_integrity( $html, $handle ) {
    $sri = array(
        'fragrance-bootstrap' => 'sha384-XXXXX', // 替换为实际哈希
    );
    if ( isset( $sri[ $handle ] ) ) {
        $html = str_replace( '/>', ' integrity="' . $sri[ $handle ] . '" crossorigin="anonymous" />', $html );
    }
    return $html;
}
add_filter( 'style_loader_tag', 'fragrance_trade_resource_integrity', 10, 2 );
```

> **注意**：Google Fonts 不支持 SRI（动态生成 CSS），保持现状即可。

**步骤 B — 可选：本地回退**

将 Bootstrap 下载到 `assets/vendor/bootstrap/`，CDN 加载失败时自动回退。此步骤为可选项，当前 CDN 可用性已较高。

**验证方法**：浏览器 DevTools → Network → 确认 Bootstrap 资源加载请求携带 `integrity` 头。

---

## 阶段五：Customizer 配置清理（低风险）

### 5.1 现状

`inc/customizer.php` 中仍有大量为已删除模板配置的 Customizer 字段（products、services、quality、process、projects、customization 等）。这些字段在后台 Customizer 面板中可见但对应的模板已不存在，用户会困惑。

### 5.2 操作步骤

1. 逐个移除已删除模板对应的 Customizer section + 字段注册代码
2. 对应的 `inc/defaults.php` 默认值也一并清理
3. 保留仍在使用的 section：hero、trust、store_info、contact_social、video、documents、faq

> **注意**：此阶段改动量大且涉及 Customizer 面板结构，建议在测试环境验证后再上线。

---

## 执行顺序与预估

| 阶段 | 内容 | 文件改动数 | 风险 | 建议优先级 |
|------|------|-----------|------|-----------|
| 一 | 删死模板 + 死图片 | 删 20 个文件 | 极低 | 立即执行 |
| 二 | JS 库瘦身 | 改 3 个文件 | 中 | 紧随其后 |
| 三 | 表单处理器标注 | 改 1 个文件 | 极低 | 随手做 |
| 四 | CDN SRI 加固 | 改 1 个文件 | 低 | 本周内 |
| 五 | Customizer 清理 | 改 2 个文件 | 中 | 下次迭代 |

---

## 每阶段完成后的检查清单

- [ ] 全站逐页访问无 500 / 404
- [ ] 浏览器控制台无 JS 报错
- [ ] WP Debug Log 无 PHP warning/notice
- [ ] Customizer 面板无残留无效 section
- [ ] Git 提交信息标注 `[cleanup]` + 阶段编号
- [ ] 推送到 Gitea 前本地验证通过

---

## 回滚方案

每个阶段独立提交，如果发现问题：

```bash
# 查看提交历史
git log --oneline

# 回退到指定提交
git revert <commit-hash>
```

阶段一和阶段二各自独立 commit，确保可单独回滚。