按照软件设计文档开始重构代码01

软件设计文档/原始文档/05-事务与工作单元设计.md

@@ -0,0 +1,201 @@
+# 软件开发文档 - 05. 事务与工作单元设计
+
+本文档详细阐述了为确保数据一致性而引入的**工作单元模式 (Unit of Work)** 的设计与实现。我们将此模式的接口命名为 `IRepositoryManager`，以更直观地反映其职责。
+
+## 1. 设计目标
+
+在复杂的业务操作中（例如，创建一个设备，同时需要创建其关联的变量表和菜单项），必须保证所有数据库操作要么全部成功，要么全部失败。这要求一个能够跨越多个仓储（Repository）的事务管理机制。
+
+`IRepositoryManager` 的核心职责就是：
+
+*   **组合操作**：将一系列独立的数据库操作组合成一个单一的、原子的工作单元。
+*   **事务控制**：提供统一的 `Commit` (提交) 和 `Rollback` (回滚) 方法。
+*   **共享上下文**：确保所有通过它访问的仓储共享同一个数据库连接和事务，这是实现原子性的前提。
+
+## 2. `DMS.Core` - 接口定义
+
+我们在核心层定义 `IRepositoryManager` 接口，它作为所有仓储的容器和事务的控制器。
+
+```csharp
+// 文件: DMS.Core/Interfaces/IRepositoryManager.cs
+namespace DMS.Core.Interfaces;
+
+/// <summary>
+/// 定义了一个仓储管理器，它使用工作单元模式来组合多个仓储操作，以确保事务的原子性。
+/// 实现了IDisposable，以确保数据库连接等资源能被正确释放。
+/// </summary>
+public interface IRepositoryManager : IDisposable
+{
+    /// <summary>
+    /// 获取设备仓储的实例。
+    /// 所有通过此管理器获取的仓储都共享同一个数据库上下文和事务。
+    /// </summary>
+    IDeviceRepository Devices { get; }
+
+    /// <summary>
+    /// 获取变量表仓储的实例。
+    /// </summary>
+    IVariableTableRepository VariableTables { get; }
+
+    /// <summary>
+    /// 获取菜单仓储的实例。
+    /// </summary>
+    IMenuRepository Menus { get; }
+
+    // ... 此处可以添加项目中所有其他的仓储
+
+    /// <summary>
+    /// 开始一个新的数据库事务。
+    /// </summary>
+    void BeginTransaction();
+
+    /// <summary>
+    /// 异步提交当前事务中的所有变更。
+    /// </summary>
+    /// <returns>一个表示异步操作的任务。</returns>
+    Task CommitAsync();
+
+    /// <summary>
+    /// 异步回滚当前事务中的所有变更。
+    /// </summary>
+    /// <returns>一个表示异步操作的任务。</returns>
+    Task RollbackAsync();
+}
+```
+
+## 3. `DMS.Infrastructure` - 具体实现
+
+在基础设施层，我们提供 `IRepositoryManager` 的 `SqlSugar` 实现。
+
+```csharp
+// 文件: DMS.Infrastructure/Data/RepositoryManager.cs
+using DMS.Core.Interfaces;
+using SqlSugar;
+
+namespace DMS.Infrastructure.Data;
+
+/// <summary>
+/// 使用 SqlSugar 实现的仓储管理器。
+/// </summary>
+public class RepositoryManager : IRepositoryManager
+{
+    private readonly ISqlSugarClient _db;
+    private readonly Lazy<IDeviceRepository> _lazyDevices;
+    private readonly Lazy<IVariableTableRepository> _lazyVariableTables;
+    private readonly Lazy<IMenuRepository> _lazyMenus;
+
+    public RepositoryManager(ISqlSugarClient db)
+    {
+        _db = db;
+        // 使用 Lazy<T> 实现懒加载，只有在第一次访问时才创建仓储实例
+        // 关键点：将当前的数据库客户端 (_db) 传递给仓储，确保它们共享事务
+        _lazyDevices = new Lazy<IDeviceRepository>(() => new DeviceRepository(_db));
+        _lazyVariableTables = new Lazy<IVariableTableRepository>(() => new VariableTableRepository(_db));
+        _lazyMenus = new Lazy<IMenuRepository>(() => new MenuRepository(_db));
+    }
+
+    public IDeviceRepository Devices => _lazyDevices.Value;
+    public IVariableTableRepository VariableTables => _lazyVariableTables.Value;
+    public IMenuRepository Menus => _lazyMenus.Value;
+
+    public void BeginTransaction()
+    {
+        _db.BeginTran();
+    }
+
+    public async Task CommitAsync()
+    {
+        await _db.CommitTranAsync();
+    }
+
+    public async Task RollbackAsync()
+    {
+        await _db.RollbackTranAsync();
+    }
+
+    public void Dispose()
+    {
+        // 数据库客户端的生命周期由DI容器管理，此处无需手动释放
+        // 但如果事务未提交/回滚，SqlSugar的Dispose会处理它
+        _db.Dispose();
+    }
+}
+```
+
+## 4. `DMS.Application` - 应用服务重构
+
+应用服务现在注入 `IRepositoryManager` 来执行事务性操作。
+
+```csharp
+// 文件: DMS.Application/Services/DeviceAppService.cs
+using DMS.Core.Interfaces;
+
+public class DeviceAppService : IDeviceAppService
+{
+    private readonly IRepositoryManager _repoManager;
+    private readonly IMapper _mapper;
+
+    public DeviceAppService(IRepositoryManager repoManager, IMapper mapper)
+    {
+        _repoManager = repoManager;
+        _mapper = mapper;
+    }
+
+    public async Task<int> CreateDeviceWithDetailsAsync(CreateDeviceWithDetailsDto dto)
+    {
+        // 不再需要 using 语句，因为 DI 容器会管理 RepositoryManager 的生命周期
+        try
+        {
+            _repoManager.BeginTransaction();
+
+            var device = _mapper.Map<Device>(dto.Device);
+            await _repoManager.Devices.AddAsync(device);
+
+            var variableTable = _mapper.Map<VariableTable>(dto.VariableTable);
+            variableTable.DeviceId = device.Id;
+            await _repoManager.VariableTables.AddAsync(variableTable);
+
+            var menu = _mapper.Map<Menu>(dto.Menu);
+            menu.TargetId = device.Id;
+            await _repoManager.Menus.AddAsync(menu);
+
+            await _repoManager.CommitAsync();
+
+            return device.Id;
+        }
+        catch (Exception ex)
+        {
+            await _repoManager.RollbackAsync();
+            // 可以在此记录日志
+            throw new ApplicationException("创建设备时发生错误，操作已回滚。", ex);
+        }
+    }
+}
+```
+
+## 5. 依赖注入配置 (`App.xaml.cs`)
+
+在WPF项目中注册 `IRepositoryManager`。
+
+```csharp
+// 文件: DMS.WPF/App.xaml.cs
+private void ConfigureServices(IServiceCollection services)
+{
+    // ...
+
+    // 注册SqlSugar客户端 (Singleton)
+    services.AddSingleton<ISqlSugarClient>(provider => {
+        // ...数据库连接配置...
+        return new SqlSugarClient(new ConnectionConfig() { ... });
+    });
+
+    // 注册仓储管理器 (Scoped 或 Transient)
+    // 对于WPF，每个业务流程使用一个新的实例是安全的，因此用Transient
+    services.AddTransient<IRepositoryManager, RepositoryManager>();
+
+    // 注册应用服务
+    services.AddTransient<IDeviceAppService, DeviceAppService>();
+
+    // 注意：不再需要单独注册每个仓储
+}
+```