2026-06-09 18:14:40 +08:00

774 lines
24 KiB
JSON
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

{
"generatedAt": "2026-06-09 18:13:02",
"generatedAtLocal": "2026-06-09 18:13:02",
"source": "remote",
"filter": {
"platform": {
"value": "web",
"label": "网页端"
},
"project": {
"value": "all",
"label": "全部"
}
},
"module": {
"name": "打印模块",
"key": "print",
"folder": "print",
"interfaceCount": 15
},
"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": "跳过项明细"
}
]
},
{
"method": "print.notifyLock",
"title": "仅执行订单锁定流程,不发送打印任务;记录打印任务日志并写入订单操作日志。兼容别名:print.notify_lock(等价转调)。",
"description": "仅执行订单锁定流程,不发送打印任务;记录打印任务日志并写入订单操作日志。兼容别名:print.notify_lock(等价转调)。",
"endpoint": "/system",
"authRequired": false,
"loginRequired": true,
"status": {
"isUsed": false,
"isPlaceholder": false
},
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "order_ids",
"type": "array",
"required": false,
"description": "订单 ID 数组(与 orderIds 互为别名)。至少需提供 order_ids/orderIds/waveGroups/data.waveGroups 中的一类以提取订单 ID。"
},
{
"name": "orderIds",
"type": "array",
"required": false,
"description": "订单 ID 数组(驼峰兼容,等同于 order_ids)。"
},
{
"name": "waveGroups",
"type": "array",
"required": false,
"description": "波次分组结构(可从中提取订单 ID,参考 order.print.getWavePlatformPrintData 返回的 waveGroups)。"
},
{
"name": "data",
"type": "object",
"required": false,
"description": "兼容包装对象;若传入 data.waveGroups,可从中提取订单 ID。"
}
],
"response": [
{
"name": "locked_count",
"type": "number",
"required": false,
"description": "成功锁定的订单数量"
},
{
"name": "order_ids_count",
"type": "number",
"required": false,
"description": "请求中识别出的订单 ID 数量"
},
{
"name": "order_ids",
"type": "array",
"required": false,
"description": "本次尝试锁定的订单 ID 列表"
},
{
"name": "source",
"type": "string",
"required": false,
"description": "操作来源标识(可选,若后端返回则提供具体来源)"
}
]
},
{
"method": "print.notify_lock",
"title": "兼容别名(等价转调到 print.notifyLock);建议使用 print.notifyLock。",
"description": "兼容别名(等价转调到 print.notifyLock);建议使用 print.notifyLock。",
"endpoint": "/system",
"authRequired": false,
"loginRequired": true,
"status": {
"isUsed": false,
"isPlaceholder": false
},
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [],
"response": []
}
]
}