680 lines
21 KiB
JSON
680 lines
21 KiB
JSON
{
|
||
"generatedAt": "2026-05-20 16:44:18",
|
||
"generatedAtLocal": "2026-05-20 16:44:18",
|
||
"source": "remote",
|
||
"filter": {
|
||
"platform": {
|
||
"value": "web",
|
||
"label": "网页端"
|
||
},
|
||
"project": {
|
||
"value": "all",
|
||
"label": "全部"
|
||
}
|
||
},
|
||
"module": {
|
||
"name": "打印模块",
|
||
"key": "print",
|
||
"folder": "print",
|
||
"interfaceCount": 13
|
||
},
|
||
"changes": {
|
||
"fromPreviousSnapshot": {
|
||
"moduleAdded": false,
|
||
"moduleRenamed": false,
|
||
"interfaceChanges": {
|
||
"addedMethods": [],
|
||
"deletedMethods": [],
|
||
"paramsUpdatedMethods": [],
|
||
"responseUpdatedMethods": []
|
||
}
|
||
}
|
||
},
|
||
"interfaces": [
|
||
{
|
||
"method": "print.send",
|
||
"title": "发送打印任务到打印电脑,并记录打印单。说明:当 type=express 时,接口按 data.waveGroups(来源于 order.print.getWavePlatformPrintData 返回的 data.waveGroups)进行处理,按 waveGroups -> platforms 串行处理,每个平台+快递 组分别发送;返回沿用现有简要风格,不返回明细。",
|
||
"description": "发送打印任务到打印电脑,并记录打印单。说明:当 type=express 时,接口按 data.waveGroups(来源于 order.print.getWavePlatformPrintData 返回的 data.waveGroups)进行处理,按 waveGroups -> platforms 串行处理,每个平台+快递 组分别发送;返回沿用现有简要风格,不返回明细。",
|
||
"endpoint": "/system",
|
||
"authRequired": false,
|
||
"loginRequired": true,
|
||
"status": {
|
||
"isUsed": false,
|
||
"isPlaceholder": false
|
||
},
|
||
"headers": [
|
||
{
|
||
"name": "Authorization",
|
||
"type": "string",
|
||
"required": true,
|
||
"description": "Bearer token"
|
||
}
|
||
],
|
||
"params": [
|
||
{
|
||
"name": "computerId",
|
||
"type": "string",
|
||
"required": false,
|
||
"description": "打印电脑 ID;历史/customize 分支可能使用。注意:type=express 场景下不适用(该字段不再作为 express 路径的必填或传输约束)。"
|
||
},
|
||
{
|
||
"name": "count",
|
||
"type": "number",
|
||
"required": false,
|
||
"description": "打印份数;对 type=customize 有效。type=express 场景下不保留,相应字段会被忽略。"
|
||
},
|
||
{
|
||
"name": "data",
|
||
"type": "object",
|
||
"required": true,
|
||
"description": "打印业务数据对象。对于 type=express:必须提供 data.waveGroups(来源于 order.print.getWavePlatformPrintData 的返回值 data.waveGroups),接口按 waveGroups->platforms 串行处理,每个 平台+快递 组分别发送;对于 type=customize,data 的具体字段由模板决定。"
|
||
},
|
||
{
|
||
"name": "printer",
|
||
"type": "string",
|
||
"required": false,
|
||
"description": "打印机名称;type=customize 使用。type=express 下忽略(由快递平台/站点决定打印目标)。"
|
||
},
|
||
{
|
||
"name": "template",
|
||
"type": "object",
|
||
"required": false,
|
||
"description": "打印模板对象;仅 type=customize 时必填且应包含 page_width、page_height、template_content。type=express 场景下忽略 template 字段。"
|
||
},
|
||
{
|
||
"name": "timestamp",
|
||
"type": "string",
|
||
"required": false,
|
||
"description": "业务时间戳;历史字段。type=express 场景下不适用。"
|
||
},
|
||
{
|
||
"name": "type",
|
||
"type": "string",
|
||
"required": true,
|
||
"description": "打印类型;支持 customize、express。对于 express 场景,必须遵守下列额外约束:提供 printStationId、requestCode,并在 data.waveGroups 中传入来自 order.print.getWavePlatformPrintData 的 waveGroups 数据。"
|
||
},
|
||
{
|
||
"name": "printStationId",
|
||
"type": "string",
|
||
"required": true,
|
||
"description": "打印站点/工作站标识(必填,type=express 时必须提供),用于指示目标打印站或分发单元。"
|
||
},
|
||
{
|
||
"name": "requestCode",
|
||
"type": "string",
|
||
"required": true,
|
||
"description": "请求去重/防重放 ID(必填,type=express 时必须提供)。接口约束:requestCode 在约定周期内不得变更(例如一次批次/会话期间),系统在同一次请求处理范围内保证对重复 requestCode 进行防重放处理;此保护仅保证同一次请求内的去重/防重放,不等同于跨请求的强幂等保证。"
|
||
}
|
||
],
|
||
"response": [
|
||
{
|
||
"name": "flag",
|
||
"type": "string",
|
||
"required": false,
|
||
"description": "全局调用结果标识,成功时为 success,失败时为 failure"
|
||
},
|
||
{
|
||
"name": "code",
|
||
"type": "number",
|
||
"required": false,
|
||
"description": "业务状态码;成功时为 200,失败时通常为 1001 或 504"
|
||
},
|
||
{
|
||
"name": "message",
|
||
"type": "string",
|
||
"required": false,
|
||
"description": "返回信息"
|
||
},
|
||
{
|
||
"name": "printId",
|
||
"type": "number",
|
||
"required": false,
|
||
"description": "打印记录 ID;任务入库成功后返回,失败时若已生成记录也会返回。接口在 express 场景下不返回明细结果,只给出调用结果摘要。"
|
||
}
|
||
]
|
||
},
|
||
{
|
||
"method": "print.getPrintResult",
|
||
"title": "print.getPrintResult 接口",
|
||
"description": "print.getPrintResult 接口",
|
||
"endpoint": "/system",
|
||
"authRequired": false,
|
||
"loginRequired": true,
|
||
"status": {
|
||
"isUsed": false,
|
||
"isPlaceholder": false
|
||
},
|
||
"headers": [
|
||
{
|
||
"name": "Authorization",
|
||
"type": "string",
|
||
"required": true,
|
||
"description": "Bearer token"
|
||
}
|
||
],
|
||
"params": [
|
||
{
|
||
"name": "printId",
|
||
"type": "string",
|
||
"required": true,
|
||
"description": "printId 参数"
|
||
}
|
||
],
|
||
"response": []
|
||
},
|
||
{
|
||
"method": "print.getPrintRecordItem",
|
||
"title": "print.getPrintRecordItem 接口",
|
||
"description": "print.getPrintRecordItem 接口",
|
||
"endpoint": "/system",
|
||
"authRequired": false,
|
||
"loginRequired": true,
|
||
"status": {
|
||
"isUsed": false,
|
||
"isPlaceholder": false
|
||
},
|
||
"headers": [
|
||
{
|
||
"name": "Authorization",
|
||
"type": "string",
|
||
"required": true,
|
||
"description": "Bearer token"
|
||
}
|
||
],
|
||
"params": [
|
||
{
|
||
"name": "id",
|
||
"type": "number",
|
||
"required": true,
|
||
"description": "id 参数"
|
||
}
|
||
],
|
||
"response": []
|
||
},
|
||
{
|
||
"method": "print.getList",
|
||
"title": "查询当前仓库下的打印台列表,支持分页与 where 条件筛选(支持字段:id、name、computer_id、custom_barcode)。",
|
||
"description": "查询当前仓库下的打印台列表,支持分页与 where 条件筛选(支持字段:id、name、computer_id、custom_barcode)。",
|
||
"endpoint": "/system",
|
||
"authRequired": false,
|
||
"loginRequired": true,
|
||
"status": {
|
||
"isUsed": false,
|
||
"isPlaceholder": false
|
||
},
|
||
"headers": [
|
||
{
|
||
"name": "Authorization",
|
||
"type": "string",
|
||
"required": true,
|
||
"description": "Bearer token"
|
||
}
|
||
],
|
||
"params": [
|
||
{
|
||
"name": "page",
|
||
"type": "number",
|
||
"required": false,
|
||
"description": "页码,默认 1"
|
||
},
|
||
{
|
||
"name": "pageSize",
|
||
"type": "number",
|
||
"required": false,
|
||
"description": "每页数量,默认 20"
|
||
},
|
||
{
|
||
"name": "where",
|
||
"type": "object",
|
||
"required": false,
|
||
"description": "筛选条件对象;支持字段:id(等值)、name、computer_id、custom_barcode;推荐使用 { operator, value, type } 标准结构"
|
||
}
|
||
],
|
||
"response": [
|
||
{
|
||
"name": "data",
|
||
"type": "object",
|
||
"required": true,
|
||
"description": "返回数据对象,包含 list 与 pagination"
|
||
}
|
||
]
|
||
},
|
||
{
|
||
"method": "print.getItem",
|
||
"title": "查询单个打印台详情,返回打印台对象(raw 行记录,含 subject_config)",
|
||
"description": "查询单个打印台详情,返回打印台对象(raw 行记录,含 subject_config)",
|
||
"endpoint": "/system",
|
||
"authRequired": false,
|
||
"loginRequired": true,
|
||
"status": {
|
||
"isUsed": false,
|
||
"isPlaceholder": false
|
||
},
|
||
"headers": [
|
||
{
|
||
"name": "Authorization",
|
||
"type": "string",
|
||
"required": true,
|
||
"description": "Bearer token"
|
||
}
|
||
],
|
||
"params": [
|
||
{
|
||
"name": "id",
|
||
"type": "number",
|
||
"required": true,
|
||
"description": "打印台 ID,必填"
|
||
}
|
||
],
|
||
"response": [
|
||
{
|
||
"name": "data",
|
||
"type": "object",
|
||
"required": true,
|
||
"description": "打印台原始记录(PrintStation raw),字段示例"
|
||
}
|
||
]
|
||
},
|
||
{
|
||
"method": "print.add",
|
||
"title": "新增打印台:关联打印电脑并可保存 subject_config(会由模型 normalizeSubjectConfig 校验)。",
|
||
"description": "新增打印台:关联打印电脑并可保存 subject_config(会由模型 normalizeSubjectConfig 校验)。",
|
||
"endpoint": "/system",
|
||
"authRequired": false,
|
||
"loginRequired": true,
|
||
"status": {
|
||
"isUsed": false,
|
||
"isPlaceholder": false
|
||
},
|
||
"headers": [
|
||
{
|
||
"name": "Authorization",
|
||
"type": "string",
|
||
"required": true,
|
||
"description": "Bearer token"
|
||
}
|
||
],
|
||
"params": [
|
||
{
|
||
"name": "computer_id",
|
||
"type": "number",
|
||
"required": true,
|
||
"description": "关联的打印电脑 ID(必填)"
|
||
},
|
||
{
|
||
"name": "name",
|
||
"type": "string",
|
||
"required": true,
|
||
"description": "打印台名称(必填)"
|
||
},
|
||
{
|
||
"name": "custom_barcode",
|
||
"type": "string",
|
||
"required": false,
|
||
"description": "自定义条码"
|
||
},
|
||
{
|
||
"name": "default_printer_name",
|
||
"type": "string",
|
||
"required": false,
|
||
"description": "默认打印机名称"
|
||
},
|
||
{
|
||
"name": "subject_config",
|
||
"type": "object",
|
||
"required": false,
|
||
"description": "打印台的主题/业务配置(可选,若存在将调用模型 normalizeSubjectConfig 进行校验)"
|
||
}
|
||
],
|
||
"response": [
|
||
{
|
||
"name": "data",
|
||
"type": "object",
|
||
"required": true,
|
||
"description": "新建的打印台对象(raw)"
|
||
}
|
||
]
|
||
},
|
||
{
|
||
"method": "print.hasName",
|
||
"title": "print.hasName 接口",
|
||
"description": "print.hasName 接口",
|
||
"endpoint": "/system",
|
||
"authRequired": false,
|
||
"loginRequired": true,
|
||
"status": {
|
||
"isUsed": false,
|
||
"isPlaceholder": false
|
||
},
|
||
"headers": [
|
||
{
|
||
"name": "Authorization",
|
||
"type": "string",
|
||
"required": true,
|
||
"description": "Bearer token"
|
||
}
|
||
],
|
||
"params": [
|
||
{
|
||
"name": "name",
|
||
"type": "string",
|
||
"required": true,
|
||
"description": "name 参数"
|
||
},
|
||
{
|
||
"name": "id",
|
||
"type": "number",
|
||
"required": false,
|
||
"description": "id 参数"
|
||
}
|
||
],
|
||
"response": []
|
||
},
|
||
{
|
||
"method": "print.updateItem",
|
||
"title": "更新打印台信息:支持更新 name、computer_id、custom_barcode、default_printer_name 以及 subject_config(会走 normalizeSubjectConfig)。",
|
||
"description": "更新打印台信息:支持更新 name、computer_id、custom_barcode、default_printer_name 以及 subject_config(会走 normalizeSubjectConfig)。",
|
||
"endpoint": "/system",
|
||
"authRequired": false,
|
||
"loginRequired": true,
|
||
"status": {
|
||
"isUsed": false,
|
||
"isPlaceholder": false
|
||
},
|
||
"headers": [
|
||
{
|
||
"name": "Authorization",
|
||
"type": "string",
|
||
"required": true,
|
||
"description": "Bearer token"
|
||
}
|
||
],
|
||
"params": [
|
||
{
|
||
"name": "id",
|
||
"type": "number",
|
||
"required": true,
|
||
"description": "打印台 ID(必填)"
|
||
},
|
||
{
|
||
"name": "computer_id",
|
||
"type": "number",
|
||
"required": false,
|
||
"description": "要更新的打印电脑 ID"
|
||
},
|
||
{
|
||
"name": "custom_barcode",
|
||
"type": "string",
|
||
"required": false,
|
||
"description": "自定义条码"
|
||
},
|
||
{
|
||
"name": "name",
|
||
"type": "string",
|
||
"required": false,
|
||
"description": "打印台名称"
|
||
},
|
||
{
|
||
"name": "default_printer_name",
|
||
"type": "string",
|
||
"required": false,
|
||
"description": "默认打印机名称"
|
||
},
|
||
{
|
||
"name": "subject_config",
|
||
"type": "object",
|
||
"required": false,
|
||
"description": "subject_config(可选),传入将替换/规范化配置"
|
||
}
|
||
],
|
||
"response": [
|
||
{
|
||
"name": "data",
|
||
"type": "object",
|
||
"required": false,
|
||
"description": "更新结果,通常返回 null"
|
||
}
|
||
]
|
||
},
|
||
{
|
||
"method": "print.del",
|
||
"title": "批量删除(软删除)打印台:将指定 ids 的记录标记为 deleted=1。",
|
||
"description": "批量删除(软删除)打印台:将指定 ids 的记录标记为 deleted=1。",
|
||
"endpoint": "/system",
|
||
"authRequired": false,
|
||
"loginRequired": true,
|
||
"status": {
|
||
"isUsed": false,
|
||
"isPlaceholder": false
|
||
},
|
||
"headers": [
|
||
{
|
||
"name": "Authorization",
|
||
"type": "string",
|
||
"required": true,
|
||
"description": "Bearer token"
|
||
}
|
||
],
|
||
"params": [
|
||
{
|
||
"name": "ids",
|
||
"type": "array",
|
||
"required": true,
|
||
"description": "要删除的打印台 ID 数组,必须为非空数组(示例: [1,2,3])"
|
||
}
|
||
],
|
||
"response": [
|
||
{
|
||
"name": "data",
|
||
"type": "object",
|
||
"required": false,
|
||
"description": "返回空数据结构,表示操作成功"
|
||
}
|
||
]
|
||
},
|
||
{
|
||
"method": "print.getComputer",
|
||
"title": "查询当前仓库下状态为 1 的打印电脑列表(raw 列表)。",
|
||
"description": "查询当前仓库下状态为 1 的打印电脑列表(raw 列表)。",
|
||
"endpoint": "/system",
|
||
"authRequired": false,
|
||
"loginRequired": true,
|
||
"status": {
|
||
"isUsed": false,
|
||
"isPlaceholder": false
|
||
},
|
||
"headers": [
|
||
{
|
||
"name": "Authorization",
|
||
"type": "string",
|
||
"required": true,
|
||
"description": "Bearer token"
|
||
}
|
||
],
|
||
"params": [],
|
||
"response": [
|
||
{
|
||
"name": "data",
|
||
"type": "array",
|
||
"required": true,
|
||
"description": "打印电脑数组,每项为打印电脑的原始记录"
|
||
}
|
||
]
|
||
},
|
||
{
|
||
"method": "print.getComputerPrinter",
|
||
"title": "获取指定打印电脑的打印机列表(从 redis: printer:{id}:printerList 读取并返回 data 数组,通常为打印机名称数组或对象数组)。",
|
||
"description": "获取指定打印电脑的打印机列表(从 redis: printer:{id}:printerList 读取并返回 data 数组,通常为打印机名称数组或对象数组)。",
|
||
"endpoint": "/system",
|
||
"authRequired": false,
|
||
"loginRequired": true,
|
||
"status": {
|
||
"isUsed": false,
|
||
"isPlaceholder": false
|
||
},
|
||
"headers": [
|
||
{
|
||
"name": "Authorization",
|
||
"type": "string",
|
||
"required": true,
|
||
"description": "Bearer token"
|
||
}
|
||
],
|
||
"params": [
|
||
{
|
||
"name": "id",
|
||
"type": "number",
|
||
"required": true,
|
||
"description": "打印电脑 ID,必填"
|
||
}
|
||
],
|
||
"response": [
|
||
{
|
||
"name": "data",
|
||
"type": "array",
|
||
"required": true,
|
||
"description": "打印机数组,通常为字符串名称数组或打印机对象数组(取决于 redis 存储格式)"
|
||
}
|
||
]
|
||
},
|
||
{
|
||
"method": "print.savePrinters",
|
||
"title": "保存 default_printer_name 与 subject_config.express_bind_printer。",
|
||
"description": "保存 default_printer_name 与 subject_config.express_bind_printer。",
|
||
"endpoint": "/system",
|
||
"authRequired": false,
|
||
"loginRequired": true,
|
||
"status": {
|
||
"isUsed": false,
|
||
"isPlaceholder": false
|
||
},
|
||
"headers": [
|
||
{
|
||
"name": "Authorization",
|
||
"type": "string",
|
||
"required": true,
|
||
"description": "Bearer token"
|
||
}
|
||
],
|
||
"params": [
|
||
{
|
||
"name": "defaultPrinter",
|
||
"type": "string",
|
||
"required": true,
|
||
"description": "默认打印机名称(必填),会写入打印台的 `default_printer_name` 字段"
|
||
},
|
||
{
|
||
"name": "express",
|
||
"type": "array",
|
||
"required": true,
|
||
"description": "快递与打印机绑定数组(必填)。每项应包含首选字段 `express_code`(string)和 `printer_name`(string)。为兼容历史字段,也接受 `express_id`(可映射为 `express_code`)和 `name`(可映射为 `printer_name`)。接口实现会将结果序列化后写入打印台的 `subject_config.express_bind_printer`。"
|
||
},
|
||
{
|
||
"name": "print_station_id",
|
||
"type": "number",
|
||
"required": true,
|
||
"description": "目标打印台 ID(必填)。接口会根据此 ID 更新对应打印台记录的 default_printer_name 与 subject_config.express_bind_printer"
|
||
}
|
||
],
|
||
"response": [
|
||
{
|
||
"name": "data",
|
||
"type": "object",
|
||
"required": false,
|
||
"description": "成功不返回业务数据,语义为成功(实现中返回 { data: null, code: 0 })"
|
||
}
|
||
]
|
||
},
|
||
{
|
||
"method": "print.retryFailed",
|
||
"title": "失败项补打:重试指定打印记录的发送。被定时任务 print-retry-compensation 调用以批量触发失败项补打。",
|
||
"description": "失败项补打:重试指定打印记录的发送。被定时任务 print-retry-compensation 调用以批量触发失败项补打。",
|
||
"endpoint": "/system",
|
||
"authRequired": false,
|
||
"loginRequired": true,
|
||
"status": {
|
||
"isUsed": false,
|
||
"isPlaceholder": false
|
||
},
|
||
"headers": [
|
||
{
|
||
"name": "Authorization",
|
||
"type": "string",
|
||
"required": true,
|
||
"description": "Bearer token"
|
||
}
|
||
],
|
||
"params": [
|
||
{
|
||
"name": "print_ids",
|
||
"type": "array",
|
||
"required": true,
|
||
"description": "要补打的打印记录 ID 数组"
|
||
},
|
||
{
|
||
"name": "force",
|
||
"type": "boolean",
|
||
"required": false,
|
||
"description": "是否强制补打(当前实现仍不放宽状态判定)"
|
||
},
|
||
{
|
||
"name": "warehouse_id",
|
||
"type": "number",
|
||
"required": false,
|
||
"description": "显式指定仓库 ID(调度任务推荐提供),若缺失将使用当前用户的 store_id"
|
||
}
|
||
],
|
||
"response": [
|
||
{
|
||
"name": "flag",
|
||
"type": "string",
|
||
"required": true,
|
||
"description": "调用标识,成功为 success"
|
||
},
|
||
{
|
||
"name": "code",
|
||
"type": "number",
|
||
"required": true,
|
||
"description": "业务状态码,成功通常为 200"
|
||
},
|
||
{
|
||
"name": "message",
|
||
"type": "string",
|
||
"required": true,
|
||
"description": "返回信息"
|
||
},
|
||
{
|
||
"name": "success_count",
|
||
"type": "number",
|
||
"required": false,
|
||
"description": "成功补打数量"
|
||
},
|
||
{
|
||
"name": "failed_count",
|
||
"type": "number",
|
||
"required": false,
|
||
"description": "补打失败数量"
|
||
},
|
||
{
|
||
"name": "skipped_count",
|
||
"type": "number",
|
||
"required": false,
|
||
"description": "被跳过的记录数量"
|
||
},
|
||
{
|
||
"name": "retried",
|
||
"type": "array",
|
||
"required": false,
|
||
"description": "补打尝试结果数组"
|
||
},
|
||
{
|
||
"name": "skipped",
|
||
"type": "array",
|
||
"required": false,
|
||
"description": "跳过项明细"
|
||
}
|
||
]
|
||
}
|
||
]
|
||
}
|