wangheng/xiaoqu_mcp_service

Fork 0

Files

T

jiashumengandxiaoqu e2835362e9 feat(mcp): add warehouse inbound query tools

2026-09-15 16:31:40 +08:00

31 KiB

Raw Blame History

xiaoqu-agent-service MCP 工具接口文档

本文档是 MCP 服务对外暴露工具的接口契约。新增/修改工具时必须同步更新本文档（开发约定见 agent-mcp-service-design.md §12）。文档中的入参与代码 @ToolParam、出参与工具实际返回保持一致；在线验证方式见文末附录。

0. 调用约定（所有工具共用）

项	说明
端点	`POST http://<host>:8088/mcp`（MCP Streamable HTTP）
认证	Header `Authorization: Bearer xqak_xxx`，Token 由管理后台或受信任 Open API 获取；服务端保存 SHA-256 及加密密文
工具可见性	`tools/list` 按 ak 作用域过滤，只返回该 ak 作用域并集内且启用状态的工具（2026-09-04 起，服务端 servlet 层重写响应实现）；`tools/call` 另有强制校验兜底，越权返回可读拒绝信息并落审计（denied）
行级数据权限	跟 ak 所属人走，照搬老系统 `getByIsAgent` 语义（见设计文档 §3.3），与作用域无关
分页	列表类工具统一 `page`（从 1 开始，默认 1）、`rows`（默认 20，上限 100，超出截断为 100 并在返回 `notice` 字段提示）
分页出参	统一含 `total`（总数）、`page`、`rows`、`records`（本页记录）、`notice`（仅截断时出现）
工具声明	`tools/list` 中每个工具带 MCP annotations：只读（`readOnlyHint=true`）、幂等（`idempotentHint=true`）、非破坏性（`destructiveHint=false`）（REQ-20260911-0011 起）

0.1 schema_version 双跑（REQ-20260911-0011 起）

默认（v1，兼容面）：tools/call 返回的 result.content[0].text 即各工具原有 JSON，无 structuredContent，老客户端零改动。
显式声明新版本：请求头加 X-Mcp-Schema-Version: 2，tools/call 响应额外写入 result.structuredContent 统一信封，content 文本保持不变：

{ "schema_version": 2, "request_id": "<服务端生成 UUID>", "data": { "…": "各工具原有 JSON" } }

版本头只接受 1/2（缺省按 1）；其他值在 tools/call 上直接返回 SCHEMA_VERSION_UNSUPPORTED 错误，不执行工具。
v2 请求下 tools/list 的每个工具额外带 outputSchema（信封结构）；业务字段契约仍以本文档各工具章节为准。

0.2 统一错误码（REQ-20260911-0011 起）

工具执行失败返回 isError=true，content[0].text 为结构化 JSON（不再是裸异常文本）；v2 下同样的错误出现在 structuredContent.error：

{ "error": { "code": "PERMISSION_DENIED", "message": "人类可读说明", "request_id": "…" } }

code	含义
UNAUTHENTICATED	缺少有效 ak 或鉴权上下文丢失
PERMISSION_DENIED	token 作用域不含该工具或工具已停用
NOT_FOUND_OR_FORBIDDEN	资源不存在或无权查看（不区分，防探测）
RATE_LIMITED	触发限流（预留）
UPSTREAM_UNAVAILABLE	上游数据源（DB/Redis）暂时不可用
SYNC_CURSOR_EXPIRED	增量同步游标过期（预留）
SCHEMA_VERSION_UNSUPPORTED	声明的 schema_version 不受支持
DATA_INTEGRITY_ERROR	数据不一致或未预期异常（兜底；细节只落服务端日志，凭 request_id 排查）

日志与审计不记录 Token/ak，手机号一律脱敏为 138****5678 形式。

1. agent.count

统计代理商总数（demo 工具）。

分类：system ｜类型：读
数据来源：m0 库 agent 表，固定条件 soft_delete = 0

入参：无

出参：

字段	类型	说明
count	number	代理商总数

{ "count": 62 }

2. agent.list.query

查询代理商列表（分页），对应老系统 /agent/listByPage。

分类：customer ｜类型：读
数据来源：m0 库 agent 表
行级权限：权限组 isagent=1（代理商身份）只查自己名下直属下级（supervisor_id = 自己agentId）；isagent=0（总部）看全部。传 id 精确查询时：代理商仅限自己或直属下级，总部可传任意合法 id，且其余过滤条件失效。

