finrep-report/design.txt

Java 业务后端（Spring Boot）各模块
2.1 GW｜接入：鉴权、审计、租户、限流
要实现的功能
鉴权与身份：对接行内 SSO / JWT / 网关透传头，识别用户与组织机构。
租户上下文：解析
并注入
tenant
id
/
_
org_
id
（或默认租户） ，贯穿后续 ORCH、REPO、
ADAPTER 调用链。
审计：记录关键 API 的访问主体、资源、时间、结果；满足后续合规扩展。
限流与防护：接口级 / 租户级限流，防止任务创建洪峰或暴力重试打穿后端与算法端。
实现思路（概要）
Spring Security + Filter 链：认证完成后将
TenantContext
UserPrincipal
放入 SecurityContext
或 请求级 ThreadLocal，
并由 WebMvc 拦截器向下传递。
限流：网关（若有）+ 应用内 Redis 令牌桶 / 滑动窗口；与租户配额策略表或配置中心联动。
审计：AOP 切面 + 异步写审计表；TraceId 与日志 MDC 对齐。
2.2 ORCH｜任务状态机：大纲 → 数据 → 成文 →
完成
要实现的功能
维护报告任务全生命周期：与需求文档一致的状态（如：待生成大纲、待确认大纲、待准备数据、
待确认数据、待生成报告、生成中、待查看结果、完成、失败等） 。
驱动
阶段迁移：在满足
前置条件（含人工确认落库）后，触发下一阶段；失败时进入可恢复或失败
终态。
与异步解耦：长耗时阶段（
整段大纲生成、全文段落批量）可 投递 MQ，由 Worker 拉活后继续调
ORCH 或直连 ADAPTER/SVC。
编排 Python 调用时机：仅在允许的阶段调用 ADAPTER；对 Python 返回做业务校验后写
REPO。
实现思路（概要）
枚举 + 显式转移表 或 Spring State Machine：转移函数内只做「校验 → 调用领域服务 → 持久化
状态」 ；避免在 Controller 写长流程。
应用服务分层（参考 finrep-application/orchestration
） ： command
表示写操作、与事务边界对
齐；幂等键防重复提交。
MQ：消
息体带 taskId 、 stage 、 tenantId ；Consumer 幂等消费（基于 DB 状态或 Redis 去
重） 。
2.3 HITL｜人工卡点持久化：大纲确认 / 数据确认
要实现的功能
大纲确认：持久化业务人员在预置知识体系范围内的勾选、取消、顺序调整结果，
形成最终知识单
元清单版本，供后续数据准备与成文唯一依据。
数据确认：持久化每知识单元的「系统自动取数结果 + 文本补录」合并后的数据包及确认状态。
版本与可追溯：可选记录确认人、确认时间、与模型草稿的差异标记
，便于审计与问题复盘。
实现思路（概要）
独立聚合表：任务 ID + 阶段 + 版本号；确认提交为一次事务：更新清单/数据包 + 推进 ORCH 状
态。
服务端强校验：禁止未配置知识单元、禁止
越
权改写结构树；与领域文档「受控生成」一致。
不将「确认权」下放 Python；Python 只消费已确认快照或 Java 明确下发的只读 DTO。
2.4 SVC｜取数编排、OSS、导出、行内 HTTP（工商/指标等）
要实现的功能
取数编排：按「知识单元 × 数据绑定」拉起 HTTP 调用、指标平台查询；将异构结果规整为可展
示、可合并的字段（供前端与 Prompt 占位符） 。
OSS：上传材料存储、预签名下载；与任务、租户路径策略绑定。
行内 HTTP：工商、风险、其他资质类接口；统一超时、重试、熔断、证书。
导出：将已定稿报告生成 DOCX/PDF（或异步任务） ；敏感留痕与文件留存策略由行内规范决定。
实现思路（概要）
端口-适配器：application 定义 DataSourcePort
，infrastructure 里按类型实现（REST、指标
SDK、Mock） 。
连接池与隔离：按下游系统分 RestTemplate/WebClient Bean，避免单点超时拖垮全站。
导出：模板 + docx4j/POI；大文件走异步 + 任务状态回写。
2.5 REPO｜任务 / 大纲 / 数据包 / 报告落库
要实现的功能
持久化任务主档、一级/二级大纲结果、最终知识单元清单、各单元数据包、单段生成结果、完
告正文与元数据。
支持按 租户 + 任务 ID 查询与列表分页；关键中间结果可 JSON 列存储并可追溯。
与 ORCH 状态原子一致：状态推进与结果写入同事务或外显状态机 + Outbox（若 MQ 与库强一
致） 。
实现思路（概要）
MyBatis / JPA + Flyway/Liquibase；热点表
预留归档策略。
大文本：可考虑与 OSS 协同（正文过大时） ，MVP 以库内 CLOB/JSON 为主亦可。
租户列 + 索引：所有业务表强制
tenant
id
，避免交叉租户访问。
_
整报
2.6 ADAPTER｜Agent 适配层：HTTP/gRPC 调用 Python
要实现的功能
将 Java 内部的「阶段请求」转换为 Python 算法服务约定的 OpenAPI / gRPC 请求。
注入 服务间认证、TraceId、TenantId、TaskId、幂等键；处理超时、重试、熔断与可映射错误
码。
误） 。
对 Python 返回的 JSON / 二进制做反序列化与契约校验（字段缺失、类型不符打业务可理解错
实现思路（概要）
OpenFeign / WebClient + Resilience4j；超时：大纲可能 30–120s，段落可更短，分级配置。
DTO 与
finrep-contract/openapi
对齐；可选代码生成减少手写漂移。
严禁前端直连 Python；所有流量经 Java，便于审计与脱敏。