argon-theme/.kiro/steering/phase-2-testing-guide.md

# 第二阶段：测试和验证指南

## 📅 开始时间
2026-01-26

## 🎯 测试目标

验证统一 API 管理系统的后端功能是否正常工作，为第三阶段的 UI 重构做准备。

## 📋 测试清单

### 1. 系统状态检查 ✅

**测试文件**: `test-system-status.php`

**访问方式**:
```
https://your-site.com/wp-content/themes/argon/test-system-status.php
```

**检查项目**:
- [ ] 所有核心函数已加载
- [ ] 数据迁移状态正常
- [ ] API 配置正确显示
- [ ] 场景配置正常工作
- [ ] 旧数据已备份

**预期结果**:
- 显示"✓ 统一 API 管理系统已就绪！"
- 如果有旧配置，应该已经迁移到新系统
- 文章摘要和评论审核场景应该有活动的 API

---

### 2. 详细功能测试 ✅

**测试文件**: `test-unified-api-system.php`

**访问方式**:
```
https://your-site.com/wp-content/themes/argon/test-unified-api-system.php
```

**检查项目**:
- [ ] 函数存在性检查通过
- [ ] 数据迁移成功
- [ ] API 配置列表正确显示
- [ ] 旧数据检查正常
- [ ] 场景化 API 测试通过
- [ ] 向后兼容性测试通过

**预期结果**:
- 所有测试项显示绿色 ✓
- 测试总结显示"✓ 统一 API 管理系统已就绪！"

---

### 3. AI 功能实际测试

#### 3.1 文章摘要测试

**步骤**:
1. 确保已配置文章摘要的活动 API
2. 创建或编辑一篇文章
3. 发布文章
4. 查看文章页面，检查是否显示 AI 摘要

**检查点**:
- [ ] AI 摘要正常生成
- [ ] 使用的是正确的 API（检查日志）
- [ ] 没有错误信息

**如果失败**:
- 检查 WordPress 错误日志
- 查看文章的 `_argon_ai_summary_error` meta
- 确认 API 密钥和端点正确

#### 3.2 评论审核测试

**步骤**:
1. 确保已配置评论审核的活动 API
2. 启用 AI 垃圾评论检测
3. 发表一条测试评论
4. 检查评论是否被正确处理

**检查点**:
- [ ] AI 检测正常工作
- [ ] 使用的是正确的 API
- [ ] 检测结果合理

**如果失败**:
- 检查 WordPress 错误日志
- 查看评论的 meta 数据
- 确认 API 密钥和端点正确

---

### 4. 小米 Mimo API 专项测试

**背景**: 用户反馈小米 Mimo 无法使用

**测试步骤**:

#### 4.1 检查配置
```php
// 在 test-system-status.php 中查看
// 小米 Mimo 的配置是否正确
```

**检查点**:
- [ ] API 密钥格式正确
- [ ] 端点是否为 `https://api.mimo.xiaomi.com/v1/chat/completions`
- [ ] 模型是否为 `MiMo-V2-Flash` 或其他有效模型

#### 4.2 手动测试 API

创建测试脚本 `test-xiaomi-api.php`:

```php
<?php
require_once('../../../wp-load.php');

if (!current_user_can('manage_options')) {
    wp_die('权限不足');
}

// 获取小米 Mimo 配置
$config = argon_get_active_api_config('summary');

if ($config['provider'] !== 'xiaomi') {
    echo '当前活动 API 不是小米 Mimo';
    exit;
}

// 测试 API 调用
$api_key = $config['api_key'];
$api_endpoint = !empty($config['api_endpoint']) 
    ? $config['api_endpoint'] 
    : 'https://api.mimo.xiaomi.com/v1/chat/completions';
$model = !empty($config['model']) ? $config['model'] : 'MiMo-V2-Flash';

$data = [
    'model' => $model,
    'messages' => [
        [
            'role' => 'user',
            'content' => '你好，这是一个测试。请回复"测试成功"。'
        ]
    ],
    'max_tokens' => 100
];

$response = wp_remote_post($api_endpoint, [
    'headers' => [
        'Content-Type' => 'application/json',
        'Authorization' => 'Bearer ' . $api_key
    ],
    'body' => json_encode($data),
    'timeout' => 30
]);

echo '<h1>小米 Mimo API 测试</h1>';
echo '<h2>请求配置</h2>';
echo '<pre>';
echo 'API 端点: ' . $api_endpoint . "\n";
echo '模型: ' . $model . "\n";
echo 'API 密钥: ' . substr($api_key, 0, 12) . '...' . "\n";
echo '</pre>';

echo '<h2>响应结果</h2>';
if (is_wp_error($response)) {
    echo '<p style="color: red;">错误: ' . $response->get_error_message() . '</p>';
} else {
    $status_code = wp_remote_retrieve_response_code($response);
    $body = wp_remote_retrieve_body($response);
    
    echo '<p>状态码: ' . $status_code . '</p>';
    echo '<h3>响应内容</h3>';
    echo '<pre>' . htmlspecialchars($body) . '</pre>';
    
    if ($status_code === 200) {
        $result = json_decode($body, true);
        if (isset($result['choices'][0]['message']['content'])) {
            echo '<p style="color: green;">✓ API 调用成功！</p>';
            echo '<p>AI 回复: ' . htmlspecialchars($result['choices'][0]['message']['content']) . '</p>';
        }
    } else {
        echo '<p style="color: red;">✗ API 调用失败</p>';
    }
}
?>
```

**检查点**:
- [ ] API 返回 200 状态码
- [ ] 响应包含有效的 JSON
- [ ] 能够正确解析 AI 回复