入参：

参数	类型	必填	说明
id	number	否	代理商 id，精确查询；传入后忽略其他过滤条件
name	string	否	代理商名称，模糊匹配
level	number	否	级别：0=总部 1=一级 2=二级
channelNo	string	否	渠道编号：Z=总部 F=分公司 D=代理
province	string	否	省份，精确匹配，如 `北京市`
city	string	否	城市，精确匹配，如 `北京市`
serialnumber	string	否	代理商编号，精确匹配
page	number	否	页码，从 1 开始，默认 1
rows	number	否	每页条数，默认 20，上限 100

出参 records 字段：

字段	说明
id / name	代理商 id / 名称
level / channelNo / serialnumber	级别 / 渠道编号 / 代理商编号
supervisorName	上级代理名称（无上级为 `-`，批量富化）
province / city / countyseat	省 / 市 / 区县
contact / phone	联系人 / 电话
agencyarea / memo	代理区域 / 备注
createTime	创建时间，`yyyy-MM-dd HH:mm:ss`

{
  "total": 62, "page": 1, "rows": 20,
  "records": [ { "id": 19, "name": "北京D类代理", "level": 2, "channelNo": "D", "...": "..." } ]
}

3. property.list.query

查询物业（客户）列表（分页），对应老系统 /property/listByPage。

分类：customer ｜类型：读
数据来源：m0 库 properyt 表
行级权限（完整版 getByIsAgent 语义）：
- 总部（isagent=0）：全部；
- 代理商（isagent=1）：自己 + 直属下级代理 + warehouse_agent_auth 代管代理名下物业，及 agent_manage_district_auth 授权代管的物业；
- 销售部门非负责人：自己创建的物业 ∪ 代管授权代理名下物业（id IN (...) 结构，与其余规则互斥，1:1 复刻老代码 saleFlag 分支）。
- 不含 enterprise_type=2 物业用户限自己物业的规则（物业用户不查此列表）。

入参：

参数	类型	必填	说明
name	string	否	物业名称，模糊匹配
agentId	number	否	所属代理商 id，精确匹配
serialnumber	string	否	物业编号，精确匹配
province	string	否	省份，精确匹配
city	string	否	城市，精确匹配
contact	string	否	联系人，精确匹配
phone	string	否	联系电话，精确匹配
page	number	否	页码，从 1 开始，默认 1
rows	number	否	每页条数，默认 20，上限 100

出参 records 字段：

字段	说明
id / name / serialnumber	物业 id / 名称 / 编号
agentName	所属代理商名称（查不到为 `未查询到`）
createName	创建人/销售姓名（未分配为 `未分配`）
province / city / countyseat / address	省 / 市 / 区县 / 详细地址
contact / phone	联系人 / 电话
createTime	创建时间，`yyyy-MM-dd HH:mm:ss`

4. district.list.query

分页查询站点列表，对应老系统 /district/districtlistByPage，但使用固定轻量字段契约。

分类：customer ｜类型：读
数据来源：m0 库 district_district_strategy 视图，固定 soft_delete = 0、id DESC
行级权限：总部看全部；代理商按自己、直属下级、代管代理及授权物业过滤；销售部门非负责人沿用老接口的互斥物业范围。筛选条件只能缩小权限结果。

入参：

参数	类型	必填	说明
id	number	否	站点 id，正整数，精确匹配
districtName	string	否	站点名称，模糊匹配
districtState	number	否	0=测试 1=履约 2=演示 3=撤机
province	string	否	省份，模糊匹配
city	string	否	城市，模糊匹配
agentId	number	否	代理商 id，正整数，精确匹配
propertyId	number	否	物业 id，正整数，精确匹配
page	number	否	页码，从 1 开始，默认 1
rows	number	否	每页条数，默认 20，上限 100

出参 records 字段：

id、districtName、districtNumber、propertyId、propertyName、agentId、agentName、province、city、countyseat、address、districtState、onlineState、hardwareCount、isSmart。

propertyName、agentName 均为批量富化，查不到时返回 未查询到。

5. district.detail.get

按站点 id 获取扩展详情。站点 id 与当前用户行权限在同一个数据库查询条件中组合。

分类：customer ｜类型：读
入参：id（number，必填，正整数）
找到：{ "found": true, "data": { ... } }
不存在或无权限：{ "found": false, "message": "站点不存在或无权访问" }

