# 学邦通用 GET 查询接口

`agent-foundation` 负责学邦鉴权、AccessToken 刷新、失败重试、分页和缓存。WorkBuddy 只调用本服务，不接触学邦密钥。

## 接口目录

```http
GET /api/xuebang/catalog?query=学员
```

- `query` 可按接口说明、分类、路径、参数名或参数说明检索。
- 默认只返回 WorkBuddy 可调用的 65 个数据查询接口。
- `includeBlocked=true` 可查看完整 68 个 GET 接口以及禁用原因。

## 查询数据

```http
POST /api/xuebang/query
Content-Type: application/json

{
  "operationId": "findListByInstitutionUsingGET_2",
  "parameters": {
    "name": "张老师"
  },
  "fetchAll": true,
  "refresh": false
}
```

- `operationId` 必须来自目录接口。
- `parameters` 只允许传该接口文档声明的参数。
- 可分页接口的 `fetchAll` 默认为 `true`，分页在服务端完成。
- `refresh=true` 会跳过缓存，适合用户明确要求实时数据时使用。
- 不传登录人、员工或校区范围时，按配置中的学邦应用管理员权限查询全部可见数据；只有用户明确指定筛选条件时才传对应参数。
- 相同接口和参数默认缓存 300 秒，可通过 `foundation.xuebang.query-cache-seconds` 调整。

## 安全边界

以下 GET 路径收录在完整目录中，但禁止通过通用查询接口调用：

- `/token/{clientId}`：由后端 Token 组件内部管理。
- `/api/user/findUserForLogin`：包含登录密码参数。
- `/api/wxapp/getStudentToken`：会返回学生访问凭证。

完整接口清单见 [xuebang-get-api-catalog.md](xuebang-get-api-catalog.md)。