# 修订历史

## V 0.2，李季修订

### 主要调整内容

#### 1. **接口路径优化**

- `/paras`→ `/ai/extract`
- `/getDocument`→ `/ai/generate-document`
- *理由：更清晰的语义化路径*

#### 2. **字段名修正**

- `filedCode`→ `fieldCode`
- `filedVal`→ `fieldValue`
- *理由：修正拼写错误，保持专业规范*

#### 3. **关键参数补充**

**新增参数：**

- `templateCode`：文档模板标识
- `businessType`：业务类型分类
- `documentId`：文档唯一标识
- `documentName`：生成文档名称

#### 4. **返回结构增强**

- **解析接口**：保持简洁，去除置信度等复杂字段
- **生成接口**：增加`documentId`和`documentName`，完善文件信息

#### 5. **文件路径调整**

- 返回MinIO绝对路径（如`http://minio.example.com/...`）
- *理由：支持直接访问，符合用户存储方案*

#### 6. **错误码规范化**

- 明确业务相关错误码（模板不存在、占位符匹配失败等）

## V 0.1，陈涛提供





# 1. 解析接口

**地址**: `/ai/extract`

**请求方法**: POST

**请求参数**:

json

复制

```
{
  "inputData": [

    {
      "fieldCode": "clue_info",
      "fieldValue": "被举报用户名称是张三，年龄30岁，某公司总经理"
    },
{
      "fieldCode": "clue_info2",
      "fieldValue": "被举报用户名称是张三，年龄30岁，某公司总经理"
    }
  ],
  "outputData": [

    {
      "fieldCode": "userName"
    },
    {
      "fieldCode": "clue_info2"
    }
  ]
}
```

**返回参数**:

json

复制

```
{
    "code": 0,
    "data": {
        "outData": [
            {
                "fieldCode": "userName",
                "fieldValue": "张三"
            },
            {
                "fieldCode": "userAge", 
                "fieldValue": "30"
            }
        ]
    },
    "msg": "ok",
    "path": null,
    "extra": null,
    "timestamp": "1764204337101",
    "errorMsg": "",
    "isSuccess": true
}
```

# 2. 文档生成接口

**地址**: `/ai/generate-document`

**请求方法**: POST

**请求参数**:

json

复制

```
{
    "inputData": [
        {
            "fieldCode": "userName",
            "fieldValue": "张三"
        },
        {
            "fieldCode": "userAge",
            "fieldValue": "30"
        }
    ],
    "fpolicFieldParamFileList": [
        {
            "fileId": 1,
            "fileName": "请示报告卡.doc"
            "templateCode": "REPORT_CARD"
        },
        {
            "fileId": 2,
            "fileName": "初步核实审批表.doc"
            "templateCode": "REPORT_CARD"

        }
    ]
}
```

**返回参数**:

json

复制

```
{
    "code": 0,
    "data": {
        "documentId": "DOC202411260001",
        "documentName": "请示报告卡_张三.docx",
        "inputData": [
            {
                "fieldCode": "userName",
                "fieldValue": "张三"
            },
            {
                "fieldCode": "userAge",
                "fieldValue": "30"
            }
        ],
        "fpolicFieldParamFileList": [
            {
                "fileId": 1,
                "fileName": "请示报告卡.doc",
                "filePath": "/202511261123/请示报告卡.doc"
            },
            {
                "fileId": 2,
                "fileName": "初步核实审批表.doc", 
                "filePath": "/202511261123/初步核实审批表.doc"
            }
        ]
    },
    "msg": "ok",
    "path": null,
    "extra": null,
    "timestamp": "1764204337101",
    "errorMsg": "",
    "isSuccess": true
}
```

# 3. 错误码定义

| 错误码 | 说明           | 处理建议                   |
| :----- | :------------- | :------------------------- |
| 0      | 成功           | -                          |
| 1001   | 模板不存在     | 检查templateCode是否正确   |
| 1002   | 占位符匹配失败 | 检查字段编码与模板是否匹配 |
| 2001   | AI解析超时     | 重新尝试解析               |
| 2002   | 字段识别失败   | 检查输入文本质量           |
| 3001   | 文件生成失败   | 重新尝试生成               |
| 3002   | 文件保存失败   | 检查存储服务状态           |

# 4. 字段说明

## 4.1 公共字段

- `businessType`: 业务类型（COMPLAINT-投诉举报、INVESTIGATION-调查核实等）
- `templateCode`: 文档模板编码
- `fieldCode`: 字段编码（需与Word模板中占位符一致）
- `fieldValue`: 字段值

## 4.2 文件相关字段

- `fileId`: 文件唯一标识
- `fileName`: 文件名称
- `filePath`: MinIO存储的绝对路径

## 5. 使用流程

1. **解析阶段**: 调用 `/ai/extract`接口，输入用户描述文本，AI提取结构化数据
2. **生成阶段**: 调用 `/ai/generate-document`接口，传入解析结果和模板信息，生成填充后的文档
3. **下载文档**: 通过返回的filePath直接访问MinIO获取生成的文件

## 6. 注意事项

1. 字段编码(fieldCode)需与Word模板中的占位符严格对应
2. 未识别的字段在生成文档时会自动留空
3. 文件路径返回MinIO的绝对访问地址，可直接下载
4. 生成失败时直接返回错误，用户重新操作

## 7. 示例调用顺序

json

复制

```
// 1. 解析调用
请求: POST /ai/extract
{
    "inputData": [
        {"fieldCode": "userNote", "fieldValue": "被举报用户名称是张三"},
        {"fieldCode": "userInfo", "fieldValue": "年龄30岁"}
    ],
  "outputData": [
    {
      "fieldCode": "userName"
    },
    {
      "fieldCode": "clue_info2"
    }
  ]
}

// 2. 生成调用  
请求: POST /ai/generate-document
{
    "inputData": [
        {"fieldCode": "userName", "fieldValue": "张三"},
        {"fieldCode": "userAge", "fieldValue": "30"}
    ],
    "fpolicFieldParamFileList": [
        "templateCode": "COMPLAINT_REPORT",
        {"fileId": 1, "fileName": "请示报告卡.doc"}
    ]
}
```