# Requirements Document

## Introduction

本文档定义了 Argon 主题 AI 垃圾评论检测功能的优化需求。当前系统已实现基础的 AI 检测功能，但在灵活性、准确性和成本控制方面存在不足。本次优化旨在通过引入多级 Prompt 系统、置信度评分、智能处理建议和学习机制，提升检测准确率并降低误判率。

## Glossary

- **AI_Detector**: AI 垃圾评论检测系统
- **Prompt_Engine**: Prompt 生成和管理引擎
- **Confidence_Score**: 置信度评分，范围 0-1，表示 AI 判断的确定性
- **Processing_Suggestion**: 处理建议，包括 auto（自动处理）、review（人工审核）、approve（直接通过）
- **Context_Builder**: 上下文信息构建器，收集评论相关的文章、用户历史等信息
- **Learning_Module**: 学习模块，记录和分析管理员审核决策
- **Detection_Threshold**: 检测阈值，用于判断是否自动处理的置信度临界值
- **Comment_Context**: 评论上下文，包括文章信息、用户历史、时间戳等
- **Feedback_Record**: 反馈记录，存储 AI 判断和管理员决策的对比数据

## Requirements

### Requirement 1: 多级 Prompt 系统

**User Story:** 作为博客管理员，我希望能够选择不同的检测模式，以便在准确性和 API 成本之间取得平衡。

#### Acceptance Criteria

1. THE Prompt_Engine SHALL 提供三种预设模式：极简模式（minimal）、标准模式（standard）、增强模式（enhanced）
2. WHEN 管理员选择极简模式 THEN THE Prompt_Engine SHALL 生成 token 消耗约 100-150 的 Prompt
3. WHEN 管理员选择标准模式 THEN THE Prompt_Engine SHALL 生成 token 消耗约 200-300 的 Prompt
4. WHEN 管理员选择增强模式 THEN THE Prompt_Engine SHALL 生成 token 消耗约 300-500 的 Prompt
5. WHERE 管理员选择自定义模式 THE Prompt_Engine SHALL 允许管理员编辑自定义 Prompt 模板
6. THE Prompt_Engine SHALL 在每个 Prompt 中包含明确的输出格式要求（JSON 格式）

### Requirement 2: 置信度评分系统

**User Story:** 作为博客管理员，我希望 AI 能够提供置信度评分，以便我了解判断的可靠性并做出相应决策。

#### Acceptance Criteria

1. WHEN AI_Detector 分析评论 THEN THE AI_Detector SHALL 返回 0-1 范围的 Confidence_Score
2. THE AI_Detector SHALL 在返回结果中包含 is_spam（布尔值）、confidence（浮点数）、reason（字符串）三个字段
3. WHEN Confidence_Score >= 0.9 THEN THE AI_Detector SHALL 标记为"非常确定"
4. WHEN 0.7 <= Confidence_Score < 0.9 THEN THE AI_Detector SHALL 标记为"比较确定"
5. WHEN 0.5 <= Confidence_Score < 0.7 THEN THE AI_Detector SHALL 标记为"中等确定"
6. WHEN Confidence_Score < 0.5 THEN THE AI_Detector SHALL 标记为"不太确定"

### Requirement 3: 智能处理建议

**User Story:** 作为博客管理员，我希望系统能够根据置信度自动决定处理方式，以便减少人工审核工作量。

#### Acceptance Criteria

1. THE AI_Detector SHALL 在返回结果中包含 Processing_Suggestion 字段
2. WHEN Confidence_Score >= Detection_Threshold AND is_spam = true THEN THE AI_Detector SHALL 返回 suggestion = "auto"
3. WHEN 0.5 <= Confidence_Score < Detection_Threshold AND is_spam = true THEN THE AI_Detector SHALL 返回 suggestion = "review"
4. WHEN Confidence_Score < 0.5 OR is_spam = false THEN THE AI_Detector SHALL 返回 suggestion = "approve"
5. THE AI_Detector SHALL 允许管理员在设置中配置 Detection_Threshold（默认值 0.85）
6. WHEN suggestion = "auto" THEN THE AI_Detector SHALL 自动将评论标记为垃圾或移至回收站
7. WHEN suggestion = "review" THEN THE AI_Detector SHALL 将评论标记为待审核状态
8. WHEN suggestion = "approve" THEN THE AI_Detector SHALL 允许评论正常发布并记录低置信度日志

### Requirement 4: 上下文信息增强

**User Story:** 作为博客管理员，我希望 AI 能够结合文章内容和用户历史进行判断，以便提高检测准确性。

#### Acceptance Criteria

1. THE Context_Builder SHALL 收集评论所属文章的标题和摘要
2. THE Context_Builder SHALL 收集评论者的历史评论数量和通过率
3. THE Context_Builder SHALL 收集评论的时间戳和 IP 地址
4. WHEN 构建检测请求 THEN THE Context_Builder SHALL 将 Comment_Context 包含在 Prompt 中
5. THE Context_Builder SHALL 对敏感信息（如完整邮箱）进行脱敏处理
6. WHERE 文章摘要超过 200 字符 THE Context_Builder SHALL 截取前 200 字符

