LingAdmin/Backend/LingAdmin.API/README.md

# LingAdmin Backend API

基于 .NET 8 和 Dapr 的后台管理系统后端服务。

## 技术栈

- **.NET 8** - Web API框架
- **Dapr** - 分布式应用运行时
- **Entity Framework Core** - ORM (Code First)
- **SQL Server** - 数据库
- **Swagger** - API文档

## 项目结构

```
LingAdmin.API/
├── Controllers/          # API控制器
│   ├── UsersController.cs
│   ├── RequisitionsController.cs
│   ├── I18nController.cs
│   └── MenusController.cs
├── Models/              # 数据模型
│   ├── User.cs
│   ├── Requisition.cs
│   ├── Language.cs
│   └── MenuItem.cs
├── Data/                # 数据库上下文
│   └── AppDbContext.cs
├── DTOs/                # 数据传输对象
│   ├── ApiResponse.cs
│   └── RequisitionDto.cs
├── dapr/                # Dapr配置
│   ├── components/
│   │   ├── statestore.yaml
│   │   └── pubsub.yaml
│   └── dapr.yaml
└── Properties/
    └── launchSettings.json
```

## API端点

### 用户管理
- `GET /api/users` - 获取用户列表
- `GET /api/users/{id}` - 获取单个用户
- `POST /api/users` - 创建用户
- `PUT /api/users/{id}` - 更新用户
- `DELETE /api/users/{id}` - 删除用户

### 请购单管理
- `GET /api/requisitions` - 获取请购单列表
- `GET /api/requisitions/{id}` - 获取单个请购单
- `POST /api/requisitions` - 创建请购单
- `PUT /api/requisitions/{id}` - 更新请购单
- `DELETE /api/requisitions/{id}` - 删除请购单

### 国际化
- `GET /api/i18n/manifest` - 获取语言清单
- `GET /api/i18n/lang/{languageCode}` - 获取指定语言的翻译

### 菜单
- `GET /api/menus` - 获取菜单列表

## 前置要求

- [.NET 8 SDK](https://dotnet.microsoft.com/download/dotnet/8.0)
- [Dapr CLI](https://docs.dapr.io/getting-started/install-dapr-cli/)
- [SQL Server](https://www.microsoft.com/sql-server) 或 SQL Server Express
- [Docker Desktop](https://www.docker.com/products/docker-desktop) (用于运行Redis)

## 安装步骤

### 1. 安装 Dapr

```powershell
# 安装 Dapr CLI
powershell -Command "iwr -useb https://raw.githubusercontent.com/dapr/cli/master/install/install.ps1 | iex"

# 初始化 Dapr
dapr init
```

### 2. 启动 Redis (用于 Dapr 状态存储和发布订阅)

```powershell
docker run -d --name redis -p 6379:6379 redis:latest
```

### 3. 配置数据库连接

修改 `appsettings.json` 中的数据库连接字符串:

```json
{
  "ConnectionStrings": {
    "DefaultConnection": "Server=localhost;Database=LingAdminDB;Trusted_Connection=True;TrustServerCertificate=True;"
  }
}
```

### 4. 创建数据库迁移

```powershell
cd LingAdmin.API
dotnet ef migrations add InitialCreate
dotnet ef database update
```

注: 如果 `dotnet ef` 命令不可用,请先安装:
```powershell
dotnet tool install --global dotnet-ef
```

## 运行应用

### 方式1: 使用 Dapr CLI

```powershell
cd LingAdmin.API
dapr run --app-id lingadmin-api --app-port 5000 --dapr-http-port 3500 --resources-path ./dapr/components -- dotnet run
```

### 方式2: 使用 Visual Studio

选择 "dapr" 启动配置文件并按 F5

### 方式3: 不使用 Dapr (仅用于测试)

```powershell
cd LingAdmin.API
dotnet run
```

应用将在 http://localhost:5000 启动。

## 访问 Swagger UI

启动应用后,访问: http://localhost:5000/swagger

## Dapr 功能

### 状态管理

使用 Redis 作为状态存储,可通过 Dapr SDK 进行访问。

### 发布/订阅

当创建新的请购单时,系统会发布 `requisition-created` 事件到 `pubsub` 组件。

### Dapr Dashboard

```powershell
dapr dashboard
```

访问 http://localhost:8080 查看 Dapr 仪表板。

## 数据库迁移

### 添加新迁移

```powershell
dotnet ef migrations add <MigrationName>
```

### 更新数据库

```powershell
dotnet ef database update
```

### 回滚迁移

```powershell
dotnet ef database update <PreviousMigrationName>
```

## 开发建议

1. **CORS配置**: 当前配置允许所有来源,生产环境请修改为特定域名
2. **身份验证**: 建议添加 JWT 或其他身份验证机制
3. **日志**: 已集成基本日志,可考虑添加 Application Insights
4. **错误处理**: 已实现基本错误处理,可根据需要扩展

## 环境变量

可以通过环境变量覆盖配置:

```powershell
$env:ASPNETCORE_ENVIRONMENT="Production"
$env:ConnectionStrings__DefaultConnection="<your-connection-string>"
```

## 故障排查

### 数据库连接失败

检查 SQL Server 是否运行,连接字符串是否正确。

### Dapr 启动失败

确保 Docker Desktop 正在运行,Redis 容器已启动。

### 端口冲突

修改 `launchSettings.json` 中的端口配置。

## 许可证

MIT