> ## Documentation Index
> Fetch the complete documentation index at: https://blog.pig4cloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Ai report system

AI报告系统是一个基于模板驱动的智能报告生成平台，通过集成大语言模型和JSON Schema约束，实现高质量、结构化的报告自动生成。

### 1.1 核心特性

* **模板驱动**: 基于Word模板，支持书签和占位符动态替换
* **AI增强**: 集成大语言模型进行内容润色和结构化提取
* **JSON约束**: 使用JSON Schema确保输出格式的一致性和数据完整性
* **自动化流程**: 端到端的报告生成，从模板解析到文件下载

### 1.2 技术架构

```
用户输入 → 内容润色(可选) → AI结构化提取 → JSON修复 → Word模板填充 → 文件下载
```

## 2. 核心组件

### 2.1 服务层组件

#### AiReportConfService

报告配置服务接口，定义了报告模板管理的核心业务逻辑：

* 模板上传与解析
* 配置信息管理
* 报告生成协调

#### AiReportConfServiceImpl

报告配置服务实现类，负责：

* Word文档解析（书签、占位符识别）
* AI模型调用与结果处理
* 模板填充与文件生成

### 2.2 控制器层

#### AiReportConfController

报告管理REST控制器，提供以下API端点：

| 方法   | 路径                       | 功能描述       |
| ---- | ------------------------ | ---------- |
| POST | `/aiReportConf/parse`    | 解析Word模板文档 |
| POST | `/aiReportConf/download` | 生成并下载报告    |

## 3. 模板管理流程

### 3.1 模板配置流程

#### 步骤1: 模板文件上传

通过文件服务上传Word模板文件，支持`.docx`格式。

#### 步骤2: 模板解析

使用`parseDoc`方法解析Word文档结构：

```java theme={null}
// 解析Word文档中的书签和占位符
List<AnchorContext> bookmarkList = DefaultAnchors.BOOKMARK_ANCHOR.locate(document);
List<AnchorContext> placeholderList = DefaultAnchors.PLACEHOLDER_ANCHOR.locate(document);
```

#### 步骤3: 字段配置

在`report_marked`字段中配置JSON格式的字段映射关系。

#### 步骤4: 模板保存

将解析后的模板信息和配置保存到数据库。

### 3.2 模板解析功能

系统支持两种类型的占位符：

* **书签（Bookmark）**: Word文档中的书签标记
* **占位符（Placeholder）**: 自定义的文本占位符

## 4. 报告生成流程

### 4.1 请求参数

#### AiReportCompletionsDTO

| 字段       | 类型     | 描述       |
| -------- | ------ | -------- |
| reportId | Long   | 报告配置ID   |
| model    | String | AI模型标识   |
| prompt   | String | 生成提示词    |
| polish   | String | 是否需要AI润色 |

### 4.2 生成流程详解

#### 步骤1: 内容润色（可选）

当`polish`参数为`YES`时，系统会对用户输入进行AI润色：

```java theme={null}
if (YesNoEnum.YES.getCode().equals(completionsDTO.getPolish())) {
    String chatted = aiAssistant.getKey().chat(
        PromptBuilder.render("report-polish.st", 
            Map.of("reportTitle", reportConfEntity.getReportTitle(),
                   "reportPrompt", reportConfEntity.getReportPrompt(),
                   "prompt", completionsDTO.getPrompt(),
                   "username", SecurityUtils.getUser().getName(),
                   "systemTime", DateUtil.now()))
    );
    completionsDTO.setPrompt(chatted);
}
```

#### 步骤2: 结构化数据提取

1. **构建JSON Schema**: 根据模板字段配置构建数据约束
2. **AI模型调用**: 使用JSON Assistant模型提取结构化数据
3. **数据修复**: 使用`JSONRepairUtil.repair()`修复JSON格式

```java theme={null}
// 构建JSON Schema
JsonSchema jsonSchema = JsonSchema.builder()
    .name("ReportResult")
    .rootElement(JsonObjectSchema.builder()
        .addProperties(fieldProperties)
        .required(fieldNames)
        .build())
    .build();

// 调用AI模型
ChatResponse chatted = aiJSONAssistant.getLeft().chat(builder.build());
String repair = JSONRepairUtil.repair(chatted.aiMessage().text());
```

#### 步骤3: 模板填充与下载

将AI生成的结构化数据填充到Word模板中：

```java theme={null}
// 将AI生成的数据填充到Word模板
Map bean = JSONUtil.toBean(repair, Map.class);
EasyWord.of(templateInputStream).doWrite(bean).toOutputStream(response.getOutputStream());
```

## 5. 提示词模板

### 5.1 报告润色模板 (report-polish.st)

````markdown theme={null}
## 核心目标
{reportPrompt}

## 输入信息
{prompt}

参考资料：当前时间：{systemTime}，用户名：{username}。

## 输出要求
* 输出内容必须是优化后的报告本身，应清晰、简洁、准确地反映报告内容。
* 不得包含任何markdown语法的修饰字符例如：``` ** ###
````

### 5.2 系统提示词模板 (report-system-json.st)

```markdown theme={null}
您应该始终遵循指令并输出一个有效的JSON对象。请根据指令使用指定的JSON对象结构。
当前时间: {systemTime}
```

### 5.3 用户提示词模板 (report-user-json.st)

```markdown theme={null}
请根据提供的 JSON Schema，严格解析并格式化以下用户输入内容 (`{userInput}`) 为格式化为一个 JSON 对象。

在处理过程中，请遵循以下规则：
1. **严格遵守 Schema**: 输出的 JSON 对象必须完全符合 JSON Schema 中定义的结构、字段类型和约束。
2. **解析与提取**: 从用户输入中准确提取信息，填充到 JSON 对象的相应字段中。
3. **补充与优化**: 如果用户输入中的信息对于某个 Schema 字段不规范、不完整或缺失，请根据 Schema 的定义和用户输入的上下文，尝试进行合理的补充或优化，确保字段值有效且符合预期。
4. **输出格式**: 仅输出最终生成的 JSON 对象字符串，不包含任何额外文本、解释或标记。

## JSON Schema
{jsonSchema}
```