文档模板管理接口

网关前缀：/ai
Base：/v1/doc-template
鉴权：Bearer Token
统一响应：{ "code": 0, "msg": null, "data": ... }

表：marketplace_doc_template
对应云集市业务类型：doc_template

---

一、接口一览

用途	方法	路径
分页查询	GET	/v1/doc-template/page
详情	GET	/v1/doc-template/{id}
新增	POST	/v1/doc-template
更新	PUT	/v1/doc-template
删除	DELETE	/v1/doc-template/{id}
上传文件	POST	/v1/doc-template/category/upload
上传缩略图	POST	/v1/doc-template/thumbnail/upload

---

二、字段说明

字段	类型	说明
id	Long	主键（雪花），新增勿传
name	String	模板文件名，必填
size	Long	文件大小（字节）
fileId	String	com_doc_file.id，下载地址使用 GET /v1/file/export/{fileId}/{fileName}；空串按 null 存
contentLength	Long	内容长度（字节）
fileType	String	文件类型，如 docx / pdf（入库转小写）
thumbnailUrl	String	缩略图地址，来自 /admin/sys-file/upload 返回的 data.url，如 /admin/sys-file/oss/file?fileName=xxx.png；空串按 null 存
remark	String	备注；空串按 null 存

说明：只传 size 或只传 contentLength 时，服务端会互相补齐。

---

三、分页查询

GET /v1/doc-template/page

参数	位置	说明
current	query	页码，默认 1
size	query	每页条数，默认 10（分页参数，与业务字段 size 同名时注意区分）
name	query	文件名模糊查询
fileType	query	文件类型精确匹配
fileId	query	fileId 精确匹配
remark	query	备注模糊查询

示例：

GET /ai/v1/doc-template/page?current=1&size=10&name=抵押&fileType=docx

data 为 MyBatis-Plus 分页结构：

{
  "records": [
    {
      "id": 10001,
      "name": "抵押贷款还款协议范本word模板.docx",
      "size": 14699,
      "fileId": "1987654321",
      "contentLength": 14699,
      "fileType": "docx",
      "thumbnailUrl": "/admin/sys-file/oss/file?fileName=xxx.png",
      "remark": "适用于抵押贷款场景",
      "createTime": "2026-08-17T16:00:00",
      "updateTime": "2026-08-17T16:00:00"
    }
  ],
  "total": 1,
  "size": 10,
  "current": 1,
  "pages": 1
}

分页参数 size（每页条数）与实体字段 size（文件字节数）同名。列表查询时 query 的 size 走分页；业务文件大小请用返回体 records[].size。

---

四、详情

GET /v1/doc-template/{id}

data 为单条模板对象（字段同上）。

---

五、新增

POST /v1/doc-template

{
  "name": "抵押贷款还款协议范本word模板.docx",
  "size": 14699,
  "fileId": "",
  "contentLength": 14699,
  "fileType": "docx",
  "thumbnailUrl": "/admin/sys-file/oss/file?fileName=xxx.png",
  "remark": "适用于抵押贷款场景"
}

data：落库后的完整对象（含生成的 id）。

---

六、更新

PUT /v1/doc-template

{
  "id": 10001,
  "name": "抵押贷款还款协议范本word模板.docx",
  "size": 14699,
  "fileId": "1987654321",
  "contentLength": 14699,
  "fileType": "docx",
  "thumbnailUrl": "/admin/sys-file/oss/file?fileName=xxx.png",
  "remark": "适用于抵押贷款场景"
}

id 必填。data：true / false。

---

七、删除

DELETE /v1/doc-template/{id}

逻辑删除。data：true / false。

---

八、上传模板文件

POST /v1/doc-template/category/upload
Content-Type: multipart/form-data

模板文件与合规 POST /v1/file/upload 同一套存储：分片上传、写入 com_doc_file（不转 PDF、不建审查任务）。返回的 fileId 是 com_doc_file.id，推荐先查询文件访问地址，再使用其中的 url 下载：

GET /ai/v1/doc-template/file/{fileId}/url
GET /ai/v1/file/export/{fileId}/{fileName}

下载时由 fileId 唯一定位文件，URL 末尾的 fileName 用于保留文件名和后缀。历史的 GET /ai/v1/file/export/{fileId} 和按文件名下载地址继续兼容。

缩略图走 /admin/sys-file/upload。只传 file（Word/PDF/PPT）时，服务端会从首页自动生成缩略图并上传；也可把图片作为 thumbnail 一起传以覆盖自动生成。

参数	位置	说明
file	form	模板文件，必填
thumbnail	form	缩略图，可选；走 /admin/sys-file/upload

示例：

POST /ai/v1/doc-template/category/upload
Content-Type: multipart/form-data
file: (binary)
thumbnail: (binary, 可选)

data：

{
  "fileId": 1987654321,
  "fileName": "抵押贷款还款协议范本word模板",
  "fileExtension": "docx",
  "originalFileName": "抵押贷款还款协议范本word模板.docx",
  "filePath": "/room/2026/08/xxx.docx",
  "fileSize": 14699,
  "hash": "md5...",
  "baseUrl": "https://...",
  "thumbnailUrl": "/admin/sys-file/oss/file?fileName=xxx.png"
}

写入模板表时可对应：fileId → fileId，originalFileName → name，fileSize → size/contentLength，fileExtension → fileType，thumbnailUrl → thumbnailUrl。

---

九、上传缩略图

POST /v1/doc-template/thumbnail/upload
Content-Type: multipart/form-data

内部调用 POST /admin/sys-file/upload。也可前端直接调该管理端接口，效果相同。

参数	位置	说明
file	form	缩略图文件，必填

POST /ai/v1/doc-template/thumbnail/upload
Content-Type: multipart/form-data
file: (binary)

或：

POST /admin/sys-file/upload
Content-Type: multipart/form-data
file: (binary)

data：

{
  "bucketName": "muotai",
  "fileName": "uuid.png",
  "originalName": "cover.png",
  "url": "/admin/sys-file/oss/file?fileName=uuid.png",
  "fileId": 123
}

把 data.url 写入模板 thumbnailUrl。