# 财顾报告Agent MVP 架构分析文档

> 分析依据：
> - 《财顾报告Agent-技术架构与选型.md》
> - 《财顾报告生成智能体后端及算法端功能模块描述及其实现思路.md》
> - 《财顾报告智能化生成产品MVP版本需求文档.md》

---

## 1. 系统上下文与边界

### 1.1 系统上下文图

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                              外部系统/用户                                    │
│  ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐              │
│  │ 业务人员  │    │  行内SSO │    │ 工商/风险 │    │ 指标平台 │              │
│  │ (浏览器) │    │          │    │   接口   │    │          │              │
│  └────┬─────┘    └────┬─────┘    └────┬─────┘    └────┬─────┘              │
└───────┼───────────────┼───────────────┼───────────────┼─────────────────────┘
        │               │               │               │
        ▼               ▼               ▼               ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                           财顾报告Agent系统                                  │
│  ┌───────────────────────────────────────────────────────────────────────┐ │
│  │                         前端 Web (React SPA)                          │ │
│  │     向导/状态看板  ──  大纲确认树  ──  数据展示/补录  ──  报告预览       │ │
│  └───────────────────────────────────────────────────────────────────────┘ │
│                                    │                                        │
│                                    ▼                                        │
│  ┌───────────────────────────────────────────────────────────────────────┐ │
│  │                    Java业务后端 (Spring Boot)                         │ │
│  │  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐         │ │
│  │  │GW接入层 │ │ORCH编排 │ │ HITL    │ │ SVC服务 │ │ REPO    │         │ │
│  │  │- 鉴权   │ │- 状态机 │ │- 卡点   │ │- 取数   │ │- 持久化 │         │ │
│  │  │- 租户   │ │- 任务   │ │- 确认   │ │- OSS    │ │- 查询   │         │ │
│  │  │- 限流   │ │- MQ     │ │- 版本   │ │- 导出   │ │         │         │ │
│  │  └─────────┘ └─────────┘ └─────────┘ └─────────┘ └─────────┘         │ │
│  │                              │                                        │ │
│  │                              ▼                                        │ │
│  │                       ┌─────────────┐                                 │ │
│  │                       │   ADAPTER   │                                 │ │
│  │                       │ 算法适配层   │                                 │ │
│  │                       └──────┬──────┘                                 │ │
│  └──────────────────────────────┼───────────────────────────────────────┘ │
│                                 │                                          │
│                                 ▼                                          │
│  ┌───────────────────────────────────────────────────────────────────────┐ │
│  │                   Python算法服务 (FastAPI)                            │ │
│  │  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐                     │ │
│  │  │   AG    │ │   RAG   │ │ PROMPT  │ │   MW    │                     │ │
│  │  │- L1大纲 │ │- 解析   │ │- Jinja  │ │- 路由   │                     │ │
│  │  │- L2大纲 │ │- 检索   │ │- 校验   │ │- 重试   │                     │ │
│  │  │- 段落   │ │- 拼装   │ │- 版本   │ │- 降级   │                     │ │
│  │  └─────────┘ └─────────┘ └─────────┘ └─────────┘                     │ │
│  └───────────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘
        │                               │               │
        ▼                               ▼               ▼
┌───────────────┐               ┌───────────────┐ ┌───────────────┐
│    模型集群    │               │   运行支撑    │ │   对象存储    │
│ (OpenAI兼容) │               │ - MySQL/PostgreSQL │   (OSS)    │
│               │               │ - Redis       │ │               │
│               │               │ - MQ(可选)    │ │               │
└───────────────┘               └───────────────┘ └───────────────┘
```

### 1.2 系统边界定义

| 边界 | 包含内容 | 排除内容 |
|------|----------|----------|
| 系统内 | 任务管理、大纲生成与确认、数据准备、报告生成、结果导出 | - |
| 系统外(对接) | 行内SSO、工商接口、风险接口、指标平台、模型集群 | - |
| 本期不建 | - | 知识配置端、数据资源配置端、权限管理中心 |

---

## 2. 核心模块与职责

### 2.1 模块职责矩阵

| 模块 | 核心职责 | 关键设计决策 |
|------|----------|--------------|
| **GW接入层** | 鉴权、租户上下文、审计、限流 | 对接行内SSO，Token透传；租户ID贯穿全链路 |
| **ORCH编排** | 任务状态机、阶段驱动、MQ异步化 | 状态为真相源；Python为无状态执行器 |
| **HITL卡点** | 大纲确认持久化、数据确认持久化、版本追溯 | 确认权在Java侧，Python不拥有写权限 |
| **SVC服务** | 取数编排、OSS集成、行内HTTP调用、导出 | 结构化指标走Java，非结构化走Python RAG |
| **REPO持久层** | 任务/大纲/数据包/报告落库 | 租户列强制存在，预留归档策略 |
| **ADAPTER适配** | HTTP/gRPC调用Python、契约校验、错误映射 | 禁止前端直连Python，所有流量经Java |
| **AG算法核心** | L1/L2大纲生成、段落生成 | 分阶段调用，单次不堆砌全篇材料 |
| **RAG检索** | 文档解析、分块、向量检索、拼装 | 按task_id隔离集合 |
| **PROMPT模板** | Jinja模板管理、JSON Schema校验 | 模板版本化，与需求文档逐条对齐 |
| **MW模型网关** | 多模型路由、重试降级、可观测 | OpenAI兼容，本地并发保护 |

### 2.2 关键调用链

```
任务创建链:
前端 → GW → ORCH(创建任务) → REPO(落库) → 返回taskId

