ai-business-write/技术文档/智慧监督AI文书写作接口定义-20251128.md

修订历史

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绝对路径（如http://minio.example.com/...）
• 理由：支持直接访问，符合用户存储方案

6. 错误码规范化

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

V 0.1，陈涛提供

1. 解析接口

地址: /ai/extract

请求方法: POST

请求参数:

json

复制

{
    "businessType": "COMPLAINT",
    "inputData": [
        {
            "fieldCode": "userNote",
            "fieldValue": "被举报用户名称是张三"
        },
        {
            "fieldCode": "userInfo", 
            "fieldValue": "年龄30岁"
        }
    ]
}

返回参数:

json

复制

{
    "code": 0,
    "data": {
        "outData": [
            {
                "fieldCode": "userName",
                "fieldValue": "张三"
            },
            {
                "fieldCode": "userAge", 
                "fieldValue": "30"
            }
        ]
    },
    "msg": "ok",
    "path": null,
    "extra": null,
    "timestamp": "1764204337101",
    "errorMsg": "",
    "isSuccess": true
}

2. 文档生成接口

地址: /ai/generate-document

请求方法: POST

请求参数:

json

复制

{
    "templateCode": "REPORT_CARD",
    "businessType": "COMPLAINT",
    "inputData": [
        {
            "fieldCode": "userName",
            "fieldValue": "张三"
        },
        {
            "fieldCode": "userAge",
            "fieldValue": "30"
        }
    ],
    "fpolicFieldParamFileList": [
        {
            "fileId": 1,
            "fileName": "请示报告卡.doc"
        },
        {
            "fileId": 2,
            "fileName": "初步核实审批表.doc"
        }
    ]
}

返回参数:

json

复制

{
    "code": 0,
    "data": {
        "documentId": "DOC202411260001",
        "documentName": "请示报告卡_张三.docx",
        "inputData": [
            {
                "fieldCode": "userName",
                "fieldValue": "张三"
            },
            {
                "fieldCode": "userAge",
                "fieldValue": "30"
            }
        ],
        "fpolicFieldParamFileList": [
            {
                "fileId": 1,
                "fileName": "请示报告卡.doc",
                "filePath": "http://minio.example.com/202511261123/请示报告卡.doc"
            },
            {
                "fileId": 2,
                "fileName": "初步核实审批表.doc", 
                "filePath": "http://minio.example.com/202511261123/初步核实审批表.doc"
            }
        ]
    },
    "msg": "ok",
    "path": null,
    "extra": null,
    "timestamp": "1764204337101",
    "errorMsg": "",
    "isSuccess": true
}

3. 错误码定义

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

4. 字段说明

4.1 公共字段

• businessType: 业务类型（COMPLAINT-投诉举报、INVESTIGATION-调查核实等）
• templateCode: 文档模板编码
• fieldCode: 字段编码（需与Word模板中占位符一致）
• fieldValue: 字段值

4.2 文件相关字段

• fileId: 文件唯一标识
• fileName: 文件名称
• filePath: MinIO存储的绝对路径

5. 使用流程

1. 解析阶段: 调用 /ai/extract接口，输入用户描述文本，AI提取结构化数据
2. 生成阶段: 调用 /ai/generate-document接口，传入解析结果和模板信息，生成填充后的文档
3. 下载文档: 通过返回的filePath直接访问MinIO获取生成的文件

6. 注意事项

1. 字段编码(fieldCode)需与Word模板中的占位符严格对应
2. 未识别的字段在生成文档时会自动留空
3. 文件路径返回MinIO的绝对访问地址，可直接下载
4. 生成失败时直接返回错误，用户重新操作

7. 示例调用顺序

json

复制

// 1. 解析调用
请求: POST /ai/extract
{
    "businessType": "COMPLAINT",
    "inputData": [
        {"fieldCode": "userNote", "fieldValue": "被举报用户名称是张三"},
        {"fieldCode": "userInfo", "fieldValue": "年龄30岁"}
    ]
}

// 2. 生成调用  
请求: POST /ai/generate-document
{
    "templateCode": "COMPLAINT_REPORT",
    "businessType": "COMPLAINT",
    "inputData": [
        {"fieldCode": "userName", "fieldValue": "张三"},
        {"fieldCode": "userAge", "fieldValue": "30"}
    ],
    "fpolicFieldParamFileList": [
        {"fileId": 1, "fileName": "请示报告卡.doc"}
    ]
}