168 lines
5.5 KiB
Markdown
168 lines
5.5 KiB
Markdown
# 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"
|
||
```
|