大纲生成链:
前端 → GW → ORCH(触发生成) → ADAPTER → Python/AG → MW → 模型
  ← 返回结构化JSON ← 校验 ← 落库 ← 状态更新

大纲确认链:
前端(树状操作) → GW → HITL(持久化确认结果) → ORCH(推进状态)

数据准备链:
ORCH → SVC(并行取数: 行内API/指标/RAG) → REPO(按知识单元落库)

报告生成链:
ORCH → ADAPTER → Python/AG(逐段生成) → MW → 模型
  ← 单段结果 ← 拼接 ← 完整报告 ← 落库
```

---

## 3. 关键接口与数据流

### 3.1 Java ↔ Python 接口契约

```yaml
# 一级大纲生成
POST /v1/outline/l1
Headers:
  X-Tenant-Id: {tenant_id}
  X-Task-Id: {task_id}
  X-Trace-Id: {trace_id}
  Authorization: Bearer {service_token}
Body:
  report_type: string
  agreement_amount: number
  enterprise_type: string
  # ... 其他任务输入
  chapter_candidates: [] # 一级章节候选清单
Response:
  chapter_results: [
    {chapter_id, chapter_name, paragraph_count_enum, reason}
  ]
  overall_logic: string

# 二级大纲生成  
POST /v1/outline/l2
Body:
  chapter_name: string
  chapter_no: string
  chapter_paragraph_count_enum: string
  # ... 一级章节结果
  leaf_chapter_candidates: [] # 末级章节候选
Response:
  chapter_name: string
  chapter_no: string
  chapter_structure: [
    {node_id, node_name, node_no, node_level, parent_node_id, source_type, source_candidate_name, is_selected}
  ]
  structure_logic: string

# 段落生成
POST /v1/section
Body:
  knowledge_unit_id: string
  report_type: string
  # ... 任务基础信息
  paragraph_logic: string # 段落撰写逻辑
  paragraph_position: string # 段落定位
  data_package: object # 数据包
  template_type: string # 四级模板类型
Response:
  generated_text: string
  usage: {prompt_tokens, completion_tokens}
```

### 3.2 数据流示意图

```
┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  任务输入    │────▶│  一级大纲    │────▶│  二级大纲    │
│  (结构化)   │     │  (结构化)   │     │  (树状结构)  │
└─────────────┘     └─────────────┘     └──────┬──────┘
                                               │
                                               ▼ 人工确认
┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  完整报告    │◀────│  段落生成    │◀────│  最终知识单元│
│  (文本拼接) │     │  (逐段生成) │     │  清单确认   │
└─────────────┘     └─────────────┘     └──────┬──────┘
                                               ▲
                                        ┌──────┴──────┐
                                        │  数据准备    │
                                        │ (多源聚合)  │
                                        └─────────────┘
