# Phase 3: 调整网关部分的需求 - Context

**Gathered:** 2026-03-03
**Status:** Ready for planning

<domain>
## Phase Boundary

调整 Gateway 模块的实体结构和 YARP 集成方式，包括：
- 重构实体模型（删除 GwTenant 和 GwServiceInstance，新增 GwCluster）
- 扩展 GwTenantRoute 的匹配和转换能力
- 实现与 YARP 配置模型的完整对接

</domain>

<decisions>
## Implementation Decisions

### 实体结构调整

#### 删除的实体
- **GwTenant** - 删除，直接使用 Platform.Tenant 通过 TenantCode 关联
- **GwServiceInstance** - 删除，改为 GwCluster 聚合根内嵌 Destination

#### 新增的实体

**GwCluster（集群聚合根）**
- `string Id` - GUID，与 YARP ClusterId 类型一致
- `string ClusterId` - 集群标识（业务 ID）
- `string Name` - 集群名称
- `string? Description` - 描述
- `List<GwDestination> Destinations` - 目标端点列表（内嵌）
- `string LoadBalancingPolicy` - 负载均衡策略 (RoundRobin, WeightedRoundRobin, LeastRequests 等)
- `GwHealthCheckConfig? HealthCheck` - 健康检查配置
- `GwSessionAffinityConfig? SessionAffinity` - 会话亲和配置
- `int Status` - 状态
- 审计字段 (CreatedBy, CreatedTime, UpdatedBy, UpdatedTime, IsDeleted, Version)

**GwDestination（内嵌值对象）**
- `string DestinationId` - 目标标识
- `string Address` - 后端地址
- `string? Health` - 健康检查端点
- `int Weight` - 权重（用于加权负载均衡）
- `int HealthStatus` - 健康状态
- `int Status` - 状态

**GwHealthCheckConfig（内嵌值对象）**
- `bool Enabled` - 是否启用
- `string? Path` - 健康检查路径 (默认 /health)
- `int IntervalSeconds` - 检查间隔（秒）
- `int TimeoutSeconds` - 超时时间（秒）

**GwSessionAffinityConfig（内嵌值对象）**
- `bool Enabled` - 是否启用
- `string Policy` - 策略 (Header)
- `string AffinityKeyName` - 亲和键名称

#### 修改的实体

**GwTenantRoute 扩展字段**
- `string? Methods` - HTTP 方法匹配 (GET,POST,PUT,DELETE 等)
- `string? Hosts` - Host 头匹配 (支持通配符)
- `string? Headers` - Header 匹配规则 (JSON 格式)
- `string? LoadBalancingPolicy` - 路由级别负载均衡策略覆盖
- `string? AuthorizationPolicy` - 授权策略
- `string? RateLimiterPolicy` - 限流策略
- `string? CorsPolicy` - CORS 策略
- `string? Transforms` - 请求/响应转换规则 (JSON 格式)

保留现有字段：
- `string Id` - GUID v7
- `string TenantCode` - 租户代码（关联 Platform.Tenant）
- `string ServiceName` - 服务名称
- `string ClusterId` - 关联 GwCluster
- `string PathPattern` - 路径匹配模式
- `int Priority` - 优先级
- `int Status` - 状态
- `bool IsGlobal` - 是否全局路由

### 路由匹配能力

- **Path**: 完整支持 YARP Path 模式 (如 `/api/{**catch-all}`)
- **Methods**: 支持 HTTP 方法过滤，逗号分隔 (如 `GET,POST`)
- **Hosts**: 支持 Host 头匹配，逗号分隔 (如 `api.example.com,*.api.com`)
- **Headers**: JSON 格式动态配置，如 `[{"Name":"X-Custom","Values":["value1"],"Mode":"ExactHeader"}]`

### 负载均衡策略

- **集群级别配置**: GwCluster.LoadBalancingPolicy 存储默认策略
- **路由级别覆盖**: GwTenantRoute.LoadBalancingPolicy 可覆盖集群默认策略
- 支持策略: `RoundRobin`, `LeastRequests`, `Random`, `PowerOfTwoChoices`, `WeightedRoundRobin`

### 会话亲和 (Session Affinity)

