python/ai-business-write
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
ai-business-write/技术文档/智慧监督AI文书写作接口定义-20251204-2.md

11 KiB
Raw Blame History

修订历史

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

请求参数:

{
  "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": "男"
            }
        ]
    },
    "msg": "ok",
    "path": null,
    "extra": null,
    "timestamp": "1764204337101",
    "errorMsg": "",
    "isSuccess": true
}

2. 文档生成接口

地址: /ai/generate-document

请求方法: POST

请求参数:

{
    "inputData": [
        {
            "fieldCode": "target_name",
            "fieldValue": "张三"
        },
        {
            "fieldCode": "target_gender",
            "fieldValue": "男"
        },
        {
            "fieldCode": "target_organization_and_position",
            "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"
            }
        ]
    },
    "msg": "ok",
    "path": null,
    "extra": null,
    "timestamp": "1764204337101",
    "errorMsg": "",
    "isSuccess": true
}

2.1 多文档生成示例

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

请求参数:

{
    "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": "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. 示例调用顺序

// 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: 初始版本