# `tcm.diagnosis/aiAnalysis` 延迟、重复请求与 Worker 生命周期审计

审计日期：2026-08-14  
审计性质：只读业务代码审计；除本报告外未修改服务端或桌面端业务代码。

## 结论摘要

1. **当前服务端调用链没有无限循环或无上限重试。** `DifyChatService` 的 cURL 总超时由服务端配置控制，当前运行配置为 90 秒；允许范围是 1～300 秒。正常情况下，一个 PHP 请求最多阻塞到 cURL 超时，再返回安全错误。
2. **桌面端 5 秒轮询重启已经足以完整解释“长期 loading / 每几秒刷新”。** 每次静默队列刷新都会重新加载当前患者详情；详情成功后又无条件启动一次 `aiAnalysis`。新请求会同时递增 detail generation 和 AI generation，旧请求即使成功也会因 generation 不匹配被丢弃，且底层 HTTP/Qt worker 不会被取消。
3. 如果 AI 响应超过 5 秒，时间线上不存在能成为“当前 generation”的旧结果，界面可永久停留在最新一轮 loading。即使响应低于 5 秒，也会每 5 秒重新进入 loading，形成可见闪烁和重复生成。
4. **服务端去重或短时缓存不是修复该 UI 症状的必要条件。** 首要修复应是桌面端不再因静默队列轮询重启同一诊单的详情/AI 请求，并让 AI 的有效性判断不被同一患者的无关 detail generation 变化作废。
5. **服务端仍建议增加防御性短缓存与 single-flight。** 当前每个重复 POST 都会独立占用 PHP worker 并调用上游；旧桌面版本、多窗口或多终端可以造成请求放大和 PHP-FPM/Dify 拥塞。服务端防御用于限流和成本控制，不应替代桌面端根因修复。

## 一、服务端请求链路

### 1. 同步控制流

- `DiagnosisController::aiAnalysis()` 在 `server/app/adminapi/controller/tcm/DiagnosisController.php:886-897` 同步调用 `DiagnosisAiLogic::analysis()`，没有队列、异步任务或先返回 job id 的机制。
- `DiagnosisAiLogic::analysis()` 在 `server/app/adminapi/logic/tcm/DiagnosisAiLogic.php:298-365` 依次完成权限/数据范围检查、病例上下文构造、模型路由、上游调用、JSON 解析并返回最终结果。
- 真正的上游调用位于 `DiagnosisAiLogic.php:326-336`。一次业务逻辑调用只执行一次 `DifyChatService::chat()`，但一次 `chat()` 不一定等于一次 HTTP 尝试，详见下节。
- 该接口没有读取或写入分析结果缓存，也没有按诊单、病例指纹或管理员建立锁。相同 `id` 的串行或并行 POST 都会重新生成。

### 2. Dify blocking 与协议回退

- Dify 请求体明确使用 `response_mode = blocking`，见 `server/app/common/service/DifyChatService.php:112-120`。因此在完整模型答案返回之前，PHP 请求没有中间进度可交付给客户端。
- 如果配置地址明确以 `/chat-messages` 结尾，只构造一个 Dify 请求；明确以 `/chat/completions` 结尾，只构造一个 OpenAI-compatible 请求，见 `DifyChatService.php:133-138`。
- 对普通 `/v1` 或其他非显式端点，代码构造两个候选：先 Dify、后 OpenAI-compatible，见 `DifyChatService.php:102-142`。只有首个请求明确返回 HTTP 404/405 时才尝试第二协议，见 `DifyChatService.php:81-85`。
- 本次审计仅输出配置分类、不输出地址：当前运行配置属于 **`ambiguous-base`**。因此通常是一个 Dify blocking HTTP 请求；若首个路径返回 404/405，同一次 `aiAnalysis` 会产生第二个实际 HTTP 请求。
- 第二次协议尝试复用全局剩余超时预算，见 `DifyChatService.php:62-78`。由于耗时按 `floor()` 取整，极端情况下总墙钟时间可能比配置值多不到 1 秒及少量本地处理开销，但不存在无限协议探测。

### 3. 超时和错误返回

- 配置默认超时为 90 秒，见 `server/config/prescription_ai.php:17-20`；服务层只接受 1～300 秒，见 `DifyChatService.php:15-17,175-178`。
- cURL 连接超时为 `min(8, max(1, ceil(timeout/4)))`，当前最多 8 秒；总请求超时为当前剩余预算，见 `DifyChatService.php:199-205`。
- `curl_exec()` 是同步阻塞点，见 `DifyChatService.php:215-218`。未配置流式读取、进度回调或客户端断开后主动取消上游。
- cURL 超时映射为 `UPSTREAM_TIMEOUT`；其他连接错误映射为 `UPSTREAM_UNAVAILABLE`，见 `DifyChatService.php:237-247`。
- HTTP 401/403、429/5xx、其他非 2xx、非法 JSON 和空回答都有有限、明确的错误返回，见 `DifyChatService.php:250-267`。
- 服务返回包含 `error_code` 和 `latency_ms`，见 `DifyChatService.php:269-274,305-312`；但 `DiagnosisAiLogic::analysis()` 对所有 `ok=false` 统一折叠成“AI智能分析暂时不可用”，见 `DiagnosisAiLogic.php:348-350`，没有把错误分类用于日志、指标或客户端重试策略。
- 上游成功但业务 JSON 不合约时返回结构错误，见 `DiagnosisAiLogic.php:353-356`；该失败同样没有结构化日志。

