ai-business-write/技术文档/接口调整说明.md

文档生成接口调整说明

📋 调整内容

1. 返回结构优化

调整前的问题

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

调整后的改进

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

---

📝 调整详情

1. 返回的 fileName

调整前：

{
    "fileName": "初步核实审批表.doc"  // 使用请求中的原始文件名
}

调整后：

{
    "fileName": "初步核实审批表_张三.docx"  // 使用实际生成的文档名
}

文档名称生成规则：

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

2. 返回的 filePath

调整前：

{
    "filePath": "/615873064429507639/20251205090700/初步核实审批表.doc"
}

调整后：

{
    "filePath": "/615873064429507639/20251205090700/初步核实审批表_张三.docx"
}

说明：

• 指向实际生成的文档文件
• 使用生成的文档名作为路径中的文件名

3. 返回的数据结构

调整前：

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

调整后：

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

---

🎯 实际效果

单文档生成示例

请求：

{
    "inputData": [
        {"fieldCode": "target_name", "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
}

多文档生成示例

请求：

{
    "inputData": [
        {"fieldCode": "target_name", "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
}

---

✅ 调整总结

主要改动

1. 返回的 fileName

   • 从请求的原始文件名改为实际生成的文档名
   • 格式统一为 .docx

2. 返回的 filePath

   • 指向实际生成的文档文件
   • 使用生成的文档名

3. 返回的数据结构

   • 移除了 inputData 字段
   • 只返回文档生成相关信息

4. 文档数量一致性

   • 请求1个文档，返回1个文档
   • 请求多个文档，返回多个文档
   • 数量完全对应

---

📚 相关文档

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

---

调整完成！ ✅