# Sharp.Data

让 EF Core 使用更简单的数据访问模块，提供开箱即用的仓储模式、审计、软删除等基础设施。

> **设计理念**：Data 模块专注于数据访问基础设施，不包含业务逻辑。实体基类是**可选的**，你可以使用自己的实体定义。

## 特性

- ✅ **极简 API** - 3 行代码启动，类似 NetServer 的设计理念
- ✅ **泛型仓储** - 提供常用 CRUD 操作，无需重复编写
- ✅ **自动审计** - 可选的审计功能，自动记录创建/修改信息
- ✅ **软删除** - 可选的软删除支持，逻辑删除而非物理删除
- ✅ **分页查询** - 复用 Common 模块的分页功能
- ✅ **多数据库** - 支持 SQLite、SQL Server、MySQL、PostgreSQL、InMemory
- ✅ **低耦合** - 仅依赖 EF Core 和 Common 模块
- ✅ **灵活扩展** - 所有功能都是可选的，按需启用

## 快速开始

### 1. 定义实体（可选使用基类）

```csharp
using Sharp.Data.Entities;

// 方式1：使用提供的基类（可选）
public class User : AuditableEntity  // 包含审计和软删除
{
    public string Name { get; set; } = string.Empty;
    public string Email { get; set; } = string.Empty;
}

// 方式2：完全自定义（不使用基类）
public class Product
{
    public Guid Id { get; set; }
    public string Name { get; set; } = string.Empty;
    public decimal Price { get; set; }
}
```

### 2. 定义 DbContext

```csharp
using Microsoft.EntityFrameworkCore;

public class AppDbContext : DbContext
{
    public AppDbContext(DbContextOptions<AppDbContext> options) : base(options) { }

    public DbSet<User> Users => Set<User>();
    public DbSet<Product> Products => Set<Product>();
}
```

### 3. 启动和使用（3 行代码）

```csharp
using Sharp.Data;

// 创建构建器并配置
var builder = new DataContextBuilder<AppDbContext>();
builder.UseSqlite("Data Source=app.db");
var db = builder.Build();

// 使用仓储
var userRepo = db.Repository<User>();

// 添加数据
await userRepo.AddAsync(new User
{
    Name = "张三",
    Email = "zhangsan@example.com"
});
await db.SaveChangesAsync(); // 如果使用 AuditableEntity，会自动记录 CreatedAt

// 查询数据
var users = await userRepo.GetAllAsync();
var user = await userRepo.FirstOrDefaultAsync(u => u.Email == "zhangsan@example.com");

// 分页查询（使用 Common 模块的 PagedResult）
var pagedUsers = await userRepo.GetPagedAsync(
    page: 1,
    pageSize: 20,
    predicate: u => u.Name.Contains("张"),
    orderBy: q => q.OrderByDescending(u => u.Id));

Console.WriteLine($"Total: {pagedUsers.TotalCount}, Pages: {pagedUsers.TotalPages}");
```

## 模块依赖

```
Sharp.Data
├── EF Core 8.0 (数据库访问)
└── Sharp.Common (复用基础功能)
    ├── PagedResult<T> (分页结果)
    ├── Result<T> (错误处理，可选)
    └── 各种扩展方法
```

## 配置选项

### 使用不同数据库

```csharp
var builder = new DataContextBuilder<AppDbContext>();

// SQLite
builder.UseSqlite("Data Source=app.db");

// SQL Server
builder.UseSqlServer("Server=.;Database=MyApp;Trusted_Connection=True;");

// MySQL
builder.UseMySql("server=localhost;database=myapp;user=root;password=123456", "8.0.35");

// PostgreSQL
builder.UseNpgsql("Host=localhost;Database=myapp;Username=postgres;Password=123456");

// 内存数据库（用于测试）
builder.UseInMemoryDatabase("TestDb");
```

### 配置功能（所有功能都是可选的）

```csharp
var builder = new DataContextBuilder<AppDbContext>();

builder.UseSqlite("Data Source=app.db")
    .UseAudit(true)              // 启用审计（仅对实现 IAuditableEntity 的实体生效）
    .UseSoftDelete(true)         // 启用软删除（仅对实现 ISoftDeletable 的实体生效）
    .UseAutoMigration(true)      // 启动时自动迁移
    .UseCurrentUser("user123")   // 设置当前用户（用于审计）
    .EnableDetailedErrors()      // 启用详细错误信息
    .EnableSensitiveDataLogging(); // 启用敏感数据日志（仅开发）

var db = builder.Build();
```

