# 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 对齐字段、模型版本记录。 |

---

## 四、三端协作关系（回顾）

```text
浏览器 → frontend → backend（REST + SSE）
                    → backend.integration.pythonagent → algo（REST）
```

任务与人工确认的 **权威状态** 在 **backend 数据库**；`algo` 尽量 **无状态或可重建**，输出结构化结果供 Java 持久化。