# CleanDDD 开发工作流

本文档描述 Fengling 微服务项目的标准开发流程，基于 Clean Architecture 和 Domain-Driven Design 原则。

## 开发技能栈

| 技能 | 用途 | 位置 |
|------|------|------|
| `cleanddd-requirements-analysis` | 需求澄清与拆解 | `~/.agents/skills/` |
| `cleanddd-modeling` | 领域模型设计（聚合/命令/事件/查询） | `~/.agents/skills/` |
| `cleanddd-dotnet-coding` | 代码实现（实体/命令/端点/事件） | `~/.agents/skills/` |
| `cleanddd-dotnet-init` | 新项目初始化 | `~/.agents/skills/` |

## 标准开发流程

### 阶段 1：需求分析
```
业务需求描述
    ↓
cleanddd-requirements-analysis
    ↓
结构化需求文档（标注业务实体、干系人）
```

### 阶段 2：领域建模
```
结构化需求
    ↓
cleanddd-modeling
    ↓
领域蓝图：
- 聚合根定义（含强类型ID）
- 领域事件列表
- 命令与查询分离
- API 端点设计
- 仓储接口
```

### 阶段 3：代码实现
```
领域蓝图
    ↓
cleanddd-dotnet-coding
    ↓
项目结构：
├── Domain/
│   ├── AggregatesModel/{Aggregate}/
│   │   ├── {Aggregate}.cs           # 聚合根
│   │   ├── {Aggregate}Id.cs         # 强类型ID
│   │   └── Events/                  # 领域事件
│   └── DomainEvents/
├── Infrastructure/
│   ├── EntityConfigurations/        # EF 配置
│   └── Repositories/                # 仓储实现
└── Web/
    ├── Application/
    │   ├── Commands/                # CQRS 命令
    │   ├── Queries/                 # CQRS 查询
    │   └── DomainEventHandlers/     # 领域事件处理器
    └── Endpoints/                   # API 端点
```

## 项目结构规范

### CleanDDD 标准结构

```
{ServiceName}/
├── src/
│   ├── {ServiceName}.Domain/              # 领域层（无依赖）
│   │   ├── AggregatesModel/
│   │   │   └── {Aggregate}/
│   │   │       ├── {Aggregate}.cs
│   │   │       ├── {Aggregate}Id.cs
│   │   │       └── Events/
│   │   └── DomainEvents/
│   │
│   ├── {ServiceName}.Infrastructure/      # 基础设施层
│   │   ├── EntityConfigurations/
│   │   ├── Repositories/
│   │   └── {ServiceName}DbContext.cs
│   │
│   └── {ServiceName}.Web/                 # 表现层
│       ├── Application/
│       │   ├── Commands/
│       │   │   └── {Feature}/
│       │   │       ├── {Command}.cs
│       │   │       └── {Command}Handler.cs
│       │   ├── Queries/
│       │   └── DomainEventHandlers/
│       └── Endpoints/
│           └── {Feature}Endpoints.cs
│
└── tests/                                  # 测试项目
    ├── {ServiceName}.Domain.UnitTests/
    ├── {ServiceName}.Infrastructure.UnitTests/
    └── {ServiceName}.Web.UnitTests/
```

### 命名约定

| 类型 | 命名格式 | 示例 |
|------|----------|------|
| 聚合根 | `{名词}` | `Campaign`, `Order` |
| 强类型ID | `{名词}Id` | `CampaignId`, `OrderId` |
| 领域事件 | `{名词}{动词}edEvent` | `CampaignCreatedEvent` |
| 命令 | `{动词}{名词}Command` | `CreateCampaignCommand` |
| 查询 | `Get{名词}Query` | `GetCampaignQuery` |
| 端点 | `{名词}Endpoints` | `CampaignEndpoints` |
| 仓储 | `I{名词}Repository` | `ICampaignRepository` |

## 代码规范

### 必须遵守

1. **强类型 ID**：所有实体使用 `IInt64StronglyTypedId` 或 `IGuidStronglyTypedId`
2. **聚合根**：继承 `Entity<TId>`，实现 `IAggregateRoot`
3. **领域事件**：在状态变更时发布 `this.AddDomainEvent()`
4. **仓储**：使用异步方法（`GetAsync`, `AddAsync`），禁止在 Handler 中调用 `SaveChanges`
5. **命令验证**：每个命令必须有对应的 `AbstractValidator<T>`
6. **端点配置**：使用属性配置 `[HttpPost]`, `[Tags]`，不使用 `Configure()` 方法

### 禁止事项

- ❌ 手动赋值实体 ID（使用 EF 值生成器）
- ❌ 在领域层引用基础设施层
- ❌ 在非聚合/实体中发布领域事件
- ❌ 仓储同步方法
- ❌ 命令 Handler 中调用 `SaveChanges`

## 网关架构说明

### 配置流向

```
K8s Service (app-router-* label)
    ↓
Console (K8sServiceWatchService)
    ↓
PendingConfigCache (内存缓存)
    ↓
PendingConfigController (用户确认)
    ↓
PostgreSQL (GwRoutes, ServiceInstances)
    ↓
PostgreSQL NOTIFY (gateway_config_changed)
    ↓
Gateway (PgSqlConfigChangeListener)
    ↓
YARP DynamicProxyConfigProvider
    ↓
TenantRoutingTransform (按 TenantCode 路由)
    ↓
后端服务
```

### 多租户路由

| 路由类型 | URL 模式 | 说明 |
|----------|----------|------|
| 全局路由 | `/{ServicePrefix}/{Version}/{Resource}` | 所有租户共享 |
| 租户路由 | `/tenant/{tenantCode}/{ServicePrefix}/{Version}/{Resource}` | 租户专属目标 |

### 关键实体

- **GwRoute**：全局路由配置（Path → Cluster）
- **GwCluster**：服务集群（含 Destinations 列表）
- **GwDestination**：目标端点（含 TenantCode 用于租户路由）

## 故障排除

| 问题 | 原因 | 解决 |
|------|------|------|
| `bigint = character varying` | 表结构过时 | 见 `DATABASE_SCHEMA_FIX.md` |
| `libgssapi_krb5.so.2` 警告 | Alpine 缺少 Kerberos 库 | 可忽略，或设 `Logging__LogLevel__Npgsql=Error` |
| Watch 连接断开不恢复 | HTTP/2 连接超时 | 已修复：onClosed 回调触发重连 |
| Config 未生效 | NOTIFY 未触发 | 检查 `LISTEN config_changes;` |

## 相关文档

- `DATABASE_SCHEMA_FIX.md` - 数据库表结构修复步骤
- `GATEWAY_ADMIN_README.md` - Gateway Admin UI 开发指南
- `../../AGENTS.md` - 项目级架构概览