AIRegulation-DocAnalysis/docs/architecture/backend-project-architecture.md

# Backend Project Architecture

## 1. Purpose

本文档定义当前 backend 的目标态架构，用于在保持单服务部署的前提下，将系统整理为职责清晰、边界稳定、可替换实现的模块化结构。本文档的重点不是描述理想化分层，而是基于当前真实代码形态，明确后续重构时必须遵守的模块职责、依赖方向、内部稳定接口和替换边界。

本文档与 `docs/rfc/backend-api-parsing-embedding-migration-requirements.md` 的关系如下：

- RFC 负责冻结本轮迁移需求、范围、风险和约束。
- 本文档负责冻结目标模块边界、依赖规则和实现组织方式。
- 后续任何代码重构、能力替换或底座升级，都应同时满足 RFC 与本文档。

## 2. Current-State Problems

基于当前代码，后端已经具备以下能力：

- 文档上传、下载、列表
- 文档解析与切片
- 向量化与 Milvus 入库
- 检索
- 基于 RAG 的 Agent 问答 workflow

但这些能力当前主要是“可运行”，还不是“结构清晰、便于替换、便于演进”的状态。核心问题如下。

### 2.1 `DocumentProcessor` 责任过载

`backend/app/services/document_processor.py` 当前同时承担：

- 文档解析
- 摘要生成
- 分块
- 向量化
- Milvus 入库
- 检索入口

这使上传处理链路、检索链路与基础设施初始化逻辑耦合在一个大类中。流程编排与具体实现没有边界，后续无论替换 parser、embedding、vector store 还是增加文档状态管理，都会直接影响同一个类。

### 2.2 检索逻辑缺少稳定边界

`backend/app/services/rag/retriever.py` 当前同时管理：

- embedder 初始化
- Milvus 连接与 collection lifecycle
- 检索执行
- 结果映射

这意味着“检索能力”不是一个稳定的业务能力接口，而是一个直接依赖具体 embedding 和 Milvus 实现的复合服务。后续如果从 `BGE-M3 + hybrid search` 切到 `1536 dense-only` 或替换向量索引实现，会直接影响检索服务本身。

### 2.3 `QAAgent` 责任过载

`backend/app/services/agent/qa_agent.py` 当前同时承担：

- 检索调用
- 上下文构建
- Prompt 选择
- LLM 调用
- SSE 流式问答流程
- 会话 workflow 编排

这导致 Agent workflow 与检索底座、LLM provider、上下文构造逻辑紧耦合。后续切换 LLM provider、替换 session store、复用 retrieval 能力时，影响面会扩散到整个 Agent 实现。

### 2.4 API 层直接编排具体服务

当前 API 路由主要在：

- `backend/app/api/routes/documents.py`
- `backend/app/api/routes/knowledge.py`
- `backend/app/api/routes/agent.py`

这些路由直接实例化具体服务类，例如 `DocumentProcessor`、`QAAgent`、`MinIOClient`。这意味着：

- API 层不仅处理 transport concerns，也在做业务编排
- 路由层知道过多内部实现细节
- 后续如果内部模块调整，路由层也要跟着改

### 2.5 文档元数据与对象存储组织方式耦合

当前文档列表与下载逻辑高度依赖 MinIO 对象命名方式和对象遍历结果。对象存储目前承担了部分“业务真相”的角色，但对象存储只适合作为文件二进制载体，不适合作为完整文档元数据和状态管理的唯一来源。

### 2.6 `knowledge` 与 `agent` 共享检索底座的边界不清晰

当前 `/knowledge/*` 与 `/agent/*` 都依赖检索能力，但共享方式不够清晰：

- `knowledge` 通过 `DocumentProcessor.search()` 访问检索
- `agent` 通过 `Retriever` 访问检索

这会导致同一检索能力未来演进成两条链路，难以统一检索策略、元数据模型和可替换边界。

## 3. Architecture Goals

本项目后端的目标态架构必须满足以下目标。

### 3.1 单服务部署

系统继续保持单服务部署，不拆分为多个微服务。架构治理发生在单服务内部，通过清晰模块边界实现高内聚低耦合，而不是通过进程级拆分回避设计问题。

### 3.2 高内聚、低耦合优先级最高

