nanhaoluo
28f0a1265e
- 更新 Mermaid 库版本从 v10 升级到 v11.12.2 - 优化错误处理逻辑，避免重复嵌套错误容器 - 修复查看源代码时可能出现的嵌套报错问题 - 改进渲染前检查，跳过已处理的错误容器和已渲染的图表 - 优化重新渲染逻辑，只处理成功渲染的图表，排除错误容器 - 增强代码提取逻辑，优先使用传入的代码参数 - 添加主题切换时的智能判断，避免不必要的重新渲染 - 更新 functions.php 中的 CDN 地址到 v11 - 更新 settings.php 中的预览功能 CDN 地址到 v11 - 改进错误容器的 DOM 结构，使用独立元素而非 innerHTML
912 lines
25 KiB
Markdown
912 lines
25 KiB
Markdown
# Design Document
|
||
|
||
## Overview
|
||
|
||
本设计文档描述了 Argon 主题 AI 垃圾评论检测优化功能的技术实现方案。系统采用模块化架构，将 Prompt 管理、置信度评分、上下文构建、学习机制等功能解耦，便于维护和扩展。
|
||
|
||
核心设计理念：
|
||
- **灵活性优先**：通过多级 Prompt 和可配置阈值适应不同场景
|
||
- **准确性保障**：引入置信度评分和上下文信息提升判断质量
|
||
- **成本可控**：提供不同模式平衡准确性和 API 费用
|
||
- **持续优化**：通过学习机制不断改进检测效果
|
||
|
||
## Architecture
|
||
|
||
系统采用分层架构设计：
|
||
|
||
```mermaid
|
||
graph TB
|
||
subgraph "表现层"
|
||
A[设置界面] --> B[评论列表界面]
|
||
end
|
||
|
||
subgraph "业务逻辑层"
|
||
C[AI_Detector 主控制器]
|
||
D[Prompt_Engine]
|
||
E[Context_Builder]
|
||
F[Learning_Module]
|
||
G[Threshold_Manager]
|
||
end
|
||
|
||
subgraph "数据访问层"
|
||
H[WordPress Options API]
|
||
I[WordPress Comments API]
|
||
J[Feedback Database]
|
||
end
|
||
|
||
subgraph "外部服务"
|
||
K[OpenAI API]
|
||
L[其他 AI Provider]
|
||
end
|
||
|
||
A --> C
|
||
B --> C
|
||
C --> D
|
||
C --> E
|
||
C --> F
|
||
C --> G
|
||
D --> K
|
||
D --> L
|
||
E --> I
|
||
F --> J
|
||
G --> H
|
||
C --> H
|
||
C --> I
|
||
```
|
||
|
||
### 核心组件职责
|
||
|
||
1. **AI_Detector**: 主控制器，协调各模块完成检测流程
|
||
2. **Prompt_Engine**: 管理不同模式的 Prompt 模板，生成检测请求
|
||
3. **Context_Builder**: 收集和构建评论上下文信息
|
||
4. **Learning_Module**: 记录反馈数据，分析误判率，提供优化建议
|
||
5. **Threshold_Manager**: 管理检测阈值和处理策略
|
||
|
||
## Components and Interfaces
|
||
|
||
### 1. Prompt_Engine
|
||
|
||
**职责**: 管理和生成不同模式的 Prompt
|
||
|
||
**接口**:
|
||
```php
|
||
class Argon_Spam_Prompt_Engine {
|
||
/**
|
||
* 获取指定模式的 Prompt
|
||
* @param string $mode 模式: minimal, standard, enhanced, custom
|
||
* @param array $context 评论上下文信息
|
||
* @return string 完整的 Prompt
|
||
*/
|
||
public function get_prompt($mode, $context);
|
||
|
||
/**
|
||
* 获取自定义 Prompt 模板
|
||
* @return string 自定义模板
|
||
*/
|
||
public function get_custom_template();
|
||
|
||
/**
|
||
* 保存自定义 Prompt 模板
|
||
* @param string $template 模板内容
|
||
* @return bool 是否成功
|
||
*/
|
||
public function save_custom_template($template);
|
||
|
||
/**
|
||
* 验证 Prompt 模板格式
|
||
* @param string $template 模板内容
|
||
* @return array ['valid' => bool, 'errors' => array]
|
||
*/
|
||
public function validate_template($template);
|
||
}
|
||
```
|
||
|
||
**Prompt 模板结构**:
|
||
|
||
极简模式（minimal）:
|
||
```
|
||
你是一个垃圾评论检测助手。请判断以下评论是否为垃圾评论。
|
||
|
||
评论内容: {content}
|
||
评论者: {author}
|
||
网站: {url}
|
||
|
||
请以 JSON 格式返回:
|
||
{
|
||
"is_spam": true/false,
|
||
"confidence": 0.0-1.0,
|
||
"reason": "简短理由"
|
||
}
|
||
```
|
||
|
||
标准模式（standard）:
|
||
```
|
||
你是一个专业的垃圾评论检测助手。请根据以下标准判断评论是否为垃圾:
|
||
1. 内容质量: 是否有实质性内容
|
||
2. 相关性: 是否与文章主题相关
|
||
3. 用户行为: 用户名、邮箱、网站是否可疑
|
||
4. 语言特征: 是否包含垃圾评论常见模式
|
||
|
||
评论信息:
|
||
- 内容: {content}
|
||
- 评论者: {author}
|
||
- 邮箱域名: {email_domain}
|
||
- 网站: {url}
|
||
- 文章标题: {post_title}
|
||
- 文章摘要: {post_excerpt}
|
||
|
||
用户历史:
|
||
- 历史评论数: {comment_count}
|
||
- 通过率: {approval_rate}
|
||
|
||
请以 JSON 格式返回:
|
||
{
|
||
"is_spam": true/false,
|
||
"confidence": 0.0-1.0,
|
||
"reason": "详细理由",
|
||
"suggestion": "auto/review/approve"
|
||
}
|
||
```
|
||
|
||
增强模式（enhanced）:
|
||
```
|
||
你是一个高级垃圾评论检测专家。请进行多维度深度分析:
|
||
|
||
1. 内容合规性分析
|
||
- 是否包含违规内容
|
||
- 是否包含广告推广
|
||
- 是否包含恶意链接
|
||
|
||
2. 内容质量分析
|
||
- 是否有实质性观点
|
||
- 语言表达是否自然
|
||
- 是否为复制粘贴内容
|
||
|
||
3. 用户行为分析
|
||
- 用户名是否可疑（随机字符、营销词汇）
|
||
- 邮箱域名是否可信
|
||
- 网站是否为垃圾站点
|
||
|
||
4. 上下文相关性分析
|
||
- 评论与文章主题的相关度
|
||
- 评论时间是否异常（批量发送）
|
||
- 用户历史行为是否正常
|
||
|
||
评论信息:
|
||
- 内容: {content}
|
||
- 评论者: {author}
|
||
- 邮箱域名: {email_domain}
|
||
- 网站: {url}
|
||
- IP 地址段: {ip_segment}
|
||
- 评论时间: {comment_time}
|
||
|
||
文章信息:
|
||
- 标题: {post_title}
|
||
- 摘要: {post_excerpt}
|
||
- 分类: {post_category}
|
||
|
||
用户历史:
|
||
- 历史评论数: {comment_count}
|
||
- 通过率: {approval_rate}
|
||
- 最近评论时间: {last_comment_time}
|
||
|
||
请以 JSON 格式返回:
|
||
{
|
||
"is_spam": true/false,
|
||
"confidence": 0.0-1.0,
|
||
"reason": "综合分析理由",
|
||
"suggestion": "auto/review/approve",
|
||
"analysis": {
|
||
"content_compliance": "分析结果",
|
||
"content_quality": "分析结果",
|
||
"user_behavior": "分析结果",
|
||
"context_relevance": "分析结果"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2. Context_Builder
|
||
|
||
**职责**: 收集和构建评论上下文信息
|
||
|
||
**接口**:
|
||
```php
|
||
class Argon_Spam_Context_Builder {
|
||
/**
|
||
* 构建评论上下文
|
||
* @param WP_Comment $comment 评论对象
|
||
* @param string $privacy_level 隐私级别: standard, strict
|
||
* @return array 上下文信息数组
|
||
*/
|
||
public function build_context($comment, $privacy_level = 'standard');
|
||
|
||
/**
|
||
* 获取文章信息
|
||
* @param int $post_id 文章 ID
|
||
* @return array ['title' => string, 'excerpt' => string, 'category' => string]
|
||
*/
|
||
private function get_post_info($post_id);
|
||
|
||
/**
|
||
* 获取用户历史统计
|
||
* @param string $email 用户邮箱
|
||
* @return array ['count' => int, 'approval_rate' => float, 'last_time' => string]
|
||
*/
|
||
private function get_user_stats($email);
|
||
|
||
/**
|
||
* 脱敏处理
|
||
* @param array $context 原始上下文
|
||
* @param string $privacy_level 隐私级别
|
||
* @return array 脱敏后的上下文
|
||
*/
|
||
private function sanitize_context($context, $privacy_level);
|
||
}
|
||
```
|
||
|
||
**上下文数据结构**:
|
||
```php
|
||
[
|
||
'content' => string, // 评论内容
|
||
'author' => string, // 评论者名称
|
||
'email_domain' => string, // 邮箱域名（脱敏）
|
||
'url' => string, // 网站 URL
|
||
'ip_segment' => string, // IP 地址段（脱敏）
|
||
'comment_time' => string, // 评论时间
|
||
'post_title' => string, // 文章标题
|
||
'post_excerpt' => string, // 文章摘要（截取 200 字符）
|
||
'post_category' => string, // 文章分类
|
||
'comment_count' => int, // 用户历史评论数
|
||
'approval_rate' => float, // 用户评论通过率
|
||
'last_comment_time' => string // 最近评论时间
|
||
]
|
||
```
|
||
|
||
### 3. AI_Detector
|
||
|
||
**职责**: 主控制器，协调检测流程
|
||
|
||
**接口**:
|
||
```php
|
||
class Argon_Spam_AI_Detector {
|
||
/**
|
||
* 检测评论是否为垃圾
|
||
* @param WP_Comment $comment 评论对象
|
||
* @param bool $async 是否异步检测
|
||
* @return array 检测结果
|
||
*/
|
||
public function detect($comment, $async = true);
|
||
|
||
/**
|
||
* 处理检测结果
|
||
* @param WP_Comment $comment 评论对象
|
||
* @param array $result 检测结果
|
||
* @return void
|
||
*/
|
||
public function process_result($comment, $result);
|
||
|
||
/**
|
||
* 批量检测评论
|
||
* @param array $comment_ids 评论 ID 数组
|
||
* @param callable $progress_callback 进度回调函数
|
||
* @return array 检测结果统计
|
||
*/
|
||
public function batch_detect($comment_ids, $progress_callback = null);
|
||
|
||
/**
|
||
* 测试 Prompt
|
||
* @param string $content 测试内容
|
||
* @param string $mode Prompt 模式
|
||
* @return array 检测结果
|
||
*/
|
||
public function test_prompt($content, $mode);
|
||
}
|
||
```
|
||
|
||
**检测结果数据结构**:
|
||
```php
|
||
[
|
||
'is_spam' => bool, // 是否垃圾评论
|
||
'confidence' => float, // 置信度 0-1
|
||
'reason' => string, // 判断理由
|
||
'suggestion' => string, // 处理建议: auto/review/approve
|
||
'analysis' => array, // 详细分析（仅增强模式）
|
||
'timestamp' => int, // 检测时间戳
|
||
'mode' => string, // 使用的 Prompt 模式
|
||
'api_provider' => string // API 提供商
|
||
]
|
||
```
|
||
|
||
### 4. Learning_Module
|
||
|
||
**职责**: 记录反馈数据，分析误判率
|
||
|
||
**接口**:
|
||
```php
|
||
class Argon_Spam_Learning_Module {
|
||
/**
|
||
* 记录反馈
|
||
* @param int $comment_id 评论 ID
|
||
* @param array $ai_result AI 检测结果
|
||
* @param string $admin_action 管理员操作: approve, spam, trash
|
||
* @return bool 是否成功
|
||
*/
|
||
public function record_feedback($comment_id, $ai_result, $admin_action);
|
||
|
||
/**
|
||
* 计算误判率
|
||
* @param int $days 统计天数
|
||
* @return array ['total' => int, 'false_positive' => int, 'false_negative' => int, 'rate' => float]
|
||
*/
|
||
public function calculate_error_rate($days = 30);
|
||
|
||
/**
|
||
* 获取优化建议
|
||
* @return array 建议列表
|
||
*/
|
||
public function get_optimization_suggestions();
|
||
|
||
/**
|
||
* 导出反馈数据
|
||
* @param int $days 导出天数
|
||
* @return string CSV 格式数据
|
||
*/
|
||
public function export_feedback($days = 30);
|
||
|
||
/**
|
||
* 获取统计数据
|
||
* @return array 统计信息
|
||
*/
|
||
public function get_statistics();
|
||
}
|
||
```
|
||
|
||
**反馈记录数据结构**:
|
||
```php
|
||
[
|
||
'comment_id' => int,
|
||
'ai_result' => array, // AI 检测结果
|
||
'admin_action' => string, // 管理员操作
|
||
'timestamp' => int,
|
||
'pattern_hash' => string, // 评论特征哈希
|
||
'is_error' => bool // 是否误判
|
||
]
|
||
```
|
||
|
||
### 5. Threshold_Manager
|
||
|
||
**职责**: 管理检测阈值和处理策略
|
||
|
||
**接口**:
|
||
```php
|
||
class Argon_Spam_Threshold_Manager {
|
||
/**
|
||
* 获取当前阈值
|
||
* @return float 阈值 0.5-1.0
|
||
*/
|
||
public function get_threshold();
|
||
|
||
/**
|
||
* 设置阈值
|
||
* @param float $threshold 阈值
|
||
* @return bool 是否成功
|
||
*/
|
||
public function set_threshold($threshold);
|
||
|
||
/**
|
||
* 判断是否应该自动处理
|
||
* @param array $result 检测结果
|
||
* @return bool 是否自动处理
|
||
*/
|
||
public function should_auto_process($result);
|
||
|
||
/**
|
||
* 获取推荐配置
|
||
* @param string $blog_size 博客规模: small, medium, large
|
||
* @return array 推荐配置
|
||
*/
|
||
public function get_recommended_config($blog_size);
|
||
}
|
||
```
|
||
|
||
## Data Models
|
||
|
||
### 1. 配置选项（WordPress Options）
|
||
|
||
```php
|
||
// Prompt 模式
|
||
'argon_spam_detection_prompt_mode' => 'standard' // minimal, standard, enhanced, custom
|
||
|
||
// 自定义 Prompt 模板
|
||
'argon_spam_detection_custom_prompt' => ''
|
||
|
||
// 检测阈值
|
||
'argon_spam_detection_threshold' => 0.85 // 0.5-1.0
|
||
|
||
// 智能抽查比例
|
||
'argon_spam_detection_sample_rate' => 30 // 0-100
|
||
|
||
// 隐私级别
|
||
'argon_spam_detection_privacy_level' => 'standard' // standard, strict
|
||
|
||
// API 配置
|
||
'argon_spam_detection_api_provider' => 'openai' // openai, custom
|
||
'argon_spam_detection_api_key' => ''
|
||
'argon_spam_detection_api_endpoint' => ''
|
||
|
||
// 实时检测开关
|
||
'argon_spam_detection_realtime_enabled' => true
|
||
|
||
// 自动禁用配置
|
||
'argon_spam_detection_auto_disable_after_errors' => 3
|
||
'argon_spam_detection_auto_disable_duration' => 3600 // 秒
|
||
|
||
// 统计数据
|
||
'argon_spam_detection_stats' => [
|
||
'total_detections' => 0,
|
||
'auto_processed' => 0,
|
||
'manual_reviewed' => 0,
|
||
'api_calls_this_month' => 0,
|
||
'last_reset_time' => 0
|
||
]
|
||
```
|
||
|
||
### 2. 评论元数据（Comment Meta）
|
||
|
||
```php
|
||
// AI 检测结果
|
||
'argon_spam_ai_result' => [
|
||
'is_spam' => bool,
|
||
'confidence' => float,
|
||
'reason' => string,
|
||
'suggestion' => string,
|
||
'analysis' => array,
|
||
'timestamp' => int,
|
||
'mode' => string,
|
||
'api_provider' => string
|
||
]
|
||
|
||
// 检测状态
|
||
'argon_spam_detection_status' => 'pending' // pending, completed, failed
|
||
|
||
// 重新检测次数
|
||
'argon_spam_redetection_count' => 0
|
||
```
|
||
|
||
### 3. 反馈数据库表
|
||
|
||
创建自定义表存储反馈数据：
|
||
|
||
```sql
|
||
CREATE TABLE {prefix}_argon_spam_feedback (
|
||
id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
|
||
comment_id BIGINT UNSIGNED NOT NULL,
|
||
ai_is_spam TINYINT(1) NOT NULL,
|
||
ai_confidence FLOAT NOT NULL,
|
||
ai_reason TEXT,
|
||
ai_suggestion VARCHAR(20),
|
||
admin_action VARCHAR(20) NOT NULL,
|
||
is_error TINYINT(1) NOT NULL,
|
||
pattern_hash VARCHAR(64),
|
||
created_at DATETIME NOT NULL,
|
||
PRIMARY KEY (id),
|
||
KEY comment_id (comment_id),
|
||
KEY created_at (created_at),
|
||
KEY is_error (is_error)
|
||
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
|
||
```
|
||
|
||
## Correctness Properties
|
||
|
||
*属性是一个特征或行为，应该在系统的所有有效执行中保持为真——本质上是关于系统应该做什么的正式陈述。属性作为人类可读规范和机器可验证正确性保证之间的桥梁。*
|
||
|
||
### Property 1: Prompt 模式完整性
|
||
|
||
*对于任何* 上下文数据，Prompt_Engine 应该能够为所有三种预设模式（minimal、standard、enhanced）生成有效的 Prompt，且每个 Prompt 都包含 JSON 格式要求。
|
||
|
||
**Validates: Requirements 1.1, 1.6**
|
||
|
||
### Property 2: Token 消耗范围约束
|
||
|
||
*对于任何* 上下文数据和任何预设模式，生成的 Prompt 的 token 消耗应该在该模式指定的范围内（极简：100-150，标准：200-300，增强：300-500）。
|
||
|
||
**Validates: Requirements 1.2, 1.3, 1.4**
|
||
|
||
### Property 3: 自定义模板往返一致性
|
||
|
||
*对于任何* 有效的自定义 Prompt 模板字符串，保存后再读取应该得到相同的模板内容。
|
||
|
||
**Validates: Requirements 1.5**
|
||
|
||
### Property 4: 检测结果数据结构完整性
|
||
|
||
*对于任何* 评论，AI_Detector 返回的结果应该包含 is_spam（布尔值）、confidence（0-1 范围的浮点数）、reason（字符串）、suggestion（字符串）四个必需字段。
|
||
|
||
**Validates: Requirements 2.1, 2.2, 3.1**
|
||
|
||
### Property 5: 置信度分类正确性
|
||
|
||
*对于任何* 置信度值，系统应该根据以下规则正确分类：>= 0.9 为"非常确定"，0.7-0.9 为"比较确定"，0.5-0.7 为"中等确定"，< 0.5 为"不太确定"。
|
||
|
||
**Validates: Requirements 2.3, 2.4, 2.5, 2.6**
|
||
|
||
### Property 6: 处理建议逻辑正确性
|
||
|
||
*对于任何* 检测结果和阈值配置，当 confidence >= threshold 且 is_spam = true 时应返回 "auto"，当 0.5 <= confidence < threshold 且 is_spam = true 时应返回 "review"，其他情况应返回 "approve"。
|
||
|
||
**Validates: Requirements 3.2, 3.3, 3.4**
|
||
|
||
### Property 7: 阈值配置往返一致性
|
||
|
||
*对于任何* 有效的阈值值（0.5-1.0），保存后再读取应该得到相同的阈值。
|
||
|
||
**Validates: Requirements 3.5**
|
||
|
||
### Property 8: 评论处理状态正确性
|
||
|
||
*对于任何* 评论和处理建议，当 suggestion = "auto" 时评论应被标记为垃圾，当 suggestion = "review" 时评论应被标记为待审核，当 suggestion = "approve" 时评论应被正常发布。
|
||
|
||
**Validates: Requirements 3.6, 3.7, 3.8**
|
||
|
||
### Property 9: 上下文数据完整性
|
||
|
||
*对于任何* 评论，Context_Builder 构建的上下文应该包含文章标题、文章摘要、用户历史评论数、用户通过率、评论时间戳、IP 地址等所有必需字段。
|
||
|
||
**Validates: Requirements 4.1, 4.2, 4.3**
|
||
|
||
### Property 10: 上下文传递正确性
|
||
|
||
*对于任何* 构建的上下文，生成的 Prompt 应该包含该上下文中的关键信息（如文章标题、评论内容等）。
|
||
|
||
**Validates: Requirements 4.4**
|
||
|
||
### Property 11: 敏感信息脱敏正确性
|
||
|
||
*对于任何* 包含敏感信息的评论，Context_Builder 返回的上下文中的邮箱应只保留域名，IP 地址应只保留前两段。
|
||
|
||
**Validates: Requirements 4.5, 10.1, 10.2**
|
||
|
||
### Property 12: 摘要截取正确性
|
||
|
||
*对于任何* 超过 200 字符的文章摘要，Context_Builder 返回的摘要应该被截取为 200 字符。
|
||
|
||
**Validates: Requirements 4.6**
|
||
|
||
### Property 13: 反馈记录完整性
|
||
|
||
*对于任何* 管理员审核操作，Learning_Module 记录的反馈应该包含 AI 判断结果、管理员决策、时间戳、评论特征哈希等所有必需字段。
|
||
|
||
**Validates: Requirements 5.1, 5.2**
|
||
|
||
### Property 14: 误判率计算正确性
|
||
|
||
*对于任何* 反馈数据集，Learning_Module 计算的误判率应该等于（误判数量 / 总检测数量）。
|
||
|
||
**Validates: Requirements 5.3**
|
||
|
||
### Property 15: 优化建议触发正确性
|
||
|
||
*对于任何* 反馈数据集，当某类型评论的误判率超过 30% 时，Learning_Module 应该生成相应的优化建议。
|
||
|
||
**Validates: Requirements 5.4**
|
||
|
||
### Property 16: 反馈数据导出格式正确性
|
||
|
||
*对于任何* 反馈数据集，导出的 CSV 数据应该包含所有必需列（comment_id、ai_result、admin_action、timestamp 等），且格式符合 CSV 标准。
|
||
|
||
**Validates: Requirements 5.5**
|
||
|
||
### Property 17: 统计数据准确性
|
||
|
||
*对于任何* 反馈数据集，Learning_Module 返回的统计数据（总检测数、自动处理数、误判数）应该与实际数据一致。
|
||
|
||
**Validates: Requirements 5.6**
|
||
|
||
### Property 18: API 错误默认值正确性
|
||
|
||
*对于任何* API 错误响应，AI_Detector 应该使用默认值（is_spam=false, confidence=0, suggestion="approve"）并允许评论正常发布。
|
||
|
||
**Validates: Requirements 8.1, 8.2**
|
||
|
||
### Property 19: 自动禁用机制正确性
|
||
|
||
*对于任何* API 调用序列，当连续失败次数达到配置的阈值（默认 3 次）时，系统应该自动禁用实时检测指定时长（默认 1 小时）。
|
||
|
||
**Validates: Requirements 8.3**
|
||
|
||
### Property 20: 错误日志容量限制
|
||
|
||
*对于任何* 错误日志序列，系统应该只保留最近的 N 条（默认 10 条）错误日志。
|
||
|
||
**Validates: Requirements 8.4**
|
||
|
||
### Property 21: 自动恢复机制正确性
|
||
|
||
*对于任何* 被禁用的检测系统，当 API 调用成功时，系统应该自动重新启用实时检测。
|
||
|
||
**Validates: Requirements 8.5**
|
||
|
||
### Property 22: 手动恢复功能正确性
|
||
|
||
*对于任何* 被禁用的检测系统，调用手动恢复功能后，系统应该立即重新启用实时检测并清除错误计数。
|
||
|
||
**Validates: Requirements 8.6**
|
||
|
||
### Property 23: 异步检测非阻塞性
|
||
|
||
*对于任何* 评论提交，当异步检测启用时，评论提交操作应该在 API 调用完成前就返回成功响应。
|
||
|
||
**Validates: Requirements 9.1**
|
||
|
||
### Property 24: 状态更新正确性
|
||
|
||
*对于任何* 评论和 API 响应，当 API 返回结果后，评论的状态应该根据处理建议正确更新（auto → 垃圾/回收站，review → 待审核，approve → 已发布）。
|
||
|
||
**Validates: Requirements 9.3**
|
||
|
||
### Property 25: 批量扫描完整性
|
||
|
||
*对于任何* 评论 ID 列表，批量扫描功能应该对列表中的每个评论都执行检测，且返回的结果数量应该等于输入的评论数量。
|
||
|
||
**Validates: Requirements 9.4**
|
||
|
||
### Property 26: 队列限速正确性
|
||
|
||
*对于任何* 批量扫描操作，API 调用的频率应该不超过配置的速率限制（如每秒最多 N 次调用）。
|
||
|
||
**Validates: Requirements 9.5**
|
||
|
||
### Property 27: 缓存一致性
|
||
|
||
*对于任何* 用户邮箱，在缓存有效期内多次查询该用户的历史统计应该返回相同的结果，且只执行一次数据库查询。
|
||
|
||
**Validates: Requirements 9.6**
|
||
|
||
### Property 28: 隐私保护完整性
|
||
|
||
*对于任何* 评论和隐私级别配置，发送给 API 的数据不应包含用户的真实姓名、完整邮箱（标准模式）或任何用户标识信息（严格模式）。
|
||
|
||
**Validates: Requirements 10.3, 10.5**
|
||
|
||
### Property 29: 隐私级别配置往返一致性
|
||
|
||
*对于任何* 有效的隐私级别值（standard 或 strict），保存后再读取应该得到相同的配置。
|
||
|
||
**Validates: Requirements 10.4**
|
||
|
||
## Error Handling
|
||
|
||
### API 错误处理
|
||
|
||
1. **连接超时**：
|
||
- 超时时间：30 秒
|
||
- 处理：记录错误日志，使用默认值，允许评论发布
|
||
- 重试：不自动重试，由自动禁用机制控制
|
||
|
||
2. **API 返回错误状态码**：
|
||
- 4xx 错误：记录错误，使用默认值，不计入连续失败
|
||
- 5xx 错误：记录错误，使用默认值，计入连续失败
|
||
- 速率限制（429）：延迟重试，不计入连续失败
|
||
|
||
3. **响应格式错误**：
|
||
- JSON 解析失败：记录错误，使用默认值
|
||
- 缺少必需字段：记录警告，使用默认值填充
|
||
- 字段类型错误：记录警告，尝试类型转换
|
||
|
||
4. **自动禁用机制**：
|
||
- 触发条件：连续失败 N 次（默认 3 次）
|
||
- 禁用时长：M 分钟（默认 60 分钟）
|
||
- 恢复条件：时间到期或手动恢复或 API 调用成功
|
||
- 通知：在管理后台显示禁用状态和原因
|
||
|
||
### 数据验证错误
|
||
|
||
1. **评论数据不完整**：
|
||
- 缺少必需字段：记录警告，跳过检测
|
||
- 字段格式错误：记录警告，尝试修复或跳过
|
||
|
||
2. **配置数据无效**：
|
||
- 阈值超出范围：使用默认值 0.85
|
||
- 模式不存在：使用默认模式 standard
|
||
- 自定义模板格式错误：显示错误提示，不保存
|
||
|
||
3. **上下文构建失败**：
|
||
- 文章不存在：使用空字符串
|
||
- 用户历史查询失败：使用默认值（count=0, rate=0）
|
||
- 数据库错误：记录错误，使用最小上下文
|
||
|
||
### 数据库错误
|
||
|
||
1. **反馈记录失败**：
|
||
- 记录错误日志
|
||
- 不影响评论处理流程
|
||
- 在管理后台显示警告
|
||
|
||
2. **统计查询失败**：
|
||
- 返回空数据或默认值
|
||
- 在管理后台显示错误提示
|
||
|
||
3. **批量操作失败**：
|
||
- 记录失败的评论 ID
|
||
- 继续处理剩余评论
|
||
- 在完成后显示失败列表
|
||
|
||
## Testing Strategy
|
||
|
||
### 测试方法
|
||
|
||
本项目采用双重测试策略：
|
||
|
||
1. **单元测试**：验证具体示例、边缘情况和错误条件
|
||
2. **属性测试**：验证通用属性在所有输入下的正确性
|
||
|
||
两种测试方法互补，共同保证系统的正确性和健壮性。
|
||
|
||
### 单元测试重点
|
||
|
||
单元测试应关注以下方面：
|
||
|
||
1. **具体示例**：
|
||
- 典型的垃圾评论示例
|
||
- 典型的正常评论示例
|
||
- 边界值测试（置信度 0.5, 0.85, 0.9 等）
|
||
|
||
2. **边缘情况**：
|
||
- 空评论内容
|
||
- 超长评论内容
|
||
- 特殊字符和 Unicode
|
||
- 文章不存在
|
||
- 用户无历史记录
|
||
|
||
3. **错误条件**：
|
||
- API 超时
|
||
- API 返回错误
|
||
- 数据库连接失败
|
||
- 配置数据无效
|
||
|
||
4. **集成点**：
|
||
- WordPress 钩子集成
|
||
- 评论状态更新
|
||
- 管理后台显示
|
||
|
||
### 属性测试配置
|
||
|
||
**测试库选择**：
|
||
- PHP: PHPUnit + Eris (Property-Based Testing)
|
||
- 或使用 Pest + Pest Property Testing Plugin
|
||
|
||
**测试配置**：
|
||
- 每个属性测试最少运行 100 次迭代
|
||
- 使用随机种子确保可重现性
|
||
- 失败时自动缩小（shrinking）到最小失败案例
|
||
|
||
**属性测试标签格式**：
|
||
```php
|
||
/**
|
||
* @test
|
||
* Feature: ai-spam-detection-optimization, Property 1: Prompt 模式完整性
|
||
*/
|
||
public function test_prompt_mode_completeness() {
|
||
// 属性测试实现
|
||
}
|
||
```
|
||
|
||
### 测试数据生成
|
||
|
||
**生成器定义**：
|
||
|
||
1. **评论生成器**：
|
||
- 随机内容（1-1000 字符）
|
||
- 随机作者名（1-50 字符）
|
||
- 随机邮箱（有效格式）
|
||
- 随机 URL（有效格式或空）
|
||
- 随机 IP 地址
|
||
|
||
2. **上下文生成器**：
|
||
- 随机文章标题（1-200 字符）
|
||
- 随机文章摘要（0-500 字符）
|
||
- 随机用户历史（count: 0-1000, rate: 0-1）
|
||
|
||
3. **配置生成器**：
|
||
- 随机阈值（0.5-1.0）
|
||
- 随机模式（minimal, standard, enhanced）
|
||
- 随机隐私级别（standard, strict）
|
||
|
||
4. **API 响应生成器**：
|
||
- 随机 is_spam（true/false）
|
||
- 随机 confidence（0-1）
|
||
- 随机 reason（1-200 字符）
|
||
- 随机 suggestion（auto/review/approve）
|
||
|
||
### 测试覆盖率目标
|
||
|
||
- **代码覆盖率**：> 80%
|
||
- **分支覆盖率**：> 75%
|
||
- **属性测试覆盖**：所有 29 个正确性属性
|
||
- **单元测试覆盖**：所有核心函数和边缘情况
|
||
|
||
### 性能测试
|
||
|
||
1. **响应时间测试**：
|
||
- 评论提交响应时间 < 100ms（异步模式）
|
||
- 同步检测响应时间 < 3s
|
||
- 批量扫描 100 条评论 < 5 分钟
|
||
|
||
2. **并发测试**：
|
||
- 模拟 10 个并发评论提交
|
||
- 验证无数据竞争和死锁
|
||
|
||
3. **负载测试**：
|
||
- 批量扫描 1000 条评论
|
||
- 验证内存使用 < 256MB
|
||
- 验证数据库查询次数合理
|
||
|
||
### 集成测试
|
||
|
||
1. **WordPress 集成**：
|
||
- 测试评论提交钩子
|
||
- 测试评论状态更新
|
||
- 测试管理后台显示
|
||
|
||
2. **API 集成**：
|
||
- 测试 OpenAI API 调用
|
||
- 测试自定义 API 端点
|
||
- 测试错误处理
|
||
|
||
3. **数据库集成**：
|
||
- 测试反馈记录存储
|
||
- 测试统计数据查询
|
||
- 测试批量操作
|
||
|
||
### 测试环境
|
||
|
||
1. **本地开发环境**：
|
||
- PHP 7.4+
|
||
- WordPress 5.8+
|
||
- MySQL 5.7+
|
||
- PHPUnit 9.5+
|
||
|
||
2. **CI/CD 环境**：
|
||
- GitHub Actions 或类似 CI 工具
|
||
- 自动运行所有测试
|
||
- 代码覆盖率报告
|
||
|
||
3. **测试数据**：
|
||
- 使用 WordPress Test Suite
|
||
- 创建测试数据库
|
||
- 使用 mock API 响应
|
||
|
||
### 测试执行顺序
|
||
|
||
1. **快速测试**（< 1 分钟）：
|
||
- 单元测试
|
||
- 快速属性测试（10 次迭代）
|
||
|
||
2. **完整测试**（< 10 分钟）：
|
||
- 所有单元测试
|
||
- 完整属性测试（100 次迭代）
|
||
- 集成测试
|
||
|
||
3. **性能测试**（< 30 分钟）：
|
||
- 响应时间测试
|
||
- 并发测试
|
||
- 负载测试
|
||
|
||
### 测试维护
|
||
|
||
1. **定期更新**：
|
||
- 随着需求变化更新测试
|
||
- 添加新发现的边缘情况
|
||
- 优化慢速测试
|
||
|
||
2. **失败分析**：
|
||
- 记录所有测试失败
|
||
- 分析失败原因
|
||
- 修复或更新测试
|
||
|
||
3. **覆盖率监控**：
|
||
- 定期检查覆盖率报告
|
||
- 识别未覆盖的代码
|
||
- 添加缺失的测试
|
||
|