# 修订历史

## V 0.3，李季修订（2025-12-05）

### 主要调整内容

#### 1. **文档生成接口优化**
- 返回的 `fileName` 为实际生成的文档名称（.docx格式），而不是请求中的原始文件名
- 返回的 `filePath` 指向实际生成的文档路径
- 移除返回数据中的 `inputData`，只返回文档生成相关信息
- 返回的文档数量与请求的文档数量一致

#### 2. **文档名称生成规则**
- 生成的文档名称为：`{基础名称}_{被核查人姓名}.docx`
- 如果没有被核查人姓名，则生成：`{基础名称}.docx`
- 所有生成的文档统一为 `.docx` 格式

## 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相对路径（如`/202511261123/请示报告卡.doc`）
- *理由：使用相对路径，客户端可根据MinIO配置拼接完整URL*

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

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

## V 0.1，陈涛提供

---

# 1. 解析接口

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

**请求方法**: POST

**请求参数**:

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

**返回参数**:

```json
{
    "code": 0,
    "data": {
        "outData": [
            {
                "fieldCode": "target_name",
                "fieldValue": "张三"
            },
            {
                "fieldCode": "target_gender",
                "fieldValue": "男"
            }
        ]
    },
    "msg": "ok",
    "path": null,
    "extra": null,
    "timestamp": "1764204337101",
    "errorMsg": "",
    "isSuccess": true
}
```

---

# 2. 文档生成接口

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

**请求方法**: POST

**请求参数**:

```json
{
    "inputData": [
        {
            "fieldCode": "target_name",
            "fieldValue": "张三"
        },
        {
            "fieldCode": "target_gender",
            "fieldValue": "男"
        },
        {
            "fieldCode": "target_organization_and_position",
            "fieldValue": "某公司总经理"
        }
    ],
    "fpolicFieldParamFileList": [
        {
            "fileId": 1,
            "fileName": "初步核实审批表.doc",
            "templateCode": "PRELIMINARY_VERIFICATION_APPROVAL"
        }
    ]
}
```

**返回参数**:

```json
{
    "code": 0,
    "data": {
        "documentId": "DOC20251205090659148",
        "documentName": "初步核实审批表_张三.docx",
        "fpolicFieldParamFileList": [
            {
                "fileId": 1,
                "fileName": "初步核实审批表_张三.docx",
                "filePath": "/615873064429507639/20251205090700/初步核实审批表_张三.docx"
            }
        ]
    },
    "msg": "ok",
    "path": null,
    "extra": null,
    "timestamp": "1764204337101",
    "errorMsg": "",
    "isSuccess": true
}
```

## 2.1 多文档生成示例

如果请求多个文档，返回对应数量的文档：

**请求参数**:

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

**返回参数**:

```json
{
    "code": 0,
    "data": {
        "documentId": "DOC20251205090659148",
        "documentName": "初步核实审批表_张三.docx",
        "fpolicFieldParamFileList": [
            {
                "fileId": 1,
                "fileName": "初步核实审批表_张三.docx",
                "filePath": "/615873064429507639/20251205090700/初步核实审批表_张三.docx"
            },
            {
                "fileId": 2,
                "fileName": "请示报告卡_张三.docx",
                "filePath": "/615873064429507639/20251205090700/请示报告卡_张三.docx"
            }
        ]
    },
    "msg": "ok",
    "isSuccess": true
}
```

## 2.2 重要说明

1. **返回的文档数量**: 与请求中的 `fpolicFieldParamFileList` 数量一致
   - 请求1个文档，返回1个文档
   - 请求多个文档，返回多个文档

2. **返回的fileName**: 
   - 是实际生成的文档名称（.docx格式）
   - 不是请求中的原始文件名
   - 格式：`{基础名称}_{被核查人姓名}.docx` 或 `{基础名称}.docx`

3. **返回的filePath**: 
   - MinIO相对路径
   - 指向实际生成的文档文件
   - 格式：`/租户ID/时间戳/文档名称.docx`

4. **文档名称生成规则**:
   - 基础名称：从请求的 `fileName` 中提取（去掉扩展名）
   - 如果 `inputData` 中包含 `target_name` 字段，则添加 `_{target_name}` 后缀
   - 最终格式统一为 `.docx`

---

