# 报告指标模板管理 & 采集训练器

**优先级:** P1
**预计工时:** 1天
**创建日期:** 2026-08-22

---

## 一、背景

小程序端报告页面已实现「固定模板 + 自由显示」展示模式：
- **固定模板**：`report_blocks` 表中预置的 blocks（score/indicator/list/text），由 `ReportBlockAssembler` 生成
- **自由显示**：解析 payload 中未出现在固定模板的指标，自动追加到末尾

目前后台缺少**模板配置管理**和**采集训练**能力，导致新报告类型无法灵活配置展示方式。

---

## 二、用户故事

| 角色 | 故事 | 验收标准 |
|------|------|---------|
| 管理员 | 为不同报告类型配置展示模板（固定块顺序+自由显示开关） | 能创建/编辑/启停模板；模板影响小程序报告渲染 |
| 管理员 | 在未知报告聚类中手动标注报告类型，作为采集器训练数据 | 能看到 LLM 解析结果；能选类型；能预览模板渲染效果 |
| 系统 | 新报告类型首次发现时自动建定义（无指纹），积累3份后生成指纹+模板 | 新类型自动创建 `report_template` 空模板；ready 状态聚类可一键生成 |

---

## 三、数据库设计

### 3.1 新建表 `report_template`

```sql
CREATE TABLE IF NOT EXISTS report_template (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    name VARCHAR(100) NOT NULL COMMENT '模板名称',
    report_type VARCHAR(50) NOT NULL COMMENT '报告类型: gut_flora/dan/physical_exam/tongue',
    config JSON NOT NULL COMMENT '模板配置JSON',
    is_active TINYINT DEFAULT 1 COMMENT '0=停用 1=启用',
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    UNIQUE KEY uk_report_type (report_type)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='报告展示模板';
```

### 3.2 Config JSON 结构

```json
{
  "fixedBlocks": [
    {
      "type": "score",
      "title": "健康评分",
      "items": ["overallScore", "gutHealthScore", "chronicDiseaseScore"],
      "order": 1
    },
    {
      "type": "indicator",
      "title": "血脂指标",
      "indicatorCodes": ["total_cholesterol", "triglyceride", "hdl"],
      "groupLabel": "血脂",
      "order": 2
    }
  ],
  "freeDisplay": {
    "enabled": true,
    "groupName": "其他指标"
  }
}
```

### 3.3 新增列 `report_unknown_upload.annotation`

```sql
ALTER TABLE report_unknown_upload ADD COLUMN annotation TEXT COMMENT '管理员标注: 手动指定类型+确认提取结果JSON';
```

---

## 四、后端实现

### 4.1 新增文件

| 文件 | 说明 |
|------|------|
| `entity/ReportTemplate.java` | 模板实体 |
| `mapper/ReportTemplateMapper.java` | MyBatis-Plus Mapper |
| `service/ReportTemplateService.java` | 业务逻辑 |
| `controller/admin/ReportTemplateController.java` | REST 接口 |

### 4.2 接口清单

```
POST /api/admin/report-template/list           分页列表
POST /api/admin/report-template/save           保存（创建或更新）
POST /api/admin/report-template/delete         删除
POST /api/admin/report-template/toggle         启用/停用
POST /api/admin/report-template/get            按reportType获取
POST /api/admin/report-template/indicators     获取可选指标列表（用于编辑器）
```

### 4.3 修改现有文件

**`ReportBlockAssembler.java`** — 新增方法：
```java
public List<Map<String, Object>> assembleWithTemplate(String reportType, Object payload) {
    // 1. 查询 template config
    // 2. 按 fixedBlocks 顺序组装
    // 3. 如果 freeDisplay.enabled，追加未配置指标
}
```

**`ReportParserAdminController.java`** — 修改 `generateType()`：
- 生成类型后，自动插入一条 `report_template` 记录（config 为空）

**`DatabaseInitializer.java`** — 添加迁移：
- CREATE TABLE report_template

**`schema.sql`** — 追加 CREATE TABLE + ALTER TABLE report_unknown_upload

---

## 五、前端实现

### 5.1 新增文件

| 文件 | 说明 |
|------|------|
| `src/api/reportTemplate.js` | API 封装 |
| `src/views/admin/ReportTemplateManage.vue` | 模板管理页 |
| `src/views/admin/ReportCollectorTrainer.vue` | 采集训练器页 |

### 5.2 ReportTemplateManage.vue 功能

- Tab 1 - 模板列表：表格（名称/类型/状态），新增/编辑按钮
- Tab 2 - 模板编辑器（弹窗）：
  - 基础信息（名称、报告类型下拉）
  - 固定块编辑器：
    - 块列表（可拖拽排序）
    - 每种块类型的配置表单：
      - score 块：选择要展示的分数字段
      - indicator 块：选择指标编码（多选+排序）、分组标签
      - list 块：配置 columns
      - text 块：标题+内容
  - 自由显示配置：开关 + 分组名 + 插入位置
  - 保存后实时更新

### 5.3 ReportCollectorTrainer.vue 功能

- 左侧：未知报告聚类列表（状态筛选：collecting/ready/generated）
- 右侧：详情面板
  - 选中聚类 → 显示上传明细列表
  - 点击某条上传记录 → 显示：
    - PDF 预览（iframe embed fileUrl）
    - LLM 解析结果（JSON 格式化展示）
    - 类型选择下拉（所有报告类型）
    - 模板预览（基于选定类型+解析结果，渲染 blocks 预览）
    - 标注保存按钮（保存 admin 确认的类型和标注）
  - 当 reportCount >= 3 且 status = ready 时，显示「生成类型」按钮

---

## 六、路由 & 菜单更新

### 6.1 路由 `router/index.js`

```js
{
  path: 'report-template',
  name: 'ReportTemplateManage',
  component: () => import('@/views/admin/ReportTemplateManage.vue'),
  meta: { title: '报告模板管理', perm: 'config:report-parser' }
},
{
  path: 'report-collector-trainer',
  name: 'ReportCollectorTrainer',
  component: () => import('@/views/admin/ReportCollectorTrainer.vue'),
  meta: { title: '报告采集训练', perm: 'config:report-parser' }
}
```

### 6.2 菜单 `Layout.vue`（报告解析系统子菜单追加）

```
报告采集训练  ─  el-icon-film  perm: config:report-parser
报告模板管理  ─  el-icon-setting perm: config:report-parser
```

---

## 七、API Reference 文档更新

在 `docs/superpowers/api/API_REFERENCE.md` 的「报告解析系统」章节追加：

| 路径 | 方法 | 说明 |
|------|------|------|
| `/api/admin/report-template/list` | POST | 模板列表 |
| `/api/admin/report-template/save` | POST | 保存模板 |
| `/api/admin/report-template/delete` | POST | 删除模板 |
| `/api/admin/report-template/toggle` | POST | 启停模板 |
| `/api/admin/report-template/get` | POST | 按类型获取 |
| `/api/admin/report-template/indicators` | POST | 获取可选指标 |

---

## 八、验证步骤

1. `mvn clean compile` 通过
2. 后端启动后访问 `/api/admin/report-template/list` 返回空列表
3. 新增模板 → 编辑固定块 → 保存 → 验证 config JSON 结构
4. 小程序报告页面加载时，使用模板 blocks 渲染
5. 采集训练器页面：查看聚类 → 选择报告 → 预览模板渲染 → 保存标注