425 lines
11 KiB
Markdown
425 lines
11 KiB
Markdown
# 修订历史
|
||
|
||
## 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**: 初始版本
|
||
|