# 报告解析服务部署依赖（LangGraph + 共享 uploads 卷）

> 任务：T29-B3-5（P2-8 环境依赖补强）
> 适用：健康报告「代传」链路（`/api/health/report/proxy-parse` → LangGraph `/api/v1/report/parse`）及
> 非代传两阶段链路（`/report/upload` + `/report/parse`）在**生产/容器化环境**部署时的强制检查项。

## 背景

Java 后端（Spring Boot，`cfc-backend`）解析健康报告 PDF 时，**优先调用 LangGraph 服务**
（`cfc-langgraph`，FastAPI，端口 9000，生产域名 `ai.etotem.com.cn`）做结构化解析，失败才回退本地 Java 解析。

- 后端配置：`cfc-backend/src/main/resources/application.yml` 的 `langgraph.base-url`
  （默认 `http://localhost:9000`，仅开发环境可用）。
- 文件通路：后端先把上传的 PDF 落盘/落 OSS，再经 `storageService.getFilePath(fileUrl)` 得到本地绝对路径，
  传给 LangGraph 的 `file_path`。**LangGraph 容器必须能读到该路径**。

## 强制检查项清单（部署前逐条确认，缺一不可）

### 1. `LANGGRAPH_BASE_URL` 环境变量必须显式设置，禁止使用默认 localhost

```yaml
# application.yml（生产必须覆盖默认值）
langgraph:
  base-url: ${LANGGRAPH_BASE_URL:http://localhost:9000}
```

| 环境 | 要求 |
|------|------|
| 开发 | 可保持默认 `http://localhost:9000`（需本机已启动 `cfc-langgraph`） |
| 生产/容器化 | **必须**设置 `LANGGRAPH_BASE_URL=https://ai.etotem.com.cn`（或内网 LangGraph 地址），否则后端会尝试连容器内 `localhost:9000` 而失败，报告解析退化为本地 Java 解析（功能可用但解析质量下降） |

> 检查命令：确认部署清单/启动脚本中已注入 `LANGGRAPH_BASE_URL`，且值与 LangGraph 服务实际地址一致。

### 2. uploads 目录必须与 LangGraph 容器共享同一 volume

后端 `upload.base-dir`（默认 `/data/cfc-uploads`）存放上传文件；`getFilePath` 返回的绝对路径
会被直接作为 LangGraph 请求体 `file_path`。若 Java 容器与 LangGraph 容器**不共享该目录**，
LangGraph 侧 `File(file_path)` 不存在 → 解析失败 → 回退本地解析（或整链失败）。

| 环境 | 要求 |
|------|------|
| 本地非容器 | 同一主机目录即可，无额外要求 |
| 容器化 | `cfc-backend` 与 `cfc-langgraph` 两个容器**必须挂载同一个 host 目录**（如 `/data/cfc-uploads`）到各自容器内相同路径；`cfc-backend` 的 `upload.base-dir` 与 LangGraph 读取 `file_path` 的目录必须是**同一目录** |

> 检查命令：
> ```bash
> # 确认两个容器挂载同一 uploads 卷
> docker inspect cfc-backend   # 查看 Mounts → Source/Target
> docker inspect cfc-langgraph # 查看 Mounts → Source/Target
> # 两者 target（容器内路径）必须一致，且等于 upload.base-dir 解析后的绝对路径
> ```

### 3. `python.executable` 本地兜底依赖（非容器可跳过）

本地（非容器）环境使用本地 Java 解析兜底时，`pdfParseService` 不依赖外部脚本；仅异步采集链路
（`report.collect`）依赖 `python` 可执行文件。生产容器化环境无需该检查（LangGraph 承担解析）。

## 环境变量一览（报告解析相关）

| 变量 | 默认值 | 生产必须 | 说明 |
|------|--------|:--------:|------|
| `LANGGRAPH_BASE_URL` | `http://localhost:9000` | ✅ | LangGraph 报告解析服务地址（生产 `https://ai.etotem.com.cn`） |
| `upload.base-dir` | `/data/cfc-uploads` | ✅ | 上传文件根目录，须与 LangGraph 容器共享 |
| `storage.type` | `jdcloud` | — | `jdcloud`（OSS）或 `local`（本地磁盘）；`local` 时共享卷要求更严格 |

## 验收（部署后自检）

1. 用一份真实募极生物肠道菌群报告 PDF 走 `/api/health/report/proxy-parse`，响应 `parseMethod="langgraph"`
   （而非 `"local"`）→ 证明 LangGraph 通路可用。
2. 若返回 `parseFallback=true`（`parseMethod="local"`），说明 LangGraph 未打通，按本清单第 1/2 项排查。