Files

T

xiaoqu ff452d89d8 feat(mcp): 新增出纸机查询工具 hardware.list/detail.query (REQ-20260910-0012)

2026-09-10 15:27:14 +08:00

18 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`（仅截断时出现）

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。

附录：在线查看工具清单

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":{}}'

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

18 KiB Raw Blame History Unescape Escape

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

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

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

附录：在线查看工具清单

18 KiB

Raw Blame History