data 字段：

分组	字段
归属	id、districtName、districtNumber、propertyId、propertyName、agentId、agentName、salesId、salesName、serviceCompanyId、serviceCompany
地址联系人	province、city、countyseat、address、contact、phone、mail
站点属性	businessFormat、attributeId、attributeName、installType、isSmart、lnfluenceLevel、buildCount、hardwareCount、airdetectorFlag
状态周期	districtState、onlineState、testDate、honourDate、weaningDate、testDays
设备耗材	deviceSalesType、paperSalesType、consumablesType、posDevicePaperNorm、toiletDevicePaperNorm
功能开关	pointState、assignmentWorkState、airState、messageFlag、reportFlag、lockMachineFlag、eventRepairFlag、rfidUseFlag、calibratedFlag、illegalPaperDisable
语音配置	lowerPaperState、noPaperState、powerWarning、waitTimes
报警配置	warning、warning2、warning3、warningTime、paperPercentWarn、maintainOrderWarning、foamCountWarning、foamPowerWarning
业务配置	pointDeduction、effectiveUseTime、consumablesPrice、billDate、billType、billTypeStr、fineMoney
运行配置	districtRefresh（Redis 未配置默认 5）、forbidFunction（Redis 未配置默认 0）
审计信息	createId、createName、createTime、modifyTime、memo

固定不返回 softDelete、enterpriseId、modifyId、内部服务 URL、重复 districtId、语义未确认的 supervisorId 和 SKU 列表。

6. sys.ping

服务自检（demo 工具，证明链路连通）。

分类：system ｜类型：读

入参：无

出参：

字段	说明
service	服务名（spring.application.name）
version	服务版本
time	服务器当前时间
redis	`PONG` 表示 Redis 连通；否则为 `ERROR: ...`

7. mall.order.list.query

查询商城订单列表（分页），对应老系统 POST /mallGoodsOrder/listByPage。

分类：customer ｜类型：读
数据来源：m1 商城库（xiaoqu_mall_d）mall_goods_order 表
行级权限（PermissionService.applyOrderRowFilter，移植老接口 WrapperUtils.getSaleCompany 语义）：
- 总部（isagent=0）：全部；
- 代理商（isagent=1）：sale_company_id IN (自己 + 直属下级 + warehouse_agent_auth 代管代理)，有代管物业授权时再 OR property_id IN (agent_manage_district_auth 代管物业)；
- 销售部门非负责人：property_id IN (自己创建的物业 + 代管代理名下物业)，与上一条互斥。

入参：

参数	类型	必填	说明
orderNo	string	否	订单编号，模糊匹配
agentId	number	否	代理商 id，精确匹配
propertyId	number	否	物业 id，精确匹配
orderType	number	否	订单类型：0=代理 1=物业
orderState	number	否	订单状态（单选）：0=待付款 1=待出库 2=待发货 3=已发货 4=已签收 5=已收货 6=已取消 7=已删除
payState	number	否	回款状态：0=待付款 1=已付款 2=付款中
startOrderTime	string	否	下单时间起，`yyyy-MM-dd`
endOrderTime	string	否	下单时间止，`yyyy-MM-dd`（含当天）
page	number	否	页码，从 1 开始，默认 1
rows	number	否	每页条数，默认 20，上限 100（超出截断为 100 并在 notice 提示）

出参 records 字段（按 id 倒序）：

字段	说明
id / orderNo / orderTime	订单 id / 编号 / 下单时间（`yyyy-MM-dd HH:mm:ss`）
orderType / agentName / propertyName	订单类型 / 代理名称 / 物业名称
saleCompany	销售公司
payMoney / paidMoney / unPayMoney	应付 / 已付 / 未付金额
orderState / payState / warehouseState	订单状态 / 回款状态 / 出库状态（0=未出库 1=已出库 2=部分出库）
customerName	客户名称：orderType=0 取代理金蝶名称，否则取物业金蝶名称（批量富化，同老接口）

8. mall.order.detail.query

按订单号查询商城订单详情（订单 + 商品明细 + 收货地址一次返回，合并老系统三个接口）。

分类：customer ｜类型：读
数据来源：m1 库 mall_goods_order + mall_order_details + mall_shipping_address
行级权限：与 mall.order.list.query 一致；订单不存在或无权查看时 record=null 并在 notice 说明（两者不区分，不泄露订单是否存在）。

入参：