# 3. 错误码定义

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

---

# 4. 字段说明

## 4.1 公共字段

- `templateCode`: 文档模板编码（必填）
- `fieldCode`: 字段编码（需与Word模板中占位符一致）
- `fieldValue`: 字段值

## 4.2 文件相关字段

- `fileId`: 文件唯一标识（请求和返回中保持一致）
- `fileName`: 
  - **请求中**: 原始文件名称（如 `初步核实审批表.doc`）
  - **返回中**: 实际生成的文档名称（如 `初步核实审批表_张三.docx`）
- `filePath`: MinIO存储的相对路径（返回中提供）

## 4.3 返回字段

- `documentId`: 文档生成批次ID
- `documentName`: 第一个文档的生成名称（用于展示）

---

# 5. 使用流程

1. **解析阶段**: 调用 `/ai/extract`接口，输入用户描述文本，AI提取结构化数据
2. **生成阶段**: 调用 `/ai/generate-document`接口，传入解析结果和模板信息，生成填充后的文档
3. **下载文档**: 通过返回的filePath使用MinIO预签名URL或客户端拼接完整路径获取生成的文件

---

# 6. 注意事项

1. 字段编码(fieldCode)需与Word模板中的占位符严格对应
2. 未识别的字段在生成文档时会自动留空
3. 返回的filePath为MinIO相对路径，需要客户端拼接MinIO访问地址
4. 生成的文档统一为.docx格式，即使请求中的文件名为.doc
5. 如果某个文档生成失败，整个请求会返回错误，不会部分成功
6. 返回的文档数量与请求数量一致，每个文档都有独立的fileId和filePath

---

# 7. 示例调用顺序

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

响应:
{
    "code": 0,
    "data": {
        "outData": [
            {"fieldCode": "target_name", "fieldValue": "张三"},
            {"fieldCode": "target_gender", "fieldValue": "男"}
        ]
    },
    "isSuccess": true
}

// 2. 生成调用（单文档）
请求: POST /ai/generate-document
{
    "inputData": [
        {"fieldCode": "target_name", "fieldValue": "张三"},
        {"fieldCode": "target_gender", "fieldValue": "男"}
    ],
    "fpolicFieldParamFileList": [
        {
            "fileId": 1,
            "fileName": "初步核实审批表.doc",
            "templateCode": "PRELIMINARY_VERIFICATION_APPROVAL"
        }
    ]
}

响应:
{
    "code": 0,
    "data": {
        "documentId": "DOC20251205090659148",
        "documentName": "初步核实审批表_张三.docx",
        "fpolicFieldParamFileList": [
            {
                "fileId": 1,
                "fileName": "初步核实审批表_张三.docx",
                "filePath": "/615873064429507639/20251205090700/初步核实审批表_张三.docx"
            }
        ]
    },
    "isSuccess": true
}

// 3. 生成调用（多文档）
请求: POST /ai/generate-document
{
    "inputData": [
        {"fieldCode": "target_name", "fieldValue": "张三"},
        {"fieldCode": "target_gender", "fieldValue": "男"}
    ],
    "fpolicFieldParamFileList": [
        {
            "fileId": 1,
            "fileName": "初步核实审批表.doc",
            "templateCode": "PRELIMINARY_VERIFICATION_APPROVAL"
        },
        {
            "fileId": 2,
            "fileName": "请示报告卡.doc",
            "templateCode": "REPORT_CARD"
        }
    ]
}

响应:
{
    "code": 0,
    "data": {
        "documentId": "DOC20251205090659149",
        "documentName": "初步核实审批表_张三.docx",
        "fpolicFieldParamFileList": [
            {
                "fileId": 1,
                "fileName": "初步核实审批表_张三.docx",
                "filePath": "/615873064429507639/20251205090700/初步核实审批表_张三.docx"
            },
            {
                "fileId": 2,
                "fileName": "请示报告卡_张三.docx",
                "filePath": "/615873064429507639/20251205090700/请示报告卡_张三.docx"
            }
        ]
    },
    "isSuccess": true
}
```

---

# 8. 版本说明

- **V 0.3**: 优化文档生成接口返回结构，返回实际生成的文档名称和路径
- **V 0.2**: 接口路径优化，字段名修正，参数补充
- **V 0.1**: 初始版本