Project.Fengling.QoderVersion/后端功能概览.md at e24925e1edba1ffee7f275c25d8bc1ca52c81562

Demo/Project.Fengling.QoderVersion

sam e24925e1ed chore(build): 添加基础构建配置和版本管理

- 新增 .dockerignore 文件，忽略多种临时及中间文件
- 新增 .gitattributes 文件，配置文本文件换行及合并行为
- 新增详细的 .gitignore 文件，排除多种开发及生成文件
- 新增 VS Code C# 代码片段，提升开发效率
- 添加 Directory.Build.props，统一 MSBuild 配置和代码分析规则
- 添加空的 Directory.Build.targets，预留构建任务扩展位置
- 添加 Directory.Packages.props，实现依赖包版本集中管理和声明

2026-02-11 12:58:54 +08:00

7.8 KiB

Raw Blame History

后端功能概览

本文档简要说明当前后端(Backend)已完成的主要功能与技术实现，便于后续开发和前后端联调。

一、整体技术栈与架构

技术栈
- .NET 10
- EF Core + SQLite
- CAP + NetCorePal 集成事件
- FastEndpoints 用于 API 端点
架构风格
- CleanDDD 分层结构：Domain / Infrastructure / Web
- 聚合根统一继承 Entity<TId>, IAggregateRoot
- 使用强类型 ID(xxxId : IGuidStronglyTypedId)
- 领域事件 + 集成事件解耦跨聚合、跨事务操作
- 命令(Command)与查询(Query)各自独立，命令处理器只操作仓储，不显式保存事务

二、已完成的核心聚合与领域模型

会员聚合(MemberAggregate)
- 会员注册、登录
- 基本信息：手机号、密码(加密后存储)、昵称
- 会员等级值对象(Level)：等级编码、名称、所需积分、积分倍率
- 积分账户：累计积分、可用积分
营销码聚合(MarketingCodeAggregate)
- 一物一码：唯一营销码与产品信息绑定
- 状态管理：未使用/已使用
- 使用营销码会发布 MarketingCodeUsedDomainEvent
积分规则聚合(PointsRuleAggregate)
- 支持按产品 / 类目 / 会员等级 / 时间区间配置规则
- 可以计算应得积分(当前实现为“取匹配规则中的最高值”)
积分交易聚合(PointsTransactionAggregate)
- 已从会员聚合中拆分为独立聚合
- 支持四类交易：获取(Earn)、消费(Consume)、退还(Refund)、过期(Expire)
- 通过集成事件异步创建记录(详见第四节)
礼品聚合(GiftAggregate)
- 礼品基本信息：名称、类型(实物/虚拟/自有产品)、描述、图片
- 业务字段：所需积分、总库存、可用库存、每人限兑数量、是否上架、排序
- 领域行为：
  - Update(...) 更新礼品信息
  - AddStock(...) 增加库存
  - ReserveStock(...) 下单时预留库存
  - DeductStock(...) 发货时扣减总库存
  - ReleaseStock(...) 订单取消时释放库存
  - PutOnShelf/PutOffShelf 上/下架
兑换订单聚合(RedemptionOrderAggregate)
- 基本字段：订单号、会员ID、礼品ID/名称/类型、数量、消耗积分
- 收货地址值对象(Address) 用于实物礼品
- 状态机：Pending → Dispatched → Delivered → Completed / Cancelled
- 领域行为：MarkAsDispatched、MarkAsDelivered、Complete、Cancel
- 领域事件：
  - RedemptionOrderCreatedDomainEvent(创建订单)
  - RedemptionOrderDispatchedDomainEvent(发货)
  - RedemptionOrderCancelledDomainEvent(取消)
  - 其他状态事件(已送达、完成)

三、会员与积分业务流程

会员注册 / 登录
- 命令：
  - RegisterMemberCommand：校验手机号唯一性，保存会员
  - LoginMemberCommand：验证手机号+密码
- 端点(示例)：
  - POST /api/members/register
  - POST /api/members/login
扫码使用营销码 → 发放积分
- 命令：UseMarketingCodeCommand
  - 校验营销码是否存在、是否可用
  - 关联会员后标记营销码为已使用
  - 更新由 IMarketingCodeRepository 完成
- 领域事件：MarketingCodeUsedDomainEvent
- 领域事件处理器：MarketingCodeUsedDomainEventHandlerForEarnPoints
  - 加载会员
  - 通过 IPointsRuleRepository.GetEffectiveRulesAsync 匹配积分规则
  - 计算应得积分 + 过期时间
  - 调用 Member.AddPoints(...)
  - 更新会员(不会在此处创建积分交易记录)

四、积分交易与集成事件流程

领域事件 → 集成事件
- 会员增加积分时发布 PointsAddedDomainEvent
- Web 层有对应的集成事件转换器(IIntegrationEventConverter)：
  - PointsAddedToPointsEarnedConverter 等
