# 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` 文本保持不变：

```json
{ "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`：

```json
{ "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 | 代理商总数 |

```json
{ "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` |

```json
{
  "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`。

---

## 19. warehouse.todo.list.query

统一查询当前登录人的仓库待办，参考老系统 `/myWarehouseOut/needToBeDealtWith`、
`/myWarehouseIn/needToBeDealtWith`、`/warehouseAllocation/warehouseAllocationProcessListByPage` 三个待办接口。

- 分类：warehouse ｜ 类型：读
- 数据来源：m2 流程视图 `warehouse_out_process` / `warehouse_in_process` / `warehouse_allocation_process`
- 权限：待办是"人"的语义，只按流程表 `user_id = 当前登录人` 过滤，不叠加代理商行级权限。
- 待办判定：`user_id = 当前登录人 AND soft_delete = 0 AND operation_type IN (0,1,2)`
  （3=纯日志排除）。`todoOnly` 默认 true 再限定 `schedule_state=1` 真待办。
- 同一笔调拨最多以调拨审批/确认、出库执行、入库执行 3 个视角出现，不去重；
  派生自调拨的真实出入库单带 `derivedFrom="allocation"`，可按 `allocationOrderNo` 归并。
- 分页实现：先全量查符合条件流程行按单据 id 内存去重 → 内存分页 → 按页 id 批量查视图行组装，防 N+1。

**入参**：

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| docType | string | 否 | out=出库单 in=入库单 allocation=调拨/采购/划转单 all=全部，默认 all |
| todoOnly | boolean | 否 | true=只返回真待办（默认）；false=当前用户参与过的全部单据 |
| orderState | number | 否 | 出库/入库单 0待审核 1被驳回 2待出库或待入库 3已完成 4已撤销 5作废；调拨类 0待审核 1被驳回 2待出库 3待入库 4已完成 5已撤销 6作废 |
| orderNo | string | 否 | 单据主单号模糊匹配 |
| page / rows | number | 否 | 页码默认 1；每页默认 20、上限 100，超出截断并在 `notice` 提示 |

**出参 records 字段**：`docType/docTypeText`（出库单/入库单/调拨单/采购单/划转单，
按调拨视图 `op_type` 区分）、`docId/docNo`、`orderState/orderStateText`、
`scheduleState/scheduleStateText`、`operationType/operationTypeText`（当前待办环节）、
仓库名（allocation 为转出/转入仓库）、`agentId/agentName`、申请人/申请时间、
`allocationOrderNo` 等关联单号、派生单 `derivedFrom="allocation"`；
调拨类另含 `opType/opTypeText/allocationCount/nextUserName/inUserName/outUserName`。
按申请时间倒序排列。

详细设计与老系统差异见 `warehouse-todo-mcp-tool-design.md`。

---

## 20. delivery.order.list.query

分页查询送货工单，对应旧系统 `POST /delivery/deliveryListByPage`。

- 分类：workorder ｜ 类型：读
- 数据来源：m2 `delivery_order`。
- 入参：`deliveryOrderNo`、`sourceOrderNo`、`agentId`、`districtName`、`orderType`、
  `orderState`、`sendMode`、`applyUserName`、申请/完成日期范围及 `page/rows`。
- `orderType`：0=装机单送货，1=出库单送货；`orderState`：0=派送中，1=已完成，2=已取消；
  `sendMode`：0=快递公司，1=自行派送。
- 申请日期按业务字段 `apply_time` 查询，不沿用旧接口的 `create_time`；申请与完成日期可同时过滤。
- 行级权限：总部看全部；代理身份可看申请代理或所属代理在自己、直属下级、授权代管范围内的工单，
  以及授权代管物业和本人参与流程的工单；销售非负责人按其可见物业范围过滤。
- 返回 `total/page/rows/records`，固定按 ID 倒序；记录同时返回状态、类型、配送方式的码值与文案。

## 21. delivery.order.detail.query

按 `id` 或 `deliveryOrderNo` 查询详情，两者至少传一个；同时传入时必须匹配同一条可见记录。

- 行级权限与列表完全一致；不存在和无权统一返回 `NOT_FOUND_OR_FORBIDDEN`。
- `record`：送货主单和文案字段。
- `logistics`：物流公司/单号或派送员信息、物流状态；无物流记录时为 null。
- `goods`：m2 `install_distribute_details` 配发物品，含物料、SN、数量、出入仓库和商城订单号。
- `shippingFiles`：m1 `mall_logistics_pic` 发货图片。
- `processes`：`schedule_state=2` 的流程记录及 m2 `warehouse_in_out_pic` 签收附件，按操作时间、ID 正序。
- `relatedDocuments`：m2 `install_to_out_warehouse` 关联的出库、入库、调拨或划转单。
- 所有附件仅返回 `id/fileName/bucket/objectKey`，不拼接公开 URL。

详细设计见 `delivery-order-mcp-tools-design.md`。

---

## 附录：在线查看工具清单

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

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