# Implementation Plan: AI 垃圾评论检测优化

## Overview

本实施计划将 AI 垃圾评论检测功能从基础版本升级为具有多级 Prompt、置信度评分、智能处理建议和学习机制的完整系统。实施采用模块化方式，每个核心组件独立开发和测试，最后进行集成。

实施策略：
- 先实现核心组件（Prompt_Engine, Context_Builder, AI_Detector）
- 再实现辅助组件（Learning_Module, Threshold_Manager）
- 然后实现数据库和设置界面
- 最后进行集成测试和优化

## Tasks

- [x] 1. 数据库表创建和初始化
  - 创建反馈数据表 `{prefix}_argon_spam_feedback`
  - 添加必要的索引（comment_id, created_at, is_error）
  - 实现数据库升级函数，在主题激活时自动创建表
  - _Requirements: 5.1, 5.2_

- [x] 2. 实现 Prompt_Engine 核心功能
  - [x] 2.1 创建 Argon_Spam_Prompt_Engine 类
    - 实现 get_prompt() 方法，支持三种预设模式
    - 实现 get_custom_template() 和 save_custom_template() 方法
    - 实现 validate_template() 方法验证模板格式
    - _Requirements: 1.1, 1.5, 1.6_


  - [ ]* 2.2 编写 Prompt_Engine 属性测试
    - **Property 1: Prompt 模式完整性**
    - **Validates: Requirements 1.1, 1.6**

  - [ ]* 2.3 编写 Prompt_Engine 属性测试
    - **Property 2: Token 消耗范围约束**
    - **Validates: Requirements 1.2, 1.3, 1.4**

  - [ ]* 2.4 编写 Prompt_Engine 属性测试
    - **Property 3: 自定义模板往返一致性**
    - **Validates: Requirements 1.5**

  - [ ]* 2.5 编写 Prompt_Engine 单元测试
    - 测试三种预设模式的 Prompt 生成
    - 测试自定义模板的保存和读取
    - 测试模板验证功能（有效和无效模板）
    - 测试边缘情况（空模板、超长模板、特殊字符）
    - _Requirements: 1.1, 1.5, 1.6_

- [x] 3. 实现 Context_Builder 核心功能
  - [x] 3.1 创建 Argon_Spam_Context_Builder 类
    - 实现 build_context() 方法收集评论上下文
    - 实现 get_post_info() 方法获取文章信息
    - 实现 get_user_stats() 方法获取用户历史统计
    - 实现 sanitize_context() 方法进行隐私脱敏
    - 添加缓存机制优化用户历史查询性能
    - _Requirements: 4.1, 4.2, 4.3, 4.5, 9.6_

  - [ ]* 3.2 编写 Context_Builder 属性测试
    - **Property 9: 上下文数据完整性**
    - **Validates: Requirements 4.1, 4.2, 4.3**

  - [ ]* 3.3 编写 Context_Builder 属性测试
    - **Property 10: 上下文传递正确性**
    - **Validates: Requirements 4.4**

  - [ ]* 3.4 编写 Context_Builder 属性测试
    - **Property 11: 敏感信息脱敏正确性**
    - **Validates: Requirements 4.5, 10.1, 10.2**

  - [ ]* 3.5 编写 Context_Builder 属性测试
    - **Property 12: 摘要截取正确性**
    - **Validates: Requirements 4.6**

  - [ ]* 3.6 编写 Context_Builder 单元测试
    - 测试文章信息获取（存在和不存在的文章）
    - 测试用户历史统计（有历史和无历史的用户）
    - 测试隐私脱敏（标准和严格模式）
    - 测试摘要截取（短摘要和长摘要）
    - 测试缓存机制（重复查询应使用缓存）
    - _Requirements: 4.1, 4.2, 4.3, 4.5, 4.6, 9.6_

