# Implementation Plan: 高级功能迁移

## Overview

本任务列表实现阶段8的三个核心功能：API文档完善、集成测试覆盖和缓存预热机制。任务按照依赖关系排序，确保增量开发和验证。

## Tasks

- [x] 1. API文档完善
  - [x] 1.1 配置XML文档生成
    - 修改HoneyBox.Api.csproj启用GenerateDocumentationFile
    - 添加NoWarn配置忽略缺少注释的警告
    - _Requirements: 1.1, 1.3_
  - [x] 1.2 完善控制器XML注释
    - 为所有控制器类添加summary注释
    - 为所有Action方法添加summary、param、returns注释
    - 添加中文描述说明
    - _Requirements: 1.3, 1.6_
  - [x] 1.3 完善DTO模型XML注释
    - 为Request/Response模型添加summary注释
    - 为模型属性添加中文描述
    - 添加example示例值
    - _Requirements: 1.6_
  - [x] 1.4 配置OpenAPI JWT认证
    - 在Program.cs中配置OpenAPI的SecurityScheme
    - 添加Bearer Token认证支持
    - _Requirements: 1.4_
  - [x] 1.5 配置多响应状态码
    - 为需要认证的接口添加401响应定义
    - 为可能失败的接口添加400响应定义
    - 使用ProducesResponseType特性
    - _Requirements: 1.5_

- [ ] 2. Checkpoint - API文档验证
  - 启动应用访问/openapi/v1.json验证文档生成
  - 访问Scalar UI验证文档展示
  - 如有问题请询问用户

- [ ] 3. 集成测试基础设施
  - [ ] 3.1 创建WebApplicationFactory
    - 在HoneyBox.Tests项目创建HoneyBoxWebApplicationFactory类
    - 配置使用内存数据库替代SQL Server
    - 配置测试环境的服务注册
    - _Requirements: 2.5_
  - [ ] 3.2 创建集成测试基类
    - 创建IntegrationTestBase抽象类
    - 实现GetAuthTokenAsync方法生成测试Token
    - 实现SeedTestDataAsync方法初始化测试数据
    - _Requirements: 2.5, 2.7_
  - [ ] 3.3 创建测试数据种子
    - 创建TestDataSeeder类
    - 实现用户、商品、订单等测试数据初始化
    - _Requirements: 2.1-2.4_

- [ ] 4. 集成测试实现
  - [ ] 4.1 实现认证模块集成测试
    - 测试微信登录流程（模拟）
    - 测试手机号登录流程
    - 测试Token验证
    - _Requirements: 2.1_
  - [ ] 4.2 实现商品模块集成测试
    - 测试商品列表查询
    - 测试商品详情查询
    - 测试商品收藏功能
    - _Requirements: 2.2_
  - [ ] 4.3 实现订单模块集成测试
    - 测试订单创建
    - 测试订单查询
    - 测试订单取消
    - _Requirements: 2.3_
  - [ ] 4.4 实现抽奖模块集成测试
    - 测试抽奖结果查询
    - 测试中奖记录查询
    - 测试道具卡抽奖
    - _Requirements: 2.4_
  - [ ]* 4.5 编写API响应格式属性测试
    - **Property 3: 集成测试响应格式一致性**
    - **Validates: Requirements 2.6**

- [ ] 5. Checkpoint - 集成测试验证
  - 运行所有集成测试确保通过
  - 如有问题请询问用户

- [ ] 6. 缓存预热实现
  - [ ] 6.1 创建缓存预热配置
    - 在appsettings.json添加CacheWarmup配置节
    - 创建CacheWarmupOptions配置类
    - 注册配置到DI容器
    - _Requirements: 3.6_
  - [ ] 6.2 创建缓存预热服务接口
    - 在HoneyBox.Core/Interfaces创建ICacheWarmupService接口
    - 定义WarmupAsync、WarmupHotGoodsAsync、WarmupSystemConfigAsync方法
    - _Requirements: 3.1, 3.2_
  - [ ] 6.3 实现缓存预热服务
    - 在HoneyBox.Core/Services创建CacheWarmupService类
    - 实现热门商品数据预热（按销量/浏览量排序）
    - 实现系统配置数据预热
    - 添加预热进度日志记录
    - _Requirements: 3.1, 3.2, 3.4_
  - [ ] 6.4 创建缓存预热后台服务
    - 在HoneyBox.Api创建CacheWarmupHostedService类
    - 继承BackgroundService实现异步预热
    - 添加错误处理确保不影响系统启动
    - _Requirements: 3.3, 3.5_
  - [ ] 6.5 注册缓存预热服务
    - 在Program.cs注册ICacheWarmupService
    - 注册CacheWarmupHostedService为托管服务
    - _Requirements: 3.1-3.6_
  - [ ]* 6.6 编写缓存预热属性测试
    - **Property 4: 缓存预热异步性**
    - **Validates: Requirements 3.3**

- [ ] 7. Checkpoint - 缓存预热验证
  - 启动应用验证预热日志输出
  - 验证缓存中存在预热数据
  - 如有问题请询问用户

- [ ] 8. 文档更新
  - [ ] 8.1 更新API迁移文档
    - 在docs/API迁移详细文档/阶段8-高级功能.md标记完成状态
    - 记录实现的功能和配置说明
    - _Requirements: 1.1-3.6_

- [ ] 9. Final Checkpoint - 完整功能验证
  - 确保所有测试通过
  - 确保API文档完整可访问
  - 确保缓存预热正常工作
  - 如有问题请询问用户

## Notes

- Tasks marked with `*` are optional and can be skipped for faster MVP
- Each task references specific requirements for traceability
- Checkpoints ensure incremental validation
- Property tests validate universal correctness properties
- 集成测试使用内存数据库，不依赖外部SQL Server
- 缓存预热在后台异步执行，不阻塞应用启动
- API文档使用.NET内置的OpenAPI支持和Scalar UI

## 技术说明

### XML注释配置
```xml
<!-- HoneyBox.Api.csproj -->
<PropertyGroup>
    <GenerateDocumentationFile>true</GenerateDocumentationFile>
    <NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>
```

### 缓存预热配置
```json
// appsettings.json
{
  "CacheWarmup": {
    "EnableWarmup": true,
    "HotGoodsCount": 100,
    "WarmupDelaySeconds": 5
  }
}
```

### 集成测试运行
```bash
cd server/C#/HoneyBox
dotnet test --filter "Category=Integration"
```