# 内部接口参考

供前后端开发与排错使用；日常使用和部署见 [README](../README.md)。

### 网页与 API

网页默认关闭自动确认，可在页面手动开启。API 的 `auto_confirm` 默认值则为 `true`。

| 接口 | 用途 |
|---|---|
| `POST /ask` | 收集执行结果后返回 JSON；需确认时返回 `need_confirm` |
| `POST /ask/stream` | SSE 流式进度、回答和确认事件 |
| `POST /threads/{thread_id}/resume` | 以 `{"reply":"确认"}` 或修改意见继续会话 |
| `GET /threads/{thread_id}/history` | 查看 `rounds` 和 `messages` |
| `GET /api/runtime` | 查看当前 `data_version`、`schema_version` |

请求示例（PowerShell）：

```powershell
$body = @{
    thread_id = "user-001"
    query = "目前有多少个项目？"
    auto_confirm = $true
    reuse_check = $true
} | ConvertTo-Json
Invoke-RestMethod -Uri "http://127.0.0.1:8000/ask" -Method Post `
    -ContentType "application/json; charset=utf-8" `
    -Body ([System.Text.Encoding]::UTF8.GetBytes($body))
```

同一 `thread_id` 共享上下文，调用方应为不同会话分配独立标识。`reuse_check` 默认 `true`，控制旧问答分支的历史答案复用；当前生产分支每次重新规划和查询，历史对话仅辅助理解。

SSE 使用 POST，可参考 [html/index.html](../html/index.html) 中的 `askStream` 实现，通过 `fetch` 读取响应流：

| 事件 | 处理 |
|---|---|
| `progress` | 用 `node` 和中文 `label` 展示处理阶段 |
| `answer_chunk` | 将 `text` 增量追加到回答区 |
| `confirm` | 展示确认内容，再调用 resume 接口 |
| `done` | 使用完整结果中的 `answer` 更新最终回答 |
| `error` | 展示失败信息 |

## 数据质量

接口 `GET /api/data-quality` 返回总数及各文件计数；`?details=true&data_version=<版本>` 返回完整问题记录，版本变化返回409。明细沿用现有服务访问边界，能访问此接口的用户可看到问题记录的全部字段。

## 人工确认答案缓存

`POST /threads/{thread_id}/answer-cache`：确认该答案正确并保存缓存。
`DELETE /threads/{thread_id}/answer-cache`：撤销对应缓存（需entry_id）。

请求仅允许：
`{"answer_id":"答案ID","checkpoint_id":"该答案的checkpoint ID","entry_id":null}`。
POST成功返回status、entry_id、approved_at；DELETE用该entry_id撤销。
接口从服务端checkpoint读取原答案，不接收答案、问题或查询条件正文。
记录失效、未完成、不符合缓存规则或版本变化返回409；缓存不可用返回503。
额外字段或缺失标识返回422。

/ask、/ask/stream的done和resume完整响应新增cache_review：
eligible、reason、answer_id、checkpoint_id、cached、hit、entry_id、approved_at。
eligible=true时前端展示“答案正确，加入缓存”，成功后可撤销。
cached/hit=true显示历史答案来源。人工计划确认和auto_confirm不等于缓存确认。

索引仅限同一thread_id、精确问题和上下文，包含数据/Schema/模型/策略版本，永久保存，数据版本发布成功后物理删除全部旧数据版本缓存。
关闭reuse_check绕过缓存读取。缓存命中直接返回已确认答案及来源，不调用模型/Neo4j。
目前无真实鉴权，不能据此宣称具有用户身份认证或允许跨用户共享缓存。