chore: 更改文件夹结构

2025-11-23 09:55:11 +08:00
parent ccadacaa9d
commit cd52131c34
13 changed files with 0 additions and 0 deletions
--- a/Document/06_开发规范.md
+++ b/Document/06_开发规范.md
@@ -0,0 +1,395 @@
+# 外卖SaaS系统 - 开发规范
+
+## 1. 代码规范
+
+### 1.1 命名规范
+
+#### C#命名规范
+```csharp
+// 类名：PascalCase
+public class OrderService { }
+
+// 接口：I + PascalCase
+public interface IOrderRepository { }
+
+// 方法：PascalCase
+public async Task<Order> CreateOrderAsync() { }
+
+// 私有字段：_camelCase
+private readonly IOrderRepository _orderRepository;
+
+// 公共属性：PascalCase
+public string OrderNo { get; set; }
+
+// 局部变量：camelCase
+var orderTotal = 100.00m;
+
+// 常量：PascalCase
+public const int MaxOrderItems = 50;
+
+// 枚举：PascalCase
+public enum OrderStatus
+{
+    Pending = 1,
+    Confirmed = 2,
+    Completed = 3
+}
+```
+
+#### 数据库命名规范
+```sql
+-- 表名：小写，下划线分隔，复数
+orders
+order_items
+merchant_stores
+
+-- 字段名：小写，下划线分隔
+order_no
+created_at
+total_amount
+
+-- 索引：idx_表名_字段名
+idx_orders_merchant_id
+idx_orders_created_at
+
+-- 外键：fk_表名_引用表名
+fk_orders_merchants
+```
+
+### 1.2 代码组织
+
+#### 项目结构
+```
+TakeoutSaaS/
+├── src/
+│   ├── TakeoutSaaS.Api/              # Web API层
+│   │   ├── Controllers/              # 控制器
+│   │   ├── Filters/                  # 过滤器
+│   │   ├── Middleware/               # 中间件
+│   │   ├── Models/                   # DTO模型
+│   │   └── Program.cs
+│   ├── TakeoutSaaS.Application/      # 应用层
+│   │   ├── Services/                 # 应用服务
+│   │   ├── DTOs/                     # 数据传输对象
+│   │   ├── Interfaces/               # 服务接口
+│   │   ├── Validators/               # 验证器
+│   │   ├── Mappings/                 # 对象映射
+│   │   └── Commands/                 # CQRS命令
+│   │       └── Queries/              # CQRS查询
+│   ├── TakeoutSaaS.Domain/           # 领域层
+│   │   ├── Entities/                 # 实体
+│   │   ├── ValueObjects/             # 值对象
+│   │   ├── Enums/                    # 枚举
+│   │   ├── Events/                   # 领域事件
+│   │   └── Interfaces/               # 仓储接口
+│   ├── TakeoutSaaS.Infrastructure/   # 基础设施层
+│   │   ├── Data/                     # 数据访问
+│   │   │   ├── EFCore/              # EF Core实现
+│   │   │   ├── Dapper/              # Dapper实现
+│   │   │   └── Repositories/        # 仓储实现
+│   │   ├── Cache/                    # 缓存实现
+│   │   ├── MessageQueue/             # 消息队列
+│   │   └── ExternalServices/         # 外部服务
+│   └── TakeoutSaaS.Shared/           # 共享层
+│       ├── Constants/                # 常量
+│       ├── Exceptions/               # 异常
+│       ├── Extensions/               # 扩展方法
+│       └── Results/                  # 统一返回结果
+├── tests/
+│   ├── TakeoutSaaS.UnitTests/        # 单元测试
+│   ├── TakeoutSaaS.IntegrationTests/ # 集成测试
+│   └── TakeoutSaaS.PerformanceTests/ # 性能测试
+└── docs/                             # 文档
+```
+
+### 1.3 代码注释
+
+```csharp
+/// <summary>
+/// 订单服务接口
+/// </summary>
+public interface IOrderService
+{
+    /// <summary>
+    /// 创建订单
+    /// </summary>
+    /// <param name="request">订单创建请求</param>
+    /// <returns>订单信息</returns>
+    /// <exception cref="BusinessException">业务异常</exception>
+    Task<OrderDto> CreateOrderAsync(CreateOrderRequest request);
+}
+
+// 复杂业务逻辑添加注释
+public async Task<decimal> CalculateOrderAmount(Order order)
+{
+    // 1. 计算菜品总金额
+    var dishAmount = order.Items.Sum(x => x.Price * x.Quantity);
+
+    // 2. 计算配送费（距离 > 3km，每公里加收2元）
+    var deliveryFee = CalculateDeliveryFee(order.Distance);
+
+    // 3. 应用优惠券折扣
+    var discount = await ApplyCouponDiscountAsync(order.CouponId, dishAmount);
+
+    // 4. 计算最终金额
+    return dishAmount + deliveryFee - discount;
+}
+```
+
+### 1.4 异常处理
+
+```csharp
+// 自定义业务异常
+public class BusinessException : Exception
+{
+    public int ErrorCode { get; }
+
+    public BusinessException(int errorCode, string message)
+        : base(message)
+    {
+        ErrorCode = errorCode;
+    }
+}
+
+// 全局异常处理中间件
+public class ExceptionHandlingMiddleware
+{
+    private readonly RequestDelegate _next;
+    private readonly ILogger<ExceptionHandlingMiddleware> _logger;
+
+    public async Task InvokeAsync(HttpContext context)
+    {
+        try
+        {
+            await _next(context);
+        }
+        catch (BusinessException ex)
+        {
+            _logger.LogWarning(ex, "业务异常：{Message}", ex.Message);
+            await HandleBusinessExceptionAsync(context, ex);
+        }
+        catch (Exception ex)
+        {
+            _logger.LogError(ex, "系统异常：{Message}", ex.Message);
+            await HandleSystemExceptionAsync(context, ex);
+        }
+    }
+
+    private static Task HandleBusinessExceptionAsync(HttpContext context, BusinessException ex)
+    {
+        context.Response.StatusCode = StatusCodes.Status422UnprocessableEntity;
+        return context.Response.WriteAsJsonAsync(new
+        {
+            success = false,
+            code = ex.ErrorCode,
+            message = ex.Message
+        });
+    }
+}
+
+// 使用示例
+public async Task<Order> GetOrderAsync(Guid orderId)
+{
+    var order = await _orderRepository.GetByIdAsync(orderId);
+    if (order == null)
+    {
+        throw new BusinessException(404, "订单不存在");
+    }
+    return order;
+}
+```
+
+## 2. Git工作流
+
+### 2.1 分支管理
+
+```
+main            # 主分支，生产环境代码
+├── develop     # 开发分支
+│   ├── feature/order-management    # 功能分支
+│   ├── feature/payment-integration # 功能分支
+│   └── bugfix/order-calculation    # 修复分支
+└── hotfix/critical-bug             # 紧急修复分支
+```
+
+### 2.2 分支命名规范
+
+- **功能分支**：`feature/功能名称`（如：`feature/order-management`）
+- **修复分支**：`bugfix/问题描述`（如：`bugfix/order-calculation`）
+- **紧急修复**：`hotfix/问题描述`（如：`hotfix/payment-error`）
+- **发布分支**：`release/版本号`（如：`release/v1.0.0`）
+
+### 2.3 提交信息规范
+
+```bash
+# 格式：<type>(<scope>): <subject>
+
+# type类型：
+# feat: 新功能
+# fix: 修复bug
+# docs: 文档更新
+# style: 代码格式调整
+# refactor: 重构
+# perf: 性能优化
+# test: 测试相关
+# chore: 构建/工具相关
+
+# 示例
+git commit -m "feat(order): 添加订单创建功能"
+git commit -m "fix(payment): 修复支付回调处理错误"
+git commit -m "docs(api): 更新API文档"
+git commit -m "refactor(service): 重构订单服务"
+```
+
+### 2.4 工作流程
+
+```bash
+# 1. 从develop创建功能分支
+git checkout develop
+git pull origin develop
+git checkout -b feature/order-management
+
+# 2. 开发并提交
+git add .
+git commit -m "feat(order): 添加订单创建功能"
+
+# 3. 推送到远程
+git push origin feature/order-management
+
+# 4. 创建Pull Request到develop分支
+
+# 5. 代码审查通过后合并
+
+# 6. 删除功能分支
+git branch -d feature/order-management
+git push origin --delete feature/order-management
+```
+
+## 3. 代码审查
+
+### 3.1 审查清单
+
+- [ ] 代码符合命名规范
+- [ ] 代码逻辑清晰，易于理解
+- [ ] 适当的注释和文档
+- [ ] 异常处理完善
+- [ ] 单元测试覆盖
+- [ ] 性能考虑（N+1查询、大数据量处理）
+- [ ] 安全性考虑（SQL注入、XSS、权限校验）
+- [ ] 日志记录完善
+- [ ] 无硬编码配置
+- [ ] 符合SOLID原则
+
+### 3.2 审查重点
+
+```csharp
+// ❌ 不好的实践
+public class OrderService
+{
+    public Order CreateOrder(CreateOrderRequest request)
+    {
+        // 直接在服务层操作DbContext
+        var order = new Order();
+        _dbContext.Orders.Add(order);
+        _dbContext.SaveChanges();
+
+        // 硬编码配置
+        var deliveryFee = 5.0m;
+
+        // 没有异常处理
+        // 没有日志记录
+
+        return order;
+    }
+}
+
+// ✅ 好的实践
+public class OrderService : IOrderService
+{
+    private readonly IOrderRepository _orderRepository;
+    private readonly IUnitOfWork _unitOfWork;
+    private readonly ILogger<OrderService> _logger;
+    private readonly IOptions<OrderSettings> _settings;
+
+    public async Task<OrderDto> CreateOrderAsync(CreateOrderRequest request)
+    {
+        try
+        {
+            // 参数验证
+            if (request == null)
+                throw new ArgumentNullException(nameof(request));
+
+            _logger.LogInformation("创建订单：{@Request}", request);
+
+            // 业务逻辑
+            var order = new Order
+            {
+                // ... 初始化订单
+                DeliveryFee = _settings.Value.DefaultDeliveryFee
+            };
+
+            // 使用仓储
+            await _orderRepository.AddAsync(order);
+            await _unitOfWork.SaveChangesAsync();
+
+            _logger.LogInformation("订单创建成功：{OrderId}", order.Id);
+
+            return _mapper.Map<OrderDto>(order);
+        }
+        catch (Exception ex)
+        {
+            _logger.LogError(ex, "创建订单失败：{@Request}", request);
+            throw;
+        }
+    }
+}
+```
+
+
+
+## 4. 单元测试规范
+
+### 4.1 测试命名
+- 命名格式：`MethodName_Scenario_ExpectedResult`
+- 测试覆盖率要求：核心业务逻辑 >= 80%
+
+### 4.2 测试示例
+
+```csharp
+[Fact]
+public async Task CreateOrder_ValidRequest_ReturnsOrderDto()
+{
+    // Arrange
+    var request = new CreateOrderRequest { /* ... */ };
+
+    // Act
+    var result = await _orderService.CreateOrderAsync(request);
+
+    // Assert
+    result.Should().NotBeNull();
+    result.OrderNo.Should().NotBeNullOrEmpty();
+}
+```
+
+## 5. 性能优化规范
+
+### 5.1 数据库查询优化
+- 避免N+1查询，使用Include预加载
+- 大数据量查询使用Dapper
+- 合理使用索引
+
+### 5.2 缓存策略
+- 商家信息：30分钟
+- 菜品信息：15分钟
+- 配置信息：1小时
+- 用户会话：2小时
+
+## 6. 文档要求
+
+### 6.1 代码文档
+- 所有公共API必须有XML文档注释
+- 复杂业务逻辑添加详细注释
+- README.md说明项目结构和运行方式
+
+### 6.2 变更日志
+维护CHANGELOG.md记录版本变更