- [x] 4. 实现 Threshold_Manager 核心功能
  - [x] 4.1 创建 Argon_Spam_Threshold_Manager 类
    - 实现 get_threshold() 和 set_threshold() 方法
    - 实现 should_auto_process() 方法判断是否自动处理
    - 实现 get_recommended_config() 方法提供推荐配置
    - _Requirements: 3.5, 6.6_

  - [ ]* 4.2 编写 Threshold_Manager 属性测试
    - **Property 6: 处理建议逻辑正确性**
    - **Validates: Requirements 3.2, 3.3, 3.4**

  - [ ]* 4.3 编写 Threshold_Manager 属性测试
    - **Property 7: 阈值配置往返一致性**
    - **Validates: Requirements 3.5**

  - [ ]* 4.4 编写 Threshold_Manager 单元测试
    - 测试阈值的保存和读取
    - 测试自动处理判断逻辑（各种置信度和阈值组合）
    - 测试推荐配置（小型、中型、大型博客）
    - 测试边界值（阈值 0.5, 0.85, 1.0）
    - _Requirements: 3.2, 3.3, 3.4, 3.5, 6.6_

- [x] 5. 实现 AI_Detector 主控制器
  - [x] 5.1 创建 Argon_Spam_AI_Detector 类
    - 实现 detect() 方法协调检测流程
    - 实现 process_result() 方法处理检测结果
    - 实现 batch_detect() 方法批量检测评论
    - 实现 test_prompt() 方法测试 Prompt 效果
    - 集成 Prompt_Engine、Context_Builder、Threshold_Manager
    - 实现异步检测机制（使用 WordPress Cron 或 Action Scheduler）
    - _Requirements: 2.1, 2.2, 3.1, 9.1, 9.2, 9.3, 9.4_

  - [ ]* 5.2 编写 AI_Detector 属性测试
    - **Property 4: 检测结果数据结构完整性**
    - **Validates: Requirements 2.1, 2.2, 3.1**

  - [ ]* 5.3 编写 AI_Detector 属性测试
    - **Property 5: 置信度分类正确性**
    - **Validates: Requirements 2.3, 2.4, 2.5, 2.6**

  - [ ]* 5.4 编写 AI_Detector 属性测试
    - **Property 8: 评论处理状态正确性**
    - **Validates: Requirements 3.6, 3.7, 3.8**

  - [ ]* 5.5 编写 AI_Detector 单元测试
    - 测试检测流程（同步和异步模式）
    - 测试结果处理（auto、review、approve 三种建议）
    - 测试批量检测（小批量和大批量）
    - 测试 Prompt 测试功能
    - 测试错误处理（API 超时、返回错误等）
    - _Requirements: 2.1, 2.2, 3.1, 3.6, 3.7, 3.8, 9.1, 9.2, 9.3, 9.4_

- [x] 6. Checkpoint - 核心组件测试
  - 确保所有核心组件测试通过，询问用户是否有问题

- [x] 7. 实现 API 错误处理机制
  - [x] 7.1 实现错误处理和自动禁用功能
    - 实现连接超时处理（30 秒超时）
    - 实现错误状态码处理（4xx、5xx、429）
    - 实现响应格式错误处理（JSON 解析失败、字段缺失）
    - 实现自动禁用机制（连续失败 N 次后禁用 M 分钟）
    - 实现手动恢复功能
    - 实现错误日志记录（最多保留 10 条）
    - _Requirements: 8.1, 8.2, 8.3, 8.4, 8.5, 8.6_

  - [ ]* 7.2 编写 API 错误处理属性测试
    - **Property 18: API 错误默认值正确性**
    - **Validates: Requirements 8.1, 8.2**

  - [ ]* 7.3 编写 API 错误处理属性测试
    - **Property 19: 自动禁用机制正确性**
    - **Validates: Requirements 8.3**

  - [ ]* 7.4 编写 API 错误处理属性测试
    - **Property 20: 错误日志容量限制**
    - **Validates: Requirements 8.4**

  - [ ]* 7.5 编写 API 错误处理属性测试
    - **Property 21: 自动恢复机制正确性**
    - **Validates: Requirements 8.5**

  - [ ]* 7.6 编写 API 错误处理属性测试
    - **Property 22: 手动恢复功能正确性**
    - **Validates: Requirements 8.6**

  - [ ]* 7.7 编写 API 错误处理单元测试
    - 测试各种错误场景（超时、4xx、5xx、429、格式错误）
    - 测试自动禁用触发和恢复
    - 测试手动恢复功能
    - 测试错误日志记录和容量限制
    - _Requirements: 8.1, 8.2, 8.3, 8.4, 8.5, 8.6_

