方案文档: 首期工具定为 agent.list.query / property.list.query(含入出参与权限语义), 原型补数据权限归属与审计客户端筛选

xiaoqu-franchisee/doc/agent-mcp-service-design.md

@@ -193,10 +193,28 @@ xiaoqu-agent-service/
 |---|---|---|
 | P1 骨架 | 工程初始化、版本组合验证、三数据源连通、codegen 跑通 | demo 工具经 MCP 调通 |
 | P2 权限 | ak 鉴权 Filter、scope 校验、数据权限引擎、审计 | 不同权限组的人查询结果隔离正确 |
-| P3 首批工具 | 仓库/客户 2~3 个只读工具 + tool 表同步 | Kimi/Claude 双端实测 |
+| P3 首批工具 | 代理商查询 + 客户(物业)查询（定义见 §9.1）+ tool 表同步 | Kimi/Claude 双端实测 |
 | P4 管理后台 | 用户/token、工具、作用域、审计四页面（Vue3 内嵌） | 管理员全流程自助配置 |
 | P5 加固 | 限流、ES 接入（按需）、写工具评审开放、CLI（Go 单二进制） | 生产上线 |
 
+### 9.1 首期工具定义（P3，均已确认）
+
+对应现有接口 `/agent/listByPage` 与 `/property/listByPage`，数据均查 m0 库，行级权限照搬 §3.3。入参精选（不做 beanToWrapper 全字段放行），枚举值写入工具 description 供模型使用；名称富化（supervisorName/agentName/createName）批量查询，消除老实现的 N+1。
+
+**`agent.list.query`**（分类 customer，读）
+
+- 语义照搬现有页面：isagent=1 时只查**下级代理**（`supervisor_id = 自己agentId`）；isagent=0 看全部。额外允许入参传 `id` 精确查询（可查到自身）。
+- 入参：`id`（精确）、`name`（模糊）、`level`（0总部/1一级/2二级）、`channelNo`（Z/F/D）、`province`、`city`、`serialnumber`、`page`（默认1）、`rows`（默认20，上限100）。**不含 `type`**（已确认去掉）。
+- 出参：id、name、level、channelNo、serialnumber、supervisorName、province/city/countyseat、contact、phone、agencyarea、memo、createTime。
+- 已裁剪：开票信息、银行账户、营业执照图片 URL（OSS 依赖，二期再议）。
+
+**`property.list.query`**（分类 customer，读）
+
+- 语义照搬：完整版 `getByIsAgent`（下级代理 + warehouse_agent_auth 代管 + agent_manage_district_auth 代管物业 + 销售非负责人限 create_id）。
+- 入参：`name`（模糊）、`agentId`、`serialnumber`、`province`、`city`、`contact`、`phone`、`page`、`rows`。
+- 出参：id、name、serialnumber、agentName、createName（销售）、province/city/countyseat、address、contact、phone、createTime。
+- 已裁剪：开票信息、银行账户。
+
 ## 10. 已明确的取舍记录
 
 - 不移植字段级（page_field 六表）功能权限 → 用 scope 替代，更简单且服务端强制