# 报告快速分析扩展：上传后即可用

日期：2026-09-13
状态：设计中

## 1. 背景与目标

当前「报告快速分析」功能（`/api/ai/report/analyze`）仅在 `report-detail.vue`（view 模式）可用。用户上传报告后：
- 菌群报告 → 跳转 `gut-flora-detail.vue`（无快速分析入口）
- 两阶段入库 → 停留 `report-confirm.vue`（无快速分析入口）

**目标**：在 `gut-flora-detail.vue` 和 `report-confirm.vue` 也提供「快速分析」入口，支持已入库的 `reportId` 和未入库的 `draftId`。

---

## 2. 架构设计

### 2.1 后端扩展（cfc-backend）

```
POST /api/ai/report/analyze
Request: { query, reportId?, draftId?, conversationId?, memberId? }
```

- 端点同时接受 `reportId` 和 `draftId`（至少一个非空）
- 后端判断：优先用 `reportId`（已入库，完整上下文），其次用 `draftId`（草稿，读 payloadJson）
- 免费版 Redis 计数、会员限制、fail-open 逻辑保持不变
- LangGraph `chat_graph` 零改动

### 2.2 数据流

```
前端页面（gut-flora-detail / report-confirm）
    │ POST /api/ai/report/analyze { query, reportId/draftId }
    ▼
AIChatController.reportAnalyze()
    ├─ 1. 会员级别检查（user.memberLevel）
    ├─ 2. FREE → Redis 计数（fail-open）
    ├─ 3. buildChatInputs(userId, params)
    │     ├─ 有 reportId → familyContextService.buildContext(userId, reportId)
    │     └─ 只有 draftId → familyContextService.buildContextFromDraft(userId, draftId) [新增]
    └─ 4. aiService.sendMessage() → LangGraph chat_graph
```

### 2.3 前端扩展（cfc-frontend）

| 页面 | 入口条件 | 传参 |
|------|---------|------|
| `report-detail.vue` | view 模式 + reportId | reportId（已有） |
| `gut-flora-detail.vue` | (!isEditing && !isDraftMode && reportId) \|\| (isDraftMode && draftId) | reportId 或 draftId |
| `report-confirm.vue` | !parsing && draftId | draftId |

---

## 3. 改动清单

### 3.1 后端（cfc-backend）

| 文件 | 改动 |
|------|------|
| `FamilyContextService.java` | 新增 `buildContextFromDraft(Long userId, Long draftId)`，注入 `HealthReportDraftService`，查草稿 → 解析 `payloadJson` → 返回含 `reportDetail` 的上下文 |
| `AIChatController.java` | 1. `buildChatInputs`：检测 `params.get("draftId")`，调用新方法<br>2. `reportAnalyze`：校验改为 `reportId || draftId`，空则报错 |

### 3.2 前端（cfc-frontend）

| 文件 | 改动 |
|------|------|
| `utils/api.js` | `reportQuickAnalyze` 新增可选参数 `draftId` |
| `pages/health/gut-flora-detail.vue` | 1. import 新增 `reportQuickAnalyze`、`getMyMembership`<br>2. data 新增 `quickAnalyze` 对象<br>3. computed 新增 `quickQuestions`<br>4. methods 新增 `openQuickAnalyze`、`closeQuickAnalyze`、`sendQuickQuestion`、`sendQuickAnalyze`<br>5. template：FAB 区域（第 229 行附近）加「🎯 快速分析」按钮 + 浮层结构<br>6. style：复用 report-detail.vue 样式（`.quick-analyze-*` 类） |
| `pages/health/report-confirm.vue` | 同 gut-flora-detail.vue，但入口条件为 `!parsing && draftId` |

---

## 4. 关键实现细节

### 4.1 FamilyContextService.buildContextFromDraft

```java
/**
 * 基于草稿 ID 构建上下文（用于快速分析）
 * @param userId 当前用户
 * @param draftId 草稿 ID
 * @return 上下文 Map，包含 reportDetail（从 payloadJson 还原）
 */
public Map<String, Object> buildContextFromDraft(Long userId, Long draftId) {
    Map<String, Object> ctx = buildContext(userId);

    if (draftId == null) return ctx;

    HealthReportDraft draft = healthReportDraftService.getDraftById(draftId);
    if (draft == null || !draft.getUserId().equals(userId)) {
        return ctx; // 权限不通过静默返回基础上下文
    }

    // 解析 payloadJson
    Map<String, Object> reportDetail = null;
    try {
        if (draft.getPayloadJson() != null && !draft.getPayloadJson().isEmpty()) {
            reportDetail = objectMapper.readValue(draft.getPayloadJson(), Map.class);
        }
    } catch (Exception e) {
        log.warn("解析草稿 payload 失败: {}", e.getMessage());
    }
    if (reportDetail != null) {
        ctx.put("reportDetail", reportDetail);
    }

    return ctx;
}
```

