feat(mcp): 新增合同查询工具 contract.list/detail.query (REQ-20260911-0002)

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

@@ -335,6 +335,64 @@
 
 ---
 
+## 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