参数	类型	必填	说明
orderNo	string	是	订单编号

出参：

record：订单关键字段（金额类 payMoney/paidMoney/unPayMoney/totalMoney/goodsMoney/postageMoney/discountMoney，状态类 orderState/payState/orderPayState/warehouseState/orderInvoiceState，时间类 orderTime/payTime/receiptTime/signTime/createTime，及 accountsType/paymentType/goodsType/saleCompany/payNo/memo 等）+ 收货信息（reveiveName/reveiveNumber/province/city/countyseat/address，由 address_id 关联 mall_shipping_address）。
items：商品明细列表，每行含 spuNo/spuName/skuNo/count/price/payMoney/payState/warehouseState。

9. mall.order.logistics.query

按订单号查询商城订单物流（发货信息 + 物流轨迹），对应老系统 GET /mallGoodsOrder/getMallLogistics。

分类：customer ｜类型：读
数据来源：m1 库 mall_order_logistics + mall_order_logistics_detai
行级权限：与 mall.order.list.query 一致；订单不存在或无权查看时 logistics=null 并在 notice 说明（两者不区分）。
注意：轨迹表 logistics_order_no 字段老系统写入时塞的是订单号而非快递单号，故按 orderNo 查询（照搬老系统语义）。物流轨迹为系统内业务节点手工写入的记录，非实时快递查询，可能不全（菜鸟定时同步已停用）。

入参：

参数	类型	必填	说明
orderNo	string	是	订单编号

出参：

logistics（无物流记录时为 null）：logisticsName（快递公司）/ logisticsOrderNo（快递单号）/ sendMode（0=快递 1=自送）/ state（0=已出单 1=已出库 2=已发货 3=已揽件 4=运输中 5=待取件 6=派送中 7=已签收）/ deliverName / deliverNumber / sendTime / receivingGoodsName / reveiveName / reveiveNumber / address。
tracks：轨迹列表，按时间正序，每行含 memo（轨迹描述）/ state / picList / createTime。

10. hardware.list.query

分页查询出纸机列表，对应老系统 POST /hardware/listByPage（HardwareViewController）。

分类：hardware ｜类型：读
数据来源：m0 库 hardware_view 视图，固定 soft_delete = 0、id DESC
行级权限（PermissionService.applyHardwareRowFilter，与站点同一 getByIsAgent(propertyFlag=true, className="property_id") 变体）：
- 总部（isagent=0）：全部；
- 代理商（isagent=1）：agent_id IN (自己 + 直属下级 + warehouse_agent_auth 代管代理)，有代管物业授权时再 OR property_id IN (agent_manage_district_auth 代管物业)；
- 销售部门非负责人：property_id IN (自己创建的物业 + 代管代理名下物业)，与上一条互斥。
富化（修正老接口 N+1，按页批量）：agentName/propertyName/districtName 走 Redis key name:Agent:{id} / name:Properyt:{id} / name:District:{id} multiGet；断纸状态 piStatus 批量读 Assignment:{snCode}:29（无 key 返回 0）；本页非空 imsi 一次性 IN 查 networkcard 表。返回 hardware_view 全字段，不做字段级权限裁剪。

入参：

参数	类型	必填	说明
snCode	string	否	sn码，模糊匹配
deviceType	number	否	设备类型：0=厕纸机 1=擦手纸机
status	number	否	设备状态：1=在线 2=故障 3=离线
online	number	否	上下线状态：1=上线 2=下线
lockMachineState	number	否	锁机状态：0=未锁机 1=已锁机
agentId	number	否	代理商 id，正整数，精确匹配
propertyId	number	否	物业 id，正整数，精确匹配
districtId	number	否	站点 id，正整数，精确匹配
buildingId	number	否	楼 id，正整数，精确匹配
floor	string	否	楼层，精确匹配
imsi	string	否	imsi码，精确匹配
page	number	否	页码，从 1 开始，默认 1
rows	number	否	每页条数，默认 20，上限 100（超出截断为 100 并在 notice 提示）

出参 records 字段：hardware_view 全字段（snCode、deviceType、status/online/lockMachineState 状态四元组、sysversion/firmwareVersion/voiceVersion/advertiseVersion、imsi、电量/纸量/电池族、各功能开关、memo 等，时间格式 yyyy-MM-dd HH:mm:ss）+ 富化字段 agentName/propertyName/districtName/piStatus + 物联网卡字段 factoryType/carrier/dataBalance/dataUsage/iccid/msisdn（按 imsi 匹配，无卡为 null）。

