ai-business-write/接口调整说明.md

# 文档生成接口调整说明

## 📋 调整内容

### 1. 返回结构优化

#### 调整前的问题
- 返回数据中包含 `inputData`，与请求数据重复
- 返回的 `fileName` 是请求中的原始文件名（如 `.doc`），而不是实际生成的文档名
- 返回结构不够清晰

#### 调整后的改进
- ✅ **移除 `inputData`**：返回数据不再包含请求中的输入数据
- ✅ **返回实际生成的文档名**：`fileName` 为实际生成的文档名称（`.docx` 格式）
- ✅ **返回数量一致**：返回的文档数量与请求的文档数量完全一致

---

## 📝 调整详情

### 1. 返回的 fileName

**调整前：**
```json
{
    "fileName": "初步核实审批表.doc"  // 使用请求中的原始文件名
}
```

**调整后：**
```json
{
    "fileName": "初步核实审批表_张三.docx"  // 使用实际生成的文档名
}
```

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

### 2. 返回的 filePath

**调整前：**
```json
{
    "filePath": "/615873064429507639/20251205090700/初步核实审批表.doc"
}
```

**调整后：**
```json
{
    "filePath": "/615873064429507639/20251205090700/初步核实审批表_张三.docx"
}
```

**说明：**
- 指向实际生成的文档文件
- 使用生成的文档名作为路径中的文件名

### 3. 返回的数据结构

**调整前：**
```json
{
    "documentId": "DOC20251205090659148",
    "documentName": "初步核实审批表_张三.docx",
    "inputData": [...],  // ❌ 包含请求数据（已移除）
    "fpolicFieldParamFileList": [...]
}
```

**调整后：**
```json
{
    "documentId": "DOC20251205090659148",
    "documentName": "初步核实审批表_张三.docx",
    "fpolicFieldParamFileList": [
        {
            "fileId": 1,
            "fileName": "初步核实审批表_张三.docx",  // ✅ 实际生成的文档名
            "filePath": "/615873064429507639/20251205090700/初步核实审批表_张三.docx"
        }
    ]
}
```

---

## 🎯 实际效果

### 单文档生成示例

**请求：**
```json
{
    "inputData": [
        {"fieldCode": "target_name", "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"
            }
        ]
    },
    "isSuccess": true
}
```

### 多文档生成示例

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

**返回：**
```json
{
    "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
}
```

---

## ✅ 调整总结

### 主要改动

1. **返回的 `fileName`**
   - 从请求的原始文件名改为实际生成的文档名
   - 格式统一为 `.docx`

2. **返回的 `filePath`**
   - 指向实际生成的文档文件
   - 使用生成的文档名

3. **返回的数据结构**
   - 移除了 `inputData` 字段
   - 只返回文档生成相关信息

4. **文档数量一致性**
   - 请求1个文档，返回1个文档
   - 请求多个文档，返回多个文档
   - 数量完全对应

---

## 📚 相关文档

- **接口文档**: `技术文档/智慧监督AI文书写作接口定义-20251204-2.md`
- **代码文件**: 
  - `app.py` - 接口实现
  - `services/document_service.py` - 文档生成服务

---

**调整完成！** ✅