# 代码审查标准与流程

> 适用项目：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 |

---

## 七、工具辅助

### 静态检查（建议引入）

```bash
# 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（建议配置）

```bash
#!/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()` 邮件地址混淆