Почетна Преглед Помоћ
Регистрација Пријавите се
vectorSeek
/
zsjz-ai
5
0
Креирај огранак 0
Датотеке Дискусије 0 Захтеви за спајање 0 Вики
Дрво: 6ef3e329e9
Гране Ознаке
zsjz-ai
/
.qoder
/
repowiki
/
zh
/
content
/
API 接口参考
/
API 接口参考.md

API 接口参考.md 26 KB
Историја Датотека

API 接口参考

本文引用的文件

  • AI_AGENT.md
  • readme.md
  • ai-gateway/src/main/java/com/zsjz/gateway/config/CorsConfig.java
  • ai-gateway/src/main/java/com/zsjz/gateway/admin/AdminAuthWebFilter.java
  • ai-gateway/src/main/java/com/zsjz/gateway/route/LoginRequestFilter.java
  • ai-gateway/src/main/java/com/zsjz/gateway/route/LoginResponseFilter.java
  • ai-gateway/src/main/java/com/zsjz/gateway/route/StickyRouteFilter.java
  • ai-gateway/src/main/java/com/zsjz/gateway/support/GatewayErrorHandler.java
  • ai-server/src/main/java/com/zsjz/ai/common/config/CorsConfig.java
  • ai-server/src/main/java/com/zsjz/ai/common/config/SaTokenWebConfig.java
  • ai-server/src/main/java/com/zsjz/ai/module/plat/controller/AuthController.java

目录

  1. 引言
  2. 项目结构与入口
  3. 统一协议与认证
  4. 网关接口
  5. 系统基础 plat
  6. Agent 对话
  7. AI 清洗
  8. 知识检索
  9. 图谱、人员、通话、交易、轨迹、治理、外部表、数据建模
  10. 跨域策略
  11. 分页、上传下载与速率限制
  12. 错误码与排查
  13. 调用示例
  14. 结论

引言

清鉴 AI 调查工具由 ai-gateway（Spring Cloud Gateway） 和 ai-server（Spring Boot 3 + MyBatis-Plus + AgentScope） 两个后端服务组成。前端通过 /js 前缀访问，实际请求最终落到 ai-server 的 /js/a 上下文路径；开发环境前端代理到 http://127.0.0.1:8980。本文按业务域整理 REST 接口参考，并重点说明认证方式、SSE 连接、跨域、分页、上传下载及常见错误排查。

章节来源

  • AI_AGENT.md
  • readme.md

项目结构与入口

  • 父工程聚合 ai-server 与 ai-gateway。
  • ai-server 启动类为 com.zsjz.ai.App，默认端口 8980。
  • 后端模块根包 com.zsjz.ai，业务模块固定取值：agent、call、dm、external、govern、graph、otg、person、plat、track、trans。

  • 所有业务 Controller 位于 module/<domain>/controller，统一返回 Result<T>。

    graph TB
Client["浏览器或 Electron 前端"] --> Gateway["Spring Cloud Gateway<br/>粘性路由 + 管理端鉴权"]
Gateway --> ServerA["ai-server 节点 A<br/>/js/a 上下文"]
Gateway --> ServerB["ai-server 节点 B<br/>/js/a 上下文"]
ServerA --> DB["PostgreSQL / DuckDB / Redis / Neo4j"]
ServerB --> DB

图示来源

  • AI_AGENT.md
  • ai-gateway/src/main/java/com/zsjz/gateway/route/StickyRouteFilter.java

章节来源

  • AI_AGENT.md

统一协议与认证

HTTP 基础

项目 约定
网关对外前缀 /js
后端上下文路径 /js/a
开发环境代理目标 http://127.0.0.1:8980
统一响应体 Result<T>，字段包含 code、message、data
成功状态码 HTTP 200，Result.code=200
登录态令牌 请求头 x-token
会话实现 Sa-Token，基于 Redis 存储 token 和用户会话

认证流程

  1. 前端调用 POST /js/a/auth/login，携带用户名与密码 JSON。
  2. 后端返回 Result<LoginVO>，其中 data.token 是 Sa-Token 凭据。
  3. 前端将 token 存入本地存储，后续请求在请求头中附加 x-token。
  4. Sa-Token 拦截器对除白名单外的路径执行登录校验；未登录时返回 HTTP 200 但 body.code=401。

  5. 网关层根据 x-token 解析 userId，并把用户绑定到某个 ai-server 节点，实现粘性路由。

    sequenceDiagram
