car-t-t/CODE_CLEANUP_PLAN.md

代码清理方案

项目：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 获取对应版本的 SRI 哈希。

// 修改前
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 过滤器注入：

// 在 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 前本地验证通过

---

回滚方案

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

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

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

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