后续模块设计以“一个模块只承载一类稳定职责”为原则。跨能力流程统一在编排层组织，不允许继续把 parser、embedding、storage、retrieval、LLM workflow 堆进同一个服务类。

### 3.3 外部 API 尽量保持兼容

现有前端与外部调用方依赖的主接口保持不变优先，包括但不限于：

- `/api/v1/documents/*`
- `/api/v1/knowledge/*`
- `/api/v1/agent/*`

内部可以重组，但外部接口不应因为内部重构而被迫大改。

### 3.4 关键能力必须可替换

以下能力必须通过稳定端口隔离实现细节：

- 文档解析
- 分块构建
- 向量化
- 向量索引
- 检索
- LLM 回答生成
- 会话存储
- 原始文件存储

后续替换方案时，只允许替换实现，不允许穿透影响其他模块。

### 3.5 `knowledge` 与 `agent` 共用同一检索底座

检索必须被视为独立的业务能力，由统一的 retrieval application service 对外暴露。`knowledge` 与 `agent` 必须复用同一个 retrieval 底座，避免两套召回策略、两套元数据模型、两套 adapter。

### 3.6 依赖必须单向流动

系统必须形成稳定的单向依赖关系：

- `api -> application -> domain`
- `application -> infrastructure` 通过端口/实现绑定
- `infrastructure -> external systems`

不允许出现基础设施实现反向驱动业务编排，也不允许 domain 依赖 Web 或第三方 SDK。

## 4. Target Module Layout

目标目录结构如下：

```text
backend/app/
  api/
  application/
    documents/
    knowledge/
    agent/
  domain/
    documents/
    retrieval/
    conversation/
  infrastructure/
    storage/
    vectorstore/
    parser/
    embedding/
    llm/
    session/
  shared/
```

该结构是本项目 backend 的目标态模块布局。后续实现可以渐进迁移，但职责边界不能偏离。

### 4.1 `api`

职责：

- HTTP 路由注册
- 请求参数校验
- 响应模型映射
- 异常转换
- SSE 事件格式输出

非职责：

- 不直接组织完整业务流程
- 不直接访问 MinIO、Milvus、Parser SDK、LLM SDK
- 不直接 new 具体基础设施客户端

### 4.2 `application`

职责：

- 用例编排
- 跨领域能力协作
- 业务流程统一入口
- workflow 级别的状态推进

非职责：

- 不直接依赖第三方 SDK
- 不承担具体存储、向量库、解析器实现细节

### 4.3 `domain`

职责：

- 核心业务对象
- 领域术语
- 稳定端口接口
- 统一元数据模型
- 检索结果模型
- 会话消息模型

非职责：

- 不依赖 FastAPI
- 不依赖 MinIO、Milvus、LLM SDK
- 不依赖路由请求响应模型

### 4.4 `infrastructure`

职责：

- 外部系统适配器实现
- 第三方 SDK 封装
- provider-specific 配置适配
- 数据格式转换

包含但不限于：

- MinIO binary store
- Milvus vector index
- Aliyun / local parser adapter
- OpenAI-compatible embedding adapter
- DeepSeek / Qwen LLM adapter
- in-memory / Redis session store

### 4.5 `shared`

职责：

- 配置
- 日志
- 通用异常
- 通用工具
- 公共基础设施无关组件

非职责：

- 不承载业务编排
- 不变成新的 `services` 大杂烩目录

## 5. Module Responsibilities

### 5.1 `api`

`api` 是 transport 层，只关心请求进来和响应出去的表达方式。它应该把请求转换为 application service 的输入，把 application service 的结果转换为 HTTP 响应。

`api` 不应该知道：

- MinIO bucket 怎么组织
- Milvus collection 怎么建
- parser 是本地还是阿里云
- embedding 是本地模型还是 API
- session 是内存还是 Redis

### 5.2 `application`

`application` 是业务编排层，是系统内唯一允许跨模块组织完整流程的层。它应该定义稳定的用例服务，而不是把流程散落在路由或基础设施实现中。

本项目至少固定以下 4 类 application service：

- `DocumentCommandService`
- `DocumentQueryService`
- `KnowledgeRetrievalService`
- `AgentConversationService`

### 5.3 `domain`

