dedsi-framework

范围与目标

本 Skill 用于：

• 快速解释 Dedsi Framework 各类库的职责与核心类型（按模块）。
• 指导在 ABP 项目中如何引用/DependsOn/配置这些模块。
• 给出 CQRS、Repository、异常处理、ORM（EF Core/SqlSugar）、CAP、FastEndpoints 的典型用法与落地检查清单。

不在范围内：

• 推断/编造 Dedsi Framework 未在文档中描述的 API 行为与参数。
• 输出与现有项目约定冲突的强绑定代码（若仓库已有实现，以仓库为准）。

信息来源：工作区根目录 DedsiFramework.md。

快速目录

• 模块速查
• ABP 接入清单
• 常用使用场景
• 排错与对齐

模块速查

下列内容是对文档中各类库与类型的“可检索速记”。当你需要定位“这个类型属于哪个库/应该在哪里用”时，优先从这里开始。

1) Dedsi.AspNetCore

定位：ASP.NET Core 扩展与中间件，增强 Web API 基础能力。

核心类型

• DedsiAspNetCoreModule：模块定义文件，配置依赖。
• DedsiControllerBase：控制器基类（继承 AbpControllerBase）。
  • 提供 FileByExcel、FileByPdf 便捷导出。
• Middlewares/DedsiGlobalExceptionHandler：全局异常处理中间件。
  • 可选：当你需要将错误响应统一为 DedsiErrorData（非 ABP 默认格式）时启用。
  • 捕获异常并统一返回 DedsiErrorData JSON。
  • 自动处理 UserFriendlyException、BusinessException 并提取错误码。
• DedsiErrorData：可选的错误响应结构封装（用于替代/兼容 ABP 默认错误响应）。
• DedsiErrorMessage：错误信息模型（Message、Code、ServiceTime）。

2) Dedsi.Ddd.Domain

定位：领域层基础扩展；增强审计、仓储、查询标记接口。

核心类型

• DedsiDddDomainModule：模块定义。
• DedsiDddDomainConsts：领域常量（例如默认 DB Schema）。
• 审计接口（扩展创建审计，含创建人姓名）
  • Auditing/Contracts/IDedsiCreationAuditedObject
  • Auditing/Contracts/IDedsiMayHaveCreator
  • Auditing/Contracts/IHasCreationName
• 查询标记
  • Queries/IDedsiQuery：标记接口，继承 ITransientDependency。
• 仓储接口
  • Repositories/IDedsiCqrsRepository：面向 CQRS 的仓储接口（Insert/Update/Delete 等）。
  • Repositories/IDedsiRepository：增强通用仓储接口。
    • GetQueryableNoTrackingAsync（无追踪查询）
    • GetPagedListAsync（分页查询）
    • DeleteManyAsync（批量删除）
    • ExecuteSqlAsync（执行原生 SQL）

3) Dedsi.Ddd.Domain.Shared

定位：领域共享项目（枚举、常量、共享对象）。

核心类型

• DedsiDddDomainSharedModule

4) Dedsi.Ddd.Application.Contracts

定位：应用服务契约层（DTO 与服务接口）。

核心类型

• DedsiDddApplicationContractsModule
• DTO
  • Dtos/DedsiPagedRequestDto：分页请求基类（PageIndex、PageSize、IsExport）。
  • Dtos/DedsiPagedResultDto：分页结果基类。
• Services/IDedsiApplicationService：应用服务基类接口。

5) Dedsi.Ddd.Application

定位：应用服务层基础实现。

核心类型

• DedsiDddApplicationModule
• Services/DedsiApplicationService：继承 ABP ApplicationService 并实现 IDedsiApplicationService。

6) Dedsi.Ddd.CQRS

定位：CQRS 核心库；集成 MediatR；提供命令/事件记录能力。

核心类型

• DedsiDddCqrsModule
• DedsiDddCqrsConsts

命令/事件记录（Recorders）

• CommandEventRecorder：记录实体。
• CqrsCeRecorder：记录服务实现（调用 Repository 保存）。
• ICqrsCeRecorder：记录服务接口。
• ICommandEventRecorderRepository：记录仓储接口。
• LocalCommandEventRecorderRepository：本地记录仓储实现（开发/日志）。

命令处理（Handlers）

• DedsiCommandHandler：命令处理器基类（注入 Logger、CurrentUser 等常用服务）。
• IDedsiCommandHandler

命令（Commands）

• DedsiCommand：命令基类（含 CommandId）。
• DedsiCommandId：命令 ID 值对象。
• IDedsiCommand