### 动态获取当前用户

```csharp
builder.UseCurrentUserProvider(() =>
{
    // 从你的认证系统获取当前用户
    return HttpContext.Current?.User?.Identity?.Name ?? "system";
});
```

## 实体基类（可选）

Data 模块提供了可选的实体基类，你**不是必须**使用它们：

### Entity<TKey> - 基础实体（可选）

```csharp
// Guid 主键（最常用）
public class Product : Entity { }

// Int 主键
public class Category : EntityInt { }

// Long 主键
public class Log : EntityLong { }

// 自定义主键类型
public class CustomEntity : Entity<string> { }

// 或者完全自定义
public class MyEntity
{
    public int Id { get; set; }
    public string Name { get; set; }
}
```

### AuditableEntity<TKey> - 审计实体（可选）

如果继承此基类，会自动管理以下字段：

- `Id` - 主键
- `CreatedAt` - 创建时间
- `CreatedBy` - 创建人
- `UpdatedAt` - 更新时间
- `UpdatedBy` - 更新人
- `IsDeleted` - 是否删除
- `DeletedAt` - 删除时间
- `DeletedBy` - 删除人

```csharp
// 使用审计基类
public class User : AuditableEntity
{
    public string Name { get; set; }
    public string Email { get; set; }
}

// 或者自己实现审计接口
public class MyEntity : IAuditableEntity, ISoftDeletable
{
    public Guid Id { get; set; }
    public DateTime CreatedAt { get; set; }
    public string? CreatedBy { get; set; }
    // ... 实现其他接口属性
}

// 或者完全自定义（不使用审计）
public class SimpleEntity
{
    public Guid Id { get; set; }
    public string Name { get; set; }
}
```

## 仓储方法

### 查询方法

```csharp
var repo = db.Repository<User>();

// 获取可查询对象
var query = repo.Query(trackChanges: false);
var activeUsers = await query.Where(u => u.Name.Contains("张")).ToListAsync();

// 根据主键获取
var user = await repo.GetByIdAsync(userId);

// 获取第一个符合条件的
var user = await repo.FirstOrDefaultAsync(u => u.Email == "test@example.com");

// 获取所有
var allUsers = await repo.GetAllAsync();

// 查找符合条件的
var users = await repo.FindAsync(u => u.Name.Contains("张"));

// 分页查询（返回 Common.ExpandFun.PagedResult<T>）
var pagedResult = await repo.GetPagedAsync(1, 20);
Console.WriteLine($"Total: {pagedResult.TotalCount}, Pages: {pagedResult.TotalPages}");

// 统计
var count = await repo.CountAsync(u => u.Name.Contains("张"));
var exists = await repo.AnyAsync(u => u.Email == "test@example.com");
```

### 修改方法

```csharp
// 添加
var user = new User { Name = "张三", Email = "zhang@example.com" };
await repo.AddAsync(user);
await db.SaveChangesAsync();

// 批量添加
var users = new List<User> { user1, user2, user3 };
await repo.AddRangeAsync(users);
await db.SaveChangesAsync();

// 更新
user.Name = "李四";
repo.Update(user);
await db.SaveChangesAsync();

// 删除（如果实体实现 ISoftDeletable，会软删除）
await repo.RemoveAsync(userId);
await db.SaveChangesAsync();

// 物理删除（对于未实现 ISoftDeletable 的实体）
repo.Remove(user);
await db.SaveChangesAsync();
```

## 查询扩展（复用 Common 模块）

```csharp
using Sharp.Data.Extensions;
using Common.ExpandFun; // PagedResult

// 分页扩展
var query = db.Context.Set<User>().Where(u => u.Name.Contains("张"));
var pagedResult = await query.ToPagedResultAsync(page: 1, pageSize: 20);

// 条件查询（来自 Common 模块的扩展）
var query = db.Context.Set<User>()
    .WhereIf(!string.IsNullOrEmpty(searchTerm), u => u.Name.Contains(searchTerm));

// 动态排序
var query = db.Context.Set<User>()
    .OrderByProperty("CreatedAt", descending: true);
```