`domain` 层定义系统内部真正稳定的概念，例如：

- `Document`
- `DocumentStatus`
- `ParsedDocument`
- `Chunk`
- `RetrievalQuery`
- `RetrievedChunk`
- `ConversationSession`
- `ConversationMessage`
- `AnswerSource`

这些对象必须脱离具体技术实现，成为 parser、embedding、vector index、agent workflow 之间的公共契约。

### 5.4 `infrastructure`

`infrastructure` 只负责“怎么接某个外部系统”，不负责“业务上应该先做什么后做什么”。例如：

- MinIO adapter 负责上传和下载文件
- Milvus adapter 负责 upsert/search/delete
- Qwen / DeepSeek adapter 负责生成回答
- Aliyun parser adapter 负责把解析结果映射成统一 `ParsedDocument`

### 5.5 `shared`

`shared` 只放横切能力。任何和文档 ingest、检索、问答编排直接相关的业务逻辑，都不应该放进 `shared`。

## 6. Stable Internal Ports

以下端口是系统内部稳定契约。后续方案替换时，只能替换实现，不允许改动上层 application service 的调用方式，也不允许影响 sibling 模块。

### 6.1 `DocumentRepository`

职责：

- 管理文档元数据
- 管理文档状态
- 管理统计字段，例如 chunk 数、索引状态、摘要状态

说明：

- 列表和状态查询应以 `DocumentRepository` 为主，而不是直接遍历对象存储。

### 6.2 `DocumentBinaryStore`

职责：

- 保存原始文件
- 下载原始文件
- 删除原始文件
- 处理对象存储相关细节

说明：

- 替换 MinIO 或对象存储方案时，只替换该实现。

### 6.3 `DocumentParser`

职责：

- 输入原始文件
- 输出统一结构化解析结果

说明：

- 本地 PDF/MinerU 或阿里云解析只能作为实现差异，不能外溢到业务流程层。

### 6.4 `ChunkBuilder`

职责：

- 输入统一解析结果
- 输出统一 chunk 模型

说明：

- chunk 规则变化只能影响该端口实现，不应影响 retrieval、agent 或 API。

### 6.5 `EmbeddingProvider`

职责：

- 输入文本列表
- 输出 embedding 向量结果

说明：

- 从本地模型切到 OpenAI-compatible embedding，只替换该实现。

### 6.6 `VectorIndex`

职责：

- upsert chunks
- delete by document
- search by query vector
- 管理索引内部 schema

说明：

- Milvus schema 或向量库替换，只能影响该层。

### 6.7 `Retriever`

职责：

- 基于 query、filter、top_k 返回统一检索结果

说明：

- `Retriever` 是业务侧的检索端口，不应再直接持有 embedder、Milvus lifecycle 和 provider-specific 逻辑。

### 6.8 `AnswerGenerator`

职责：

- 基于 query 与 context 生成最终回答
- 屏蔽具体 LLM provider 差异

说明：

- DeepSeek、Qwen 或其他模型切换时，只替换该实现。

### 6.9 `ConversationStore`

职责：

- 创建和读取 session
- 持久化消息历史
- 管理会话生命周期

说明：

- 从内存实现切到 Redis 或数据库实现时，只替换该实现。

## 7. Application Services

### 7.1 `DocumentCommandService`

职责：

- 接收文档上传命令
- 生成 `doc_id`
- 保存原始文件
- 触发解析、分块、向量化、入库
- 更新文档状态和统计信息
- 返回最终处理结果

说明：

- 当前 `DocumentProcessor` 的“流程编排”职责在目标态应迁移到这里。
- parser、chunker、embedder、vector index 的具体实现不应继续塞进一个大类里统一管理。

### 7.2 `DocumentQueryService`

职责：

- 文档列表
- 文档下载
- 文档状态查询
- 文档管理视图查询

说明：

- 列表和状态查询应基于 `DocumentRepository`
- 下载应通过 `DocumentBinaryStore`
- 不再依赖 MinIO 对象结构作为业务视图主来源

### 7.3 `KnowledgeRetrievalService`

职责：

- 对外提供统一检索能力
- 管理 retrieval query 到 retrieval result 的业务转换
- 被 `/knowledge/*` 和 Agent workflow 共用