事件总线（EventBus）

• DedsiEvent、DedsiEventId、IDedsiEvent
• DedsiLocalEventBus：自定义本地事件总线；重写 PublishAsync 以自动记录事件日志。

中介者（Mediators）

• DedsiMediator：封装 MediatR；发送命令前后自动记录日志。
• IDedsiMediator

7) Dedsi.EntityFrameworkCore

定位：EF Core 集成；实现 Dedsi.Ddd.Domain 的仓储接口；并提供 Dapper 集成。

核心类型

• DedsiEntityFrameworkCoreModule
• DbContext
  • EntityFrameworkCore/DedsiEfCoreDbContext
  • EntityFrameworkCore/IDedsiEfCoreDbContext
• PropertySetters/DedsiAuditPropertySetter：自动填充 CreatorName。
• 查询基类
  • Queries/DedsiDapperQuery
  • Queries/DedsiEfCoreQuery：提供 GetNoTrackingQueryableAsync。
• 仓储实现
  • Repositories/DedsiDddEfCoreRepository：IDedsiCqrsRepository 的 EF Core 实现。
  • Repositories/DedsiEfCoreRepository：IDedsiRepository 的 EF Core 实现（分页、批量删除等）。

8) Dedsi.SqlSugar

定位：SqlSugar ORM 集成；提供另一种数据访问方式。

核心类型

• DedsiSqlSugarModule
• Extensions/DedsiSqlSugarExtensions：在模块配置中注册 SqlSugar（SqlServer、MySql）。
• Queries/DedsiSqlSugarQuery：基于 SqlSugar 的查询基类，实现 IDedsiQuery。

9) Dedsi.Core

定位：核心模块（最基础定义）。

• DedsiCoreModule

10) Dedsi.CAP

定位：集成 DotNetCore.CAP，处理分布式事务与消息队列。

• DedsiCapModule

11) Dedsi.FastEndpoints

定位：集成 FastEndpoints，提供轻量级 API 端点开发方式。

• DedsiFastEndpointsModule

12) Dedsi.CleanArchitecture.*（Domain/HttpApi/Infrastructure）

定位：更像是整洁架构（Clean Architecture）模板/示例结构，不一定属于框架“核心能力”。

核心类型

• Dedsi.CleanArchitecture.Domain
  • DedsiCleanArchitectureDomainModule
  • DedsiCleanArchitectureDomainConsts
• Dedsi.CleanArchitecture.HttpApi
  • DedsiCleanArchitectureHttpApiModule
• Dedsi.CleanArchitecture.Infrastructure
  • DedsiCleanArchitectureInfrastructureModule

ABP 接入清单

目标：把 Dedsi Framework 当作 ABP 模块集合接入。不同项目的模块装配点可能在 Host / HttpApi / Application 等层；以你的解决方案分层为准。

1) 选择你需要的模块

• Web API（异常处理/导出）→ Dedsi.AspNetCore
• DDD 基础（审计接口/仓储接口/查询标记）→ Dedsi.Ddd.Domain + Dedsi.Ddd.Domain.Shared
• 应用服务 → Dedsi.Ddd.Application.Contracts + Dedsi.Ddd.Application
• CQRS（MediatR + 记录）→ Dedsi.Ddd.CQRS
• EF Core 仓储实现 + Dapper Query → Dedsi.EntityFrameworkCore
• SqlSugar Query → Dedsi.SqlSugar
• 分布式事务/消息 → Dedsi.CAP
• FastEndpoints → Dedsi.FastEndpoints

2) 在 ABP Module 上声明 DependsOn（模板）

具体模块类名来自文档；实际命名空间/包引用以你的项目引用为准。

using Volo.Abp.Modularity;

[DependsOn(
    typeof(DedsiAspNetCoreModule),
    typeof(DedsiDddDomainModule),
    typeof(DedsiDddDomainSharedModule),
    typeof(DedsiDddApplicationContractsModule),
    typeof(DedsiDddApplicationModule),
    typeof(DedsiDddCqrsModule),
    typeof(DedsiEntityFrameworkCoreModule)
)]
public class YourProjectModule : AbpModule;

// 如果需要可编译示例，使用：
// public class YourProjectModule : AbpModule
// {
// }

3) 异常/错误响应策略（推荐）