**判断：** 应用代码层不存在无限等待。实际端到端时长仍受 PHP-FPM `request_terminate_timeout`、PHP `max_execution_time`、Nginx/网关 read timeout、负载均衡 timeout 和客户端 timeout 共同限制。仓库中未发现该部署链路的 FPM/Nginx timeout 配置，生产环境必须单独核验。任何外层 timeout 小于 90 秒时，客户端可能先收到断连，而 PHP worker/上游是否立即停止取决于 SAPI 与代理的断连传播；当前代码没有显式取消保障。

## 二、PHP worker 生命周期与重复请求放大

- 从控制器进入直到 Dify blocking 返回，单个 PHP worker 始终被该 HTTP 请求占用。
- 桌面端为 `aiAnalysis` 单独设置 105 秒 HTTP timeout，见 `app/src/doctor_workstation/services/repository.py:1346-1358`。它比服务端 90 秒多 15 秒，单次调用的 timeout 顺序合理。
- 桌面 API 客户端只对 GET 自动重试；POST 固定只有一次 transport attempt，见 `app/src/doctor_workstation/services/api_client.py:253-278`。因此重复 POST 不是 httpx 自动重试造成，而是 UI 轮询主动重新提交。
- 服务端没有幂等键、完成结果缓存、进行中标记或 single-flight。N 个同诊单并发请求会占用 N 个 PHP worker，并通常产生 N 次 Dify 请求。
- 在 90 秒上游延迟、5 秒重启周期下，单个持续可见的接诊台理论上可同时留下约 `90 / 5 = 18` 个尚未完成的 AI HTTP 请求；多个终端会线性放大。PHP-FPM worker 数不足时，新请求会在网关/FPM 队列等待，形成“模型本身不慢但接口越来越慢”的二次拥塞。
- 桌面 `run_async()` 使用全局 `QThreadPool`，worker 从 `function()` 返回前不能取消，见 `app/src/doctor_workstation/ui/widgets.py:265-284,308-328`。旧请求占满本地线程池后，最新 generation 的请求还可能排在旧任务之后，进一步延长 loading。

## 三、桌面端 5 秒轮询的确定性根因

以下链路无需任何服务端死锁即可复现问题：

1. 接诊页计时器每 5 秒执行 `refresh(silent=True)`，见 `app/src/doctor_workstation/ui/pages/reception.py:917-919`。
2. `refresh()` 每次重新请求队列第一页，见 `reception.py:1922-1940`。
3. 队列返回后，即使仍选中同一预约，静默刷新也再次调用 `_load_detail()`，见 `reception.py:2080-2084`。
4. `_load_detail()` 无论是否已有请求，都会递增 `_detail_generation` 并启动新 worker，见 `reception.py:2152-2175`。
5. 详情成功后，只要存在诊单 id，就无条件调用 `_load_ai_analysis()`，见 `reception.py:2296-2314`。
6. `_load_ai_analysis()` 未检查“同一诊单已经 loading/success”，而是直接递增 `_ai_analysis_generation`、设置 loading 并启动新 POST，见 `reception.py:1718-1763`。
7. AI 结果必须同时匹配 AI generation 和当时的 detail generation，见 `reception.py:1704-1716`。后续 5 秒轮询只要递增 detail generation，旧 AI 结果就会被认定为过期。
8. 过期 success/error/finished 回调均不会结束当前 loading；success 在 `reception.py:1773-1779` 被丢弃，error/finished 也有相同当前上下文门控，见 `reception.py:1821-1849`。

典型时间线（模型耗时 8 秒）：

| 时间 | 行为 | 当前 AI generation | 结果 |
|---|---|---:|---|
| 0s | 启动请求 A | 1 | loading |
| 5s | 静默轮询重新加载详情并启动 B | 2 | A 已过期 |
| 8s | A 成功 | 2 | 被丢弃 |
| 10s | 启动 C | 3 | B 已过期 |
| 13s | B 成功 | 3 | 被丢弃 |
| 后续 | 每 5 秒重复 | 持续增加 | 永远只显示最新 loading |

因此：