- [x] 8. 实现性能优化功能
  - [x] 8.1 实现异步检测和批量扫描
    - 优化异步检测流程（使用 WordPress Cron 或 Action Scheduler）
    - 实现批量扫描队列机制（避免 API 速率限制）
    - 实现进度回调和状态更新
    - 优化数据库查询（使用缓存和批量查询）
    - _Requirements: 9.1, 9.2, 9.3, 9.4, 9.5, 9.6_

  - [ ]* 8.2 编写性能优化属性测试
    - **Property 23: 异步检测非阻塞性**
    - **Validates: Requirements 9.1**

  - [ ]* 8.3 编写性能优化属性测试
    - **Property 24: 状态更新正确性**
    - **Validates: Requirements 9.3**

  - [ ]* 8.4 编写性能优化属性测试
    - **Property 25: 批量扫描完整性**
    - **Validates: Requirements 9.4**

  - [ ]* 8.5 编写性能优化属性测试
    - **Property 26: 队列限速正确性**
    - **Validates: Requirements 9.5**

  - [ ]* 8.6 编写性能优化属性测试
    - **Property 27: 缓存一致性**
    - **Validates: Requirements 9.6**

  - [ ]* 8.7 编写性能优化单元测试
    - 测试异步检测（评论提交响应时间 < 100ms）
    - 测试批量扫描（100 条评论 < 5 分钟）
    - 测试队列限速（每秒最多 N 次调用）
    - 测试缓存机制（重复查询使用缓存）
    - _Requirements: 9.1, 9.2, 9.3, 9.4, 9.5, 9.6_

- [x] 9. 实现 Learning_Module 学习机制
  - [x] 9.1 创建 Argon_Spam_Learning_Module 类
    - 实现 record_feedback() 方法记录反馈
    - 实现 calculate_error_rate() 方法计算误判率
    - 实现 get_optimization_suggestions() 方法生成优化建议
    - 实现 export_feedback() 方法导出反馈数据
    - 实现 get_statistics() 方法获取统计数据
    - _Requirements: 5.1, 5.2, 5.3, 5.4, 5.5, 5.6_

  - [ ]* 9.2 编写 Learning_Module 属性测试
    - **Property 13: 反馈记录完整性**
    - **Validates: Requirements 5.1, 5.2**

  - [ ]* 9.3 编写 Learning_Module 属性测试
    - **Property 14: 误判率计算正确性**
    - **Validates: Requirements 5.3**

  - [ ]* 9.4 编写 Learning_Module 属性测试
    - **Property 15: 优化建议触发正确性**
    - **Validates: Requirements 5.4**

  - [ ]* 9.5 编写 Learning_Module 属性测试
    - **Property 16: 反馈数据导出格式正确性**
    - **Validates: Requirements 5.5**

  - [ ]* 9.6 编写 Learning_Module 属性测试
    - **Property 17: 统计数据准确性**
    - **Validates: Requirements 5.6**

  - [ ]* 9.7 编写 Learning_Module 单元测试
    - 测试反馈记录（各种管理员操作）
    - 测试误判率计算（不同数据集）
    - 测试优化建议生成（误判率 > 30%）
    - 测试反馈数据导出（CSV 格式）
    - 测试统计数据获取（准确性验证）
    - _Requirements: 5.1, 5.2, 5.3, 5.4, 5.5, 5.6_

