接口文档 · 接口日志 / AI 流程日志查询（教师端 · 系统运维）

满足根 CLAUDE.md #3/#5。本组为「接口日志可见」的查询侧——由独立运维后台 apps/admin（teacher-admin.weizhiqingtu.com，见 ../后台系统设计与对接.md）消费。 Base URL：dev http://localhost:8000；生产 https://teacher-api.weizhiqingtu.com。日志分类：系统运维。 鉴权（管理员）：全部为受保护口，须带 Authorization: Bearer <access> 且 token 为管理员（is_admin，由后端 ADMIN_LOGINS 白名单决定）。无 token → 401；非管理员 → 403（require_admin，见 ../鉴权设计.md、../后台系统设计与对接.md）。

数据只读自既有表：接口日志 t_api_logs、AI 流程 t_ai_runs / t_ai_steps（表结构见 ../本端数据库表/智能体与日志表.md）。后端实现 server/app/api/admin.py。DB 不可用时优雅降级为空结果（不抛 500）。

统一返回包装 ApiResult<T>：{ "code": 0, "message": "ok", "data": <T> }。分页壳 Paged<T>：{ items, total, page, size }。

1. 接口日志列表 GET /api/admin/logs

按前端页面功能分类查询接口日志，倒序（最新在前）。

Query：

参数 必填 类型 说明
category 否 string 分类过滤（通用/备课/作业批改/知识库/智能体/数据看板/学校管理/登录鉴权/在线升级/系统运维）
method 否 string 方法（GET/POST/…/WS_CONNECT/WS_CLOSE），自动大写
status 否 int HTTP 状态码精确匹配
path 否 string 路径模糊匹配（ILIKE）
trace_id 否 string 链路 id 精确匹配
start / end 否 datetime(ISO) 时间范围（含端点）
page 否 int 页码，默认 1，≥1
size 否 int 每页条数，默认 20，1–200

响应 data（Paged<ApiLogItem>），ApiLogItem：

{
  "id": "8f1c...",
  "traceId": "a1b2c3d4e5f6a7b8",
  "method": "GET",
  "path": "/api/teacher/me",
  "category": "登录鉴权",
  "status": 200,
  "durationMs": 12,
  "teacherId": "0d2e...",
  "summary": { "query": { "page": "1" } },
  "createdAt": "2026-06-15T08:30:01"
}

curl -H "Authorization: Bearer $T" \
  "http://localhost:8000/api/admin/logs?category=登录鉴权&page=1&size=20"

错误码：401(无 token)/403(非管理员) 无/非法 token；422 参数类型不合法。

2. 接口日志分类统计 GET /api/admin/logs/stats

按分类聚合计数（总数 + 错误数 status≥400 + 各分类），供顶部统计卡 + 分类筛选项。

Query：start / end（datetime，可选）。

响应 data（ApiLogStats）：

{
  "total": 1280,
  "errors": 7,
  "byCategory": [
    { "category": "登录鉴权", "count": 540, "errors": 3 },
    { "category": "系统运维", "count": 120, "errors": 0 }
  ]
}

错误码：401(无 token)/403(非管理员)。

3. 接口日志详情 GET /api/admin/logs/{log_id}

单条日志（含入参/出参摘要 summary）。Path：log_id（uuid）。

响应 data 为单个 ApiLogItem（同上）。错误码：401(无 token)/403(非管理员)；404 日志不存在；422 log_id 非 uuid。

4. AI 流程 run 列表 GET /api/admin/ai/runs

备课合成 / 批改 / 识别等多步 AI 管线的 run 级记录，倒序。

Query：

参数 必填 类型 说明
flow 否 string 流程名精确匹配（如 lesson_synth）
status 否 string running / success / error
page 否 int 页码，默认 1
size 否 int 每页，默认 20，1–200

响应 data（Paged<AiRunItem>），AiRunItem：

{
  "id": "1a2b...",
  "flow": "lesson_synth",
  "teacherId": "0d2e...",
  "status": "success",
  "error": null,
  "startedAt": "2026-06-15T08:00:00",
  "finishedAt": "2026-06-15T08:00:09"
}

错误码：401(无 token)/403(非管理员)。

5. AI 流程 run 详情 GET /api/admin/ai/runs/{run_id}

run 详情 + 各步骤（t_ai_steps 按 seq 升序）。Path：run_id（uuid）。

响应 data（AiRunDetail = AiRunItem + input / output / steps[]），steps[] 项 AiStepItem：

{
  "id": "1a2b...",
  "flow": "lesson_synth",
  "status": "success",
  "startedAt": "2026-06-15T08:00:00",
  "finishedAt": "2026-06-15T08:00:09",
  "input": { "topic": "..." },
  "output": { "ok": true },
  "steps": [
    { "id": "s1", "seq": 1, "name": "outline", "status": "success", "durationMs": 1200,
      "input": null, "output": null, "createdAt": "2026-06-15T08:00:02" }
  ]
}

错误码：401(无 token)/403(非管理员)；404 run 不存在；422 run_id 非 uuid。

自洽校验（#5 闭环）

调用以上任一口后，再查 GET /api/admin/logs?category=系统运维，应能看到本组查询接口自身的访问记录——证明「新接口默认被日志中间件覆盖」。