11. hardware.detail.query

按 snCode 或 id 查询出纸机详情（二选一必填），行级权限与 hardware.list.query 一致。

分类：hardware ｜类型：读
数据来源：m0 库 hardware_view + district_district_strategy（站点信息）+ networkcard（物联网卡）
设备不存在或无权查看时 record=null 并在 notice 说明（两者不区分，不泄露设备是否存在）。

入参：

参数	类型	必填	说明
snCode	string	条件必填	sn码，精确匹配；与 id 二选一
id	number	条件必填	设备 id，正整数，精确匹配；与 snCode 二选一

出参：

record：hardware_view 全字段 + 与列表同一套富化（agentName/propertyName/districtName、piStatus、物联网卡 factoryType/carrier/dataBalance/dataUsage/iccid/msisdn）。
record.site（关联站点，district 表现有字段）：districtId、districtName、province、city、countyseat、address、contact、phone、buildingId、floor。注意 district 表无经纬度和楼名字段，楼座/楼层取 hardware_view。

12. contract.list.query

分页查询合同列表，对应老系统 /contract/listByPage 合同列表页（权限库 webpage id=394 contractList，页面字段定义 ContractListOutput）。

分类：customer ｜类型：读
数据来源：m2 库 contract_new 表，固定 soft_delete = 0、id DESC
行级权限（PermissionService.applyContractRowFilter，与站点/出纸机同一 getByIsAgent(propertyFlag=true) 变体，agent 维度落 contract_agent_id，property 维度落 property_id）：
- 总部（isagent=0）：全部；
- 代理商（isagent=1）：contract_agent_id IN (自己 + 直属下级 + warehouse_agent_auth 代管代理)，有代管物业授权时再 OR property_id IN (agent_manage_district_auth 代管物业)；
- 销售部门非负责人：property_id IN (自己创建的物业 + 代管代理名下物业)，与上一条互斥。
富化（按页批量 IN 查询，消除 N+1）：contractAgentName/customerAgentName 查 m0 agent，createName 查 m0 user；saleName/propertyName/customerName/customerNo 为合同表冗余快照，直接返回。

入参：

参数	类型	必填	说明
contractNo	string	否	合同编号，模糊匹配
contractName	string	否	合同名称，模糊匹配
propertyName	string	否	物业名称，模糊匹配
customerName	string	否	客户名称（金蝶客户名称快照），模糊匹配
customerNo	string	否	客户编号（=物业 serialnumber），精确匹配
contractAgentId	number	否	合同所属公司 id，精确匹配
customerAgentId	number	否	客户所属公司 id，精确匹配
propertyId	number	否	所属物业 id，精确匹配
contractStatus	number	否	合同状态：0=待审 1=驳回 2=正常 3=过期 4=终止
expireRemind	number	否	到期提醒开关：0=关 1=开
endDateFrom	string	否	合同结束日期起，格式 yyyy-MM-dd（查即将到期合同用）
endDateTo	string	否	合同结束日期止，格式 yyyy-MM-dd（含当天）
page	number	否	页码，从 1 开始，默认 1
rows	number	否	每页条数，默认 20，上限 100（超出截断为 100 并在 notice 提示）

出参 records 字段：contract_new 主要字段（id、contractNo、contractName、contractAgentId/customerAgentId、propertyId/propertyName、customerNo/customerName、amount、contact、startDate/endDate（yyyy-MM-dd）、expireRemind/remindDays/remindTime/reminded、saleId/saleName、contractStatus、stopReasonType/stopReason、createId、createTime）+ 富化字段 contractAgentName/customerAgentName/createName + 状态文案 contractStatusText。

13. contract.detail.query

按 id 或 contractNo 查询合同详情（二选一必填），行级权限与 contract.list.query 一致。

分类：customer ｜类型：读
数据来源：m2 库 contract_new + contract_file（附件）+ contract_process（流程/待办/操作记录）
合同不存在或无权查看时 record=null 并在 notice 说明（两者不区分，不泄露合同是否存在）；id/contractNo 都未传时 notice 提示"必须传一个"。

入参：

参数	类型	必填	说明
id	number	条件必填	合同 id；与 contractNo 二选一
contractNo	string	条件必填	合同编号，精确匹配；与 id 二选一

出参：