participant FE as "前端"
participant GW as "网关"
participant SV as "ai-server"
participant ST as "Sa-Token"

FE->>GW: POST /js/a/auth/login {username,password}
GW->>SV: 转发登录请求
SV->>ST: 校验账号
ST-->>SV: 登录成功
SV-->>GW: Result{code:200,data:{token,userId,username}}
GW->>GW: 记录用户与节点绑定
GW-->>FE: 返回登录结果

FE->>GW: 后续请求 + x-token
GW->>GW: 解析 userId → 选择绑定节点
GW->>SV: 转发业务请求
SV-->>GW: Result<T>
GW-->>FE: 透传响应

图示来源

  • ai-server/src/main/java/com/zsjz/ai/module/plat/controller/AuthController.java
  • ai-server/src/main/java/com/zsjz/ai/common/config/SaTokenWebConfig.java
  • ai-gateway/src/main/java/com/zsjz/gateway/route/LoginResponseFilter.java
  • ai-gateway/src/main/java/com/zsjz/gateway/route/StickyRouteFilter.java

章节来源

  • AI_AGENT.md
  • ai-server/src/main/java/com/zsjz/ai/module/plat/controller/AuthController.java
  • ai-server/src/main/java/com/zsjz/ai/common/config/SaTokenWebConfig.java
  • ai-gateway/src/main/java/com/zsjz/gateway/route/LoginResponseFilter.java
  • ai-gateway/src/main/java/com/zsjz/gateway/route/StickyRouteFilter.java

网关接口

