finrep-report/STRUCTURE.md

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 持久化。