gongzhiyongandClaude Sonnet 4.6
04d8fbb740
- 前端文件移入 frontend/ 子目录 - 新建 backend/ 目录（待开发） - 新增 CLAUDE.md、claudehd.md、EXTERNAL_SERVICES.md Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
434 lines
11 KiB
Markdown
434 lines
11 KiB
Markdown
# SOC 项目后端功能方案（按功能拆解）
|
||
|
||
> 约束：在未获得明确允许前，不修改前端交互，只补后端能力、接口和数据层。
|
||
> 目标：严格围绕当前 `~/go/soc` 这个 Gemini 风格前端，为每一个功能明确说明“用什么技术，完成什么功能，怎么落地”。
|
||
|
||
---
|
||
|
||
## 1. 对话流式回复
|
||
|
||
### 要完成什么功能
|
||
- 用户在当前聊天输入框发送消息
|
||
- 后端实时返回回答内容
|
||
- 支持“思考中 / 检索中 / 生成中”的流式状态
|
||
- 不改变现有前端交互，只替换当前前端 `simulateAIResponse()`
|
||
|
||
### 用什么技术
|
||
- **FastAPI**：提供聊天接口
|
||
- **SSE（Server-Sent Events）**：把大模型回答流式推给前端
|
||
- **Azure OpenAI**：生成最终回答
|
||
- **PostgreSQL**：保存消息记录和会话记录
|
||
|
||
### 怎么落地
|
||
- 新增接口：`POST /api/chat/stream`
|
||
- 前端发送用户消息到后端
|
||
- 后端先写入用户消息
|
||
- 再调用 Azure OpenAI 流式生成
|
||
- 将生成过程通过 SSE 持续返回给前端
|
||
- 最终把 assistant 回复保存入库
|
||
|
||
### 输出结果
|
||
- 前端保持当前 Gemini 风格交互不变
|
||
- 用户发送后能看到真实流式回答
|
||
- 替换掉前端 mock 返回逻辑
|
||
|
||
---
|
||
|
||
## 2. 会话管理
|
||
|
||
### 要完成什么功能
|
||
- 左侧历史会话列表从真实数据读取
|
||
- 支持新建会话
|
||
- 支持切换会话
|
||
- 支持删除会话
|
||
- 支持自动生成会话标题
|
||
|
||
### 用什么技术
|
||
- **FastAPI**：提供 REST API
|
||
- **PostgreSQL**：保存 conversation 和 message
|
||
- **SQLAlchemy / SQLModel**：管理数据表和查询
|
||
|
||
### 怎么落地
|
||
- 新增接口：
|
||
- `GET /api/conversations`
|
||
- `POST /api/conversations`
|
||
- `GET /api/conversations/{id}`
|
||
- `PATCH /api/conversations/{id}`
|
||
- `DELETE /api/conversations/{id}`
|
||
- 用户首次发送消息时自动创建会话
|
||
- 默认用首条消息前 20~30 字生成标题
|
||
- 前端左侧栏改为读取真实会话数据
|
||
|
||
### 输出结果
|
||
- 当前左侧 mock 会话列表替换成数据库真实数据
|
||
- 用户聊天记录可恢复
|
||
|
||
---
|
||
|
||
## 3. 内部知识库检索
|
||
|
||
### 要完成什么功能
|
||
- 当用户提问产品、方案、配置、内部资料时
|
||
- 后端优先查询内部知识库
|
||
- 再把知识库结果交给大模型总结回答
|
||
- 回答中带来源信息
|
||
|
||
### 用什么技术
|
||
- **KB_AGENT 接口**：调用内部知识库搜索
|
||
- **FastAPI service layer**：封装知识库调用
|
||
- **Azure OpenAI**：对检索结果总结与生成回答
|
||
|
||
### 怎么落地
|
||
- 新增服务模块：`kb_agent.py`
|
||
- 根据 `EXTERNAL_SERVICES.md` 中的：
|
||
- `KB_AGENT_URL`
|
||
- `KB_AGENT_API_KEY`
|
||
- `KB_AGENT_SEARCH_PATH`
|
||
- 后端在识别为内部知识问题时：
|
||
1. 请求知识库搜索
|
||
2. 获取 top-k 文档片段
|
||
3. 做摘要裁剪
|
||
4. 将结果作为上下文交给 Azure OpenAI
|
||
- 前端不改交互，只在回答里附带引用来源块
|
||
|
||
### 输出结果
|
||
- 当前产品类问题不再纯靠大模型空想
|
||
- 回答能基于内部知识库
|
||
- 更适合售前、售后、研发支持场景
|
||
|
||
---
|
||
|
||
## 4. 外部 AI 搜索
|
||
|
||
### 要完成什么功能
|
||
- 当用户问实时互联网信息、行业动态、外部资料时
|
||
- 后端自动执行外部搜索
|
||
- 支持网页搜索、内容读取、结果重排
|
||
- 满足快速模式和深度模式
|
||
- 后续支持图片和视频结果展示
|
||
|
||
### 用什么技术
|
||
- **Jina Search API**：做外部搜索
|
||
- **Jina Reader**：读取网页正文
|
||
- **Rerank 模型**：对结果重排
|
||
- **Azure OpenAI**：基于外部资料生成答案
|
||
|
||
### 怎么落地
|
||
- 新增模块：
|
||
- `jina_search.py`
|
||
- `jina_reader.py`
|
||
- `reranker.py`
|
||
- 固定流程：
|
||
- Search -> Read -> Rerank -> LLM
|
||
- 提供三种模式：
|
||
- `fast`：低延迟，少量搜索
|
||
- `deep`：高质量，多轮检索
|
||
- `auto`：后端自动判断
|
||
- 前端仍保持原有聊天区交互，只增加来源区块展示
|
||
|
||
### 输出结果
|
||
- 外部问题可获得更准确结果
|
||
- 不再只依赖大模型参数知识
|
||
- 满足企业级搜索准确度要求
|
||
|
||
---
|
||
|
||
## 5. 工单系统只读接入
|
||
|
||
### 要完成什么功能
|
||
- 支持查询工单列表
|
||
- 支持查询工单详情
|
||
- 支持汇总最近高优先级工单
|
||
- 支持在聊天中回答“最近有什么 P0/P1 工单”“某类问题集中在哪里”
|
||
- 支持首页/聊天区展示工单摘要数据
|
||
|
||
### 用什么技术
|
||
- **Gongdan HTTP API**：工单数据来源
|
||
- **FastAPI**：对前端提供统一工单接口
|
||
- **PostgreSQL（可选缓存）**：保存摘要缓存或查询记录
|
||
- **Azure OpenAI**：对工单数据做归纳总结
|
||
|
||
### 怎么落地
|
||
- 新增模块：`gongdan_client.py`
|
||
- 新增接口：
|
||
- `GET /api/tickets/summary`
|
||
- `GET /api/tickets`
|
||
- `GET /api/tickets/{id}`
|
||
- 对话场景下：
|
||
- 用户问工单问题
|
||
- 后端查询 gongdan
|
||
- 将结果整理后交给大模型总结
|
||
- 非对话场景下：
|
||
- 前端通过 summary 接口读取摘要
|
||
|
||
### 输出结果
|
||
- 当前前端 mock 工单摘要可替换为真实工单数据
|
||
- 用户能直接在聊天里分析工单问题
|
||
|
||
---
|
||
|
||
## 6. 文档生成
|
||
|
||
### 要完成什么功能
|
||
- 用户在聊天中要求生成方案、汇报、纪要、总结
|
||
- 后端把需求提交给文档生成 Agent
|
||
- 返回任务状态
|
||
- 文档完成后可返回下载地址或结果卡片
|
||
|
||
### 用什么技术
|
||
- **Doc Creator Agent HTTP API**：生成正式文档
|
||
- **FastAPI BackgroundTasks / 异步任务机制**：管理任务状态
|
||
- **PostgreSQL**：保存文档任务记录
|
||
- **Azure OpenAI**：前置整理文档提纲或结构
|
||
|
||
### 怎么落地
|
||
- 新增接口：
|
||
- `POST /api/documents/generate`
|
||
- `GET /api/documents/{task_id}`
|
||
- 对话中识别“生成文档”类意图
|
||
- 后端创建任务记录
|
||
- 调用 doc creator agent
|
||
- 前端保持当前聊天交互，后续只在消息中增加文档结果卡片
|
||
|
||
### 输出结果
|
||
- 用户可从聊天直接发起正式文档生成
|
||
- 满足销售、售前、汇报场景
|
||
|
||
---
|
||
|
||
## 7. 沙盒代码执行
|
||
|
||
### 要完成什么功能
|
||
- 处理表格、JSON、日志、数据分析类任务
|
||
- 允许后端在安全沙盒中执行代码
|
||
- 返回执行结果、图表、文件
|
||
- 不直接改前端交互，只把结果作为消息内容或附件返回
|
||
|
||
### 用什么技术
|
||
- **Daytona Sandbox**：安全执行环境
|
||
- **FastAPI**：封装沙盒执行入口
|
||
- **Python 工具链**：pandas / matplotlib / json / csv 等
|
||
- **PostgreSQL**：记录执行任务
|
||
|
||
### 怎么落地
|
||
- 新增接口：`POST /api/sandbox/run`
|
||
- 第一阶段不开放任意代码执行
|
||
- 先封装几类固定能力：
|
||
- CSV 汇总
|
||
- JSON 转换
|
||
- 数据统计
|
||
- 图表生成
|
||
- 对话编排层按意图决定是否调用 sandbox
|
||
|
||
### 输出结果
|
||
- 数据分析、表格处理能力可真正执行
|
||
- 后端具备“算”的能力，而不只是“说”的能力
|
||
|
||
---
|
||
|
||
## 8. 附件上传与解析
|
||
|
||
### 要完成什么功能
|
||
- 用户上传文件后，后端能接收附件
|
||
- 保存附件元数据
|
||
- 提取文本内容供知识理解、搜索或分析使用
|
||
- 后续支持文档总结、数据分析、代码执行
|
||
|
||
### 用什么技术
|
||
- **FastAPI UploadFile**：接收文件
|
||
- **对象存储/本地文件存储**：保存附件
|
||
- **文本解析库**：PDF、DOCX、TXT、CSV 解析
|
||
- **PostgreSQL**：保存附件元数据
|
||
|
||
### 怎么落地
|
||
- 新增接口：
|
||
- `POST /api/attachments`
|
||
- `GET /api/attachments/{id}`
|
||
- 后端保存文件路径与文件类型
|
||
- 针对不同格式做解析
|
||
- 将解析文本挂到对应消息上下文里
|
||
|
||
### 输出结果
|
||
- 后续聊天可真正支持“基于附件分析”
|
||
- 为文档生成、沙盒分析、知识问答提供基础能力
|
||
|
||
---
|
||
|
||
## 9. 工具编排层
|
||
|
||
### 要完成什么功能
|
||
- 判断用户问题该调用哪个能力
|
||
- 决定先查 KB、还是先查工单、还是先外部搜索
|
||
- 决定是否进入文档生成或沙盒执行
|
||
- 把多个工具结果统一整理成大模型上下文
|
||
|
||
### 用什么技术
|
||
- **Python Orchestrator**：自定义编排逻辑
|
||
- **Azure OpenAI**：辅助做工具选择与结果总结
|
||
- **FastAPI service layer**：承接 API 和工具层
|
||
|
||
### 怎么落地
|
||
- 新增模块：
|
||
- `planner.py`
|
||
- `chat_orchestrator.py`
|
||
- `context_builder.py`
|
||
- 第一阶段可以先做规则驱动：
|
||
- 问产品/项目 -> KB
|
||
- 问实时外部信息 -> Search
|
||
- 问工单 -> Tickets
|
||
- 问生成汇报 -> Documents
|
||
- 问数据处理 -> Sandbox
|
||
- 第二阶段再逐步引入 LLM 辅助路由
|
||
|
||
### 输出结果
|
||
- 后端从“多个孤立接口”升级成“统一智能后端”
|
||
- 前端仍然只需要一个对话入口
|
||
|
||
---
|
||
|
||
## 10. 数据持久化
|
||
|
||
### 要完成什么功能
|
||
- 保存历史会话
|
||
- 保存聊天消息
|
||
- 保存工具调用记录
|
||
- 保存附件记录
|
||
- 保存文档任务记录
|
||
|
||
### 用什么技术
|
||
- **PostgreSQL**：主数据库
|
||
- **SQLAlchemy / SQLModel**：ORM
|
||
- **Alembic**：数据库迁移
|
||
|
||
### 怎么落地
|
||
- 至少建立以下表：
|
||
- `conversations`
|
||
- `messages`
|
||
- `tool_runs`
|
||
- `attachments`
|
||
- `document_tasks`
|
||
- 以后如需多租户，再增加：
|
||
- `users`
|
||
- `organizations`
|
||
- `memberships`
|
||
- `audit_logs`
|
||
|
||
### 输出结果
|
||
- 数据不丢失
|
||
- 会话可追溯
|
||
- 工具调用过程可排查
|
||
|
||
---
|
||
|
||
## 11. 接口层总表
|
||
|
||
### 第一阶段建议建设的接口
|
||
|
||
#### 基础接口
|
||
- `GET /health`
|
||
|
||
#### 会话接口
|
||
- `GET /api/conversations`
|
||
- `POST /api/conversations`
|
||
- `GET /api/conversations/{id}`
|
||
- `PATCH /api/conversations/{id}`
|
||
- `DELETE /api/conversations/{id}`
|
||
|
||
#### 聊天接口
|
||
- `POST /api/chat/stream`
|
||
|
||
#### 工单接口
|
||
- `GET /api/tickets/summary`
|
||
- `GET /api/tickets`
|
||
- `GET /api/tickets/{id}`
|
||
|
||
#### 搜索接口
|
||
- `POST /api/search/internal`
|
||
- `POST /api/search/external`
|
||
|
||
#### 文档接口
|
||
- `POST /api/documents/generate`
|
||
- `GET /api/documents/{task_id}`
|
||
|
||
#### 附件接口
|
||
- `POST /api/attachments`
|
||
- `GET /api/attachments/{id}`
|
||
|
||
#### 沙盒接口
|
||
- `POST /api/sandbox/run`
|
||
|
||
---
|
||
|
||
## 12. 推荐技术组合总结
|
||
|
||
### 基础后端框架
|
||
- **FastAPI**：API 服务
|
||
- **Uvicorn / Gunicorn**：服务运行
|
||
|
||
### 数据层
|
||
- **PostgreSQL**：数据持久化
|
||
- **SQLAlchemy / SQLModel**：ORM
|
||
- **Alembic**：迁移管理
|
||
|
||
### AI 与搜索
|
||
- **Azure OpenAI**：LLM 生成与总结
|
||
- **KB_AGENT**：内部知识库检索
|
||
- **Jina Search / Reader / Rerank**：外部搜索链路
|
||
|
||
### 外部业务系统
|
||
- **Gongdan API**：工单只读
|
||
- **Doc Creator Agent**：文档生成
|
||
- **Daytona Sandbox**：受控代码执行
|
||
|
||
### 交互协议
|
||
- **SSE**：流式输出
|
||
- **REST API**：管理类接口
|
||
|
||
---
|
||
|
||
## 13. 第一阶段开发顺序
|
||
|
||
### 第一步
|
||
先完成：
|
||
- FastAPI 基础框架
|
||
- PostgreSQL 接入
|
||
- conversations/messages 表
|
||
- `/api/chat/stream`
|
||
- `/api/conversations`
|
||
|
||
### 第二步
|
||
接入：
|
||
- Azure OpenAI
|
||
- KB_AGENT
|
||
- 工单系统
|
||
|
||
### 第三步
|
||
接入：
|
||
- Jina 外部搜索
|
||
- 来源引用
|
||
- 工具状态流式事件
|
||
|
||
### 第四步
|
||
接入：
|
||
- 文档生成任务
|
||
- 附件解析
|
||
- Sandbox
|
||
|
||
---
|
||
|
||
## 14. 最终结论
|
||
|
||
这个项目当前最合适的后端建设方式，不是泛泛而谈“做一个 AI 平台后端”，而是严格按功能拆：
|
||
|
||
- 用 **FastAPI + SSE** 完成真实聊天流式回复
|
||
- 用 **PostgreSQL** 完成会话和消息持久化
|
||
- 用 **Azure OpenAI** 完成回答生成
|
||
- 用 **KB_AGENT** 完成内部知识检索
|
||
- 用 **Jina Search/Reader/Rerank** 完成外部搜索
|
||
- 用 **Gongdan API** 完成工单只读分析
|
||
- 用 **Doc Creator Agent** 完成正式文档生成
|
||
- 用 **Daytona Sandbox** 完成安全数据处理与代码执行
|
||
|
||
而且整个过程中：
|
||
**前端交互不改，只替换数据来源和后端能力。**
|