record：与列表同一套字段（含富化和 contractStatusText）。
files：合同附件列表，id/fileName/fileUrl/createTime，按 id 正序。
processes：审批流程记录，按 id 正序，字段 nodeType（0=创建 1=部门内审核 2=层级审核 3=终止 4=抄送）、auditLevel、operationType（0=创建 1=审核通过 2=审核驳回 3=终止 4=修改再提交 5=抄送）、userId/userName、scheduleState（0=无需待办 1=待办 2=已办）、remark、operateTime，均附 nodeTypeText/operationTypeText/scheduleStateText 文案。

14. integration.context.get

身份与能力自检（REQ-20260911-0012）：返回当前 Token 的集成上下文。所有数据每次调用实时取库，不缓存权限。

分类：integration ｜类型：读
数据来源：svc 库 agent_api_key / token_scope / agent_scope + ToolGuard 实时能力计算（与 tools/call 强制校验同源）

入参：无

出参：

字段	类型	说明
tenant_id	string	Token 所属数据域标识 = 启用状态的作用域编码（排序后逗号拼接；当前签发规则为一作用域一 Token）
principal_type	string	`user_delegated`（用户委托）/ `tenant_service`（服务主体）。当前按 token 绑定用户推导；`agent_api_key.principal_type` 列由后续需求（5629）补充后切换为读列
subject_id	number	用户 ID 或服务主体 ID
scopes	string[]	该 Token 允许调用的工具名集合（排序），与 tools/call 强制校验结果严格一致
data_scope_version	number	数据权限版本：token_scope 绑定集合最大 modify_time（空取 create_time）的 epoch 毫秒；无绑定为 0
capability_levels	string[]	`QUERY` / `SYNC`：能力集合中含 `*.changes.list` 工具时具备 SYNC（数据驱动）；无能力时为空数组
server_time	string	带时区的服务器时间（ISO_OFFSET_DATE_TIME）

15. warehouse.out.list.query

分页查询出库单，参考旧系统 POST /myWarehouseOut/allListByPage，但修复其出库日期误映射为申请日期、部分渠道未过滤和逐单查询明细的问题。

分类：warehouse ｜类型：读
数据来源：m2 warehouse_out、warehouse_out_details、warehouse_out_audit_process
行级权限：总部看全部；代理身份可看主单所属代理为自己/直属下级/授权代管代理的出库单，或明细涉及上述代理所属/负责管理仓库的出库单，或本人参与审核/处理的出库单。三类条件取并集；筛选条件只能缩小结果。
列表关联数据按本页主单 ID 批量查询，不逐单 N+1 查询。

入参：

参数	类型	必填	说明
outOrderNo / allocationOrderNo / mallOrderNo	string	否	出库/调拨/商城单号，模糊匹配
deliveryOrderNo / installOrderNo / pickupOrderNo	string	否	送货/装机/取货工单号，模糊匹配
agentId / warehouseId / warehouseTypeId / applyUserId	number	否	所属代理/涉及仓库/出库类型/申请人 ID，精确匹配
orderState	number	否	0=待审核 1=被驳回 2=待出库 3=已完成 4=已撤销 5=作废
sendMode	number	否	0=快递公司 1=自行派送
outSynchronizeState	number	否	0=未同步 1=已同步 2=无需同步
assetSynchronizeState	number	否	-1=无需同步 0=未同步 1=已同步
useCustomerType / useCustomerId	number	否	客户类型（0内部/1渠道商/2直营）和客户 ID
useCustomerName	string	否	客户名称，模糊匹配
outDateFrom / outDateTo	string	否	出库日期范围，`yyyy-MM-dd`，结束日期含当天
applyDateFrom / applyDateTo	string	否	申请日期范围，`yyyy-MM-dd`，结束日期含当天
page / rows	number	否	页码默认 1；每页默认 20、上限 100

出参 records 字段：主单 id/outOrderNo/allocationOrderNo/mallOrderNo、sourceType （NORMAL/ALLOCATION/MALL）、代理和出库类型、warehouseIds/warehouseNames、出库/商品数量、状态码与文案、申请人/时间、客户、schedulePeople、warehouseOutPeople/warehouseOutTimes、发货物流、同步状态、关联送货/装机/取货单号、备注及创建/修改时间。

16. warehouse.out.detail.query

按主键或出库单号查询完整出库单详情；调拨出库单可直接查询，以 sourceType=ALLOCATION 标识。

