feat: release B2B Trade theme 2.1.0
This commit is contained in:
WorkBuddy
+99
-227
@@ -1,266 +1,138 @@
|
||||
# 代码审查标准与流程
|
||||
# B2B Trade 发布审查标准
|
||||
|
||||
> 适用项目：B2B Trade 主题（fragrance-trade）
|
||||
> 技术栈：WordPress 经典主题 / PHP 7.4+ / Bootstrap 5.3 / jQuery
|
||||
> 版本：v1.0 | 2026-07-24
|
||||
适用范围：B2B Trade 2.1.x，WordPress 6.8+，PHP 8.1+。
|
||||
|
||||
---
|
||||
## 1. 自动检查
|
||||
|
||||
## 一、审查原则
|
||||
每次发布必须满足：
|
||||
|
||||
1. **安全优先** — WordPress 主题的 XSS / SQL 注入 / CSRF 是红线
|
||||
2. **就事论事** — 评论针对代码，不针对人
|
||||
3. **说清楚为什么** — 不只说"改这个"，要解释原因和潜在风险
|
||||
4. **给方向不给答案** — 引导作者自己思考，除非是明确的安全漏洞
|
||||
5. **赞美好代码** — 发现优秀实践要明确指出，让团队学习
|
||||
- `git diff --check` 无输出；
|
||||
- 所有 PHP 文件在 PHP 8.1 CLI 下通过 `php -l`；
|
||||
- PHPCS 通过 WordPress Coding Standards 与 PHPCompatibilityWP；
|
||||
- `node --check assets/js/theme.js` 通过；
|
||||
- CSS 花括号配对，所有 `url(...)` 本地资源存在；
|
||||
- PHP、CSS 和 JS 不包含脚本、样式或字体 CDN 请求；
|
||||
- 主题引用的本地静态资源全部存在；
|
||||
- 仓库不包含已清退的旧业务词、旧视频弹窗库或旧产品位图。
|
||||
|
||||
---
|
||||
## 2. 初始化与数据安全
|
||||
|
||||
## 二、优先级体系
|
||||
|
||||
每个审查意见必须标注以下级别之一：
|
||||
|
||||
| 级别 | 标记 | 含义 | 处理要求 |
|
||||
|------|------|------|----------|
|
||||
| 🔴 阻断 | Blocker | 安全漏洞 / 数据丢失 / 破坏功能 | **必须修复后才能合并** |
|
||||
| 🟡 建议 | Suggestion | 输入验证缺失 / 性能问题 / 可维护性 | **应当修复，可协商** |
|
||||
| 💭 细节 | Nit | 命名 / 风格 / 文档 | 修不修都行，不阻塞 |
|
||||
|
||||
---
|
||||
在空数据库中：
|
||||
|
||||
## 三、WordPress 主题专项审查清单
|
||||
1. 安装 WordPress 并激活主题；
|
||||
2. 确认创建 7 个带种子标识的服务；
|
||||
3. 确认创建 `home`、`about`、`faq`、`contact`；
|
||||
4. 再运行两次初始化；
|
||||
5. 确认服务数和页面数不增加；
|
||||
6. 确认 `fragrance_trade_schema_version` 仅在无错误时推进。
|
||||
|
||||
### 🔴 阻断级检查项（必须全部通过）
|
||||
在已有数据库中：
|
||||
|
||||
#### 3.1 安全性
|
||||
- 已有页面正文、标题和状态不被覆盖；
|
||||
- 草稿、私密或回收站页面不被自动发布；
|
||||
- 对应页面模板被补齐；
|
||||
- 后台显示非发布状态提醒；
|
||||
- 已有 `_service_image` 和 `store_map_url` 保持有效。
|
||||
|
||||
- [ ] **直接访问防护** — 所有 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 功能正确性
|
||||
需要注入一次 `wp_insert_post()` 错误，确认错误被记录、管理员可见且迁移版本不推进。
|
||||
|
||||
- [ ] **关键路径错误处理** — 表单提交失败有 fallback（非空白白屏）
|
||||
- [ ] **数据完整性** — 不会因空值 / 缺失字段导致 fatal error
|
||||
- [ ] **重定向安全** — 使用 `wp_safe_redirect()` + `wp_validate_redirect()`，禁止直接 `header('Location:')`
|
||||
## 3. 页面冒烟
|
||||
|
||||
### 🟡 建议级检查项
|
||||
以下页面必须返回预期状态，并且 PHP 日志无 Warning、Deprecated、Parse 或 Fatal：
|
||||
|
||||
#### 3.3 输入验证与数据
|
||||
| 页面 | 预期 |
|
||||
| --- | --- |
|
||||
| 首页 | 200 |
|
||||
| 服务列表 | 200 |
|
||||
| 服务详情 | 200 |
|
||||
| 案例列表 | 200 |
|
||||
| 案例详情 | 200 |
|
||||
| 关于门店 | 200 |
|
||||
| 常见问题 | 200 |
|
||||
| 联系我们 | 200 |
|
||||
| 普通文章 | 200 |
|
||||
| 搜索结果 | 200 |
|
||||
| 不存在路径 | 404 |
|
||||
|
||||
- [ ] Customizer 字段是否有对应类型的 `sanitize_callback`
|
||||
- [ ] `get_theme_mod()` 取值后是否有默认值兜底
|
||||
- [ ] 用户上传的 URL 是否用 `esc_url_raw()` 存入、`esc_url()` 输出
|
||||
浏览器控制台不得出现 JavaScript 错误，Network 面板不得出现主题资源 404。
|
||||
|
||||
#### 3.4 性能
|
||||
## 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`
|
||||
1. 有特色图片时优先显示特色图片；
|
||||
2. 无特色图片、有 `_service_image` 时显示旧 URL；
|
||||
3. 两者都没有时显示对应 SVG 占位图；
|
||||
4. 首页和列表输出 `fragrance-capability`；
|
||||
5. 详情输出 `large`。
|
||||
|
||||
#### 3.6 前端质量
|
||||
### 地图
|
||||
|
||||
- [ ] **CDN 资源** — 第三方 CDN 必须有 SRI 完整性哈希 + 本地回退
|
||||
- [ ] **第三方库** — 禁止将多个库的压缩代码拼接到单文件；用 npm + 构建流程管理
|
||||
- [ ] **无障碍** — 图片有 `alt`，表单有 `label`，按钮有可读文本
|
||||
- [ ] **响应式** — 移动端布局不溢出，触控目标不小于 44×44px
|
||||
- [ ] `prefers-reduced-motion` — 动画尊重用户偏好
|
||||
分别确认：
|
||||
|
||||
### 💭 细节级检查项
|
||||
1. 显式地图 URL 优先于地址；
|
||||
2. 只有地址时生成百度地图导航；
|
||||
3. 地址和 URL 都为空时不渲染地图卡片；
|
||||
4. 页面不出现任何硬编码门店地址。
|
||||
|
||||
- [ ] 文本域统一为 `fragrance-trade`，所有字符串包裹 `__()` / `esc_html_e()`
|
||||
- [ ] 注释说明"为什么"而非"做了什么"
|
||||
- [ ] 长行拆分（单行 PHP echo 不超过 120 字符）
|
||||
- [ ] CSS 自定义属性命名遵循 `--token-name` 格式
|
||||
### 导航
|
||||
|
||||
---
|
||||
- 未分配菜单时输出 6 项默认导航；
|
||||
- 少于两个菜单项时后台显示提醒；
|
||||
- 桌面导航与移动 Offcanvas 均可键盘操作；
|
||||
- 当前菜单不会造成横向滚动。
|
||||
|
||||
## 四、审查流程
|
||||
### 视频与 FAQ
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ 代码审查流程 │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ 1. 提交前自检 │
|
||||
│ 作者按 §三 清单自检 → 确认无 🔴 项 │
|
||||
│ ↓ │
|
||||
│ 2. 提交审查 │
|
||||
│ Gitea PR / 提交说明 → 附上改动摘要和测试方式 │
|
||||
│ ↓ │
|
||||
│ 3. 审查者检查 │
|
||||
│ 按 §三 清单逐项 → 标注 🔴🟡💭 → 写明原因和建议方向 │
|
||||
│ ↓ │
|
||||
│ 4. 分支处理 │
|
||||
│ ├─ 有 🔴 → 打回，作者修复后重新提交 │
|
||||
│ ├─ 有 🟡 → 讨论确认，修复或记录为后续任务 │
|
||||
│ └─ 仅 💭 → 可选修复，直接通过 │
|
||||
│ ↓ │
|
||||
│ 5. 合并 │
|
||||
│ 审查者 Approve → 作者合并 → 删除分支 │
|
||||
│ ↓ │
|
||||
│ 6. 回顾（每周） │
|
||||
│ 汇总本周审查发现的共性问题 → 更新本标准 │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
- 有视频 URL 时只产生普通新窗口链接；
|
||||
- 链接包含 `target="_blank"` 与 `rel="noopener noreferrer"`；
|
||||
- 无视频 URL 时显示联系门店入口；
|
||||
- FAQ 手风琴可点击和键盘操作，ARIA 状态随展开更新。
|
||||
|
||||
### 4.1 提交规范
|
||||
### 联系
|
||||
|
||||
提交 PR / 提交审查时，标题格式：
|
||||
- 联系页不存在提交表单；
|
||||
- 服务入口不生成服务查询参数；
|
||||
- 电话、邮箱与 WhatsApp 链接按配置显示；
|
||||
- 主题不注册前端提交或邮件发送 Hook。
|
||||
|
||||
```
|
||||
[类型] 简述 — 具体改动
|
||||
## 5. 兼容矩阵
|
||||
|
||||
类型：feat / fix / refactor / style / security / docs / chore
|
||||
```
|
||||
至少完成：
|
||||
|
||||
示例：
|
||||
```
|
||||
[security] RFQ 表单 — 增加 nonce 验证
|
||||
[feat] 案例详情页 — 添加施工前后对比图
|
||||
[refactor] inc/defaults.php — 按区块分组重组配置键
|
||||
```
|
||||
| 环境 | 用途 |
|
||||
| --- | --- |
|
||||
| WordPress 7.0 系列 + PHP 8.3 | 当前版本主回归 |
|
||||
| WordPress 6.8 系列 + PHP 8.2 | 最低 WordPress 分支 |
|
||||
| PHP 8.1 CLI | 最低 PHP 语法检查 |
|
||||
|
||||
### 4.2 审查时间线
|
||||
兼容环境可由维护者现有的 WordPress 测试站点提供，不要求主题仓库附带容器配置。
|
||||
|
||||
| 阶段 | 时限 | 说明 |
|
||||
|------|------|------|
|
||||
| 初次审查 | 提交后 24h 内 | 审查者完成首轮检查 |
|
||||
| 修复后复审 | 作者修复后 12h 内 | 审查者确认修复 |
|
||||
| 超时升级 | 超 48h 未回应 | @项目负责人介入协调 |
|
||||
## 6. 视觉与无障碍
|
||||
|
||||
---
|
||||
桌面至少检查 1440 × 1000，移动至少检查 390 × 844：
|
||||
|
||||
## 五、审查评论模板
|
||||
- 首页、服务列表、服务详情、案例列表、关于、FAQ、联系；
|
||||
- 无水平滚动、布局跳动、遮挡或断裂；
|
||||
- 图片具有明确尺寸与替代文本；
|
||||
- 可交互元素有可见焦点；
|
||||
- 文本与背景保持可读对比度；
|
||||
- Offcanvas 打开后焦点可进入，关闭后可返回触发按钮；
|
||||
- 新窗口链接的可访问名称能表达用途。
|
||||
|
||||
### 🔴 阻断级
|
||||
主题预览图必须来自通过桌面验收的中性演示首页，不得包含过时业务内容、品牌承诺或虚构真实门店照片。
|
||||
|
||||
```
|
||||
🔴 [安全/XSS] 第 42 行：用户输入直接输出到 HTML
|
||||
## 7. 发布元数据
|
||||
|
||||
原因：
|
||||
$subtitle 变量来自 $_POST，未经 esc_html() 转义直接 echo，
|
||||
攻击者可注入 <script> 标签执行任意代码。
|
||||
发布前确认 `style.css`：
|
||||
|
||||
建议：
|
||||
echo esc_html( $subtitle );
|
||||
```
|
||||
- `Version: 2.1.0`
|
||||
- `Requires at least: 6.8`
|
||||
- `Tested up to: 7.0`
|
||||
- `Requires PHP: 8.1`
|
||||
- Theme URI 指向实际仓库
|
||||
- 文本域为 `fragrance-trade`
|
||||
|
||||
### 🟡 建议级
|
||||
|
||||
```
|
||||
🟡 [性能/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()` 邮件地址混淆
|
||||
同时确认 `languages/fragrance-trade.pot` 已按当前源码重新生成，本地 Bootstrap 许可证随主题包发布。
|
||||
|
||||
Reference in New Issue
Block a user