2026-06-04 19:26:45 +08:00

323 lines
12 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-04 19:02:14",
"generatedAtLocal": "2026-06-04 19:02:14",
"source": "remote",
"filter": {
"platform": {
"value": "web",
"label": "网页端"
},
"project": {
"value": "all",
"label": "全部"
}
},
"module": {
"name": "快递编码管理模块",
"key": "setting.express",
"folder": "setting.express",
"interfaceCount": 7
},
"changes": {
"fromPreviousSnapshot": {
"moduleAdded": false,
"moduleRenamed": false,
"interfaceChanges": {
"addedMethods": [],
"deletedMethods": [],
"paramsUpdatedMethods": [],
"responseUpdatedMethods": []
}
}
},
"interfaces": [
{
"method": "index.getExpressList",
"title": "获取快递列表。默认返回系统基础快递与当前登录仓库自定义快递编码的合并结果:系统快递在前,仓库自定义编码在后,同一 `code` 仅保留首条(系统同码优先保留系统记录)。当 `systemOnly` 为真值(支持 `true`、`1`、`'1'`、`'true'`)时,仅返回系统基础快递列表。仅接受 `express_code` 入参,服务端会先 trim 再转为大写:`systemOnly=true` 时按系统快递编码过滤系统基础快递列表;`systemOnly=false` 时按自定义编码映射记录中的系统快递编码字段 `express_code` 过滤,仅返回当前登录仓库下匹配该系统快递编码的自定义编码列表,不再回传系统基础项。仓库范围来自当前登录用户 `ctx.user.store_id`;未识别到仓库时,自定义编码列表为空。接口优先读取缓存,未命中时回源 `wms_express` 与 `wms_express_setting`。",
"description": "获取快递列表。默认返回系统基础快递与当前登录仓库自定义快递编码的合并结果:系统快递在前,仓库自定义编码在后,同一 `code` 仅保留首条(系统同码优先保留系统记录)。当 `systemOnly` 为真值(支持 `true`、`1`、`'1'`、`'true'`)时,仅返回系统基础快递列表。仅接受 `express_code` 入参,服务端会先 trim 再转为大写:`systemOnly=true` 时按系统快递编码过滤系统基础快递列表;`systemOnly=false` 时按自定义编码映射记录中的系统快递编码字段 `express_code` 过滤,仅返回当前登录仓库下匹配该系统快递编码的自定义编码列表,不再回传系统基础项。仓库范围来自当前登录用户 `ctx.user.store_id`;未识别到仓库时,自定义编码列表为空。接口优先读取缓存,未命中时回源 `wms_express` 与 `wms_express_setting`。",
"endpoint": "/system",
"authRequired": false,
"loginRequired": true,
"status": {
"isUsed": false,
"isPlaceholder": false
},
"headers": [],
"params": [
{
"name": "systemOnly",
"type": "boolean|number|string",
"required": false,
"description": "是否仅返回系统基础快递列表;仅 `true`、`1`、`'1'`、`'true'` 会被识别为 true,其余值按 false 处理"
},
{
"name": "express_code",
"type": "string",
"required": false,
"description": "系统快递编码;服务端会去首尾空格并转为大写。`systemOnly=true` 时按该系统快递编码过滤系统基础快递列表;`systemOnly=false` 时按自定义映射记录中的系统快递编码字段 `express_code` 过滤当前仓库的自定义编码列表,而不是按自定义 `code` 过滤"
}
],
"response": [
{
"name": "flag",
"type": "string",
"required": true,
"description": "全局调用结果标识,成功时为 `success`"
},
{
"name": "code",
"type": "number",
"required": true,
"description": "业务状态码,成功时返回 200"
},
{
"name": "message",
"type": "string",
"required": true,
"description": "返回消息,成功时通常为 `ok`"
},
{
"name": "data",
"type": "array",
"required": true,
"description": "快递列表数组。默认模式下先返回系统基础快递,再追加当前仓库自定义编码;当传入 `express_code` 且 `systemOnly=false` 时,仅返回当前仓库下系统快递编码等于该 `express_code` 的自定义映射记录,不返回系统基础项。每项字段如下:"
}
]
},
{
"method": "setting.express.list",
"title": "查询当前仓库范围的快递映射列表,支持 where + pagination",
"description": "查询当前仓库范围的快递映射列表,支持 where + pagination",
"endpoint": "/system",
"authRequired": false,
"loginRequired": true,
"status": {
"isUsed": false,
"isPlaceholder": false
},
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "pagination",
"type": "object",
"required": false,
"description": "分页参数,支持 page / pageSize,兼容 currentPage / page_size / size"
},
{
"name": "where",
"type": "object",
"required": false,
"description": "统一 where 条件对象;推荐使用 { operator, value, type } 标准结构"
}
],
"response": []
},
{
"method": "setting.express.listBase",
"title": "返回系统快递基础列表(系统级别基础快递,不含仓库自定义)",
"description": "返回系统快递基础列表(系统级别基础快递,不含仓库自定义)",
"endpoint": "/system",
"authRequired": false,
"loginRequired": true,
"status": {
"isUsed": false,
"isPlaceholder": false
},
"headers": [],
"params": [],
"response": []
},
{
"method": "setting.express.create",
"title": "创建快递映射,仅写入已实现字段(code、name、express_code 等)",
"description": "创建快递映射,仅写入已实现字段(code、name、express_code 等)",
"endpoint": "/system",
"authRequired": false,
"loginRequired": true,
"status": {
"isUsed": false,
"isPlaceholder": false
},
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "code",
"type": "string",
"required": true,
"description": "快递映射编码;接口会转为大写"
},
{
"name": "name",
"type": "string",
"required": true,
"description": "快递名称(最大 50 字符)"
},
{
"name": "express_code",
"type": "string",
"required": true,
"description": "系统快递编码;同时支持驼峰写法 expressCode"
}
],
"response": []
},
{
"method": "setting.express.checkCodeUnique",
"title": "校验快递编码在当前仓库/主体维度唯一性,仅支持 code 与可选 id 排除自身",
"description": "校验快递编码在当前仓库/主体维度唯一性,仅支持 code 与可选 id 排除自身",
"endpoint": "/system",
"authRequired": false,
"loginRequired": true,
"status": {
"isUsed": false,
"isPlaceholder": false
},
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "code",
"type": "string",
"required": true,
"description": "待校验的快递编码"
},
{
"name": "id",
"type": "number",
"required": false,
"description": "排除自身 id(更新时使用)"
}
],
"response": []
},
{
"method": "setting.express.update",
"title": "更新快递映射。必须提供 `id`(必填),且至少提供 `code`、`name` 或 `express_code` 中的一个用于更新;同时支持 `expressCode` 驼峰写法。",
"description": "更新快递映射。必须提供 `id`(必填),且至少提供 `code`、`name` 或 `express_code` 中的一个用于更新;同时支持 `expressCode` 驼峰写法。",
"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;也兼容别名 `setting_id` / `settingId`"
},
{
"name": "code",
"type": "string",
"required": false,
"description": "快递映射编码(最大 50 字符,接口会大写化并校验在当前仓库的唯一性)"
},
{
"name": "name",
"type": "string",
"required": false,
"description": "快递名称(最大 50 字符)"
},
{
"name": "express_code",
"type": "string",
"required": false,
"description": "系统快递编码(必须为系统已存在的编码);支持 `expressCode` 驼峰写法"
}
],
"response": [
{
"name": "data",
"type": "object",
"required": true,
"description": "更新后的快递映射对象(规范化字段)"
}
]
},
{
"method": "setting.express.delete",
"title": "批量软删除快递映射;接受 ids 参数,已删除记录会在结果中标记。",
"description": "批量软删除快递映射;接受 ids 参数,已删除记录会在结果中标记。",
"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数组;支持数组、逗号字符串或单个ID。"
}
],
"response": [
{
"name": "ids",
"type": "array",
"required": true,
"description": "请求中的所有 id 列表(原样返回)"
},
{
"name": "deleted_ids",
"type": "array",
"required": true,
"description": "本次实际被软删除的 ID 列表(即原本未被删除的 ID)"
},
{
"name": "already_deleted_ids",
"type": "array",
"required": true,
"description": "请求中已处于已删除状态的 ID 列表"
},
{
"name": "status",
"type": "string",
"required": true,
"description": "固定返回 'deleted'"
}
]
}
]
}