分类：warehouse ｜类型：读
行级权限与 warehouse.out.list.query 完全一致，并加入同一个主表查询。
不存在或无权访问统一返回 NOT_FOUND_OR_FORBIDDEN，不泄露记录是否存在。

入参：

参数	类型	必填	说明
id	number	条件必填	出库单主键；与 outOrderNo 至少传一个
outOrderNo	string	条件必填	出库单号；与 id 至少传一个；同时传入时必须匹配同一条记录
includeSerials	boolean	否	是否返回 SN 子行，默认 false
serialLimit	number	否	SN 返回上限，默认 100、最大 500

出参：

record：主单、来源类型、状态文案、客户、同步状态及关联工单号。
warehouses：物料汇总行涉及的仓库去重集合。
items：parent_id=0 物料汇总行，含物料、仓库、数量、价格和出库确认信息。
serials/serialTotal/serialTruncated：可选 SN 子行、完整总数和截断标记；未请求 SN 时 serials=[]、serialTruncated=false。
processes：已处理记录（schedule_state=2），按操作时间、ID 正序，状态码与文案同时返回。
address/logistics：m1 收货地址及发货物流；无地址时 address=null。
files.application/files.confirmation：申请/确认图片，返回 id/fileName/bucket/objectKey；服务不持有 OSS 签名密钥，不生成临时访问 URL。
certificate：出库凭证备注及凭证文件；均不存在时为 null。

详细设计与取舍见 warehouse-out-mcp-tools-design.md。

17. warehouse.in.list.query

分页查询入库单，参考旧系统 POST /myWarehouseIn/allListByPage，但将入库日期与申请日期分别过滤，并按本页主单 ID 批量加载仓库和待办信息。

分类：warehouse ｜类型：读
数据来源：m2 warehouse_in、warehouse_in_details、warehouse_in_audit_process
行级权限：总部看全部；代理身份可看所属代理范围、所属或负责仓库涉及、或本人参与处理的入库单。
单号支持入库/调拨/关联出库/商城/送货/装机/取货/撤机；另支持代理、仓库、入库类型、申请人、状态、同步状态、物流和入库/申请日期范围筛选。
返回 total/page/rows/records；每条记录含 sourceType（ALLOCATION/OUTBOUND_LINKED/MALL/NORMAL）、状态文案、仓库集合、待办人、实际入库人和入库日期。

18. warehouse.in.detail.query

按 id 或 inOrderNo 查询详情，两者至少传一个；同时传入时必须匹配同一条可见记录。调拨入库单可直接查询。

行级权限与列表完全一致；不存在和无权统一返回 NOT_FOUND_OR_FORBIDDEN。
返回 record/sceneType/warehouses/items/processes/files/relatedOutOrder。
items 按物料定义、物料索引和仓库汇总；includeSerials 默认 false，serialLimit 默认 100、上限 500，同时返回 serialTotal/serialTruncated。
files.application/files.confirmation 仅返回 id/fileName/bucket/objectKey。
relatedOutOrder 仅给出关联出库单号和查询工具名，不内嵌出库单内容。

详细设计见 warehouse-in-mcp-tools-design.md。

附录：在线查看工具清单

AK=xqak_xxx; H=http://localhost:8088/mcp
# 1) initialize，从响应头取 mcp-session-id
# 2) 带 mcp-session-id 发 notifications/initialized
# 3) 带 mcp-session-id 调用 tools/list
curl -X POST $H -H "Authorization: Bearer $AK" -H "mcp-session-id: $SID" \
  -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

也可在管理后台「工具管理」页查看全量注册工具（不受作用域过滤）。

31 KiB Raw Blame History Unescape Escape

xiaoqu-agent-service MCP 工具接口文档

0. 调用约定（所有工具共用）

0.1 schema_version 双跑（REQ-20260911-0011 起）

0.2 统一错误码（REQ-20260911-0011 起）

1. agent.count

2. agent.list.query

3. property.list.query

4. district.list.query

5. district.detail.get

6. sys.ping

7. mall.order.list.query

8. mall.order.detail.query

9. mall.order.logistics.query

10. hardware.list.query

11. hardware.detail.query

12. contract.list.query

13. contract.detail.query

14. integration.context.get

15. warehouse.out.list.query

16. warehouse.out.detail.query

17. warehouse.in.list.query

18. warehouse.in.detail.query

附录：在线查看工具清单

31 KiB

Raw Blame History