# AI 事故信息采集 API（LangGraph 迁移分支）

本分支是“将对话后端从 FastGPT 工作流迁移到 LangGraph”课程的迁移准备分支。

当前状态：对外 API 契约保持不变，`/chat` 的供应商细节已封装到后端适配层（FastGPT 仍
为唯一实现），迁移计划见 [docs/langgraph-backend-migration-plan.md](docs/langgraph-backend-migration-plan.md)。
本阶段交付说明与验证证据见 [docs/assignment-baseline.md](docs/assignment-baseline.md)。

## 环境要求

- Python 3.11（使用 Conda 环境 `py3.11`，见 [AGENTS.md](AGENTS.md)）
- `fastgpt-client` SDK（当前以本地可编辑方式安装，见下文）

## 安装

```bash
conda activate py3.11

# 项目依赖
pip install -r requirements.txt

# FastGPT SDK（本地可编辑安装；SDK 源码在独立仓库维护）
pip install -e /path/to/fastgpt-python-sdk
```

## 配置

服务端通过环境变量读取 FastGPT 连接信息。复制示例配置并按环境填写：

```bash
cp .env.example .env
```

需要设置的变量：

| 变量 | 说明 |
|---|---|
| `ANALYSIS_SERVICE_URL` | FastGPT 服务地址 |
| `ANALYSIS_AUTH_TOKEN` | FastGPT API Key |
| `APP_ID` | FastGPT 应用 ID |

## 运行

```bash
python -m uvicorn src.main:app --host 127.0.0.1 --port 8000
```

- `GET /` 存活检查
- `POST /chat` 对话（`?stream=true` 为 SSE 流式）
- `POST /set_info`、`POST /get_info`、`DELETE /delete_session` 业务数据接口

## 测试

```bash
conda run -n py3.11 python -m pytest -q
```

测试分三层：

- `test/api/test_public_schema_contract.py`：公共请求/响应 schema 的契约冻结测试
- `test/api/test_chat_backend_boundary.py`：API 层与后端适配层的边界测试（fake 后端）
- `test/backends/test_fastgpt_backend.py`：FastGPT 适配器的翻译测试（fake SDK）

## 目录结构

```text
src/
  api/endpoints.py        # HTTP 协议层：schema、state 前缀解析、SSE 事件
  backends/chat.py        # 后端中立契约（ChatBackend Protocol、ChatInput/ChatResult/事件）
  backends/fastgpt.py     # FastGPT 适配器：SDK 调用与响应翻译
  core/fastgpt_client.py  # 客户端生命周期与依赖注入（lifespan）
  schemas/models.py       # 公共 Pydantic 模型
docs/langgraph-backend-migration-plan.md  # 十阶段迁移作业计划
evals/                    # 调用真实服务的评测用例与 runner
```

## 已知限制

- LangGraph 脚手架与后端适配层骨架已就位（作业 1—2）：`src/agent/`、
  `src/backends/langgraph.py`、`AGENT_BACKEND` 开关；节点逻辑与适配器实现
  为待完成的 TODO，对应测试 `test/agent/`、`test/backends/test_langgraph_backend.py`
  在完成前会失败，属预期状态。
- `set_info` / `get_info` / `delete_session` 仍直接依赖 FastGPT 状态与历史，迁移到共享
  业务状态属于作业 6。
- 服务启动需要有效的 FastGPT 配置；仅运行单元测试不需要。