CoderController（代码助手）

cn.myapps.ai.controller.CoderController —— AI 模块的代码助手控制器，基于 LangChain4j 与 Coder RAG 知识库提供代码生成、历史查询、记忆清除。会话记忆 ID 从请求令牌中解析（Security.getDesignerIdFromToken，对应设计器登录态），仅解析、不鉴权——令牌缺失时 memoryId 为 null，请求不会被拒绝。

• Tag：AI 服务
• 基址：${myapps.context-path.ai:}/api（缺省 context-path /ai，故完整前缀常为 /ai/api）
• 鉴权：否（obpm-ai 无鉴权过滤器，详见 index.md「鉴权说明」）
• 响应：直接返回 ResponseEntity<Map<String, Object>> / ResponseEntity<List<ChatMessageDto>>，非 统一 Resource（见 index.md「响应结构与错误码」）

memoryId 来源：三个端点的 memoryId 均由 Security.getDesignerIdFromToken(httpServletRequest) 从请求中解析「设计器 accessToken」得到。accessToken 按以下顺序查找：query 参数 / Cookie / 请求头 accessToken / 请求头 Authorization: Bearer <token>。解析失败返回 null，控制器不报错（生成的代码 / 取到的历史会以 memoryId=null 返回）。

1. 生成代码（RAG 增强）

携带 Coder RAG 召回与可选系统提示词发送一条消息给 AI，返回生成的代码建议。

• 接口类型：REST 资源
• 请求方式：POST
• 请求路径：<context-path>/api/coder/generate（完整：${myapps.context-path.ai:}/api/coder/generate）
• 鉴权：否（令牌仅用于解析 memoryId）
• Tag：AI 服务

请求体

JSON 对象（application/json）：

字段	类型	必填	说明
message	string	是	用户消息内容，不能为空
topK	int	否	RAG 召回 top-k，缺省 10
systemPromptId	long	否	系统提示词 ID，缺省不使用

与 AiController.chat 不同，本端点**不接受 disk_id**：Coder RAG 始终查询 obpm-kms 的 coder 向量索引（cookbook），由 CoderService.generateCode 内部经 Feign 调用 KmsCoderRagFeignClient。

请求示例

POST /ai/api/coder/generate?accessToken=<设计器令牌> HTTP/1.1
Content-Type: application/json

{
  "message": "写一个用于校验邮箱格式的 iScript 函数",
  "topK": 10,
  "systemPromptId": 2
}

响应

结构：ResponseEntity<Map<String, Object>>，非 统一 Resource。

data：

字段	类型	说明
response	string	AI 生成的内容（通常含代码片段）
memoryId	string/null	从设计器令牌解析的会话记忆 ID；令牌缺失时为 null
topK	int	实际使用的 top-k
systemPromptId	long/null	实际使用的系统提示词 ID
mode	string	固定 "RAG"

成功示例（HTTP 200）：

{
  "response": "```javascript\nfunction isValidEmail(email) { ... }\n```",
  "memoryId": "designer-001",
  "topK": 10,
  "systemPromptId": 2,
  "mode": "RAG"
}

失败示例（HTTP 400，消息为空 / 业务异常）：

{ "error": "消息不能为空" }

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

2. 获取代码助手聊天历史

按当前请求令牌解析的 memoryId 取代码助手聊天历史。

• 接口类型：REST 资源
• 请求方式：GET
• 请求路径：<context-path>/api/coder/history
• 鉴权：否（令牌仅用于解析 memoryId）
• Tag：AI 服务

请求参数

参数名	位置	类型	必填	说明
accessToken	query / cookie / header	string	否	设计器访问令牌，用于解析 memoryId（详见上文「memoryId 来源」）

请求示例

GET /ai/api/coder/history?accessToken=<设计器令牌> HTTP/1.1

响应

结构：ResponseEntity<List<ChatMessageDto>>，非 统一 Resource。

data：JSON 数组，元素结构：

字段	类型	说明
role	string	角色："user" / "assistant" / "unknown"
content	string	LangChain4j ChatMessageSerializer.messageToJson 序列化后的消息 JSON 字符串

成功示例（HTTP 200）：

[
  { "role": "user", "content": "{\"type\":\"user-message\",\"text\":\"写一个校验邮箱的函数\"}" },
  { "role": "assistant", "content": "{\"type\":\"ai-message\",\"text\":\"```javascript\\n...\\n```\"}" }
]

3. 清除代码助手聊天记忆

按当前请求令牌解析的 memoryId 清除代码助手聊天记忆。

• 接口类型：REST 资源
• 请求方式：DELETE
• 请求路径：<context-path>/api/coder/memory
• 鉴权：否（令牌仅用于解析 memoryId）
• Tag：AI 服务

请求参数

参数名	位置	类型	必填	说明
accessToken	query / cookie / header	string	否	设计器访问令牌，用于解析 memoryId（详见上文「memoryId 来源」）

请求示例

DELETE /ai/api/coder/memory?accessToken=<设计器令牌> HTTP/1.1

响应

结构：ResponseEntity<Map<String, String>>，非 统一 Resource。

成功示例（HTTP 200）：

{
  "message": "聊天记忆已清除",
  "memoryId": "designer-001"
}

---