4.4 KiB
4.4 KiB
Requirements Document
Introduction
本规格文档定义了 HoneyBox 抽奖系统 .NET 8 Web API 项目基础架构搭建的需求。目标是建立一个完整的项目结构，包含四层架构（Api、Core、Infrastructure、Model），配置好所有基础设施（数据库、缓存、日志、依赖注入等），为后续业务开发提供稳定的技术基础。
Glossary
- HoneyBox_Api: Web API 入口层，包含控制器、中间件、过滤器
- HoneyBox_Core: 核心业务层，包含服务实现、接口定义、映射配置
- HoneyBox_Infrastructure: 基础设施层，包含 Redis 缓存、外部服务集成、Autofac 模块
- HoneyBox_Model: 数据模型层，包含数据库实体、DTO、DbContext、统一响应基类
- ApiResponse: 统一响应格式基类，所有接口返回格式一致
- Mapster: 高性能对象映射框架
- Autofac: 依赖注入容器，支持模块化注册
Requirements
Requirement 1: 项目结构搭建
User Story: As a 开发者, I want 创建标准的四层项目结构, so that 代码组织清晰、职责分离明确。
Acceptance Criteria
- THE HoneyBox_Solution SHALL 包含四个项目：HoneyBox.Api、HoneyBox.Model、HoneyBox.Core、HoneyBox.Infrastructure
- THE HoneyBox_Api SHALL 依赖 HoneyBox.Core 和 HoneyBox.Model
- THE HoneyBox_Core SHALL 依赖 HoneyBox.Model 和 HoneyBox.Infrastructure
- THE HoneyBox_Infrastructure SHALL 不依赖任何项目内部模块
- THE HoneyBox_Model SHALL 不依赖任何项目内部模块
- WHEN 项目创建完成 THEN 解决方案 SHALL 能够正常编译
Requirement 2: 数据模型层配置
User Story: As a 开发者, I want 配置数据模型层连接 SQL Server 数据库, so that 能够访问已迁移的业务数据。
Acceptance Criteria
- THE HoneyBox_Model SHALL 包含 EF Core SQL Server 依赖包
- THE HoneyBox_Model SHALL 包含从数据库生成的实体类（Entities 目录）
- THE HoneyBox_Model SHALL 包含 HoneyBoxDbContext 类（Data 目录）
- THE HoneyBox_Model SHALL 包含统一响应基类 ApiResponse（Base 目录）
- THE HoneyBox_Model SHALL 包含 DTO 模型结构（Models 目录，按控制器分文件夹）
- WHEN 配置完成 THEN DbContext SHALL 能够连接到 SQL Server 数据库
Requirement 3: 基础设施层配置
User Story: As a 开发者, I want 配置基础设施层提供外部服务支持, so that 业务层能够使用缓存等基础服务。
Acceptance Criteria
- THE HoneyBox_Infrastructure SHALL 包含 Redis 缓存服务接口和实现
- THE HoneyBox_Infrastructure SHALL 包含 Autofac 模块注册类
- THE ICacheService SHALL 提供 GetAsync、SetAsync、RemoveAsync、ExistsAsync 方法
- THE RedisCacheService SHALL 实现 ICacheService 接口
- WHEN Redis 连接配置正确 THEN 缓存服务 SHALL 能够正常读写数据
Requirement 4: 核心业务层配置
User Story: As a 开发者, I want 配置核心业务层的基础结构, so that 后续业务服务开发有统一的规范。
Acceptance Criteria
- THE HoneyBox_Core SHALL 包含 Mapster 对象映射依赖包
- THE HoneyBox_Core SHALL 包含 MappingConfig 映射配置类
- THE HoneyBox_Core SHALL 包含 Services 和 Interfaces 目录结构
- THE HoneyBox_Core SHALL 包含 Constants 常量定义目录
- WHEN Mapster 配置完成 THEN 对象映射 SHALL 能够正常工作
Requirement 5: API 层配置
User Story: As a 开发者, I want 配置 API 层的中间件和基础设施, so that API 服务能够正常运行。
Acceptance Criteria
- THE HoneyBox_Api SHALL 配置 Autofac 作为依赖注入容器
- THE HoneyBox_Api SHALL 配置 Serilog 日志输出到控制台和文件
- THE HoneyBox_Api SHALL 配置 Swagger API 文档
- THE HoneyBox_Api SHALL 配置全局异常处理过滤器
- THE HoneyBox_Api SHALL 配置 CORS 跨域策略
- WHEN 应用启动 THEN Swagger 文档 SHALL 可以通过 /swagger 访问
Requirement 6: 健康检查接口
User Story: As a 运维人员, I want 有一个健康检查接口, so that 能够监控服务运行状态。
Acceptance Criteria
- WHEN 访问 /api/health THEN THE System SHALL 返回服务健康状态
- THE 健康检查响应 SHALL 包含数据库连接状态
- THE 健康检查响应 SHALL 包含 Redis 连接状态
- THE 健康检查响应 SHALL 使用统一的 ApiResponse 格式
- IF 数据库或 Redis 连接失败 THEN THE System SHALL 返回对应的错误状态