- [x] 10. Checkpoint - 辅助组件测试
  - 确保所有辅助组件测试通过，询问用户是否有问题

- [x] 11. 实现隐私保护功能
  - [x] 11.1 实现数据脱敏和隐私保护
    - 在 Context_Builder 中实现邮箱脱敏（仅保留域名）
    - 在 Context_Builder 中实现 IP 脱敏（仅保留前两段）
    - 实现隐私级别配置（标准/严格）
    - 在严格模式下不发送任何用户标识信息
    - _Requirements: 10.1, 10.2, 10.3, 10.4, 10.5_

  - [ ]* 11.2 编写隐私保护属性测试
    - **Property 28: 隐私保护完整性**
    - **Validates: Requirements 10.3, 10.5**

  - [ ]* 11.3 编写隐私保护属性测试
    - **Property 29: 隐私级别配置往返一致性**
    - **Validates: Requirements 10.4**

  - [ ]* 11.4 编写隐私保护单元测试
    - 测试邮箱脱敏（标准和严格模式）
    - 测试 IP 脱敏（标准和严格模式）
    - 测试隐私级别配置保存和读取
    - 测试严格模式下不发送用户标识信息
    - _Requirements: 10.1, 10.2, 10.3, 10.4, 10.5_

- [x] 12. 实现设置界面
  - [x] 12.1 创建设置页面 UI
    - 添加 Prompt 模式选择下拉框（极简/标准/增强/自定义）
    - 添加自定义 Prompt 编辑器（仅在自定义模式下显示）
    - 添加检测阈值滑块（0.5-1.0，步长 0.05）
    - 添加智能抽查比例设置（0-100%）
    - 添加隐私级别选择（标准/严格）
    - 添加 API 配置（提供商、密钥、端点）
    - 显示当前月份 API 调用统计和预估费用
    - 添加"测试 Prompt"功能（输入示例评论测试效果）
    - 提供不同博客规模的推荐配置模板
    - 显示最近的 API 错误日志（最多 10 条）
    - 添加"手动重试"按钮恢复检测
    - _Requirements: 6.1, 6.2, 6.3, 6.4, 6.5, 6.6, 8.4, 8.6_

  - [x] 12.2 实现设置保存和验证
    - 实现设置保存逻辑（使用 WordPress Options API）
    - 实现设置验证（阈值范围、模式有效性等）
    - 实现测试 Prompt 功能（调用 AI_Detector.test_prompt()）
    - 实现推荐配置应用功能
    - 实现手动重试功能
    - _Requirements: 6.1, 6.2, 6.3, 6.4, 6.5, 6.6, 8.6_

  - [ ]* 12.3 编写设置界面单元测试
    - 测试设置保存和读取
    - 测试设置验证（有效和无效值）
    - 测试测试 Prompt 功能
    - 测试推荐配置应用
    - 测试手动重试功能
    - _Requirements: 6.1, 6.2, 6.3, 6.4, 6.5, 6.6, 8.6_

- [x] 13. 实现后台显示增强
  - [x] 13.1 增强评论列表显示
    - 在评论列表添加置信度标签（不同颜色表示不同等级）
    - 实现鼠标悬停显示详细分析原因
    - 在评论详情页显示完整 AI 分析报告
    - 添加"重新检测"按钮（支持选择不同模式）
    - 在管理员操作后显示"反馈已记录"提示
    - _Requirements: 7.1, 7.2, 7.3, 7.4, 7.5, 7.6_

  - [x] 13.2 集成 Learning_Module 反馈记录
    - 在管理员批准/拒绝评论时调用 Learning_Module.record_feedback()
    - 在评论列表显示反馈状态
    - 在设置页面显示准确率统计
    - _Requirements: 5.1, 5.6, 7.6_

  - [ ]* 13.3 编写后台显示单元测试
    - 测试置信度标签显示（各种置信度值）
    - 测试详细分析显示
    - 测试重新检测功能
    - 测试反馈记录集成
    - _Requirements: 7.1, 7.2, 7.3, 7.4, 7.5, 7.6_