- 集成事件定义(实现 IIntegrationEvent):
  - PointsEarnedIntegrationEvent
  - PointsConsumedIntegrationEvent
  - PointsRefundedIntegrationEvent
  - PointsExpiredIntegrationEvent
- 集成事件只携带 ID 和必要基础字段(MemberId, Amount, RelatedId, ExpiryDate 等), 不包含聚合对象。
集成事件处理器(IIntegrationEventHandler)
- 在 Web 层实现, 通过 ApplicationDbContext 读写积分交易表:
  - 收到 Earn/Consume/Refund/Expire 事件
  - 基于 RelatedId 或批次ID 做幂等性检查
  - 调用 PointsTransaction.CreateXxxTransaction(...) 创建交易聚合
  - 保存到 PointsTransactions 表
事务与一致性
- 积分变更(会员聚合) 与积分交易记录(PointsTransaction 聚合) 处于不同事务
- 通过领域事件 → 集成事件 → 处理器链路实现最终一致性

五、礼品与积分商城功能

礼品管理(管理端)
- 命令(Commands)：
  - CreateGiftCommand：创建礼品
  - UpdateGiftCommand：更新礼品信息
  - PutOnShelfCommand / PutOffShelfCommand：上/下架
  - AddGiftStockCommand：增加库存
- 查询(Queries)：
  - GetGiftsQuery：按类型/是否上架筛选列表
  - GetGiftByIdQuery：礼品详情
- 仓储：IGiftRepository + GiftRepository
- 端点(Endpoints)：
  - POST /api/admin/gifts
  - PUT /api/admin/gifts/{GiftId}
  - POST /api/admin/gifts/{GiftId}/putonshelf
  - POST /api/admin/gifts/{GiftId}/putoffshelf
  - POST /api/admin/gifts/{GiftId}/addstock
  - GET /api/admin/gifts
  - GET /api/admin/gifts/{GiftId}
会员端积分商城
- 礼品浏览与详情：
  - GET /api/gifts：仅返回已上架礼品
  - GET /api/gifts/{GiftId}：礼品详情
- 兑换礼品(创建兑换订单):
  - 命令：CreateRedemptionOrderCommand
    - 校验礼品存在且已上架
    - 校验库存及每人限兑数量(通过 IRedemptionOrderRepository.GetMemberRedemptionCountAsync)
    - 校验会员可用积分是否足够
    - 调用会员聚合 ConsumePoints 扣减积分并更新会员
    - 构造收货地址(实物礼品必须提供地址)
    - 创建兑换订单聚合 RedemptionOrder
    - 使用仓储 IRedemptionOrderRepository.AddAsync 持久化
  - 端点：POST /api/gifts/redeem
- 会员查询自己的兑换订单：
  - 查询：GetRedemptionOrdersQuery / GetRedemptionOrderByIdQuery
  - 端点：
    - GET /api/redemption-orders/my(按会员+状态过滤)
    - GET /api/redemption-orders/{OrderId}
后台兑换订单管理(管理端)
- 列表/详情：同上查询, 管理端端点前缀 /api/admin/redemption-orders
- 状态流转命令：
  - MarkOrderAsDispatchedCommand：发货
  - CompleteOrderCommand：完成
  - CancelOrderCommand：取消
- 对应端点：
  - POST /api/admin/redemption-orders/{OrderId}/dispatch
  - POST /api/admin/redemption-orders/{OrderId}/complete
  - POST /api/admin/redemption-orders/{OrderId}/cancel
兑换订单相关领域事件处理器
- RedemptionOrderCreatedDomainEventHandler：
  - 加载礼品聚合
  - 调用 Gift.ReserveStock(...) 预留库存
  - 调用仓储 UpdateAsync 持久化
- RedemptionOrderCancelledDomainEventHandler：
  - 释放库存 Gift.ReleaseStock(...)
- RedemptionOrderDispatchedDomainEventHandler：
  - 发货后扣减总库存 Gift.DeductStock(...)

六、当前状态与后续工作建议

当前状态
- 后端项目可以成功编译(dotnet build)；存在若干 Sonar 质量规则警告(主要是 TODO/异常处理提示), 不影响运行
- 会员、营销码、积分规则、积分交易、礼品、兑换订单等核心领域模型和主要业务流程已经打通
后续可选工作
- 增加更多查询(如礼品统计、积分流水查询分页等)
- 完善认证鉴权(从 JWT 中获取当前登录会员ID, 替换临时 MemberId 参数)
- 根据前端实际需要, 补充 DTO 字段或调整 API 结构

7.8 KiB Raw Blame History Unescape Escape

后端功能概览

一、整体技术栈与架构

二、已完成的核心聚合与领域模型

三、会员与积分业务流程

四、积分交易与集成事件流程

五、礼品与积分商城功能

六、当前状态与后续工作建议

7.8 KiB

Raw Blame History