xiaoqu-agent-service/doc/agent-mcp-tools-reference.md

# 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` 文案。

---

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

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

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