STRUCTURE.md 12 KB
finrep-report 工程目录说明
本仓库为 单仓（Monorepo），聚合 Web 前端、Java 业务后端、Python 算法 / Agent 三端。前端 只调用 Java 后端；Java 通过 pythonagent 适配层调用 algo 服务。
约定：Java 根包名为 com.yuxin.finrep；Python 包根为 finrep_algo_agent。目录中当前多为占位（.gitkeep），后续可在此结构上添加 package.json、pom.xml、pyproject.toml 等。
一、frontend/（Web 前端）
面向业务人员的 浏览器 SPA（建议技术栈：React + 企业级组件库）。不直接请求算法端；统一走 backend 提供的 HTTPS API 与 SSE。
| 子目录 | 作用 |
|---|---|
public/ |
不参与打包的静态资源：如 favicon.ico、robots.txt、固定可缓存的公共文件等。 |
src/assets/ |
需经构建处理的资源：图片、图标、小号字体等（由打包工具优化路径与哈希）。 |
src/components/ |
可复用 UI 组件；其中 common/ 放置与设计系统无关的通用控件（按钮封装、空状态、加载中等）。业务强相关大块可再建 features/ 等子目录（按需扩展）。 |
src/layouts/ |
整体布局壳：顶栏、侧栏、内容区组合；各业务页挂载在布局之下。 |
src/pages/ |
页面级入口：与路由一一对应，例如任务列表、任务向导、大纲确认树、数据确认、报告预览与导出等。 |
src/routes/ |
路由表、路由守卫（登录态、权限）、懒加载页面配置。 |
src/services/ |
HTTP / SSE 客户端封装：调用 Java 的 REST、订阅任务进度；集中处理 baseURL、Token、错误码与 TraceId 头（若规范要求）。 |
src/hooks/ |
React Hooks：如任务轮询、SSE 连接、表单与向导步骤状态等与 UI 紧耦合的复用逻辑。 |
src/stores/ |
全局或跨页状态（Redux、Zustand、Recoil 等选型待定）：当前任务、用户信息、租户上下文等。 |
src/utils/ |
纯函数工具：日期格式化、树数据转换、与后端 DTO 对齐的轻量映射等。 |
src/styles/ |
全局样式、CSS 变量、主题 token；与组件库主题对齐。 |
src/types/ |
TypeScript 类型：与后端 OpenAPI 生成或手写对齐的请求 / 响应、枚举、领域 DTO。 |
tests/ |
前端单测 / 组件测（如 Vitest + Testing Library）；与 src 目录结构可镜像或按需组织。 |
二、backend/（Java 业务后端）
Spring Boot 多模块 结构：承载 鉴权、多租户、任务状态机、落库、行内接口、OSS、导出，以及 调用算法服务的 HTTP/gRPC 客户端。
2.1 模块总览
| 模块 | 作用 |
|---|---|
finrep-parent |
父 POM（后续添加）：统一依赖版本、插件、子模块列表。 |
finrep-common |
跨模块通用代码：上下文、异常、工具、常量。 |
finrep-domain |
领域模型与领域语义分包（任务、大纲、数据准备、生成等），不依赖 Web 与具体持久化框架（或仅依赖极少注解，按团队规约）。 |
finrep-application |
应用服务层：编排 / 状态机推进、用例（command/query）、入站/出站端口接口、面向产品的策略（如选默认模型策略的 Java 侧部分）。 |
finrep-infrastructure |
落地实现：数据库、Redis、MQ、对象存储、外部 HTTP、pythonagent、可观测性配置等。 |
finrep-web |
对外 HTTP/SSE：REST 控制器、请求/响应 DTO、安全、全局异常、WebMvc 配置。 |
finrep-worker |
异步消费者（与 MQ 配合）：长耗时阶段消费、分布式锁、可选定时补偿。 |
finrep-contract |
OpenAPI 等契约：openapi/ 下放 YAML/JSON，可供前后端与 Python 对齐（与 Java 代码生成配置配合使用）。 |
docs/ |
后端专项说明（部署参数、环境约定等），与仓库根目录产品文档区分。 |
2.2 finrep-common 包路径 .../common/
| 包 | 作用 |
|---|---|
context |
TenantContext、UserContext、traceId 等在请求链路中的承载与 ThreadLocal/传递封装。 |
exception |
业务异常基类、错误码枚举；与 web 层统一异常 advice 对应。 |
util |
通用工具类（字符串、集合、JSON 辅助等）。 |
constant |
全局常量、HTTP 头名称约定、状态枚举与持久化一致时集中定义（或与 domain 协同）。 |
2.3 finrep-domain 包路径 .../domain/
| 包 | 作用 |
|---|---|
task |
报告任务聚合、任务生命周期、状态机枚举（领域语义层面）。 |
outline |
一级/二级大纲、最终知识单元清单等领域对象与规则（不含 HTTP 与 ORM）。 |
dataprep |
知识单元数据包、数据确认等领域概念。 |
generation |
单段生成结果、完整报告等领域概念。 |
knowledge |
与「知识单元 / 适用范围」相关的领域类型（若与预置配置边界相关）。 |
tenant |
租户/组织值对象、隔离相关领域规则。 |
shared |
域内多处共用的值对象、标识符类型等。 |
2.4 finrep-application 包路径 .../application/
| 包 | 作用 |
|---|---|
orchestration |
主链路编排：阶段推进、与人工卡点协作、调用出站端口（持久化、MQ、算法客户端）。 |
command |
写用例：创建任务、提交大纲确认、提交数据确认、触发生成等。 |
query |
读用例：任务详情、大纲草稿、数据包展示、报告预览数据等。 |
service |
复杂用例实现类、跨聚合协调（若与 command/query 拆分并行存在）。 |
policy |
应用层策略：例如 Java 侧路由到不同算法接口、租户级功能开关等。 |
port/in |
入站端口：由 web 或 worker 调用的应用服务接口。 |
port/out |
出站端口：持久化、缓存、消息、算法服务、OSS 等由 infrastructure 实现的接口定义。 |
2.5 finrep-infrastructure 包路径 .../infrastructure/
| 包 | 作用 |
|---|---|
persistence/entity |
JPA Entity / 或 MyBatis PO 等，与表结构对应。 |
persistence/repository |
仓储实现：封装 SQL / JPA 访问。 |
persistence/mapper |
MyBatis Mapper 接口与 XML（若选用 MyBatis）。 |
redis |
分布式锁、缓存、限流计数、任务进度缓存等。 |
mq/producer |
投递异步任务消息。 |
mq/consumer |
若部分消费逻辑共享；也可仅放在 finrep-worker 由团队二选一。 |
mq/message |
消息体 DTO、Topic/Tag 常量。 |
integration/http |
调用行内 HTTP API（工商、风险、通用网关等）。 |
integration/metrics |
指标平台或统一数据服务客户端。 |
integration/external |
其他外部系统适配（与 metrics/http 并列归类）。 |
integration/pythonagent |
调用 algo（Python） 的客户端：OpenAPI 生成或手写 WebClient/Feign；统一超时、重试、mTLS/Token、TraceId 传递。 |
storage/oss |
对象存储上传/下载/预签名 URL。 |
config |
Bean 装配、多数据源、RestTemplate/WebClient 工厂等。 |
observability |
日志 MDC、MeterRegistry、Tracing 与 Java 侧埋点。 |
resources/db/migration |
Flyway / Liquibase 脚本目录。 |
2.6 finrep-web 包路径 .../web/
| 包 | 作用 |
|---|---|
rest/dto |
入参/出参对象；与 OpenAPI 一致。 |
rest/advice |
全局异常、统一响应包装、参数校验错误映射。 |
sse |
Server-Sent Events：向浏览器推送任务阶段、当前知识单元进度等。 |
security |
Spring Security：认证、鉴权、从令牌解析租户/用户。 |
config |
Web 层专属配置：CORS、国际化、Jackson 等。 |
resources/static / templates：若需服务端薄模板或静态页（多数 SPA 仅 static 放空由 Nginx 托管前端构建产物）。
2.7 finrep-worker 包路径 .../worker/
| 包 | 作用 |
|---|---|
consumer |
MQ 监听入口：收到消息后调用 application 层推进或调用算法。 |
handler |
按消息类型拆分的处理逻辑（大纲生成、全文生成批次等）。 |
scheduler |
可选 @Scheduled：重试、超时扫描、清理临时数据。 |
config |
Worker 进程专属配置（线程池、并发度等）。 |
三、algo/（Python 算法 / Agent 服务）
FastAPI（建议） 对内提供 OpenAI 兼容 大模型调用与 报告专用技能：一级/二级大纲、段落生成、RAG 检索等。由 backend 内网调用；不对公网暴露（或与网关结合白名单）。
| 子目录 | 作用 |
|---|---|
src/finrep_algo_agent/api/routers |
HTTP 路由：按技能或资源划分 POST /v1/outline/l1 等接口定义。 |
src/finrep_algo_agent/api/deps |
FastAPI Depends：鉴权、限流、公共请求体解析、从 Header 注入 trace/tenant。 |
src/finrep_algo_agent/agent |
多步编排入口：LangGraph 或状态图定义、Human-in-the-loop 占位（实际卡点仍在 Java/库表时，此处仅接收已确认上下文）。 |
src/finrep_algo_agent/skills/outline_l1 |
一级大纲技能：拼装 Prompt、调模型、解析/校验 JSON、返回结构化一级章节结果。 |
src/finrep_algo_agent/skills/outline_l2 |
二级大纲 / 知识单元装配技能：按章调用、章节编号结构、与需求文档 JSON 契约对齐。 |
src/finrep_algo_agent/skills/section_gen |
按知识单元生成正文技能：模板变量注入、段落级调用与拼接顺序由 Java 调多次或一次批处理（按设计定）。 |
src/finrep_algo_agent/skills/rag_retrieve |
仅检索：返回引用片段供上游拼 Prompt；或由 services 组合进 section_gen。 |
src/finrep_algo_agent/llm/client |
OpenAI 兼容 HTTP 客户端封装（base_url、api_key、超时）。 |
src/finrep_algo_agent/llm/router |
多模型路由：按请求元数据选择模型别名、主备降级。 |
src/finrep_algo_agent/llm/providers |
各厂商/集群差异适配（若路由不足以覆盖）。 |
src/finrep_algo_agent/rag/ingestion |
文档解析、分块、写入向量库（离线或准实时任务）。 |
src/finrep_algo_agent/rag/retrieval |
查询改写、相似度检索、重排序（若需要）。 |
src/finrep_algo_agent/rag/vectorstore |
向量库访问封装（pgvector、Milvus 等）。 |
src/finrep_algo_agent/prompts/templates |
Jinja2 / 文本模板文件；与需求文档章节结构对齐的版本管理。 |
src/finrep_algo_agent/prompts/builders |
从领域 DTO 生成 messages 列表的构建器代码。 |
src/finrep_algo_agent/schemas |
Pydantic 模型：请求/响应、大纲 JSON、与 Java DTO 命名对齐说明。 |
src/finrep_algo_agent/services |
组合技能与仓储的高层服务；供 routers 薄层调用。 |
src/finrep_algo_agent/core |
领域无关内核：常量、共用异常、运行模式枚举等。 |
src/finrep_algo_agent/config |
pydantic-settings / 环境变量：模型 URL、密钥（来自密钥管理）、功能开关。 |
src/finrep_algo_agent/observability |
日志结构化、Metrics、与 OpenTelemetry 对接。 |
tests/unit |
单测：解析、Prompt 构建、mock LLM。 |
tests/integration |
集成测：需真实或 testcontainers 模型/向量库时启用。 |
scripts/ |
一次性脚本：索引重建、批量评测、Prompt 回归等。 |
deploy/ |
Dockerfile、k8s YAML、行内发布说明。 |
docs/ |
算法侧设计：接口契约、与 Java 对齐字段、模型版本记录。 |
四、三端协作关系（回顾）
浏览器 → frontend → backend（REST + SSE）
→ backend.integration.pythonagent → algo（REST）
任务与人工确认的 权威状态 在 backend 数据库；algo 尽量 无状态或可重建，输出结构化结果供 Java 持久化。