architecture-analysis.md 20 KB
财顾报告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 接口契约
# 一级大纲生成
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