### Requirement 5: 学习优化机制

**User Story:** 作为博客管理员，我希望系统能够从我的审核决策中学习，以便不断优化检测准确性。

#### Acceptance Criteria

1. WHEN 管理员批准或拒绝 AI 标记的评论 THEN THE Learning_Module SHALL 记录 Feedback_Record
2. THE Feedback_Record SHALL 包含 AI 判断结果、管理员决策、时间戳、评论特征哈希
3. THE Learning_Module SHALL 定期分析 Feedback_Record 计算误判率
4. WHEN 某类型评论的误判率 > 30% THEN THE Learning_Module SHALL 在管理后台显示优化建议
5. THE Learning_Module SHALL 提供"导出反馈数据"功能用于分析
6. THE Learning_Module SHALL 在设置页面显示当前的准确率统计（总检测数、自动处理数、误判数）

### Requirement 6: 设置界面优化

**User Story:** 作为博客管理员，我希望有清晰的设置界面来配置检测参数，以便根据博客规模调整策略。

#### Acceptance Criteria

1. THE AI_Detector SHALL 在设置页面提供 Prompt 模式选择下拉框
2. THE AI_Detector SHALL 在设置页面提供 Detection_Threshold 滑块（范围 0.5-1.0，步长 0.05）
3. THE AI_Detector SHALL 在设置页面提供"智能抽查比例"设置（范围 0-100%）
4. THE AI_Detector SHALL 在设置页面显示当前月份的 API 调用统计和预估费用
5. THE AI_Detector SHALL 提供"测试 Prompt"功能，允许管理员输入示例评论测试检测效果
6. THE AI_Detector SHALL 在设置页面提供不同博客规模的推荐配置模板

### Requirement 7: 后台显示增强

**User Story:** 作为博客管理员，我希望在评论列表中看到 AI 检测结果的详细信息，以便快速做出审核决策。

#### Acceptance Criteria

1. WHEN 评论被 AI 检测 THEN THE AI_Detector SHALL 在评论列表显示置信度标签
2. THE AI_Detector SHALL 使用不同颜色标识不同置信度等级（红色：>0.9，橙色：0.7-0.9，黄色：0.5-0.7）
3. WHEN 鼠标悬停在置信度标签上 THEN THE AI_Detector SHALL 显示详细的分析原因
4. THE AI_Detector SHALL 在评论详情页显示完整的 AI 分析报告
5. THE AI_Detector SHALL 提供"重新检测"按钮允许管理员使用不同模式重新分析
6. WHEN 管理员批准或拒绝 AI 判断 THEN THE AI_Detector SHALL 显示反馈已记录的提示

### Requirement 8: API 错误处理

**User Story:** 作为博客管理员，我希望系统能够优雅地处理 API 错误，以便在 API 不可用时不影响评论功能。

#### Acceptance Criteria

1. WHEN API 请求失败 THEN THE AI_Detector SHALL 记录错误日志并允许评论正常发布
2. WHEN API 返回格式错误 THEN THE AI_Detector SHALL 使用默认值（is_spam=false, confidence=0, suggestion="approve"）
3. THE AI_Detector SHALL 在连续失败 3 次后自动禁用实时检测 1 小时
4. THE AI_Detector SHALL 在设置页面显示最近的 API 错误日志（最多 10 条）
5. WHEN API 恢复正常 THEN THE AI_Detector SHALL 自动重新启用实时检测
6. THE AI_Detector SHALL 提供"手动重试"按钮允许管理员立即恢复检测

### Requirement 9: 性能优化

**User Story:** 作为博客管理员，我希望 AI 检测不会显著影响评论提交速度，以便保持良好的用户体验。

#### Acceptance Criteria

1. THE AI_Detector SHALL 使用异步方式调用 API，不阻塞评论提交
2. WHEN 实时检测启用 THEN THE AI_Detector SHALL 在评论提交后立即返回"评论已提交，正在审核中"
3. THE AI_Detector SHALL 在 API 响应后更新评论状态（通过或待审核）
4. THE AI_Detector SHALL 提供"批量扫描"功能，允许管理员对现有评论进行批量检测
5. WHEN 批量扫描运行 THEN THE AI_Detector SHALL 使用队列机制避免 API 速率限制
6. THE AI_Detector SHALL 缓存用户历史统计数据，避免重复查询数据库

### Requirement 10: 数据隐私保护

**User Story:** 作为博客管理员，我希望系统在发送数据给 AI 时保护用户隐私，以便符合数据保护法规。

#### Acceptance Criteria

1. THE AI_Detector SHALL 对邮箱地址进行脱敏处理（仅保留域名）
2. THE AI_Detector SHALL 对 IP 地址进行脱敏处理（仅保留前两段）
3. THE AI_Detector SHALL 不发送用户的真实姓名和联系方式
4. THE AI_Detector SHALL 在设置页面提供"数据脱敏级别"选项（标准/严格）
5. WHERE 严格模式启用 THE AI_Detector SHALL 不发送任何用户标识信息
6. THE AI_Detector SHALL 在隐私政策中说明 AI 检测功能的数据使用方式