- **模型耗时 > 5 秒：** 可以稳定复现永久 loading。
- **模型耗时 < 5 秒：** 可能短暂显示成功，但下一轮仍重新进入 loading，并且每 5 秒产生新模型费用。
- **服务端加短缓存：** 第一轮完成后，后续某次请求可能迅速命中缓存，从而“看起来修好”；但无意义的 detail/AI generation 重启仍存在，缓存过期后问题会复现，所以不能把缓存当根因修复。

## 四、日志与可观测性

### 当前状态

- `DiagnosisAiLogic` 只在捕获未预期 `Throwable` 时写 warning，字段为 `diagnosis_id`、`profile`、`admin_id`、异常类，见 `DiagnosisAiLogic.php:337-343`。它没有记录提示词、病例文本、上游回答、地址或密钥，密钥安全边界是正确的。
- cURL timeout、429/5xx、401/403、非法 JSON等均由 `DifyChatService` 作为普通数组返回，不抛异常；`analysis()` 随后统一失败且不记录。因此当前几乎无法从日志判断是超时、上游繁忙、协议路径、JSON 合约还是配置问题。
- `latency_ms` 已在服务层计算，但 `analysis()` 没有消费或记录。
- 管理端通用 `OperationLog` 当前在 `server/app/adminapi/event.php:15-23` 被禁用，所以正常情况下不会把接口响应落入操作日志。
- **潜在隐私风险：** 若未来重新启用 `OperationLog`，其 `server/app/adminapi/listener/OperationLog.php:48-75` 会保存完整请求参数和响应；现有裁剪只处理少数大字段，见 `OperationLog.php:79-107`，会把 `diagnosis_advice`、`risk_assessment`、`treatment_advice` 等患者衍生临床内容写入日志。重新启用前必须对该路由跳过响应记录或专门脱敏。

### 安全可观测性建议

记录结构化事件或指标，但只允许以下非临床元数据：

- 随机 correlation/request id；
- `model_key` 和实际协议（dify/openai-compatible），不要记录模型提示词；
- `outcome`、内部 `error_code`、HTTP 状态类别；
- `latency_ms`、连接耗时、上游 attempt 数；
- `cache_hit`、`singleflight_role`、锁等待时间；
- 当前 PHP/FPM 并发或队列指标应由基础设施采集。

禁止记录：API key、Authorization header、base URL、病例正文、上游请求 `inputs/query`、上游回答、患者姓名/手机号/身份证、诊断建议/风险/治疗建议。诊单 id 也是可关联标识；若确需跨日志关联，使用仅服务端可验证的 HMAC 标识且不记录原 id或病例指纹。

## 五、风险分级

| 等级 | 风险 | 影响 |
|---|---|---|
| P0 | 5 秒轮询使 detail/AI generation 持续失效 | 永久 loading、每几秒刷新、旧结果全部丢弃 |
| P1 | 无服务端去重/缓存，重复 POST 全部进入 Dify | PHP-FPM 耗尽、上游拥塞、成本放大、其他接口延迟 |
| P1 | 旧 Qt/httpx worker 无取消且使用全局线程池 | 最新请求本地排队，整页其他异步任务受影响 |
| P1 | 生产代理/FPM timeout 未在仓库定义 | 可能先于 90 秒中断，错误表现依部署而异 |
| P2 | 运行配置为 ambiguous base | 404/405 时一次业务请求产生两次 HTTP 尝试 |
| P2 | 普通上游错误没有安全结构化日志/指标 | 无法判断 timeout、busy、配置或格式故障 |
| P2 | 若恢复通用 OperationLog，会保存 AI 临床响应 | 患者衍生数据进入长期日志存储 |

## 六、最小安全改进方案（不在本次审计实现）

### 优先级 1：先修桌面控制流

必须同时满足以下两点，仅增加 `_ai_analysis_loading` guard 不够：

1. 静默队列轮询在预约/诊单未变化时，不重新启动当前患者完整详情；或者至少不递增会影响 AI 有效性的 detail generation。
2. AI 请求以稳定的 `(appointment_id, diagnosis_id)` 和自身 AI generation 判断有效性；同一诊单处于 loading 或已有 success 时不自动重启。只有患者切换、诊单内容明确更新、人工重试/刷新时才强制生成。

原因：即使阻止第二个 AI POST，只要静默详情刷新仍递增 detail generation，第一轮 AI success 仍会在 `_ai_analysis_context_current()` 中被丢弃。

### 优先级 2：补安全观测，再决定阈值

在不记录患者内容的前提下，增加 outcome/error_code/latency/protocol/attempt/cache 指标。先确认 P50/P95/P99、每诊单请求次数、同键并发数和 FPM 饱和度，再确定缓存 TTL 与限流阈值。

### 优先级 3：服务端防御性完成缓存 + single-flight

建议而非 UI 修复前置条件：