网关暴露的管理接口统一位于 /gateway/admin/**，不走普通业务鉴权，而是由网关自身过滤器处理。

管理接口通用规则

项目 说明
URL 模式 /gateway/admin/**
前置开关 gateway.admin.enabled=false 时直接返回 404，接口“消失”
IP 白名单 gateway.admin.ip-whitelist，支持单 IP 与 CIDR，空表示不限
认证方式 请求头 x-token，经 Sa-Token 共享 Redis 解析出 userId
权限要求 用户需满足 sys_user.is_admin=1 且 status=1
响应格式 网关内部 JSON，结构同 ApiResult 
flowchart TD
    Start["进入 /gateway/admin/**"] --> Enabled{"管理接口已启用？"}
    Enabled -->|否| NotFound["返回 404"]
    Enabled -->|是| IpCheck["校验来源 IP 白名单"]
    IpCheck -->|不通过| Forbidden["返回 403"]
    IpCheck -->|通过| TokenCheck["校验 x-token"]
    TokenCheck -->|无效| Unauthorized["返回 401"]
    TokenCheck -->|有效| AdminCheck["检查 is_admin=1 且 status=1"]
    AdminCheck -->|不通过| Forbidden
    AdminCheck -->|通过| Pass["放行并注入管理员 userId"]

图示来源

  • ai-gateway/src/main/java/com/zsjz/gateway/admin/AdminAuthWebFilter.java

章节来源

  • ai-gateway/src/main/java/com/zsjz/gateway/admin/AdminAuthWebFilter.java

系统基础 plat

认证接口

方法 URL 请求体 响应 说明
POST /js/a/auth/login LoginDTO，包含用户名和密码 Result<LoginVO> 登录成功后返回 token、userId、username
POST /js/a/auth/logout 无 Result<Void> 注销 token 并释放该用户占用的案件数据源
GET /js/a/auth/info 无 Result<UserVO> 获取当前登录用户信息
POST /js/a/auth/changePwd ChangePwdDTO Result<Void> 自助修改密码
POST /js/a/auth/verifyPwd VerifyPwdDTO，可选 password Result<Boolean> 锁屏解锁等场景校验密码，失败返回 data=false

其他基础接口

Sa-Token 白名单中还开放以下路径，用于健康检查、授权校验、地图静态资源等：

  • /js/a/sys/health
  • /js/a/sys/checkAuth
  • /js/a/sys/info
  • /js/a/sys/code
  • /js/a/sys/noNet
  • /js/a/sys/map/**

这些接口无需登录即可访问。

章节来源

  • ai-server/src/main/java/com/zsjz/ai/module/plat/controller/AuthController.java
  • ai-server/src/main/java/com/zsjz/ai/common/config/SaTokenWebConfig.java

Agent 对话

Agent 子系统围绕 module/agent 展开，核心能力包括：

  • REST 对话接口。
  • SSE 流式事件推送。
  • 模型与厂商配置。
  • SQL 工具执行与结果分页。
  • Python 沙箱分析。
  • RAG 模板与向量索引。
  • 意图识别与追问生成。
  • 工作空间元数据。

Agent REST 接口概览

模块 典型 URL 模式 用途
对话 /js/a/agent/chat/** 发起对话、查询会话消息、停止推理等
模型 /js/a/agent/model/** 模型与 Provider 的 CRUD
SQL 结果 /js/a/agent/result/** execute_sql 结果集分页查询
Python 文件 /js/a/agent/py/files/** 访问 Python 产出图片等资源
专家/能力/工具包 /js/a/agent/expert/**、/js/a/agent/capability/**、/js/a/agent/tool-pack/** Agent 能力配置
洞察 /js/a/agent/insight/** 洞察分析相关接口

Agent 对话 Controller 采用 REST + SSE 混合方式：普通问答走 REST，流式输出走 SSE。SQL 结果分页由独立 Controller 提供，避免长连接阻塞。

章节来源

  • AI_AGENT.md

SSE 连接建立

SSE 属于长连接，客户端需要：

  1. 使用原生 fetch 或 WebSocket/SSE 客户端发起请求。
  2. 请求头携带 x-token。
  3. 设置 Accept: text/event-stream。
  4. 保持连接不断开，直到服务端关闭或发送结束事件。

若前端使用浏览器 fetch，注意：

  • 不要自动把响应当作 JSON 解析。
  • 逐行读取 text/event-stream。
  • 遇到连接中断要按重连策略重试。

SSE 事件类型

Agent SSE 事件一般包含以下几类语义（具体事件名以各 Controller 实现为准）： | 事件类型 | 含义 | |---|---| | 开始事件 | 对话任务已创建并开始处理 | | 文本增量 | 大模型返回的文本片段 | | 工具调用 | 正在调用 execute_sql、render_chart、execute_python 等业务工具 | | 工具结果 | 工具执行完成，附带结构化结果 | | 图表配置 | render_chart 返回的 ECharts 配置 | | 错误事件 | 业务异常、工具执行失败、模型调用失败 | | 结束事件 | 对话完成，可清理本地状态 |

SSE 消息格式

SSE 消息通常包含：

  • event：事件类型。
  • data：JSON 或纯文本消息体。
  • id：可选消息标识，便于断线续传。

对于 Agent 对话，data 常见字段包括： | 字段 | 类型 | 说明 | |---|---|---| | sessionId | 字符串 | 会话标识 | | messageId | 字符串 | 消息标识 | | type | 字符串 | 消息类型，如思考、工具调用、结果、错误 | | content | 字符串 | 人类可读内容 | | toolName | 字符串 | 工具名称，如 execute_sql | | resultId | 字符串 | SQL 结果缓存 ID | | error | 字符串 | 错误信息 |

心跳保活协议

SSE 保活建议遵循以下原则：

  1. 客户端侧定期检测连接是否活跃；长时间无事件时应主动重连。
  2. 服务端应保证在较长空闲时间内仍维持连接，或在必要时发送心跳事件。
  3. 客户端重连时尽量带上最后收到的 messageId，以便服务端补齐遗漏消息。
  4. 如果连接被顶下线或 token 失效，服务端可能返回错误事件或断开连接，客户端应据此引导重新登录。

Agent 会话关键流程

sequenceDiagram
    participant FE as "前端"
    participant GW as "网关"
    participant AC as "AgentChatController"
    participant SVC as "AgentChatService"
    participant TOOLS as "工具集"
    participant STORE as "SQL 结果缓存"

    FE->>GW: POST /js/a/agent/chat (x-token)
    GW->>AC: 转发请求
    AC->>SVC: 创建或查找会话
    SVC->>TOOLS: 调用意图识别 / 工具
    TOOLS->>STORE: execute_sql 写入结果
    STORE-->>TOOLS: resultId + 列定义 + 分页信息
    SVC-->>AC: 流式事件
    AC-->>FE: SSE event/text/data
    FE->>GW: 拉取 SQL 结果分页
    GW->>AC: 转发分页请求
    AC-->>FE: 返回结果页

图示来源

  • AI_AGENT.md
  • ai-gateway/src/main/java/com/zsjz/gateway/route/StickyRouteFilter.java

章节来源

  • AI_AGENT.md

AI 清洗

AI 清洗模块位于 module/dm 与 module/aiclean，主要职责是把多源异构数据导入后清洗、映射、治理，并沉淀到 DuckDB 案情库。

典型接口方向

模块 URL 模式 功能
数据建模 /js/a/dm/** 表元数据、字段映射、导入模板、清洗任务
AI 清洗 /js/a/aiclean/** 智能清洗、值转换、字段短名、同义词
清洗错误日志 /js/a/dm/clean-error-log/** 查看清洗过程中的错误记录

输入输出要点

  • 输入多为表单、JSON 或文件上传，涉及 Excel、CSV 等表格数据。
  • 输出多为 Result<T>，分页查询返回 MyBatis-Plus Page<T>。
  • 金额、比率字段使用 BigDecimal，避免浮点精度问题。

章节来源

  • AI_AGENT.md

知识检索

知识检索围绕 RAG 与知识库展开，涉及：

  • 知识库 CRUD。
  • 模板元数据语义检索。
  • 向量索引重建。
  • Embedding 调试。

典型接口方向

模块 URL 模式 功能
知识库 /js/a/knowledge/** 知识库列表、新增、更新、删除、检索
Embedding 调试 /js/a/embedding/** 向量模型调试
Agent RAG 工具 通过 search_table_schema 工具间接暴露 基于 pgvector 的模板元数据语义检索

知识库下载接口返回裸文件流，不带 Result 包装，前端需使用带 x-token 的 fetch 获取 blob 并触发保存。

章节来源

  • AI_AGENT.md

图谱、人员、通话、交易、轨迹、治理、外部表、数据建模

图谱 graph

典型 URL 模式 功能
/js/a/graph/** 关系图查询、图谱节点与边数据

人员 person

典型 URL 模式 功能
/js/a/person/person-basic-info/** 人员基本信息
/js/a/person/person-group/** 人员分组
/js/a/person/resident-population/** 常住人口
/js/a/person/intimacy/** 亲密度分析
/js/a/person/data-profile/** 人物画像

通话 call

典型 URL 模式 功能
/js/a/call/call-record/** 通话原始明细
/js/a/call/call-night/** 夜间通话统计
/js/a/call/call-continuous/** 持续联系统计
/js/a/call/call-sensitive/** 敏感日期联系统计

交易 trans

典型 URL 模式 功能
/js/a/trans/trans-record/** 交易记录
/js/a/trans/trans-fund-flow/** 资金流水、资金流向图、资金流向轨迹
/js/a/trans/trans-frequency/** 高频交易统计
/js/a/trans/trans-continuous/** 连续交易统计
/js/a/trans/trans-cash-flow/** 现金流水
/js/a/trans/trans-card-hold/** 共同持卡
/js/a/trans/trans-financial/** 金融账户统计
/js/a/trans/trans-fixed-deposit/** 定期存款
/js/a/trans/trans-fast-fund-flow/** 快进快出
/js/a/trans/trans-big/** 大额交易统计
/js/a/trans/trans-sensitive/** 敏感交易统计
/js/a/trans/cash-key/**、financial-key/**、fixed-deposit-key/** 交易关键参数配置

轨迹 track

典型 URL 模式 功能
/js/a/track/track-cell-tower/** 基站轨迹
/js/a/track/track-en-local/** 本地轨迹
/js/a/track/track-meet/** 轨迹相遇
/js/a/track/track-together-live/** 同住轨迹
/js/a/track/track-together-travel/** 同行轨迹
/js/a/track/express-info/** 快递信息

治理 govern

典型 URL 模式 功能
/js/a/govern/** 治理任务、治理树
/js/a/govern/govern-tree/** 治理树与关联人/银行/通话操作人分页

外部表 external

典型 URL 模式 功能
/js/a/external/** 外部表元数据、字段元数据

数据建模 dm

典型 URL 模式 功能
/js/a/dm/** 数据建模、清洗、模板、错误日志

上述接口普遍遵循：

  • 查询参数放在 URL 查询串或 JSON body。
  • 分页使用 MyBatis-Plus Page<T>。
  • 金额字段使用 BigDecimal。
  • 多数接口受 Sa-Token 登录态保护。

章节来源

  • AI_AGENT.md

跨域策略

跨域由网关与后端共同控制：

层级 行为
后端 ai-server 默认开启 CORS，允许任意 Origin，允许所有方法和请求头，开启 credentials=true，暴露 Content-Disposition，优先级最高
网关 ai-gateway 默认关闭 CORS；仅在 gateway.cors.enabled=true 时启用，允许所有方法、所有请求头，不携带凭据，暴露 X-Gateway-Node、Content-Disposition、X-Request-Id

关键点：

  • 因为鉴权靠 x-token 请求头，不属于 Cookie，所以不需要 Cookie 凭证。
  • 后端 SSE 和文件下载可能使用带 credentials: 'include' 的 fetch，因此后端必须允许凭据。
  • 若网关也开启 CORS，不应重复暴露多个 Access-Control-Allow-Origin，否则浏览器会拒绝响应。

章节来源

  • ai-server/src/main/java/com/zsjz/ai/common/config/CorsConfig.java
  • ai-gateway/src/main/java/com/zsjz/gateway/config/CorsConfig.java

分页、上传下载与速率限制

分页

  • 后端统一使用 MyBatis-Plus Page<T>。
  • 分页拦截器已注册，DuckDB 主库使用 PaginationInnerInterceptor(DbType.DUCKDB)。
  • 常见分页字段包括页号、页大小、排序条件、过滤条件。
  • 部分 Agent 工具（如 execute_sql）会返回 resultId，再由分页接口拉取结果。

上传

  • 上传通常走 multipart/form-data，例如清洗模板、数据文件、知识库附件。
  • 网关对登录请求体会做最大 64KB 解析，但普通上传不受该限制约束。
  • 下载接口返回裸文件流，不经过 Result 包装。

下载

  • 下载接口依赖响应头 Content-Disposition 传递文件名。
  • 后端 CORS 显式暴露 Content-Disposition，使跨域前端能读取文件名。
  • 前端需用 fetch 获取 blob，再触发浏览器保存。

速率限制

当前代码证据中未发现统一的限流控制器或全局限流拦截器。生产环境如需限流，应在网关或应用层增加独立限流组件。现有风险点主要体现在：

  • 长连接 SSE 未明确看到统一心跳或超时策略。
  • 登录请求体解析有 64KB 限制。
  • 登录响应体绑定解析有 256KB 限制。

章节来源

  • AI_AGENT.md
  • ai-gateway/src/main/java/com/zsjz/gateway/route/LoginRequestFilter.java
  • ai-gateway/src/main/java/com/zsjz/gateway/route/LoginResponseFilter.java
  • ai-server/src/main/java/com/zsjz/ai/common/config/CorsConfig.java

错误码与排查

通用响应结构

后端统一返回 Result<T>： | 字段 | 含义 | |---|---| | code | 业务状态码，成功通常为 200 | | message | 人类可读消息 | | data | 业务数据 |

网关错误

网关错误处理器会根据异常类型返回明确 HTTP 状态码： | HTTP 状态 | 含义 | |---|---| | 404 | 无匹配路由或资源不存在 | | 401 | 未登录或 token 失效 | | 403 | 非管理员访问管理接口、IP 不在白名单 | | 502 | 后端节点连接失败或超时 | | 503 | 粘性路由不可用、绑定节点不可用、服务暂无可用节点 | | 500 | 网关内部错误 |

常见错误排查

401 未登录或登录失效

可能原因：

  • 未携带 x-token。
  • token 过期。
  • 账号被新登录顶下线。
  • 账号被踢下线。
  • token 伪造或 Redis 中会话不存在。

排查步骤：

  1. 确认请求头是否携带 x-token。
  2. 确认是否先调用 /js/a/auth/login 拿到 token。
  3. 检查 Sa-Token 会话是否仍在 Redis。
  4. 检查是否出现“被顶下线”，必要时重新登录。

403 权限不足

可能原因：

  • 访问 /gateway/admin/** 但 IP 不在白名单。
  • 访问管理接口但用户不是管理员或已停用。
  • 业务层判定无权限。

排查步骤：

  1. 确认来源 IP 是否在 gateway.admin.ip-whitelist。
  2. 确认用户 is_admin=1 且 status=1。
  3. 检查业务逻辑中的权限判断。

503 服务不可用

可能原因：

  • 用户绑定的节点已停用或 DOWN。
  • 用户未绑定节点且服务没有默认节点。
  • 当前无可用健康节点。
  • 粘性路由选择失败。

排查步骤：

  1. 检查网关日志中用户绑定节点。
  2. 检查对应 ai-server 节点是否存活。
  3. 检查 defaultNodeId 是否配置。
  4. 不要期望 503 时自动切换到其他节点，因为数据可能留在原节点磁盘。

SSE 中断

可能原因：

  • 网络断开。
  • token 失效导致后端返回错误或断开。
  • 服务端负载过高或连接超时。
  • 前端过早关闭 fetch 或页面卸载。
  • 中间代理（Nginx、CDN、浏览器）中断长连接。

排查步骤：

  1. 检查浏览器 Network 面板中 SSE 请求状态。
  2. 检查是否因 token 失效收到错误事件。
  3. 增加客户端重连机制。
  4. 检查代理层是否设置了过短的超时时间。
  5. 关注网关上游连接失败或超时日志。

章节来源

  • ai-gateway/src/main/java/com/zsjz/gateway/admin/AdminAuthWebFilter.java
  • ai-gateway/src/main/java/com/zsjz/gateway/route/StickyRouteFilter.java
  • ai-gateway/src/main/java/com/zsjz/gateway/support/GatewayErrorHandler.java
  • ai-server/src/main/java/com/zsjz/ai/common/config/SaTokenWebConfig.java

调用示例

curl 示例

登录：

curl -X POST http://localhost:8980/js/a/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"your-password"}'

携带 token 调用业务接口：

curl http://localhost:8980/js/a/auth/info \
  -H "x-token: 从登录响应 data.token 获取"

下载文件（示例）：

curl -o file.xlsx http://localhost:8980/js/a/knowledge/download/xxx \
  -H "x-token: 从登录响应 data.token 获取"

前端调用示例

使用带 x-token 的 fetch：

const res = await fetch('/js/a/auth/info', {
  headers: { 'x-token': localStorage.getItem('token') }
});
const json = await res.json();
if (json.code === 401) {
  // 跳转登录
} else if (json.code === 200) {
  // 渲染用户信息
}

SSE 调用示例：

const res = await fetch('/js/a/agent/chat/sse', {
  method: 'POST',
  headers: {
    'x-token': localStorage.getItem('token'),
    'Accept': 'text/event-stream'
  },
  body: JSON.stringify({ message: '分析近期夜间通话异常' })
});

const reader = res.body.getReader();
const decoder = new TextDecoder();
while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  const text = decoder.decode(value);
  // 按 event/data 解析 SSE 事件
}

章节来源

  • ai-server/src/main/java/com/zsjz/ai/module/plat/controller/AuthController.java
  • AI_AGENT.md

结论

清鉴 AI 调查工具的 API 以 /js/a 为后端入口，通过网关进行粘性路由与管理端准入控制。认证基于 Sa-Token，token 通过 x-token 请求头传递；所有业务接口默认受登录态保护。Agent 对话同时支持 REST 与 SSE，SSE 需要客户端自行处理连接保活与重连。跨域默认在后端开启，网关默认关闭以避免重复跨域头。分页统一使用 MyBatis-Plus Page<T>，下载接口返回裸文件流并依赖 Content-Disposition 响应头。常见错误 401、403、503 与 SSE 中断应优先从 token、IP 白名单、节点健康状态和连接生命周期排查。