# Fintec AI Framework 架构设计文档

## 📋 目录

- [整体架构](#整体架构)
- [模块职责](#模块职责)
- [技术栈](#技术栈)

---

## 整体架构

### 架构图

![spring_ai_architecture](./pic/spring_ai_architecture.svg)

## 模块职责

### 1. fintec-framework-ai-core (核心模块)

**定位**: 纯 JAR - 契约、模型与常量定义

**职责**:
- 统一的 AI 配置管理 (`AiCoreProperties`)
- 统一响应模型 (`AiResponse` + `TokenUsage` + `ErrorInfo`)
- 统一异常体系 (`AiException`)
- Graph 核心接口 (`Node`, `Condition`)

**设计原则**: 

- 无 Spring 依赖（纯 POJO/接口）
- 不包含自动配置
- 被所有 autoconfigure 模块依赖

**关键类**:
```
com.ccb.fintec.core.properties.AiCoreProperties
com.ccb.fintec.core.dto.AiResponse
com.ccb.fintec.core.exception.AiException
com.ccb.fintec.core.graph.Node
com.ccb.fintec.core.graph.Condition
```

---

### 2. fintec-framework-agent-spring-boot-starter (Agent 模块)

**定位**: 对话式 AI 和多模态能力中心

**职责**:
- **基础对话**: ChatClient 封装,同步/流式响应
- **Tool Calling**: @Tool 自动注册和调用
- **对话记忆**: ChatMemory + JDBC/Redis 持久化
- **Advisor 链**: Memory/RAG/Log/Guardrails
- **结构化输出**: .entity(Class) JSON解析
- **多模态输入**: 图片理解、文档理解
- **语音合成**: TTS (Text-to-Speech) - 暂不支持
- **语音识别**: STT (Speech-to-Text) - 暂不支持

**核心组件**:
```
AgentTemplate          - 对话模板
MultimodalTemplate     - 多模态模板
```

**典型场景**:

- 智能客服机器人
- AI 编程助手
- 多模态交互应用

---

### 3. fintec-framework-rag-spring-boot-starter (RAG 模块)

**定位**: 检索增强生成和图片生成中心

**职责**:
- **RAG 检索增强**: RetrievalAugmentationAdvisor
- **ETL 文档管道**: PDF/Word/网页读取分块
- **Embedding**: 向量化接口
- **Vector Store**: PGVector/Redis/Chroma 等
- **图片生成**: ImageModel (DALL-E等)

**核心组件**:
```
RagTemplate            - RAG模板
ImageGenerationTemplate - 图片生成模板
```

**典型场景**:
- 企业知识库问答
- 智能文档检索
- AI 绘画应用

---

### 4. fintec-framework-agent-spring-boot-starter (Graph 模块)

**定位**: 工作流编排引擎

**职责**:
- **Sequential**: 顺序链式执行
- **Parallel**: 并行执行聚合
- **Routing**: 条件分支路由
- **Loop + Recursive**: 循环和递归
- **Human in the Loop**: 人工干预节点

**核心组件**:
```
Node                   - 工作流节点
Condition              - 条件边
SequentialWorkflow     - 顺序工作流
ParallelWorkflow       - 并行工作流
RoutingWorkflow        - 路由工作流
LoopWorkflow           - 循环工作流
GraphTemplate          - 工作流模板
```

**典型场景**:
- 复杂业务流程编排
- 多步骤 AI 任务
- 决策树系统

---

### 5. fintec-framework-mcp-server-spring-boot-starter (MCP 模块)

**定位**: Model Context Protocol 支持

**职责**:
- **MCP Server**: SSE + STDIO + Streamable-HTTP
- **MCP Client**: 连接远程 MCP Server
- **工具发现**: 自动扫描 @Tool 注解
- **协议适配**: 多种传输协议支持

**核心组件**:
```
ToolCallbackProvider   - 工具回调提供者
McpAutoConfiguration   - MCP自动配置
```

**典型场景**:
- AI 调用外部 API
- 跨系统集成
- 微服务编排

---

## 技术栈

### 基础框架
- **JDK**: 17+
- **Spring Boot**: 3.4.6+
- **Spring AI**: 1.1.0+
- **Maven**: 3.6+

### AI 模型支持
- **LLM**: OpenAI GPT、Ollama、通义千问、Anthropic Claude
- **Embedding**: OpenAI Embedding、本地 Embedding
- **Image**: DALL-E 3、Stable Diffusion
- **Audio**: OpenAI Whisper/TTS

### 向量数据库
- **PGVector**: PostgreSQL 向量扩展
- **Redis**: Redis Stack
- **Chroma**: 原生向量数据库
- **Milvus**: 大规模向量检索

### 数据存储
- **JDBC**: MySQL/PostgreSQL/Oracle
- **Redis**: 会话缓存
- **Caffeine**: 本地缓存