# DataAgent

**Repository Path**: ymjake/data-agent

## Basic Information

- **Project Name**: DataAgent
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-05
- **Last Updated**: 2026-08-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Data-Agent (.NET)

一个基于 ASP.NET Core 的 **Text2SQL 智能体** 重写版，参考 [spring-ai-alibaba/DataAgent]（Kotlin + Spring Boot + StateGraph），以个人 Vertical Slice Architecture 模板 [todo-list] 为底座。目标是做一个能端到端演示的面试作品：用户输入一句业务问题，智能体经过「RAG 双通道召回 → 规划 → 人工确认(HITL) → SQL 生成/执行 → 报告生成」全链路，结果通过 SSE 流式返回。

当前进度：Phase 0（移除 Outbox）+ Phase 1（领域模型 + EF 配置 + 迁移）已完成，正在推进 Phase 2/3（LLM 基建与召回节点）。详细计划见 [docs/PLAN.md]，领域模型设计决策见 [docs/DOMAIN-MODEL-DESIGN.md]。

## 项目结构

- `src/TodoList.Api`：Minimal API、功能切片、领域模型、EF Core + PostgreSQL、Dapper 查询、认证授权、Swagger、API 版本控制
- `src/Aspire.AppHost`：Aspire 编排，负责启动 Api、PostgreSQL、Seq
- `src/Aspire.ServiceDefaults`：Aspire Service Defaults、健康检查、服务发现、OpenTelemetry 基础配置
- `tests/TodoList.Domain.UnitTests`：领域单元测试（不依赖 Docker）
- `tests/TodoList.IntegrationTests`：基于 Aspire 的 HTTP / 数据库切片集成测试
- `docs/`：重写计划（PLAN）与领域模型设计说明（DOMAIN-MODEL-DESIGN）

## 技术特点

- Vertical Slice Architecture（每功能一个切片文件夹）
- 自定义轻量 CQRS 分发 + 装饰器（不依赖 MediatR）
- 充血领域模型：聚合根 / 实体 / 值对象 + 领域事件
- FluentValidation
- Minimal APIs + API Versioning + Swagger / OpenAPI
- JWT 认证
- EF Core + PostgreSQL（`UseSnakeCaseNamingConvention`，迁移已启用）
- Dapper 读侧支持
- OpenTelemetry + Seq
- 数据初始化（`IDataSeeder`）
- xUnit、Shouldly、Aspire 集成测试与领域单元测试
- AspNetCore 常用中间件配置

## 领域模型（Data Agent 侧，Phase 1 已落地）

```
Domain/
├── AgentTasks/                       # 聚合：A2A 任务状态机
│   ├── AgentTask.cs                  # 聚合根（Submitted→Working→InputRequired→…）
│   ├── AgentTaskStatus.cs
│   ├── AgentTaskErrors.cs
│   └── Events/                       # 5 个领域事件
├── DatabaseSchemas/                  # 聚合：数据库结构一致性
│   ├── DbTable.cs                    # 聚合根（AddColumn/AddForeignKey 防重）
│   ├── DbColumn.cs                   # 实体
│   ├── DbForeignKey.cs               # 值对象（Owned，规避跨聚合一致性冲突）
│   └── DbTableErrors.cs
├── GlossaryKnowledge/                # 单实体聚合：术语知识
│   ├── GlossaryKnowledge.cs
│   └── GlossaryKnowledgeErrors.cs
└── QuestionKnowledge/                # 单实体聚合：问答知识
    ├── QuestionKnowledge.cs
    └── QuestionKnowledgeErrors.cs
```

关键建模决策（详见 `docs/DOMAIN-MODEL-DESIGN.md`）：

1. **Knowledge 拆成两个 Single-Entity Aggregate**：判断标准是"谁维护不变式 / 谁是外部访问入口"，而非复杂度。
2. **DbForeignKey 降级为值对象**（`OwnsMany`）：外键是表间关系声明，不天然属于任一侧 DbTable；持有 Guid 引用避免跨聚合一致性问题。
3. **导航属性保持移除**：领域模型只留 FK Guid，join 全部推给 Infrastructure 层（与模板 shadow-FK 风格一致）。
4. **DbTable 用 AggregateRoot**：`AddColumn` / `AddForeignKey` 防重即聚合内不变式。

已生成 EF 迁移 `AddDataAgentDomain`：`db_table` / `db_column` / `db_foreign_key` / `glossary_knowledge` / `question_knowledge` 五张表，含唯一索引（表名+库、列名+表、term+库），映射到原 Kotlin 项目 `database.sql` 的数据结构，为后续数据导入做准备。