```

---

## 4. 数据与一致性策略

### 4.1 核心数据对象

| 对象 | 存储位置 | 一致性要求 | 说明 |
|------|----------|------------|------|
| 报告任务 | MySQL | 强一致 | 主对象，贯穿全生命周期 |
| 任务状态 | MySQL | 强一致 | 状态机驱动，原子更新 |
| 一级大纲结果 | MySQL | 最终一致 | 含原始输出和解析结果 |
| 最终知识单元清单 | MySQL | 强一致 | 经人工确认，后续执行依据 |
| 知识单元数据包 | MySQL | 强一致 | 自动获取+人工补录合并 |
| 单段生成结果 | MySQL | 最终一致 | 原子段落，支持问题排查 |
| 完整报告 | MySQL/OSS | 最终一致 | 过大时可存OSS |
| 上传材料 | OSS | 最终一致 | 预签名URL访问 |
| RAG向量索引 | 向量库 | 最终一致 | 按task_id隔离 |

### 4.2 一致性策略

```
┌─────────────────────────────────────────────────────────────┐
│                      一致性决策矩阵                          │
├─────────────────────────────────────────────────────────────┤
│  场景                    │  策略                            │
├─────────────────────────────────────────────────────────────┤
│  状态推进+结果写入        │  同一事务或Outbox模式            │
│  MQ消息+DB写入           │  本地事务表+异步发送 或 事务消息   │
│  Java调用Python          │  重试幂等，Python无状态          │
│  缓存(进度等)            │  最终一致，可接受短暂不一致       │
│  多副本OSS              │  由OSS保证最终一致               │
└─────────────────────────────────────────────────────────────┘
```

### 4.3 租户隔离策略

- **强制租户列**：所有业务表必须包含 `tenant_id` 列
- **索引设计**：复合索引 `(tenant_id, task_id)` 或 `(tenant_id, created_at)`
- **查询拦截**：ORM层或MyBatis插件自动注入租户条件
- **存储隔离**：OSS路径按 `/{tenant_id}/{task_id}/` 组织

---

## 5. 非功能需求

### 5.1 安全需求

| 安全域 | 需求 | 实现建议 |
|--------|------|----------|
| 认证 | 对接行内SSO | JWT Token验证，刷新机制 |
| 授权 | 服务间调用认证 | mTLS或HMAC签名 |
| 数据脱敏 | 敏感字段不下传Python | Java侧脱敏，Python消费OSS只读链接 |
| 审计 | 关键API访问记录 | AOP切面+异步写审计表 |
| 传输安全 | 全链路TLS | 证书由基础设施统一管理 |

### 5.2 性能需求

| 指标 | 目标值 | 备注 |
|------|--------|------|
| 任务创建 | < 500ms | 不含文件上传 |
| 大纲生成(一级) | < 30s | 单次LLM调用 |
| 大纲生成(二级) | < 60s | 多章节循环调用 |
| 单段生成 | < 30s | 段落级调用 |
| 整篇报告生成 | < 5min | 20-30段，可异步 |
| 页面加载 | < 2s | 大纲树、数据展示页 |
| 并发任务 | 10+ | MVP阶段 |

### 5.3 可观测性

```
┌─────────────────────────────────────────────────────────────┐
│                      可观测性分层                            │
├─────────────────────────────────────────────────────────────┤
│  日志层                                                      │
│    - TraceId贯穿全链路 (前端 → Java → Python → 模型)        │
│    - MDC上下文：tenantId, taskId, userId, stage              │
│    - 结构化日志，便于聚合检索                                 │
├─────────────────────────────────────────────────────────────┤
│  指标层                                                      │
│    - Java: JVM、HTTP接口、DB连接池、Redis                    │
│    - Python: 请求数、延迟、Token消耗、模型路由分布            │
│    - 业务: 任务阶段分布、生成成功率、各阶段耗时               │
├─────────────────────────────────────────────────────────────┤
│  链路层                                                      │
│    - OpenTelemetry或SkyWalking                              │
│    - 关键Span: 大纲生成、段落生成、数据获取                   │
├─────────────────────────────────────────────────────────────┤
│  告警层                                                      │
│    - 核心接口P99延迟突增                                      │
│    - 模型调用失败率>5%                                        │
│    - 任务状态卡住(超过预期时间未推进)                          │
└─────────────────────────────────────────────────────────────┘
```

---

## 6. 技术风险与 ADR 摘要

### 6.1 关键技术决策(ADR)

#### ADR-001: Java + Python 双端架构

**背景**：业务后端(Java)与算法端(Python)的分工边界

**决策**：采用 Web → Java → Python → Java 的调用链，Python不直接暴露给前端

**理由**：
- 与行内常见分工一致
- 安全、网关、审计统一落在Java
- Python专注智能计算，不替代Java做持久化

**后果**：
- 需要定义清晰的HTTP/gRPC契约
- Java成为潜在性能瓶颈，需合理设计异步化

---

#### ADR-002: 任务状态机以Java为真相源

**背景**：任务状态分布在Java还是Python

**决策**：任务状态真相源在Java，Python为无状态执行器

**理由**：
- 事务、安全、集成主控在Java
- Python故障不影响任务状态一致性
- 便于后续扩展和审计

**后果**：
- Python需幂等设计
- Java需管理异步调用状态

---

#### ADR-003: 分段生成而非长文本生成

**背景**：报告生成方式选择

**决策**：按知识单元逐段生成，最后拼接

**理由**：
- 适配行内模型能力约束
- 降低单次调用失败影响范围
- 预留段落级重生成扩展点

**后果**：
- 段落间衔接一致性挑战
- 总生成时间较长，需异步化

---

#### ADR-004: 结构化大纲输出

**背景**：大纲生成输出格式

**决策**：强制JSON Schema结构化输出

**理由**：
- 便于程序解析和后续处理
- 支持人工确认界面生成
- 降低模糊性

**后果**：
- 提示词工程复杂度增加
- 需要校验和重试机制

---

### 6.2 技术风险清单

| 风险ID | 风险描述 | 可能性 | 影响 | 缓解措施 |
|--------|----------|--------|------|----------|
| R-001 | 模型输出JSON解析失败 | 中 | 高 | Schema校验+重试+降级提示 |
| R-002 | 长耗时生成导致超时 | 中 | 中 | MQ异步化+进度推送+可查询状态 |
| R-003 | Python服务故障影响生成 | 低 | 高 | 健康检查+熔断+优雅降级 |
| R-004 | 行内接口响应慢/故障 | 中 | 中 | 超时配置+熔断+Mock数据 |
| R-005 | 多租户数据隔离失效 | 低 | 高 | ORM层强制注入+审计对账 |
| R-006 | 敏感数据泄露 | 低 | 高 | 脱敏+权限控制+审计日志 |

---

*文档版本：MVP阶段*
*最后更新：2026-03-31*