# LingAdmin 分布式微服务架构

基于 Dapr 的后台管理系统分布式服务框架。

## 📋 目录

- [架构概述](#架构概述)
- [服务划分](#服务划分)
- [技术栈](#技术栈)
- [项目结构](#项目结构)
- [快速开始](#快速开始)
- [API 文档](#api-文档)
- [Dapr 集成](#dapr-集成)
- [安全机制](#安全机制)
- [部署指南](#部署指南)

---

## 🏗️ 架构概述

本系统采用微服务架构，使用 Dapr 作为分布式应用运行时，实现服务发现、状态管理、发布订阅等核心功能。

### 架构图

```
                                    ┌─────────────────────────────────────────────────────────┐
                                    │                        Client                            │
                                    │              (Web App / Mobile App)                      │
                                    └─────────────────────────┬───────────────────────────────┘
                                                              │
                                                              ▼
                                    ┌─────────────────────────────────────────────────────────┐
                                    │                    API Gateway                           │
                                    │                   (Port: 5000)                           │
                                    │  ┌─────────────────────────────────────────────────┐    │
                                    │  │ • 请求路由 (YARP)                                │    │
                                    │  │ • JWT 认证                                       │    │
                                    │  │ • 限流保护                                       │    │
                                    │  │ • 请求日志                                       │    │
                                    │  └─────────────────────────────────────────────────┘    │
                                    └─────────────────────────┬───────────────────────────────┘
                                                              │
                          ┌───────────────────────────────────┼───────────────────────────────────┐
                          │                                   │                                   │
                          ▼                                   ▼                                   ▼
        ┌─────────────────────────────┐     ┌─────────────────────────────┐     ┌─────────────────────────────┐
        │    Identity Service         │     │  Authorization Service      │     │    Business Services        │
        │       (Port: 5001)          │     │       (Port: 5002)          │     │      (可扩展...)            │
        │  ┌───────────────────────┐  │     │  ┌───────────────────────┐  │     │  ┌───────────────────────┐  │
        │  │ • 用户注册            │  │     │  │ • 角色管理            │  │     │  │ • 业务逻辑             │  │
        │  │ • 用户登录            │  │     │  │ • 权限管理            │  │     │  │ • ...                  │  │
        │  │ • Token 管理          │  │     │  │ • 用户角色分配        │  │     │  └───────────────────────┘  │
        │  │ • 密码管理            │  │     │  │ • 权限验证            │  │     └─────────────────────────────┘
        │  └───────────────────────┘  │     │  └───────────────────────┘  │
        └──────────────┬──────────────┘     └──────────────┬──────────────┘
                       │                                   │
                       │         ┌─────────────────────────┤
                       │         │                         │
                       ▼         ▼                         ▼
        ┌─────────────────────────────────────────────────────────────────────────────────────────┐
        │                                       Dapr Sidecar                                       │
        │  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐                 │
        │  │ 服务调用      │  │ 状态存储      │  │ 发布订阅      │  │ 配置管理      │                 │
        │  └──────────────┘  └──────────────┘  └──────────────┘  └──────────────┘                 │
        └─────────────────────────────────────────┬───────────────────────────────────────────────┘
                                                  │
                          ┌───────────────────────┼───────────────────────┐
                          │                       │                       │
                          ▼                       ▼                       ▼
                ┌──────────────────┐    ┌──────────────────┐    ┌──────────────────┐
                │     Redis        │    │   SQL Server     │    │    其他存储       │
                │  (State/PubSub)  │    │   (Database)     │    │                  │
                └──────────────────┘    └──────────────────┘    └──────────────────┘
```

---

## 🎯 服务划分

### 1. API Gateway (API 网关)

| 属性 | 说明 |
|------|------|
| **端口** | 5000 |
| **Dapr App ID** | api-gateway |
| **职责** | 请求路由、认证、限流、日志 |

**核心功能：**
- 使用 YARP 进行请求路由
- JWT Token 验证
- 请求限流 (100 次/分钟)
- 请求追踪和日志记录
- 健康检查端点

### 2. Identity Service (身份认证服务)

| 属性 | 说明 |
|------|------|
| **端口** | 5001 |
| **Dapr App ID** | identity-service |
| **数据库** | LingAdmin_Identity |
| **职责** | 用户身份管理 |

**核心功能：**
- 用户注册 (`POST /api/auth/register`)
- 用户登录 (`POST /api/auth/login`)
- Token 刷新 (`POST /api/auth/refresh-token`)
- 用户登出 (`POST /api/auth/logout`)
- 修改密码 (`POST /api/auth/change-password`)
- 用户信息管理

**数据模型：**
```
User
├── Id (int)
├── Name (string)
├── Email (string, unique)
├── PasswordHash (string)
├── Status (string: Active/Inactive/Suspended)
├── CreatedAt (datetime)
├── LastLoginAt (datetime?)
└── UpdatedAt (datetime?)

RefreshToken
├── Id (int)
├── UserId (int, FK)
├── Token (string)
├── ExpiresAt (datetime)
├── CreatedAt (datetime)
├── CreatedByIp (string?)
├── RevokedAt (datetime?)
├── RevokedByIp (string?)
└── ReplacedByToken (string?)
```

### 3. Authorization Service (授权服务)

| 属性 | 说明 |
|------|------|
| **端口** | 5002 |
| **Dapr App ID** | authorization-service |
| **数据库** | LingAdmin_Authorization |
| **职责** | 角色和权限管理 |

**核心功能：**
- 角色 CRUD 操作
- 权限管理
- 用户角色分配
- 权限验证 (供其他服务调用)

**数据模型：**
```
Role                           Permission
├── Id (int)                   ├── Id (int)
├── Name (string)              ├── Name (string)
├── Code (string, unique)      ├── Code (string, unique)
├── Description (string?)      ├── Description (string?)
├── IsSystem (bool)            ├── Resource (string)
├── CreatedAt (datetime)       ├── Action (string)
└── UpdatedAt (datetime?)      └── CreatedAt (datetime)

UserRole                       RolePermission
├── UserId (int, PK)           ├── RoleId (int, PK)
├── RoleId (int, PK, FK)       ├── PermissionId (int, PK, FK)
├── AssignedAt (datetime)      └── AssignedAt (datetime)
└── AssignedBy (int?)
```

**预置权限：**
| 权限代码 | 描述 | 资源 | 操作 |
|----------|------|------|------|
| users:read | 查看用户 | users | read |
| users:create | 创建用户 | users | create |
| users:update | 编辑用户 | users | update |
| users:delete | 删除用户 | users | delete |
| roles:read | 查看角色 | roles | read |
| roles:create | 创建角色 | roles | create |
| roles:update | 编辑角色 | roles | update |
| roles:delete | 删除角色 | roles | delete |
| permissions:read | 查看权限 | permissions | read |
| permissions:assign | 分配权限 | permissions | assign |

**预置角色：**
| 角色代码 | 描述 | 权限 |
|----------|------|------|
| SuperAdmin | 超级管理员 | 所有权限 |
| Admin | 管理员 | 大部分权限（不含删除） |
| User | 普通用户 | 基本读取权限 |
| Editor | 编辑 | 内容编辑相关权限 |
| Auditor | 审核员 | 审核相关权限 |

---

## 🛠️ 技术栈

| 组件 | 技术 | 版本 |
|------|------|------|
| 框架 | .NET | 8.0 |
| 分布式运行时 | Dapr | 1.12.0 |
| API 网关 | YARP | 2.1.0 |
| ORM | Entity Framework Core | 8.0 |
| 数据库 | SQL Server | 2019+ |
| 缓存/消息 | Redis | 7.0+ |
| 认证 | JWT | - |
| 密码加密 | BCrypt | 4.0.3 |
| API 文档 | Swagger/OpenAPI | - |

---

## 📁 项目结构

```
Backend/
└── Services/
    ├── LingAdmin.Microservices.sln    # 解决方案文件
    ├── start-all.ps1                   # 启动所有服务脚本
    ├── stop-all.ps1                    # 停止所有服务脚本
    │
    ├── Shared/
    │   └── LingAdmin.Shared/           # 共享库
    │       ├── Models/                 # 共享数据模型
    │       ├── DTOs/                   # 共享 DTO
    │       └── Events/                 # Dapr 事件定义
    │
    ├── ApiGateway/
    │   └── LingAdmin.ApiGateway/       # API 网关服务
    │       ├── Controllers/            # 控制器 (健康检查等)
    │       ├── Middleware/             # 中间件
    │       └── Properties/             # 启动配置
    │
    ├── IdentityService/
    │   └── LingAdmin.IdentityService/  # 身份认证服务
    │       ├── Controllers/            # 认证相关 API
    │       ├── Data/                   # 数据库上下文
    │       └── Services/               # 业务服务
    │
    ├── AuthorizationService/
    │   └── LingAdmin.AuthorizationService/  # 授权服务
    │       ├── Controllers/            # 角色权限 API
    │       ├── Data/                   # 数据库上下文
    │       └── Services/               # 业务服务
    │
    └── dapr/
        ├── dapr.yaml                   # Dapr 多应用配置
        └── components/
            ├── statestore.yaml         # 状态存储配置
            └── pubsub.yaml             # 发布订阅配置
```

---

## 🚀 快速开始

### 前置要求

1. **.NET 8 SDK**
   ```powershell
   winget install Microsoft.DotNet.SDK.8
   ```

2. **Dapr CLI**
   ```powershell
   powershell -Command "iwr -useb https://raw.githubusercontent.com/dapr/cli/master/install/install.ps1 | iex"
   dapr init
   ```

3. **Docker Desktop** (用于 Redis)
   ```powershell
   winget install Docker.DockerDesktop
   ```

4. **SQL Server**
   ```powershell
   winget install Microsoft.SQLServer.2022.Developer
   ```

### 安装步骤

1. **克隆项目并还原依赖**
   ```powershell
   cd Backend/Services
   dotnet restore LingAdmin.Microservices.sln
   ```

2. **配置数据库连接**
   
   修改各服务的 `appsettings.Development.json`:
   ```json
   {
     "ConnectionStrings": {
       "DefaultConnection": "Server=localhost;Database=<ServiceDB>;Trusted_Connection=True;TrustServerCertificate=True;"
     }
   }
   ```

3. **创建数据库迁移**
   ```powershell
   # Identity Service
   cd IdentityService/LingAdmin.IdentityService
   dotnet ef migrations add InitialCreate
   
   # Authorization Service
   cd ../../AuthorizationService/LingAdmin.AuthorizationService
   dotnet ef migrations add InitialCreate
   ```

4. **启动 Redis**
   ```powershell
   docker run -d --name redis -p 6379:6379 redis:latest
   ```

5. **启动所有服务**
   ```powershell
   cd Backend/Services
   .\start-all.ps1
   ```

   或者使用 Dapr CLI:
   ```powershell
   cd Backend/Services/dapr
   dapr run -f dapr.yaml
   ```

### 验证安装

访问以下 Swagger UI 页面:
- API Gateway: http://localhost:5000/swagger
- Identity Service: http://localhost:5001/swagger
- Authorization Service: http://localhost:5002/swagger

---

## 📖 API 文档

### 认证 API (通过网关访问)

#### 用户注册
```http
POST /api/auth/register
Content-Type: application/json

{
  "name": "张三",
  "email": "zhangsan@example.com",
  "password": "Password@123"
}
```

#### 用户登录
```http
POST /api/auth/login
Content-Type: application/json

{
  "email": "zhangsan@example.com",
  "password": "Password@123",
  "rememberMe": true
}
```

**响应:**
```json
{
  "success": true,
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4...",
    "expiresAt": "2026-02-03T13:00:00Z",
    "user": {
      "id": 1,
      "name": "张三",
      "email": "zhangsan@example.com",
      "status": "Active",
      "roles": ["User"],
      "permissions": ["users:read", "roles:read"]
    }
  },
  "message": "Login successful",
  "code": 200
}
```

#### 刷新 Token
```http
POST /api/auth/refresh-token
Content-Type: application/json

{
  "refreshToken": "your-refresh-token"
}
```

### 角色权限 API

#### 获取所有角色
```http
GET /api/roles
Authorization: Bearer <access-token>
```

#### 分配角色给用户
```http
POST /api/roles/assign
Authorization: Bearer <access-token>
Content-Type: application/json

{
  "userId": 1,
  "roleIds": [2, 3]
}
```

#### 获取用户权限
```http
GET /api/authorization/users/{userId}/permissions
```

---

## 🔗 Dapr 集成

### 服务调用

服务之间通过 Dapr 进行调用:

```csharp
// 从 Identity Service 调用 Authorization Service
var permissions = await _daprClient.InvokeMethodAsync<UserPermissionsDto>(
    HttpMethod.Get,
    "authorization-service",  // 目标服务的 App ID
    $"api/authorization/users/{userId}/permissions");
```

### 事件发布

```csharp
// 发布用户创建事件
await _daprClient.PublishEventAsync(
    "pubsub",           // PubSub 组件名
    "user-created",     // 主题名
    new UserCreatedEvent { UserId = user.Id, Email = user.Email });
```

### 事件订阅

```csharp
[Topic("pubsub", "user-created")]
[HttpPost("events/user-created")]
public async Task HandleUserCreated(UserCreatedEvent @event)
{
    // 处理用户创建事件
    await _roleService.AssignRolesToUserAsync(@event.UserId, new[] { 3 }); // 分配默认角色
}
```

### 状态存储

```csharp
// 保存状态
await _daprClient.SaveStateAsync("statestore", $"user-session-{userId}", sessionData);

// 读取状态
var session = await _daprClient.GetStateAsync<SessionData>("statestore", $"user-session-{userId}");
```

---

## 🔒 安全机制

### JWT 认证

- **算法**: HMAC SHA256
- **Access Token 有效期**: 60 分钟 (可配置)
- **Refresh Token 有效期**: 7 天 (可配置)

### 密码策略

- 最少 8 个字符
- 至少一个大写字母
- 至少一个小写字母
- 至少一个数字
- 至少一个特殊字符

### Token 刷新机制

1. Access Token 过期后，使用 Refresh Token 获取新的 Token 对
2. Refresh Token 使用后立即失效（轮换机制）
3. 密码修改后所有 Refresh Token 自动失效

---

## 🚢 部署指南

### Docker Compose 部署

创建 `docker-compose.yml`:

```yaml
version: '3.8'

services:
  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    networks:
      - lingadmin

  sqlserver:
    image: mcr.microsoft.com/mssql/server:2022-latest
    environment:
      - ACCEPT_EULA=Y
      - SA_PASSWORD=YourStrong!Password
    ports:
      - "1433:1433"
    networks:
      - lingadmin

  api-gateway:
    build:
      context: .
      dockerfile: ApiGateway/LingAdmin.ApiGateway/Dockerfile
    ports:
      - "5000:5000"
    depends_on:
      - redis
    networks:
      - lingadmin

  identity-service:
    build:
      context: .
      dockerfile: IdentityService/LingAdmin.IdentityService/Dockerfile
    ports:
      - "5001:5001"
    depends_on:
      - sqlserver
      - redis
    networks:
      - lingadmin

  authorization-service:
    build:
      context: .
      dockerfile: AuthorizationService/LingAdmin.AuthorizationService/Dockerfile
    ports:
      - "5002:5002"
    depends_on:
      - sqlserver
      - redis
    networks:
      - lingadmin

networks:
  lingadmin:
    driver: bridge
```

### Kubernetes 部署

使用 Dapr 注解部署到 Kubernetes:

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: identity-service
spec:
  replicas: 3
  selector:
    matchLabels:
      app: identity-service
  template:
    metadata:
      labels:
        app: identity-service
      annotations:
        dapr.io/enabled: "true"
        dapr.io/app-id: "identity-service"
        dapr.io/app-port: "5001"
    spec:
      containers:
        - name: identity-service
          image: lingadmin/identity-service:latest
          ports:
            - containerPort: 5001
```

---

## 📝 扩展服务

要添加新的微服务，请按照以下步骤：

1. 创建新项目，引用 `LingAdmin.Shared`
2. 配置 Dapr 组件
3. 在 `dapr.yaml` 中添加服务配置
4. 在 API Gateway 的路由配置中添加新路由
5. 实现服务间通信（使用 Dapr Service Invocation）

---

## 🤝 贡献指南

1. Fork 本仓库
2. 创建功能分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 提交 Pull Request

---

## 📄 许可证

MIT License