car-t-t/CODE_REVIEW_STANDARD.md

代码审查标准与流程

适用项目：B2B Trade 主题（fragrance-trade） 技术栈：WordPress 经典主题 / PHP 7.4+ / Bootstrap 5.3 / jQuery 版本：v1.0 | 2026-07-24

---

一、审查原则

1. 安全优先 — WordPress 主题的 XSS / SQL 注入 / CSRF 是红线
2. 就事论事 — 评论针对代码，不针对人
3. 说清楚为什么 — 不只说"改这个"，要解释原因和潜在风险
4. 给方向不给答案 — 引导作者自己思考，除非是明确的安全漏洞
5. 赞美好代码 — 发现优秀实践要明确指出，让团队学习

---

二、优先级体系

每个审查意见必须标注以下级别之一：

级别	标记	含义	处理要求
🔴 阻断	Blocker	安全漏洞 / 数据丢失 / 破坏功能	必须修复后才能合并
🟡 建议	Suggestion	输入验证缺失 / 性能问题 / 可维护性	应当修复，可协商
💭 细节	Nit	命名 / 风格 / 文档	修不修都行，不阻塞

---

三、WordPress 主题专项审查清单

🔴 阻断级检查项（必须全部通过）

3.1 安全性

• 直接访问防护 — 所有 PHP 文件以 if ( ! defined( 'ABSPATH' ) ) exit; 开头
• SQL 注入 — 禁止拼接 SQL；必须使用 $wpdb->prepare() 或 WP API（get_posts(), WP_Query）
• XSS 防护 — 所有输出必须经过转义：
  • HTML 文本 → esc_html()
  • URL → esc_url()
  • 属性 → esc_attr()
  • 富文本 → wp_kses_post()
• CSRF 防护 — 所有表单提交 / POST 处理必须有 wp_nonce_field() + check_admin_referer()
• 输入净化 — 所有 $_POST / $_GET / $_SERVER 必须用 wp_unslash() + 对应 sanitize_* 函数
• 邮件头注入 — 从用户输入构造邮件头时，必须剥离 \r\n
• 文件包含 — 禁止用户输入直接传入 include / require / get_template_part()
• 权限检查 — 任何管理员操作必须有 current_user_can() 检查

3.2 功能正确性

• 关键路径错误处理 — 表单提交失败有 fallback（非空白白屏）
• 数据完整性 — 不会因空值 / 缺失字段导致 fatal error
• 重定向安全 — 使用 wp_safe_redirect() + wp_validate_redirect()，禁止直接 header('Location:')

🟡 建议级检查项

3.3 输入验证与数据

• Customizer 字段是否有对应类型的 sanitize_callback
• get_theme_mod() 取值后是否有默认值兜底
• 用户上传的 URL 是否用 esc_url_raw() 存入、esc_url() 输出

3.4 性能

• N+1 查询 — 循环内不执行数据库查询，提前预取
• 资源加载 — 脚本用 wp_enqueue_script，不硬编码 <script src>
• 图片优化 — 使用响应式 srcset / loading="lazy"
• Transient 缓存 — 耗时操作（远程请求、复杂查询）用 transient 缓存

3.5 可维护性

• 死代码 — 新增模板文件必须有对应的 get_template_part() 调用；废弃文件及时删除
• 命名规范 — 函数 / 变量统一 fragrance_trade_ 前缀，蛇形命名
• 函数长度 — 单函数不超过 80 行，超过则考虑拆分
• 重复代码 — 相同逻辑出现 3 次以上应提取为 helper 函数
• 文件组织 — 新功能按职责归入 inc/ 对应模块，不堆在 functions.php

3.6 前端质量

• CDN 资源 — 第三方 CDN 必须有 SRI 完整性哈希 + 本地回退
• 第三方库 — 禁止将多个库的压缩代码拼接到单文件；用 npm + 构建流程管理
• 无障碍 — 图片有 alt，表单有 label，按钮有可读文本
• 响应式 — 移动端布局不溢出，触控目标不小于 44×44px
• prefers-reduced-motion — 动画尊重用户偏好

💭 细节级检查项

• 文本域统一为 fragrance-trade，所有字符串包裹 __() / esc_html_e()
• 注释说明"为什么"而非"做了什么"
• 长行拆分（单行 PHP echo 不超过 120 字符）
• CSS 自定义属性命名遵循 --token-name 格式

---

四、审查流程

┌─────────────────────────────────────────────────────────────┐
│                      代码审查流程                             │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  1. 提交前自检                                               │
│     作者按 §三 清单自检 → 确认无 🔴 项                       │
│                          ↓                                  │
│  2. 提交审查                                                 │
│     Gitea PR / 提交说明 → 附上改动摘要和测试方式             │
│                          ↓                                  │
│  3. 审查者检查                                                │
│     按 §三 清单逐项 → 标注 🔴🟡💭 → 写明原因和建议方向      │
│                          ↓                                  │
│  4. 分支处理                                                 │
│     ├─ 有 🔴 → 打回，作者修复后重新提交                      │
│     ├─ 有 🟡 → 讨论确认，修复或记录为后续任务                │
│     └─ 仅 💭 → 可选修复，直接通过                            │
│                          ↓                                  │
│  5. 合并                                                     │
│     审查者 Approve → 作者合并 → 删除分支                     │
│                          ↓                                  │
│  6. 回顾（每周）                                              │
│     汇总本周审查发现的共性问题 → 更新本标准                   │
│                                                             │
└─────────────────────────────────────────────────────────────┘