- 每次请求仍先执行权限和 DataScope 检查，缓存命中不得绕过授权。
- 使用已有 `DiagnosisAiLogic::buildCaseContext()` 生成的 SHA-256 病例指纹（`DiagnosisAiLogic.php:683-704`），组合 prompt version、model key、租户/诊单内部标识生成**不含明文患者数据**的内部缓存键。
- 只缓存已经通过严格解析的最终结构，建议 TTL 30～60 秒；诊单内容变化后指纹变化，自然失效。不要缓存 timeout、权限失败、非法 JSON 或部分响应。
- 使用跨 PHP-FPM 进程的原子 shared-cache lock/Redis `SET NX EX` 或等价机制；不能用 PHP 静态变量，也不要用非原子 `get` 后 `set` 充当锁。
- 锁必须带随机 ownership token，只有持有者可释放；TTL 应略大于上游最大运行时长并能从异常路径释放，避免永久锁。
- 锁竞争者可短时间等待完成缓存，超过小预算后返回明确、可重试的“分析进行中”错误；不要让所有竞争者都阻塞 90 秒，否则虽然保护了 Dify，仍会占满 PHP worker。
- `generated_at` 应随缓存结果一起保存，缓存命中不得伪造为新生成时间。

如果典型模型耗时长期接近一分钟，最终应考虑异步 job + 状态查询，而不是继续扩大同步 HTTP/FPM timeout；这属于协议升级，不是本次“最小改进”。

### 其他低成本措施

- 若实际服务确定为 Dify，将 `BASE_URL` 配置为显式 `/chat-messages`，避免 404/405 协议探测；不要在日志或前端暴露地址。
- 明确并统一四层 timeout：Dify cURL < PHP-FPM/Nginx/负载均衡 < 桌面 105 秒，并留出 JSON 编码和网络缓冲。
- 若重新启用管理端 OperationLog，为 `tcm.diagnosis/aiAnalysis` 禁止记录 response body，或仅记录固定 outcome 元数据。

## 七、建议测试

### 桌面回归

1. 模拟 AI 延迟 8 秒、队列轮询 5 秒；保持同一患者 20 秒，断言只提交一次 `aiAnalysis` 且最终进入 success。
2. 同一患者静默队列刷新时，断言 detail generation 不会让在途 AI 结果失效。
3. 切换患者后旧结果必须丢弃，新患者只提交一次请求。
4. 人工“重试”应强制新请求；success 状态不得被普通 5 秒轮询重置为 loading。
5. 验证关闭/隐藏页面后不会继续周期性提交 AI。

### 服务端 timeout 与协议

1. 使用本地 HTTP stub 延迟超过配置 timeout，断言在边界附近返回 `UPSTREAM_TIMEOUT`，无无限等待。
2. stub 首次返回 404、第二路径成功，断言最多两次 HTTP 尝试且共用总预算。
3. 429、500、401、非法 JSON、空回答分别映射到预期安全 error code，且响应/日志不包含上游 body、地址或密钥。
4. 配置显式 Dify 端点时断言只构造一个 blocking 请求。

### 去重/缓存（若实施）

1. 10 个相同诊单/指纹并发请求只产生一次上游调用；完成后全部得到同一严格结构或定义明确的“进行中”结果。
2. 同一诊单内容更新后不得命中旧指纹缓存；不同模型或 prompt version 不得串用。
3. 缓存命中仍必须执行权限和 DataScope，越权请求不得借缓存读取结果。
4. 上游失败、解析失败、PHP 异常后锁能释放，失败结果不缓存。
5. 多 PHP-FPM 进程下验证原子锁，而非仅单进程单元测试。
6. 捕获全部应用日志并断言不出现测试 API key、手机号、身份证、邮箱、病例文本和三个分析字段内容。

### 部署集成

1. 在真实 FPM/Nginx 拓扑用受控慢 stub 验证 90 秒服务端 timeout 能先于代理/客户端 timeout 返回。
2. 客户端在途断开后观测 PHP worker 和上游连接是否持续，量化 orphan request 生命周期。
3. 以每 5 秒一个重复请求进行负载测试，记录 FPM active/idle/queue、上游并发和其他普通接口 P95。

## 八、本次验证

以下现有直接测试已通过，测试未向真实患者数据或真实模型发送请求：

- `php server/tests/PrescriptionAiConfigTest.php`
  - ENABLE、BASE_URL、TIMEOUT、QWEN_API_KEY、OPENAI_API_KEY 均报告 configured；未输出任何实际值。
- `php server/tests/PrescriptionAiUpstreamContractTest.php`
  - Dify blocking 请求、OpenAI-compatible 请求构造、显式端点单协议、URL/timeout 安全校验均通过。

现有测试验证了配置和静态请求契约，但尚未覆盖真实慢响应、PHP-FPM 生命周期、同诊单并发、桌面 5 秒轮询与服务端调用次数的组合场景。