**常见问题**:
1. **401 Unauthorized**: API 密钥无效或过期
2. **403 Forbidden**: API 密钥没有权限
3. **404 Not Found**: API 端点错误
4. **429 Too Many Requests**: 超过速率限制
5. **500 Internal Server Error**: 服务器错误

---

### 5. 向后兼容性测试

**测试场景**: 确保旧代码仍然能正常工作

**测试步骤**:

1. **测试旧的 API 获取函数**:
```php
// 在 test-unified-api-system.php 中已包含
$old_config = argon_get_ai_provider_config('openai');
```

**检查点**:
- [ ] 函数返回有效配置
- [ ] 配置包含 api_key, api_endpoint, model, provider
- [ ] 如果新系统有数据，优先使用新系统
- [ ] 如果新系统无数据，回退到旧系统

2. **测试多 API 管理函数**:
```php
// 旧的多 API 函数应该仍然可用
$openai_apis = argon_get_provider_apis('openai');
$active_api = argon_get_active_api('openai');
```

**检查点**:
- [ ] 旧函数仍然可用
- [ ] 返回的数据格式正确

---

### 6. 错误日志检查

**位置**: 
- WordPress 调试日志: `wp-content/debug.log`
- 服务器错误日志: 根据服务器配置

**检查内容**:
- [ ] 没有 PHP Fatal Error
- [ ] 没有 PHP Warning（除非是已知的）
- [ ] 没有 AI API 调用错误
- [ ] 没有数据迁移错误

**如何启用调试**:
在 `wp-config.php` 中添加：
```php
define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
define('WP_DEBUG_DISPLAY', false);
```

---

## 📊 测试结果记录

### 系统状态
- [ ] ✅ 通过
- [ ] ⚠️ 部分通过（记录问题）
- [ ] ❌ 失败（记录错误）

**问题记录**:
```
问题 1: [描述]
- 错误信息: 
- 复现步骤:
- 预期行为:
- 实际行为:

问题 2: [描述]
...
```

### AI 功能测试
- [ ] ✅ 文章摘要正常
- [ ] ✅ 评论审核正常
- [ ] ✅ 小米 Mimo 正常

**问题记录**:
```
[如有问题，在此记录]
```

### 向后兼容性
- [ ] ✅ 旧函数正常工作
- [ ] ✅ 数据迁移成功
- [ ] ✅ 回退机制正常

---

## 🔧 问题排查指南

### 问题 1: 数据迁移失败

**症状**: `argon_ai_apis_migrated` 为 'false'

**排查步骤**:
1. 检查是否有旧数据
2. 查看错误日志
3. 手动执行迁移函数
4. 检查数据库权限

**解决方案**:
```php
// 手动触发迁移
delete_option('argon_ai_apis_migrated');
argon_migrate_ai_apis();
```

### 问题 2: API 配置为空

**症状**: `argon_get_all_apis()` 返回空数组

**排查步骤**:
1. 检查是否有旧配置
2. 检查数据迁移状态
3. 查看数据库中的 `argon_ai_apis` 选项

**解决方案**:
- 如果有旧配置但未迁移，手动触发迁移
- 如果没有旧配置，需要在设置页面添加新配置

### 问题 3: AI 功能不工作

**症状**: 文章摘要或评论审核不生成结果

**排查步骤**:
1. 检查是否配置了活动 API
2. 检查 API 密钥是否有效
3. 查看错误日志
4. 测试 API 连通性

**解决方案**:
- 确保设置了活动 API
- 验证 API 密钥和端点
- 检查网络连接
- 查看 API 提供商的状态

### 问题 4: 小米 Mimo 无法使用

**可能原因**:
1. API 密钥格式错误
2. API 端点错误
3. 模型名称错误
4. 网络连接问题
5. API 配额用尽

**排查步骤**:
1. 使用 `test-xiaomi-api.php` 测试
2. 检查 API 密钥格式（应该是 `sk-` 开头）
3. 确认端点为 `https://api.mimo.xiaomi.com/v1/chat/completions`
4. 确认模型为 `MiMo-V2-Flash`
5. 查看详细的错误响应

---

## ✅ 测试通过标准

满足以下条件即可进入第三阶段（UI 重构）：

1. **核心功能**:
   - [x] 所有核心函数正常工作
   - [x] 数据迁移成功
   - [x] API 配置正确存储和读取

2. **AI 功能**:
   - [ ] 文章摘要正常生成
   - [ ] 评论审核正常工作
   - [ ] 至少一个 AI 提供商可用

3. **向后兼容**:
   - [x] 旧函数仍然可用
   - [x] 旧数据已备份
   - [x] 回退机制正常

4. **无严重错误**:
   - [ ] 没有 PHP Fatal Error
   - [ ] 没有数据丢失
   - [ ] 没有功能退化

---

## 📝 测试完成后的行动

### 如果测试通过 ✅
1. 更新文档，记录测试结果
2. 准备进入第三阶段（UI 重构）
3. 创建 Git 分支用于 UI 开发

### 如果测试失败 ❌
1. 记录所有问题和错误信息
2. 分析问题原因
3. 修复问题
4. 重新测试
5. 确认修复后再进入下一阶段

---

## 🔗 相关文件

- `test-system-status.php` - 快速状态检查
- `test-unified-api-system.php` - 详细功能测试
- `test-xiaomi-api.php` - 小米 Mimo 专项测试（需创建）
- `functions.php` - 核心函数实现
- `.kiro/steering/phase-1-complete.md` - 第一阶段总结
- `.kiro/steering/ai-refactor-next-steps.md` - 下一步计划

---

## 📞 需要帮助？

如果在测试过程中遇到问题，请提供：
1. 测试脚本的完整输出
2. WordPress 错误日志内容
3. 具体的错误信息和截图
4. 复现步骤

我将帮助您分析和解决问题。