## 最佳实践

### 1. 控制台应用

```csharp
using Sharp.Data;

var builder = new DataContextBuilder<AppDbContext>();
builder.UseSqlite("Data Source=app.db");
using var db = builder.Build();

// 使用 db 进行数据操作
var repo = db.Repository<User>();
await repo.AddAsync(new User { Name = "Test" });
await db.SaveChangesAsync();

// 自动释放资源
```

### 2. WPF 应用

```csharp
// App.xaml.cs
public partial class App : Application
{
    public static IDataContext Database { get; private set; } = null!;

    protected override void OnStartup(StartupEventArgs e)
    {
        base.OnStartup(e);

        var builder = new DataContextBuilder<AppDbContext>();
        builder.UseSqlite("Data Source=app.db")
            .UseCurrentUserProvider(() => GetCurrentUser());

        Database = builder.Build();
    }

    protected override void OnExit(ExitEventArgs e)
    {
        Database?.Dispose();
        base.OnExit(e);
    }
}
```

### 3. ASP.NET Core 应用

```csharp
// Program.cs
builder.Services.AddScoped<IDataContext>(sp =>
{
    var dataBuilder = new DataContextBuilder<AppDbContext>();

    dataBuilder.UseSqlServer(builder.Configuration.GetConnectionString("Default"))
        .UseCurrentUserProvider(() =>
        {
            var httpContext = sp.GetService<IHttpContextAccessor>()?.HttpContext;
            return httpContext?.User?.Identity?.Name ?? "anonymous";
        });

    return dataBuilder.Build();
});

builder.Services.AddHttpContextAccessor();
```

## 与其他 Sharp 模块集成

### 与 Sharp.Common 集成（已内置）

Data 模块已经引用了 Common 模块，可以直接使用：

- `PagedResult<T>` - 分页结果
- `Result<T>` - 错误处理（可选）
- 各种扩展方法

### 与 Sharp.Log 集成

```csharp
using Sharp.Log;

var loggerFactory = SharpLogDefaults.CreateLoggerFactory();

builder.ConfigureDbContext(options =>
{
    options.UseLoggerFactory(loggerFactory);
});
```

## 高级功能

### 访问底层 DbContext

```csharp
var db = builder.Build();

// 执行原生 SQL
await db.Context.Database.ExecuteSqlRawAsync(
    "DELETE FROM Logs WHERE CreatedAt < @p0",
    DateTime.Now.AddDays(-30));

// 开始事务
using var transaction = await db.Context.Database.BeginTransactionAsync();
try
{
    await db.SaveChangesAsync();
    await transaction.CommitAsync();
}
catch
{
    await transaction.RollbackAsync();
    throw;
}
```

## 常见问题

### Q: 我必须使用 Entity/AuditableEntity 基类吗？

**不是！** 基类是**完全可选**的。你可以：

- 使用自己的实体定义
- 实现 `IAuditableEntity` 或 `ISoftDeletable` 接口
- 完全不使用审计和软删除功能

### Q: 如何使用自定义实体？

```csharp
// 完全自定义，不使用任何基类
public class MyEntity
{
    public int Id { get; set; }
    public string Name { get; set; }
    public DateTime CreatedAt { get; set; }
}

// 正常使用仓储
var repo = db.Repository<MyEntity>();
await repo.AddAsync(new MyEntity { Name = "Test" });
```

### Q: PagedResult 在哪里定义的？

`PagedResult<T>` 来自 `Sharp.Common` 模块（`Common.ExpandFun` 命名空间），Data 模块复用它以避免重复。

### Q: 如何禁用审计或软删除？

```csharp
builder.UseAudit(false)       // 禁用审计
       .UseSoftDelete(false);  // 禁用软删除
```

## 性能建议

1. 查询时使用 `Query(trackChanges: false)` 提升性能
2. 批量操作使用 `AddRangeAsync`/`UpdateRange`
3. 生产环境关闭 `EnableSensitiveDataLogging`
4. 使用分页查询避免一次加载大量数据

## 许可证

MIT License