4.1 提交规范

提交 PR / 提交审查时，标题格式：

[类型] 简述 — 具体改动

类型：feat / fix / refactor / style / security / docs / chore

示例：

[security] RFQ 表单 — 增加 nonce 验证
[feat] 案例详情页 — 添加施工前后对比图
[refactor] inc/defaults.php — 按区块分组重组配置键

4.2 审查时间线

阶段	时限	说明
初次审查	提交后 24h 内	审查者完成首轮检查
修复后复审	作者修复后 12h 内	审查者确认修复
超时升级	超 48h 未回应	@项目负责人介入协调

---

五、审查评论模板

🔴 阻断级

🔴 [安全/XSS] 第 42 行：用户输入直接输出到 HTML

原因：
$subtitle 变量来自 $_POST，未经 esc_html() 转义直接 echo，
攻击者可注入 <script> 标签执行任意代码。

建议：
echo esc_html( $subtitle );

🟡 建议级

🟡 [性能/N+1] 第 18-25 行：循环内执行 get_post_meta()

原因：
在 while 循环内逐条查询 post_meta，10 篇文章 = 10 次查询，
页面加载时会明显变慢。

建议：
循环前用 get_post_meta( $post_ids, 'key', false ) 批量预取，
或在循环内缓存结果。

💭 细节级

💭 [命名] 第 8 行：$d 变量名过于简短

考虑改为 $display_date 或 $post_date，6 个月后回来看能秒懂。

---

六、当前项目待修复清单

基于 2026-07-24 代码扫描结果，以下问题应优先处理：

优先级	问题	文件	说明
🟡	11 个死模板文件	template-parts/home/	products, services, quality, process, faq, rfq, factory, video, customization, documents, projects 未被引用
🟡	plugins.js 拼接 6 个库	assets/js/plugins.js	jQuery Easing + Jarallax + Colorbox + AOS + anime.js + HC-Sticky 混在一起，无版本标记，无法维护
🟡	CDN 无 SRI	inc/setup.php:47-54	Bootstrap + Google Fonts 缺少 integrity 哈希，无本地回退
🟡	零测试	全项目	无 phpunit / 无 .phpcs.xml / 无 CI
💭	defaults.php 扁平数组	inc/defaults.php	~170 个键未分组，可按区块拆分
💭	jQuery 冗余依赖	assets/js/theme.js	仅 colorbox 用 jQuery，其余为原生 DOM，可考虑去掉 jQuery

---

七、工具辅助

静态检查（建议引入）

# PHP 代码规范检查 — WordPress 标准
composer create-project wp-coding-standards/wpcs
phpcs --standard=WordPress --extensions=php inc/ template-parts/

# 自动修复可修复的问题
phpcbf --standard=WordPress --extensions=php inc/ template-parts/

Git Pre-commit Hook（建议配置）

#!/bin/bash
# .git/hooks/pre-commit
# 提交前自动检查 PHP 语法 + 基本安全扫描

ERRORS=0

# 1. PHP 语法检查
for file in $(git diff --cached --name-only --diff-filter=ACM | grep "\.php$"); do
    php -l "$file" > /dev/null 2>&1 || { echo "语法错误: $file"; ERRORS=1; }
done

# 2. 检查是否包含危险函数
for file in $(git diff --cached --name-only --diff-filter=ACM | grep "\.php$"); do
    grep -n 'eval\s*(' "$file" && { echo "⚠️ eval() 检测到: $file"; ERRORS=1; }
    grep -n 'exec\s*(' "$file" && { echo "⚠️ exec() 检测到: $file"; ERRORS=1; }
    grep -n 'system\s*(' "$file" && { echo "⚠️ system() 检测到: $file"; ERRORS=1; }
done

exit $ERRORS

---

八、审查者轮值

角色	职责
主审	按 §三 清单逐项检查，出具审查意见
复审	对主审意见复核，确认无遗漏（可选）
作者	回复意见，修复 🔴🟡 项，说明 💭 项处理决定

小团队（≤3人）可轮流担任主审，无需固定复审。

---

附录：本项目已有的优秀实践（请保持）

• ✅ 所有文件 ABSPATH 守卫
• ✅ RFQ 表单完整安全链：nonce + honeypot + 速率限制 + 邮件头注入防护
• ✅ Customizer 字段全部配置 sanitize_callback
• ✅ 统一 fragrance_trade_ 函数前缀
• ✅ CSS 使用自定义属性设计令牌系统
• ✅ JS 尊重 prefers-reduced-motion + passive 事件监听
• ✅ antispambot() 邮件地址混淆