说明：

- 当前 `knowledge` 与 `agent` 必须统一依赖这一层，不允许各自再维护一套检索流程。

### 7.4 `AgentConversationService`

职责：

- 统一管理问答 workflow
- 读取或创建会话
- 调用 `KnowledgeRetrievalService`
- 构建问答上下文
- 调用 `AnswerGenerator`
- 保存回答和引用来源

说明：

- 当前 `QAAgent` 的 workflow 编排职责在目标态应迁移到这里，或被其吸收后只保留 façade 角色。
- SSE 与普通问答必须共用这一层，不允许复制业务编排逻辑。

## 8. Core Workflows

### 8.1 文档上传入库链路

目标流程如下：

1. `api/documents` 接收上传请求并完成输入校验。
2. `DocumentCommandService` 生成 `doc_id`，初始化文档记录和状态。
3. `DocumentBinaryStore` 保存原始文件。
4. `DocumentParser` 对原始文件执行解析，输出统一结构化结果。
5. `ChunkBuilder` 将解析结果转换为统一 chunk 集合。
6. `EmbeddingProvider` 为 chunks 生成向量。
7. `VectorIndex` 将 chunks 与 vectors 写入索引。
8. `DocumentRepository` 更新文档状态、chunk 数量、索引状态、元数据。
9. API 返回处理结果。

约束：

- 上传处理链路的主编排必须只存在于 `DocumentCommandService`
- 不允许再由 route 或基础设施类直接组织全流程

### 8.2 文档查询链路

目标流程如下：

1. `api/documents` 调用 `DocumentQueryService`
2. 文档列表与状态查询通过 `DocumentRepository`
3. 文档下载通过 `DocumentBinaryStore`
4. 对象存储命名规则只作为实现细节，不作为最终业务真相

约束：

- 文档“存在、状态、统计信息”必须有稳定元数据模型
- 不允许继续通过对象存储遍历结果拼出全部业务语义

### 8.3 Agent 问答链路

目标流程如下：

1. `api/agent` 接收问答请求
2. `AgentConversationService` 读取或创建 session
3. `KnowledgeRetrievalService` 统一执行检索
4. `AnswerGenerator` 基于 query 和 retrieval context 生成回答
5. `ConversationStore` 保存消息历史和引用来源
6. API 将结果以普通 JSON 或 SSE 格式输出

约束：

- 普通问答和 SSE 问答只允许输出形式不同
- 业务编排链必须完全复用
- 检索能力必须来自同一 `KnowledgeRetrievalService`

## 9. Dependency Rules

系统内部依赖方向固定如下：

```text
api -> application -> domain
application -> infrastructure (through ports)
infrastructure -> external systems
```

具体规则如下：

- `api` 可以依赖 `application` 和 API 自己的 request/response models
- `application` 可以依赖 `domain` 和端口绑定后的 infrastructure 实现
- `domain` 不能依赖 `api` 或 `infrastructure`
- `infrastructure` 可以依赖 `domain` 定义的端口和数据模型，但不能反向驱动 application 逻辑

## 10. Migration Mapping From Current Code

当前关键代码到目标模块的映射如下。

### 10.1 文档处理

当前：

- `backend/app/services/document_processor.py`

目标：

- 其流程编排职责迁移到 `application/documents/DocumentCommandService`
- 解析、分块、向量、入库分别通过端口接入
- 检索入口从该类中剥离，不再由 ingest orchestration 承担 search 职责

### 10.2 检索

当前：

- `backend/app/services/rag/retriever.py`

目标：

- `domain/retrieval` 中定义 `Retriever` 端口和统一检索结果模型
- `infrastructure/vectorstore` 中承载具体检索实现
- `application/knowledge/KnowledgeRetrievalService` 作为统一检索用例入口

### 10.3 Agent Workflow

当前：

- `backend/app/services/agent/qa_agent.py`

目标：

- workflow 编排职责迁移到 `application/agent/AgentConversationService`
- 具体 LLM 调用走 `AnswerGenerator`
- 具体 session 读写走 `ConversationStore`
- 检索统一走 `KnowledgeRetrievalService`

### 10.4 存储

当前：

- `backend/app/services/storage/minio_client.py`
- `backend/app/services/storage/milvus_client.py`