### 4.2 AIChatController.buildChatInputs 修改

```java
private Map<String, Object> buildChatInputs(Long userId, Map<String, String> params) {
    // ... 现有 mascot、memberId、surveyId、selfCheckId 逻辑不变 ...

    Long reportId = null;
    Long draftId = null;
    if (reportIdStr != null && !reportIdStr.trim().isEmpty()) {
        reportId = Long.valueOf(reportIdStr);
    }
    String draftIdStr = params.get("draftId");
    if (draftIdStr != null && !draftIdStr.trim().isEmpty()) {
        draftId = Long.valueOf(draftIdStr);
    }

    Map<String, Object> inputs;
    if (reportId != null) {
        inputs = familyContextService.buildContext(userId, reportId);
    } else if (draftId != null) {
        inputs = familyContextService.buildContextFromDraft(userId, draftId);
    } else {
        inputs = familyContextService.buildContext(userId);
    }
    // ... mascot、portrait、selfCheck、memory 后续逻辑不变 ...
}
```

### 4.3 AIChatController.reportAnalyze 校验修改

```java
String reportIdStr = params.get("reportId");
String draftIdStr = params.get("draftId");
if ((reportIdStr == null || reportIdStr.trim().isEmpty())
        && (draftIdStr == null || draftIdStr.trim().isEmpty())) {
    return Result.error("报告ID或草稿ID不能为空");
}
```

### 4.4 api.js 扩展

```javascript
// 报告快速分析（免费版每日1次，付费版多轮）
export const reportQuickAnalyze = (query, reportId, conversationId, draftId) => {
  var data = { query: query }
  if (reportId) data.reportId = reportId
  if (draftId) data.draftId = draftId
  if (conversationId) data.conversationId = conversationId
  return request('/api/ai/report/analyze', 'POST', data)
}
```

### 4.5 gut-flora-detail.vue 入口条件

```html
<!-- 仅查看模式：reportId 或 draftId 存在时 -->
<view class="quick-analyze-fab" v-if="!isEditing && (reportId || draftId)" @tap="openQuickAnalyze">
```

### 4.6 report-confirm.vue 入口条件

```html
<!-- 解析完成、非解析中 -->
<view class="quick-analyze-fab" v-if="!parsing && draftId" @tap="openQuickAnalyze">
```

---

## 5. 会员限制与免费版策略

- 完全复用现有逻辑：`user.memberLevel` 判定 FREE/FAMILY/PROVIDER
- FREE：每日 1 次（Redis 计数 key 唯一，`report:analyze:free:userId:date`，无区分 reportId/draftId）
- FREE：前端不传 `conversationId` → LangGraph 每次新建会话 → 锁死多轮
- 付费版：可传 `conversationId` 实现多轮

---

## 6. 错误处理

| 场景 | 行为 |
|------|------|
| query 为空 | `Result.error("消息不能为空")` |
| reportId 和 draftId 均空 | `Result.error("报告ID或草稿ID不能为空")` |
| 草稿不存在/无权限 | 静默降级，仅返回基础上下文（AI 仅做通用回答） |
| 免费版超限 | `Result.error("免费版每日仅限 1 次快速分析，升级会员解锁更多")` |
| Redis 异常 | fail-open 放行 + warn 日志 |
| AI 服务不可用 | `Result.error("AI 服务暂不可用，请稍后重试")` |

---

## 7. 验收标准

| 场景 | 预期 |
|------|------|
| gut-flora-detail（reportId）点击快速分析 | 正常返回 answer |
| gut-flora-detail（draftId）点击快速分析 | 正常返回 answer（基于草稿 payload） |
| report-confirm（draftId）点击快速分析 | 正常返回 answer |
| 免费版第 2 次（任意页面） | 返回超限错误 |
| 付费版多轮追问 | 带 conversationId，AI 记得上文 |
| Redis 停掉 | 免费版仍可用（fail-open） |

---

## 8. 风险与注意事项

1. **草稿 payload 结构**：`payloadJson` 是 `ParsedReportPayload.Payload` 的 JSON，结构与 `getReportDetail` 返回的 `reportDetail` 兼容（含 summary/indicators/gutFlora/diseaseRisks 等）
2. **权限校验**：草稿属于上传用户，`getDraftById` 后需校验 `draft.getUserId().equals(userId)`
3. **Redis 计数 key**：复用现有 key，同一用户同一天无论 reportId 还是 draftId 共用 1 次额度
4. **样式复用**：直接复制 report-detail.vue 的 `.quick-analyze-*` CSS 类名，避免重复维护