一、 本周工作概述
本周围绕AI能力接入，完成了以下工作：
1. 确定模型服务：选择 Sophnet 平台的 DeepSeek-V4-Flash 作为当前阶段的大模型能力来源。
2. 后端代理封装：在 Spring Boot 后端新增 AI 模块，通过后端统一调用第三方模型接口。
3. 前端交互落地：在管理台顶部新增 AI 助手入口，支持用户通过弹窗输入问题并获取AI回答。
4. 联调问题排查：解决了本地跨域、接口路径、API Key配置格式、模型鉴权等问题。
5. 文档同步更新：补充了接口文档、架构设计、开发文档、数据库设计和流程图中的AI助手接入说明。
二、 AI接入方案设计：前端不直接接触密钥
本周最重要的技术决策是：前端不直接调用大模型平台，而是统一调用后端接口 `/api/ai/chat`。
这样设计主要基于三点考虑：
1. 安全性：API Key 不会暴露在浏览器端，避免被用户通过控制台或网络请求直接获取。
2. 可维护性：后续如果切换模型供应商，只需要修改后端配置和模型调用服务，不需要改动前端调用方式。
3. 可扩展性：后端可以逐步加入调用日志、限流、异常处理、Prompt版本管理和模型路由能力。
当前调用链路如下：
前端 AiChatButton.vue
-> frontend/src/api/ai.ts
-> POST /api/ai/chat
-> 后端 AiChatController
-> AiChatService
-> Sophnet /v1/chat/completions
-> DeepSeek-V4-Flash
-> 返回 answer 给前端展示
三、 后端实现：封装通用AI对话能力
后端新增了 `modules/ai` 模块，当前主要包括：
1. 配置类：读取 `ai.sophnet` 下的 base-url、api-key、model 、stream 等配置。
2. DTO对象：定义前端请求参数 `question` 和后端响应字段 `answer`。
3. Service层：使用 Spring `RestClient` 调用 Sophnet 的 OpenAI兼容 Chat Completions 接口。
4. Controller层：对外暴露 `/api/ai/chat`，保持项目统一的 `ApiResponse` 返回结构。
当前 Sophnet 请求体采用 OpenAI兼容格式：
model: DeepSeek-V4-Flash
stream : false
messages: system + user
这说明本周不仅是“把接口调通”，更重要的是建立了后续所有AI能力的基础调用模式。合同生成、摘要提取、合同润色、风险识别等功能，都可以在这个模型调用链路上替换不同的 system prompt 和业务 prompt 来扩展。
四、 前端实现：AI助手弹窗接入
前端新增了 `AiChatButton.vue` 组件，并挂载到主布局 `MainLayout.vue` 的顶部用户区域。
当前交互流程是：
1. 用户登录系统后，在右上角点击“AI助手”。
2. 系统弹出对话框。
3. 用户输入问题并按 Enter 或点击发送。
4. 前端调用 `/api/ai/chat`。
5. 后端返回AI生成结果后，前端追加展示在对话记录中。
这个设计虽然目前还是基础问答形态，但已经完成了从用户界面到大模型返回结果的完整闭环，为后续“合同上下文问答”“当前页面智能解释”“合同风险辅助分析”等功能打下了基础。
实测可以正常调用，如图，询问问题可以正常获取回复
五、 联调问题与技术收获
本周联调过程中遇到了几个典型问题：
1. CORS跨域问题
后端最初只允许 `localhost:4000`，而 Vite 默认前端端口是 `localhost:5173`，导致登录请求被浏览器拦截。最终通过补充 CORS 允许来源解决。
2. API Key配置问题
AI接口最初返回 `401 Unauthorized: 授权信息不正确`。排查后发现问题不是密钥本身，而是 `application.yml` 中默认值写法包含了双引号，导致请求头实际变成了 `Bearer "key"`。去掉双引号后，模型调用恢复正常。
3. 模型接口格式问题
Sophnet 提供的是 OpenAI兼容的 Chat Completions 接口，因此后端调用地址应为 `/v1/chat/completions`，请求体使用 `messages` 数组，而不是 Responses API 的 `input` 格式。
六、 文档更新与阶段总结
本周同步更新了项目相关设计文档：
1. 在接口文档中新增 `/api/ai/chat` 接口说明、请求响应示例和配置注意事项。
2. 在总体架构设计中补充 Sophnet DeepSeek 接入方案和通用AI对话服务。
3. 在开发文档中补充 AI 助手组件、后端模块路径、配置项和联调注意点。
4. 在数据库设计中补充通用AI对话和模型调用日志的后续落库建议。
5. 在流程图中加入 AI助手到后端模型代理再到 DeepSeek-V4-Flash 的调用链路。