目标：

- MinIO 迁移到 `infrastructure/storage`
- Milvus 迁移到 `infrastructure/vectorstore`

### 10.5 解析

当前：

- `backend/app/services/parser/*`
- `backend/app/services/parser/mineru_parser.py`

目标：

- 全部迁移到 `infrastructure/parser`
- 对外只暴露统一 `DocumentParser` 端口实现

### 10.6 向量化

当前：

- `backend/app/services/embedding/*`

目标：

- 迁移到 `infrastructure/embedding`
- 对外只暴露统一 `EmbeddingProvider`

### 10.7 LLM

当前：

- `backend/app/services/llm/*`

目标：

- 迁移到 `infrastructure/llm`
- 由 `AnswerGenerator` 屏蔽 provider 差异

### 10.8 会话

当前：

- `backend/app/services/agent/session_manager.py`

目标：

- 迁移到 `infrastructure/session`
- 对外通过 `ConversationStore` 暴露

### 10.9 API 模型与内部模型

当前：

- `backend/app/api/models/*`
- `backend/app/schemas/*`

目标：

- 对外 request/response model 保留在 `api`
- 内部 DTO / VO / domain object 收敛到 `application` 或 `domain`
- 不允许 API model 直接渗透到 domain

## 11. Technology Replacement Boundaries

### 11.1 本地解析 / MinerU -> 阿里云文档解析

替换原则：

- 只替换 `DocumentParser` adapter
- `DocumentCommandService` 不应感知解析提供商差异
- `ChunkBuilder` 只接收统一解析结果模型

### 11.2 BGE-M3 -> OpenAI-compatible embedding

替换原则：

- 只替换 `EmbeddingProvider`
- `KnowledgeRetrievalService` 与 `DocumentCommandService` 不应感知 embedding 来源变化

### 11.3 Milvus `1024 + sparse` -> `1536 dense-only`

替换原则：

- 只替换 `VectorIndex` 实现
- collection schema、index 参数、dense-only search 属于 index 内部实现细节
- 上层 retrieval 和 agent workflow 不应因为 schema 变化而改业务接口

### 11.4 DeepSeek / Qwen 切换

替换原则：

- 只替换 `AnswerGenerator` 背后的 provider adapter
- 上层 conversation workflow 不应直接依赖具体模型 SDK

### 11.5 内存 session -> Redis / DB session

替换原则：

- 只替换 `ConversationStore`
- API 和 application service 不应感知 session 持久化细节

## 12. Guardrails

后续所有 backend 重构和新增功能必须遵守以下规则：

- 禁止 `api/routes` 直接实例化 parser、embedder、Milvus、MinIO、LLM client
- 禁止 `application` 层直接 import 第三方 SDK
- 禁止 `domain` 层依赖 FastAPI、Pydantic route model、MinIO SDK、Milvus SDK、LLM SDK
- 禁止 SSE 和普通问答各自维护独立 workflow
- 禁止把对象存储命名规则作为唯一业务元数据来源
- 禁止新建第二个“大一统流程类”替代 `DocumentProcessor`
- 禁止 `knowledge` 和 `agent` 各自维护独立检索实现
- 禁止 parser、embedding、vector index、llm provider 的替换穿透到 API 层

## 13. Architecture Review Checklist

后续评审和重构验收时，至少核对以下问题：

1. 上传、下载、列表、解析、切片、向量、入库、检索、Agent Workflow 是否都映射到了明确模块。
2. 系统是否仍保持单服务，而不是被动演化成伪微服务结构。
3. 是否存在唯一、清晰的目标目录结构。
4. 是否定义了稳定端口列表。
5. 是否定义了文档上传入库、文档查询、Agent 问答三条核心 workflow。
6. 是否定义了单向依赖方向。
7. 是否明确列出了架构禁令。
8. 是否定义了当前关键代码到目标模块的映射。
9. 是否明确定义了 parser、embedding、vector index、LLM、session store 的替换边界。
10. 是否明确 `knowledge` 与 `agent` 共用同一 retrieval 底座。
11. 是否明确 API 层只负责 transport concerns，不再直接承担业务编排。
12. 是否保证后续替换方案时，上层 application service 与外部 API 契约不被迫变化。