• 优先使用 ABP 默认异常处理与错误响应（项目的既有格式为准）。
• 可选：如果前端/调用方必须使用 DedsiErrorData 作为统一错误契约，再启用 DedsiGlobalExceptionHandler。
• 注意：DedsiGlobalExceptionHandler 属于“替换/包裹默认输出”的中间件，注册顺序可能改变最终返回格式；若项目已有 ABP 统一错误返回约定，优先保持一致。

4) 审计（CreatorName）启用检查（EF Core）

• 若你使用 EF Core 集成：确认 DedsiAuditPropertySetter 生效。
• 期望行为：实体实现/包含 CreatorName 时，在创建时自动填充。

常用使用场景

场景 A：统一 API 错误返回（优先 ABP）

目标：错误响应格式与项目 ABP 约定保持一致；仅在需要时切换到 DedsiErrorData。

落地策略（二选一）：

• 推荐：ABP 默认错误响应
  • 保持 ABP 的异常处理与错误返回，不额外接管格式。
  • 业务层使用 BusinessException / UserFriendlyException 表达可预期错误（并携带错误码/消息）。
• 可选：DedsiErrorData 错误响应
  • 仅当调用方明确要求 DedsiErrorData 契约时，在 Host 管线启用 DedsiGlobalExceptionHandler。
  • 启用后预期：异常统一返回 DedsiErrorData JSON（Message/Code/ServiceTime）。

场景 B：Controller 导出文件

目标：快速导出 Excel/PDF。

落地步骤：

• Controller 继承 DedsiControllerBase。
• 调用 FileByExcel / FileByPdf（参数与具体生成逻辑以框架实现为准）。

场景 C：CQRS + 自动记录（命令/事件）

目标：命令与事件在发送/发布时自动记录。

要点：

• 发命令：优先使用 DedsiMediator（而非直接使用 MediatR 的默认接口），以便“发送前后自动记录”。
• 发事件：使用 DedsiLocalEventBus 发布事件，以便 PublishAsync 自动记录事件日志。
• 记录落地：通过 ICqrsCeRecorder + ICommandEventRecorderRepository（可选本地实现 LocalCommandEventRecorderRepository）。

场景 D：Repository/Query 的统一抽象

目标：读写分离与通用数据访问能力统一。

策略建议：

• 写侧（命令）使用 IDedsiCqrsRepository / 其 EF Core 实现 DedsiDddEfCoreRepository。
• 读侧（查询）使用 IDedsiQuery 标记，并选择：
  • EF Core：继承/使用 DedsiEfCoreQuery 获取无追踪 IQueryable（GetNoTrackingQueryableAsync）。
  • Dapper：使用 DedsiDapperQuery。
  • SqlSugar：使用 DedsiSqlSugarQuery。

场景 E：分页/批量操作/原生 SQL

目标：在通用仓储上统一分页、批量删除、执行 SQL。

要点：

• 使用 IDedsiRepository（或其实现 DedsiEfCoreRepository）提供：
  • GetPagedListAsync
  • DeleteManyAsync
  • ExecuteSqlAsync

排错与对齐

1) “不知道该引用哪个库”

• 先查“模块速查”定位类型所在模块。
• 再检查你的项目是否引用了对应 NuGet 包/项目引用，以及 ABP DependsOn 是否添加。

2) “异常没有变成 DedsiErrorData”

先确认你到底期望哪一种格式：

• 若期望 ABP 默认错误响应：不要启用（或移除）DedsiGlobalExceptionHandler；并检查是否有自定义中间件/过滤器接管了异常输出。
• 若期望 DedsiErrorData：检查 DedsiGlobalExceptionHandler 是否注册、顺序是否在路由/终结点之前；并检查业务层是否抛出了 BusinessException / UserFriendlyException（便于错误码提取）。

3) “CreatorName 没有自动填充”

• 仅在 EF Core 集成链路下，检查 DedsiAuditPropertySetter 是否启用。
• 检查实体是否实现了文档提到的创建审计相关接口或包含 CreatorName 字段。

4) “CQRS 记录没有落库/没有输出”

• 发命令是否通过 DedsiMediator，发事件是否通过 DedsiLocalEventBus。
• ICqrsCeRecorder 与 ICommandEventRecorderRepository 是否有实现并完成 DI 注册。
• 开发期可先切换到 LocalCommandEventRecorderRepository 验证记录链路（如果项目允许）。

交付物

• 本 Skill 仅用于解释/指导 Dedsi Framework 使用；如需我基于你具体仓库生成/调整实际代码（模块装配、管线注册、CQRS 示例等），请提供对应项目结构或让我检索解决方案目录。