AI 模块 API¶

AI 模块是 MyApps 平台的**人工智能服务**（obpm-ai），基于 LangChain4j 提供大模型对话、RAG 检索增强、代码生成助手、系统提示词管理，以及 OpenAI 兼容 API 的反向代理转发等能力。该模块默认运行在 8080 端口，context-path 占位符为 ${myapps.context-path.ai:}（部署时替换为具体上下文路径，缺省为 /ai，见 obpm-ai/src/main/resources/application.properties 中 server.servlet.context-path=/ai、server.port=8080）。

覆盖进度：5 / 5 控制器（已覆盖 AiController、AiProxyController、AiWelcomeController、CoderController、SystemPromptController）

AI 模块共有 5 个控制器，合计 19 个端点（AI 对话 6 + AI 代理 1 + 欢迎页 1 + 代码助手 3 + 系统提示词 8）。

已文档化控制器¶

文件	中文名	基址	端点数
`ai-controller.md`	AiController（AI 对话/RAG）	`${myapps.context-path.ai:}/api`	6
`ai-proxy.md`	AiProxyController（OpenAI 兼容代理转发）	`/ai/api`（硬编码）	1
`ai-welcome.md`	AiWelcomeController（欢迎首页跳转）	`${myapps.context-path.ai:}`	1
`coder.md`	CoderController（代码助手）	`${myapps.context-path.ai:}/api`	3
`system-prompt.md`	SystemPromptController（系统提示词 CRUD）	`${myapps.context-path.ai:}/api/system-prompt`	8

鉴权说明¶

（据源码）obpm-ai 模块本身不启用任何 accessToken 鉴权过滤器。这与 runtime / message / kms 等模块不同，原因如下：

CommWebMvcConfig（obpm-common）不会被 obpm-ai 加载：obpm-common 未提供 META-INF/spring.factories 或 META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports 自动配置文件；obpm-ai 的入口 cn.myapps.ai.ObpmAiApplication（@SpringBootApplication 默认仅扫描 cn.myapps.ai.**）也未通过 @ComponentScan、@Import 等方式引入 cn.myapps.common.conf.CommWebMvcConfig。因此 CommonSecurityFilter、PassFilter、HiddenHttpMethodFilter 等共享过滤器**均不会在 obpm-ai 进程内注册**。
obpm-ai 自身未定义 SecurityFilter：obpm-ai 工作树内仅有的过滤器/拦截器为：
cn.myapps.ai.config.AiCorsConfig：注册 CorsFilter（Ordered.HIGHEST_PRECEDENCE），仅处理跨域预检，不参与鉴权；
cn.myapps.ai.config.AiProxyWebMvcConfig + AiProxyAsyncTimeoutInterceptor：仅对 /ai/api/llm-proxy/** 在异步转发开始后设置 300s 超时，不参与鉴权。
结果：所有端点对外完全开放，请求经 CorsFilter 后直接进入控制器。控制器内即使调用 Security.getDesignerIdFromToken(request)（见 CoderController）也仅用于**从令牌解析用户身份**，解析失败返回 null（用作 memoryId 等），不拒绝请求。

lite 统一部署（与 obpm-kms 同进程）：此时 AiController 注入 obpm-kms 的 AccessibleKmsDiskIdsProvider 实现（cn.myapps.kms.integration.AccessibleKmsDiskIdsProviderImpl），chat 端点在未显式传 disk_id 时按当前登录态解析可访问网盘；解析失败返回 401/400（业务校验，非过滤器层鉴权）。统一部署下的整体鉴权由部署侧前置过滤器提供，不在 obpm-ai 工作树源码内，本文不展开。

内部调用（Feign）¶

AiService 通过 Feign 调用 obpm-kms 的 RAG 端点（KmsRagFeignClient、KmsCoderRagFeignClient，使用 cn.myapps.common.conf.FeignConfig），由 KMS 侧的 CommonSecurityFilter 配合 systemToken 完成 Feign 鉴权（KMS 侧鉴权细节见 ../kms/index.md「鉴权说明」）。

完整鉴权机制与错误码说明见：顶层 index.md。

响应结构与错误码¶

AI 模块控制器**不使用**顶层 index.md 描述的统一 Resource（errcode/errmsg/data/errors）封装，而是直接返回 Spring ResponseEntity<Map<String, Object>>（或 ResponseEntity<List<...>>、ResponseEntity<byte[]>），即**裸 JSON 对象/数组或原始字节**，HTTP 状态码由 ResponseEntity 直接控制。

成功响应（2xx）¶

{
  "response": "AI 回复文本",
  "memoryId": "user_123",
  "mode": "RAG"
}

字段随端点不同而异（见各控制器文档）。

失败响应（4xx/5xx）¶

控制器对异常普遍 try/catch 后返回 ResponseEntity.badRequest().body(Map.of("error", "<错误描述>"))，HTTP 状态码 400，无 errcode 字段：

{ "error": "聊天请求失败: <异常消息>" }

错误码补充¶

AI 模块未引入模块专属业务错误码。错误以 HTTP 状态码 + 裸 JSON { "error": "..." } 形式返回：

HTTP	含义
200	成功
400	请求参数有误 / 业务异常（消息体 `{ "error": "..." }`）
401	仅 `AiController.chat` 在未登录且未传 `disk_id`（或 token 校验失败）时返回（业务校验，非鉴权过滤器）
404	`SystemPromptController.getSystemPrompt` 在提示词不存在时返回（`ResponseEntity.notFound()`，无响应体）
500	`AiProxyController.proxy` 转发上游失败时返回（消息体 `{"error":{"message":"..."}}`）

注：AiProxyController 透传上游大模型网关响应，状态码与响应体由上游决定（OpenAI 兼容格式，可能为 SSE 流式或 JSON）。

覆盖说明¶

本阶段覆盖 obpm-ai 工作树下的全部 5 个有端点控制器：AiController（AI 对话/RAG，6 个端点，含 chat、history、memory、health）、AiProxyController（OpenAI 兼容 API 反向代理转发，1 个端点 /llm-proxy/**，单方法支持 GET/POST/PUT/PATCH/DELETE/HEAD/OPTIONS 七种方法，透传上游大模型网关响应）、AiWelcomeController（欢迎首页 302 跳转，1 个端点）、CoderController（代码助手，3 个端点，使用 Security.getDesignerIdFromToken 取 memoryId）、SystemPromptController（系统提示词 CRUD，8 个端点，含按用户查询 / 默认提示词读写）。本批后 AI 模块**全部覆盖完成**。