- [x] 14. Checkpoint - UI 和集成测试
  - 确保所有 UI 和集成功能正常工作，询问用户是否有问题

- [x] 15. 集成 WordPress 钩子
  - [x] 15.1 集成评论提交钩子
    - 在 `pre_comment_approved` 钩子中调用 AI_Detector.detect()
    - 根据检测结果决定评论状态（auto/review/approve）
    - 实现智能抽查逻辑（根据配置的抽查比例）
    - _Requirements: 3.6, 3.7, 3.8, 6.3, 9.1, 9.2_

  - [x] 15.2 集成评论管理钩子
    - 在 `wp_set_comment_status` 钩子中调用 Learning_Module.record_feedback()
    - 在 `edit_comment` 钩子中更新检测结果
    - _Requirements: 5.1, 7.6_

  - [x] 15.3 集成主题激活钩子
    - 在主题激活时创建数据库表
    - 初始化默认配置
    - _Requirements: 5.1_

  - [ ]* 15.4 编写 WordPress 集成测试
    - 测试评论提交流程（各种检测结果）
    - 测试评论状态更新
    - 测试反馈记录
    - 测试主题激活初始化
    - _Requirements: 3.6, 3.7, 3.8, 5.1, 9.1, 9.2_

- [x] 16. 性能测试和优化
  - [ ]* 16.1 运行性能测试
    - 测试评论提交响应时间（目标 < 100ms）
    - 测试同步检测响应时间（目标 < 3s）
    - 测试批量扫描性能（100 条评论 < 5 分钟）
    - 测试并发评论提交（10 个并发）
    - 测试内存使用（批量扫描 1000 条评论 < 256MB）
    - _Requirements: 9.1, 9.2, 9.4_

  - [x] 16.2 优化性能瓶颈
    - 根据性能测试结果优化慢速代码
    - 优化数据库查询（添加索引、使用缓存）
    - 优化 API 调用（批量处理、限速）
    - _Requirements: 9.4, 9.5, 9.6_

- [x] 17. 文档和用户指南
  - [x] 17.1 编写开发文档
    - 编写 API 文档（所有公共方法）
    - 编写架构文档（组件关系和数据流）
    - 编写测试文档（如何运行测试）
    - 编写贡献指南（如何添加新功能）

  - [x] 17.2 编写用户指南
    - 编写设置指南（如何配置各项参数）
    - 编写使用指南（如何使用各项功能）
    - 编写故障排除指南（常见问题和解决方案）
    - 编写最佳实践指南（不同博客规模的推荐配置）

- [x] 18. 最终集成测试
  - [ ]* 18.1 运行完整测试套件
    - 运行所有单元测试
    - 运行所有属性测试（100 次迭代）
    - 运行所有集成测试
    - 运行性能测试
    - 生成代码覆盖率报告（目标 > 80%）

  - [x] 18.2 手动测试关键流程
    - 测试评论提交和检测流程
    - 测试管理员审核和反馈记录
    - 测试批量扫描功能
    - 测试设置界面和配置保存
    - 测试错误处理和自动禁用
    - 测试隐私保护功能

- [x] 19. Final Checkpoint - 完整功能验证
  - 确保所有功能正常工作，所有测试通过，询问用户是否准备发布

## Notes

- 任务标记 `*` 的为可选测试任务，可根据项目进度决定是否实施
- 每个任务都引用了相关的需求编号，便于追溯
- Checkpoint 任务用于阶段性验证，确保增量开发的质量
- 属性测试使用 PHPUnit + Eris 或 Pest + Pest Property Testing Plugin
- 每个属性测试最少运行 100 次迭代
- 单元测试关注具体示例、边缘情况和错误条件
- 集成测试验证组件之间的协作和 WordPress 集成
- 性能测试确保系统满足响应时间和资源使用要求