## 当前实现亮点

### 1. 不依赖第三方中介者库

项目没有使用 `MediatR`，而是项目内自己的轻量 CQRS 分发实现（`ICommandDispatcher` / `IQueryDispatcher`，基于运行时请求类型缓存 handler wrapper），保留 CQRS 代码组织方式，减少依赖。

### 2. 横切逻辑通过装饰器处理

日志和验证通过开放泛型装饰器挂在 handler 外层（`ValidationDecorator` / `LoggingDecorator`），handler 本身只关心业务。

### 3. CORS 采用白名单配置

不使用 `AllowAnyOrigin` 默认策略，通过 `Cors:AllowedOrigins` 白名单，并精确应用到版本化 API 路由组上。

### 4. 领域事件

`User` / `TodoItem` / `AgentTask` 继承 `AggregateRoot`，业务动作通过实体方法表达并记录领域事件，`IDomainEventsDispatcher` 在请求生命周期内分发到 `IDomainEventHandler<T>`。

## 主要接口

所有业务接口统一挂在 `/api/v1` 下：

- `POST /api/v1/users/register`
- `POST /api/v1/users/login`
- `GET /api/v1/users/me`
- `POST /api/v1/todos`
- `GET /api/v1/todos`
- `GET /api/v1/todos/{id}`
- `PUT /api/v1/todos/{id}/complete`
- `DELETE /api/v1/todos/{id}`

## 启动方式

使用 Aspire AppHost 启动完整本地环境（自动拉起 PostgreSQL、Seq、Api）：

```powershell
dotnet run --project src\Aspire.AppHost\Aspire.AppHost.csproj
```

如果单独启动 Api，需要自行提供 `ConnectionStrings:Database`：

```powershell
dotnet run --project src\TodoList.Api\TodoList.Api.csproj
```

Swagger 地址：

```text
http://localhost:5000/swagger
```

## 验证

```powershell
dotnet build TodoList.slnx
dotnet test tests\TodoList.Domain.UnitTests\TodoList.Domain.UnitTests.csproj
dotnet test tests\TodoList.IntegrationTests\TodoList.IntegrationTests.csproj
```

- 领域单元测试只覆盖有真实行为的领域模型（实体工厂方法、状态变化、失败分支、领域事件）。
- 切片集成测试从 HTTP 入口验证路由、认证授权、验证器装饰器、ProblemDetails、持久化和重要业务分支，使用 Mock authentication（`TestAuthHandler`）避免测试间互相耦合。
- 领域单元测试不依赖 Docker；集成测试依赖 `Aspire.Hosting.Testing`，需要本地可用的 Docker 或兼容容器运行时。

## 技术栈映射（原 Kotlin 项目 → 本 .NET 版）

| 原项目（Kotlin） | 本计划（.NET） |
|---|---|
| Spring Boot 3 + Kotlin | ASP.NET Core 10 + C# |
| Jimmer ORM + pgvector | EF Core 10 + Npgsql（向量查询用原始 SQL） |
| Spring AI（OpenAI 兼容） | `Microsoft.Extensions.AI` + OpenAI 兼容 base-url |
| StateGraph | MAF Workflow（`Microsoft.Agents.AI.Workflows`） |
| A2A Java SDK | A2A .NET SDK（`A2A` / `A2A.AspNetCore`） |
| Python Docker 沙盒 | `System.Diagnostics.Process` 调 docker（Phase 8） |
| 前端 Vue3 + `@a2a-js/sdk` | 原前端基本不动（纯 A2A 协议） |

## 路线图

- [x] Phase 0：工程准备（移除 Outbox / 领域事件 outbox 通道，保留 Result/Error 基建）
- [x] Phase 1：领域模型 + EF 配置 + 迁移生成验证
- [ ] Phase 2：LLM 基建（IChatClient / IEmbeddingGenerator）+ Prompt 管理
- [ ] Phase 3：召回节点（证据召回 / Schema 召回 / 表关系裁剪）
- [ ] Phase 4：MAF Workflow 编排骨架
- [ ] Phase 5：A2A 接入（agent-card + JSON-RPC + SSE）
- [ ] Phase 6：HITL 人机确认
- [ ] Phase 7：SQL 生成 / 执行 + 报告
- [ ] Phase 8：Python Docker 沙盒（后置）
- [ ] Phase 9：收尾（测试、README、演示脚本）

[spring-ai-alibaba/DataAgent]: https://github.com/spring-ai-alibaba/DataAgent
[todo-list]: https://gitee.com/ymjake/todo-list