- **策略**: Header 方式
- **标识来源**: UserId 优先，TenantCode 兜底
- **AffinityKeyName**: `X-Session-Key`
- **实现逻辑**: 
  1. 已登录用户: 使用 `UserId` 作为会话键
  2. 未登录用户: 使用 `TenantCode` 作为会话键
  3. 同一会话键的请求路由到同一后端实例

### 健康检查

- **方式**: 主动健康检查 (Active Health Check)
- **配置位置**: GwCluster.HealthCheck
- **默认配置**:
  - Path: `/health`
  - Interval: 30 秒
  - Timeout: 10 秒

### 请求/响应转换 (Transforms)

- **格式**: JSON 数组
- **示例**:
  ```json
  [
    {"RequestHeader": "X-Forwarded-For", "Set": "true"},
    {"ResponseHeader": "X-Served-By", "Set": "gateway"}
  ]
  ```
- 支持的转换类型: RequestHeader, ResponseHeader, PathPrefix, PathRemovePrefix 等

### 租户关联

- **GwTenant 删除**: 不再单独维护网关租户表
- **关联方式**: 通过 `TenantCode` 直接关联 Platform.Tenant
- **TenantCode 来源**: 
  - 已登录用户: 从 User.TenantInfo.TenantCode 获取
  - 请求头: 从 `X-Tenant-Code` 获取

### ID 类型约定

| 实体 | ID 类型 | 原因 |
|------|---------|------|
| GwTenantRoute | `string` (GUID v7) | 与 YARP RouteId 一致 |
| GwCluster | `string` (GUID) | 与 YARP ClusterId 一致 |
| GwDestination | 无独立 ID | 内嵌值对象 |

### Claude's Discretion

- Transforms JSON 的具体结构和验证规则
- HealthCheckConfig 和 SessionAffinityConfig 的详细字段设计
- Header 匹配规则 JSON 的完整 Schema
- 错误处理和验证逻辑

</decisions>

<specifics>
## Specific Ideas

- 会话亲和 Header 名称: `X-Session-Key`
- 健康检查默认路径: `/health`
- 负载均衡默认策略: `PowerOfTwoChoices` (YARP 推荐)
- Header 匹配采用 JSON 格式，支持运行时动态配置

</specifics>

<code_context>
## Existing Code Insights

### 需要删除的文件
- `Fengling.Platform.Domain/AggregatesModel/GatewayAggregate/GwTenant.cs`
- `Fengling.Platform.Domain/AggregatesModel/GatewayAggregate/GwServiceInstance.cs`

### 需要修改的文件
- `Fengling.Platform.Domain/AggregatesModel/GatewayAggregate/GwTenantRoute.cs` - 扩展字段
- `Fengling.Platform.Infrastructure/PlatformDbContext.cs` - 更新 DbSet 和配置
- `Fengling.Platform.Infrastructure/IInstanceStore.cs` - 删除或改为 IClusterStore
- `Fengling.Platform.Infrastructure/InstanceStore.cs` - 删除或改为 ClusterStore

### 需要新增的文件
- `Fengling.Platform.Domain/AggregatesModel/GatewayAggregate/GwCluster.cs`
- `Fengling.Platform.Domain/AggregatesModel/GatewayAggregate/GwDestination.cs`
- `Fengling.Platform.Domain/AggregatesModel/GatewayAggregate/GwHealthCheckConfig.cs`
- `Fengling.Platform.Domain/AggregatesModel/GatewayAggregate/GwSessionAffinityConfig.cs`
- `Fengling.Platform.Infrastructure/IClusterStore.cs`
- `Fengling.Platform.Infrastructure/ClusterStore.cs`

### 参考资源
- YARP 配置模型文档: `docs/yarp-configuration-model.md`
- YARP 官方仓库: https://github.com/microsoft/reverse-proxy

</code_context>

<deferred>
## Deferred Ideas

- 被动健康检查 (Passive Health Check) - 可在后续版本添加
- 限流策略配置 (RateLimiterPolicy) - 可在后续版本添加
- 授权策略配置 (AuthorizationPolicy) - 可在后续版本添加
- CORS 策略配置 (CorsPolicy) - 可在后续版本添加

</deferred>

---

*Phase: 03-*
*Context gathered: 2026-03-03*