nojava
423 lines
31 KiB
Markdown
423 lines
31 KiB
Markdown
# AI 助手功能 - 需求规格说明书
|
||
|
||
| 文档版本 | 修订日期 | 修订人 | 修订内容 |
|
||
| :------- | :--------- | :----- | :----------------------------------------------------------------------- |
|
||
| V1.0 | 2026-05-23 | — | 初始版本，定义首页 AI 助手聊天功能需求 |
|
||
| V1.1 | 2026-05-23 | — | 增加多轮上下文（最多 5 轮/会话）、会话持久化、左侧历史会话列表与回看能力 |
|
||
| V1.2 | 2026-05-23 | — | 产品约定（D-01～D-06）经确认纳入正式需求，移除待确认表述 |
|
||
|
||
---
|
||
|
||
## 1. 项目概述
|
||
|
||
### 1.1 功能背景
|
||
|
||
当前 Jog 博客系统公开站点顶部导航（`BlogLayout`）仅提供 **「首页」** 入口。访客与登录用户无法在站内直接获得与博客、写作相关的智能问答能力。为提升站点互动性与 AI 能力曝光，在首页导航区新增 **「AI 助手」** 入口，提供独立的对话页面：用户可 **多轮追问**（单会话最多 5 轮），问答内容 **持久化存储**；页面 **左侧展示历史会话**，点选可 **完整回看** 当时的全部提问与 AI 回复。
|
||
|
||
### 1.2 功能目标
|
||
|
||
- 在公开站点顶部导航增加「AI 助手」入口，与「首页」并列，便于发现与访问
|
||
- 支持 **多轮上下文对话**（单会话最多 **5 轮**），超出后引导用户 **新建会话** 继续提问
|
||
- **持久化** 用户每条提问与 AI 每条回复，刷新或换设备登录后可恢复历史
|
||
- 页面 **左侧会话列表** + **右侧对话区**，点选历史会话可只读回看完整往来记录
|
||
- 复用现有 DashScope（阿里云百炼）OpenAI 兼容接入与 `dashscope.*` 配置
|
||
- 通过登录鉴权与用户级限流，控制调用成本与滥用风险
|
||
|
||
### 1.3 适用范围
|
||
|
||
| 角色 | 涉及范围 |
|
||
| :------------- | :----------------------------------------------------------------------- |
|
||
| 产品经理 | 验证导航、多轮上限、新会话流程、左侧历史与回看交互 |
|
||
| 前端开发工程师 | 左右分栏布局、会话列表、多轮发送、新会话、历史回看 |
|
||
| 后端开发工程师 | 对话 API、会话/消息持久化、多轮上下文组装、Flyway 表结构 |
|
||
| 测试工程师 | 多轮边界、持久化、历史加载、5 轮上限等用例 |
|
||
| 运维工程师 | 复用 `DASHSCOPE_API_KEY`；关注对话表容量与备份策略 |
|
||
|
||
### 1.4 现状说明
|
||
|
||
| 项目 | 现状 |
|
||
| :------- | :------------------------------------------------------------------- |
|
||
| 顶部导航 | `jog-frontend/src/layouts/BlogLayout.vue` 中 `el-menu` 仅含「首页」 |
|
||
| 路由 | 公开布局子路由仅有 `/` 与 `/article/:id` |
|
||
| AI 能力 | 已有摘要、润色等 `/api/app/**` 接口，均依赖 DashScope |
|
||
| 数据存储 | 尚无 AI 对话相关表，需新增 Flyway 迁移 |
|
||
|
||
### 1.5 改动合理性评估（V1.1）
|
||
|
||
| 改动项 | 合理性说明 |
|
||
| :--------------- | :------------------------------------------------------------------------- |
|
||
| 多轮 + 最多 5 轮 | 满足追问与指代理解；限制轮次可控制 Token 成本与模型超时风险，与现有 AI 功能限流思路一致 |
|
||
| 问答持久化 | 与「左侧历史、完整回看」强依赖；需登录态绑定 `user_id`，避免数据串户 |
|
||
| 左侧历史列表 | 常见聊天产品形态；列表按 **会话** 聚合（见 2 名词解释），避免每条提问占一行导致列表过长 |
|
||
| 新会话 | 5 轮上限后的自然出口；同时用于用户主动开启新话题 |
|
||
|
||
---
|
||
|
||
## 2. 名词解释
|
||
|
||
| 术语 | 说明 |
|
||
| :------------- | :------------------------------------------------------------------------------------- |
|
||
| AI 助手 | 面向站点用户的通用问答对话功能 |
|
||
| 会话（Session）| 一次连续对话线程，拥有唯一 `sessionId`；左侧历史列表的 **每一行对应一个会话** |
|
||
| 轮次（Round） | **1 轮 = 1 条用户提问 + 1 条 AI 回复**（均成功落库后计 1 轮）；单会话最多 **5 轮** |
|
||
| 新会话 | 用户主动点击「新会话」，创建新的 `sessionId`，右侧对话区清空，轮次计数从 0 开始 |
|
||
| 只读回看 | 从左侧点选 **已满 5 轮** 的会话，或用户仅查看历史时：展示完整消息记录，**不可再发送** |
|
||
| 继续对话 | 点选 **未满 5 轮** 的历史会话时：加载历史消息，可在该 `sessionId` 下继续追问 |
|
||
| 会话标题 | 列表展示用，默认取该会话 **首条用户提问** 前 30 字（超出以 `…` 结尾） |
|
||
| DashScope | 阿里云百炼 API，本系统通过 OpenAI 兼容 `chat/completions` 调用 |
|
||
|
||
---
|
||
|
||
## 3. 功能需求清单
|
||
|
||
### 3.1 导航入口（前端）
|
||
|
||
（与 V1.0 一致，编号保留。）
|
||
|
||
#### 3.1.2 业务规则
|
||
|
||
| 编号 | 规则项 | 业务规则说明 |
|
||
| :------------------- | :----------- | :--------------------------------------------------------------------------------------------------- |
|
||
| FR-AI-CHAT-NAV-01 | 按钮位置 | 位于 `BlogLayout` 顶部 `el-menu` 内，紧挨「首页」之后，文案为「AI 助手」 |
|
||
| FR-AI-CHAT-NAV-02 | 路由 | 跳转 `/ai-assistant`，路由 `name` 建议 `AiAssistant`，页面标题「AI 助手」 |
|
||
| FR-AI-CHAT-NAV-03 | 激活态 | 当前路由为 `/ai-assistant` 时菜单项高亮 |
|
||
| FR-AI-CHAT-NAV-04 | 可见性 | 未登录可见入口；**发送消息、查看历史列表** 需登录（见 3.2） |
|
||
| FR-AI-CHAT-NAV-05 | 样式 | 与「首页」一致，可选聊天图标 |
|
||
|
||
#### 3.1.3 验收标准
|
||
|
||
| 编号 | 验证场景 | 预期结果 |
|
||
| :------------------- | :--------------------------- | :------------------------------------------------- |
|
||
| AC-AI-CHAT-NAV-01 | 任意公开页查看顶部导航 | 可见「首页」与「AI 助手」 |
|
||
| AC-AI-CHAT-NAV-02 | 点击「AI 助手」 | 进入 `/ai-assistant` |
|
||
| AC-AI-CHAT-NAV-03 | 在 AI 助手页刷新 | 「AI 助手」为激活态 |
|
||
|
||
---
|
||
|
||
### 3.2 AI 助手对话页（前端）
|
||
|
||
#### 3.2.1 功能描述
|
||
|
||
新增 `AiAssistant.vue`（`BlogLayout` 子路由）。页面为 **左右分栏**：
|
||
|
||
- **左侧（约 260px）**：顶部「新会话」按钮 + 当前用户的 **历史会话列表**（按最近更新时间倒序）
|
||
- **右侧**：当前会话的 **完整消息流**（用户/AI 气泡）+ 底部输入区与「发送」；显示当前会话 **轮次指示**（如 `3/5`）
|
||
|
||
用户发送问题时携带当前 `sessionId`（新会话时由后端创建或前端先调创建接口获得）。成功后消息入库并在右侧追加。左侧列表在首条提问成功后出现/更新该会话项。
|
||
|
||
#### 3.2.2 页面布局
|
||
|
||
```
|
||
┌────────────────────────────────────────────────────────────────────┐
|
||
│ Jog Logo [首页] [AI助手] 登录/用户 │
|
||
├──────────────┬─────────────────────────────────────────────────────┤
|
||
│ [ 新会话 ] │ 当前会话标题（首问摘要） 轮次 3/5 │
|
||
│──────────────│─────────────────────────────────────────────────────│
|
||
│ 历史会话列表 │ · 用户：……（右/主色） │
|
||
│ · 如何在… │ · AI：……（左/灰底） │
|
||
│ 05-23 14:20│ · 用户：…… │
|
||
│ · Spring… │ · AI：…… │
|
||
│ 05-22 09:10│─────────────────────────────────────────────────────│
|
||
│ （滚动） │ [ 请输入您的问题... ] [ 发送 ] │
|
||
└──────────────┴─────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
#### 3.2.3 业务规则
|
||
|
||
| 编号 | 规则项 | 业务规则说明 |
|
||
| :------------------- | :--------------- | :---------------------------------------------------------------------------------------------------------------------- |
|
||
| FR-AI-CHAT-FE-01 | 分栏布局 | 左侧固定宽约 260px，右侧 `flex:1`；小屏（<768px）可折叠左侧为抽屉（可选，首版允许左右同时展示并横向滚动） |
|
||
| FR-AI-CHAT-FE-02 | 新会话按钮 | 左侧顶部主按钮「新会话」；点击后：清空右侧消息、清空当前 `sessionId`、轮次显示 `0/5`、输入区可用；**不删除** 已有历史会话 |
|
||
| FR-AI-CHAT-FE-03 | 历史列表项 | 展示会话标题（首问前 30 字）+ 最后更新时间；当前选中会话高亮；默认进入页面时选中 **最近一次活跃会话**（若无则空状态） |
|
||
| FR-AI-CHAT-FE-04 | 点选历史 | 调用 `GET .../sessions/{id}/messages` 加载 **该会话全部消息**（按时间正序），右侧完整展示用户提问与 AI 回复全文 |
|
||
| FR-AI-CHAT-FE-05 | 继续 vs 只读 | 若该会话 `roundCount < 5`：加载后可继续发送（`sessionId` 设为当前）；若 `roundCount >= 5`：**只读回看**，输入区禁用，展示提示条 |
|
||
| FR-AI-CHAT-FE-06 | 五轮上限提示 | 当前会话已达 5 轮时：禁用发送；提示「当前会话已满 5 轮，请点击左侧 **新会话** 开始新的对话」；`ElMessage.warning` 可选 |
|
||
| FR-AI-CHAT-FE-07 | 轮次指示 | 右侧标题栏展示 `当前轮次/5`（仅统计已成功完成的 user+assistant 一对） |
|
||
| FR-AI-CHAT-FE-08 | 输入框 | `textarea`，占位符「请输入您的问题…」，1~6 行自适应 |
|
||
| FR-AI-CHAT-FE-09 | 发送 | 主按钮「发送」；`Ctrl/Cmd+Enter` 发送；trim 后 1~2000 字符 |
|
||
| FR-AI-CHAT-FE-10 | 登录校验 | 未登录：左侧列表为空或展示「登录后查看历史」；发送时提示并跳转 `/login?redirect=/ai-assistant` |
|
||
| FR-AI-CHAT-FE-11 | Loading | 请求中发送按钮 loading、输入只读；列表末「正在思考…」 |
|
||
| FR-AI-CHAT-FE-12 | 消息展示 | 用户/AI 分色气泡；AI 文本 `pre-wrap`；首版不做 Markdown |
|
||
| FR-AI-CHAT-FE-13 | 失败处理 | 若 AI 调用失败：**不** 将本轮计入 `roundCount`；用户消息可保留为「发送失败」状态或允许重试（见 3.3 FR-AI-CHAT-BE-15） |
|
||
| FR-AI-CHAT-FE-14 | 刷新恢复 | 刷新页面后重新拉取会话列表与当前/最近会话消息，**不依赖** localStorage 存对话正文 |
|
||
| FR-AI-CHAT-FE-15 | 空状态 | 无会话时右侧展示欢迎文案；左侧列表空状态「暂无对话，点击新会话开始」 |
|
||
| FR-AI-CHAT-FE-16 | 列表分页 | 会话列表默认加载最近 **50** 条，底部「加载更多」分页（`page`/`size`） |
|
||
| FR-AI-CHAT-FE-17 | 滚动 | 右侧消息区内部滚动；新消息后滚到底部；回看历史会话打开时滚到底部 |
|
||
|
||
#### 3.2.4 验收标准
|
||
|
||
| 编号 | 验证场景 | 预期结果 |
|
||
| :------------------- | :----------------------------------------- | :--------------------------------------------------------------- |
|
||
| AC-AI-CHAT-FE-01 | 已登录，点击「新会话」后连续问答 3 次 | 右侧 3 组问答，指示 `3/5`，左侧出现 1 个会话项 |
|
||
| AC-AI-CHAT-FE-02 | 当前会话第 5 轮成功后尝试第 6 次发送 | 发送被拦截，提示点击「新会话」 |
|
||
| AC-AI-CHAT-FE-03 | 点击「新会话」后再提问 | 新会话独立入库，左侧新增或切换到新会话项 |
|
||
| AC-AI-CHAT-FE-04 | 点选已满 5 轮的历史会话 | 完整展示 5 轮共 10 条消息，输入区禁用，提示只读 |
|
||
| AC-AI-CHAT-FE-05 | 点选仅 2 轮的历史会话并继续提问 | 加载 2 轮历史后继续，第 3 轮成功后为 `3/5` |
|
||
| AC-AI-CHAT-FE-06 | 刷新页面 | 会话列表与最近会话消息与刷新前一致 |
|
||
| AC-AI-CHAT-FE-07 | 未登录进入页面 | 无法发送；引导登录 |
|
||
|
||
---
|
||
|
||
### 3.3 AI 对话与会话接口（后端）
|
||
|
||
#### 3.3.1 功能描述
|
||
|
||
提供会话管理与多轮对话能力：
|
||
|
||
1. 创建/继续会话并发送消息（调用大模型时带入 **当前会话已成功落库的全部历史**，最多 **5 轮 = 10 条消息**）
|
||
2. 查询当前用户会话列表
|
||
3. 查询指定会话下的全部消息（供左侧点选回看）
|
||
|
||
所有问答 **写入数据库**；仅允许操作 **当前登录用户** 自己的会话。
|
||
|
||
#### 3.3.2 数据模型（Flyway）
|
||
|
||
建议新增迁移 `V5__ai_chat_tables.sql`（版本号以仓库实际递增为准）：
|
||
|
||
**表 `ai_chat_session`**
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| :------------- | :------------- | :---------------------------------------- |
|
||
| id | BIGINT PK | 会话 ID |
|
||
| user_id | BIGINT | 所属用户，索引 |
|
||
| title | VARCHAR(64) | 会话标题，首条用户消息截断 |
|
||
| round_count | TINYINT | 已完成轮次，0~5 |
|
||
| last_message_at| DATETIME | 最后一条消息时间，列表排序用 |
|
||
| created_at | DATETIME | 创建时间 |
|
||
| updated_at | DATETIME | 更新时间 |
|
||
| deleted | TINYINT | 逻辑删除，默认 0（与项目 `@TableLogic` 一致） |
|
||
|
||
**表 `ai_chat_message`**
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| :---------- | :------------ | :---------------------------------- |
|
||
| id | BIGINT PK | 消息 ID |
|
||
| session_id | BIGINT | 外键 → `ai_chat_session.id` |
|
||
| role | VARCHAR(16) | `user` / `assistant` |
|
||
| content | TEXT | 提问或回复 **全文** |
|
||
| sort_order | INT | 会话内顺序，从 1 递增 |
|
||
| created_at | DATETIME | 创建时间 |
|
||
|
||
#### 3.3.3 接口清单
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
| :----- | :------------------------------------- | :----------------------------- |
|
||
| POST | `/api/app/ai/sessions` | 创建空会话，返回 `sessionId` |
|
||
| GET | `/api/app/ai/sessions` | 分页查询当前用户会话列表 |
|
||
| GET | `/api/app/ai/sessions/{sessionId}/messages` | 查询会话全部消息（正序） |
|
||
| POST | `/api/app/ai/chat` | 在指定会话中发送用户消息并返回 AI 回复 |
|
||
|
||
#### 3.3.4 发送消息接口 `POST /api/app/ai/chat`
|
||
|
||
**请求体**
|
||
|
||
```json
|
||
{
|
||
"sessionId": 1001,
|
||
"message": "那和 GraphQL 有什么区别？"
|
||
}
|
||
```
|
||
|
||
| 字段 | 必填 | 说明 |
|
||
| :---------- | :--- | :------------------------------------------------------------------- |
|
||
| sessionId | 是 | 会话 ID；须属于当前用户且 `round_count < 5` |
|
||
| message | 是 | 本条用户提问，1~2000 字符（trim 后） |
|
||
|
||
**处理流程**
|
||
|
||
1. 校验登录、`sessionId` 归属、`round_count < 5`、`message` 合法
|
||
2. 插入 `ai_chat_message`（role=`user`）
|
||
3. 读取该会话已有消息（最多 5 轮历史），按 `sort_order` 组装 `messages` 数组送入 DashScope（含 System Prompt）
|
||
4. 调用模型，得到 `reply`
|
||
5. 插入 `ai_chat_message`（role=`assistant`，content=全文）
|
||
6. 更新 `session.round_count += 1`、`last_message_at`；若为首条用户消息则更新 `title`
|
||
7. 返回 `reply` 及更新后的 `roundCount`
|
||
|
||
**响应 `data` 示例**
|
||
|
||
```json
|
||
{
|
||
"sessionId": 1001,
|
||
"reply": "GraphQL 与 REST 的主要区别在于……",
|
||
"roundCount": 3,
|
||
"maxRounds": 5,
|
||
"model": "qwen-turbo",
|
||
"promptTokens": 512,
|
||
"completionTokens": 180,
|
||
"costMillis": 2400
|
||
}
|
||
```
|
||
|
||
#### 3.3.5 业务规则
|
||
|
||
| 编号 | 规则项 | 业务规则说明 |
|
||
| :------------------- | :--------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||
| FR-AI-CHAT-BE-01 | 鉴权 | 全部接口需登录；`sessionId` 必须属于当前 `userId`，否则 `403` 或 `404` |
|
||
| FR-AI-CHAT-BE-02 | 轮次上限 | `round_count >= 5` 时拒绝 `POST /chat`，返回 `400`，message：「当前会话已满 5 轮，请新建会话」 |
|
||
| FR-AI-CHAT-BE-03 | 多轮上下文 | 调用模型时传入：System Prompt + 该会话已落库的 user/assistant 消息（按时间序），**最多 10 条**（5 轮）；不含本次尚未入库的 user 消息则先入库 user 再调模型 |
|
||
| FR-AI-CHAT-BE-04 | 上下文长度保护 | 组装后的总字符数超过 `dashscope.max-input`（默认 8000）时，**从最早的用户/助手对开始丢弃**，直至不超限（System 与当前 user 消息保留） |
|
||
| FR-AI-CHAT-BE-05 | 存储 | 用户 `message` 与 AI `reply` **全文** 写入 `ai_chat_message.content`，供历史回看 |
|
||
| FR-AI-CHAT-BE-06 | 会话列表 | `GET /sessions` 按 `last_message_at` 降序；返回 `id, title, roundCount, lastMessageAt`；默认 `size=50` |
|
||
| FR-AI-CHAT-BE-07 | 消息列表 | `GET /sessions/{id}/messages` 返回 `id, role, content, sortOrder, createdAt` 全量正序 |
|
||
| FR-AI-CHAT-BE-08 | 新会话 | `POST /sessions` 创建 `round_count=0` 的记录；前端「新会话」优先调此接口拿到 `sessionId` 再提问 |
|
||
| FR-AI-CHAT-BE-09 | 模型与 Key | 复用 `DashScopeProperties`；Key 缺失返回既有 `AI_API_KEY_MISSING` |
|
||
| FR-AI-CHAT-BE-10 | System Prompt | 与 V1.0 一致，并补充：「当前为同一会话的多轮对话，请结合上文回答，避免重复已说过的内容。」 |
|
||
| FR-AI-CHAT-BE-11 | 回复截断 | 单条 `reply` 超过 4000 字符截断并 `…` |
|
||
| FR-AI-CHAT-BE-12 | 超时/限流/异常 | 超时 30s → `5002`；用户每分钟最多 **10 次** `POST /chat`（Redis `ai_chat:rate:`）；DashScope 失败 → `5001` |
|
||
| FR-AI-CHAT-BE-13 | 日志 | 日志中 **不打印** 问答全文，可记录 `sessionId`、轮次、字符长度、token、耗时 |
|
||
| FR-AI-CHAT-BE-14 | 软删除 | 会话表支持逻辑删除（为后续「删除历史」预留）；首版前端 **不提供** 删除入口 |
|
||
| FR-AI-CHAT-BE-15 | 失败不落 assistant | 模型调用失败时：已插入的 user 消息 **保留**；不插入 assistant、不增加 `round_count`；返回错误码，前端允许用户 **重试发送**（同 `sessionId` 不重复插 user，或后端按幂等键去重——首版允许重复 user 消息则需在需求中禁止，**采用：失败时仅重试模型，不重复插入 user**） |
|
||
|
||
**FR-AI-CHAT-BE-15 实现约定**：发送接口在步骤 2 插入 user 后若模型失败，user 消息保留；重试时若上一条为未配对的 user，则 **不再插入新 user**，仅重新请求模型并写入 assistant。
|
||
|
||
#### 3.3.6 错误码补充
|
||
|
||
| 错误码 / HTTP | 描述 | 触发条件 |
|
||
| :------------ | :----------------------- | :-------------------------------- |
|
||
| 400 | 参数错误 | message 非法 |
|
||
| 400 | 会话轮次已满 | `round_count >= 5` |
|
||
| 403/404 | 会话不存在或无权访问 | `sessionId` 非本人 |
|
||
| 401 | 未登录 | 无 Token |
|
||
| 429 | 请求过于频繁 | 限流 |
|
||
| 5001/5002 | AI 不可用 / 超时 | DashScope 异常 |
|
||
|
||
#### 3.3.7 验收标准
|
||
|
||
| 编号 | 验证场景 | 预期结果 |
|
||
| :------------------- | :------------------------------------ | :-------------------------------------------- |
|
||
| AC-AI-CHAT-BE-01 | 新会话连续 5 次成功 `/chat` | `round_count=5`，第 6 次返回 400 |
|
||
| AC-AI-CHAT-BE-02 | 第 3 轮提问含指代「它」 | 模型请求体含前 2 轮共 4 条历史消息 |
|
||
| AC-AI-CHAT-BE-03 | `GET .../messages` | 返回条数与轮次一致，content 为当时全文 |
|
||
| AC-AI-CHAT-BE-04 | 用户 A 访问用户 B 的 sessionId | 403/404 |
|
||
| AC-AI-CHAT-BE-05 | 模型失败后重试 | 不重复 user 行，成功后 round_count 正确 +1 |
|
||
|
||
---
|
||
|
||
### 3.4 配置与部署
|
||
|
||
仍复用 `dashscope.*` 与 `DASHSCOPE_API_KEY`。新增表由 Flyway 自动迁移。部署后验证：多轮对话、刷新恢复、第 5 轮后新建会话。
|
||
|
||
---
|
||
|
||
## 4. 交互流程
|
||
|
||
### 4.1 首次提问（新会话）
|
||
|
||
```
|
||
1. 用户进入 /ai-assistant（已登录）
|
||
2. 点击「新会话」→ POST /sessions → 获得 sessionId
|
||
3. 输入问题 → POST /chat { sessionId, message }
|
||
4. 后端存 user → 调模型（仅 System + 本条 user）→ 存 assistant → roundCount=1
|
||
5. 右侧展示问答；左侧列表出现该会话（标题=首问截断）
|
||
```
|
||
|
||
### 4.2 同会话多轮追问
|
||
|
||
```
|
||
1. 用户在当前 session 继续输入（roundCount < 5）
|
||
2. POST /chat → 后端载入已有消息作为上下文 → 返回 reply
|
||
3. roundCount 递增；满 5 后 FR-AI-CHAT-FE-06 拦截发送
|
||
```
|
||
|
||
### 4.3 回看历史会话
|
||
|
||
```
|
||
1. 用户点击左侧某会话项
|
||
2. GET /sessions/{id}/messages → 右侧展示全部 user/assistant 全文
|
||
3. 若 roundCount < 5：可继续发送；若 = 5：只读 + 提示新会话
|
||
```
|
||
|
||
### 4.4 满 5 轮后继续提问
|
||
|
||
```
|
||
1. 用户在本会话第 5 轮成功后再次发送
|
||
2. 前端拦截并提示「请点击新会话」
|
||
3. 用户点击「新会话」→ 新 sessionId → 重新开始 0/5
|
||
```
|
||
|
||
---
|
||
|
||
## 5. 接口与代码对齐（规划）
|
||
|
||
### 5.1 后端
|
||
|
||
| 模块 | 文件 | 变更说明 |
|
||
| :-------------- | :---------------------------------------------------------------- | :-------------------------------- |
|
||
| jog-admin | `db/migration/V5__ai_chat_tables.sql` | 会话与消息表 |
|
||
| jog-module-blog | `entity/AiChatSession.java`, `AiChatMessage.java` | 实体 |
|
||
| jog-module-blog | `mapper/...` | MyBatis-Plus Mapper |
|
||
| jog-module-blog | `dto/*`, `vo/*` | 请求/响应对象 |
|
||
| jog-module-blog | `service/AiChatService` + `impl` | 多轮组装、持久化、DashScope 调用 |
|
||
| jog-module-blog | `controller/AiChatController.java` | 上述 REST 接口 |
|
||
|
||
### 5.2 前端
|
||
|
||
| 模块 | 文件 | 变更说明 |
|
||
| :----------- | :---------------------------------------- | :-------------------------- |
|
||
| jog-frontend | `layouts/BlogLayout.vue` | 「AI 助手」导航 |
|
||
| jog-frontend | `router/index.js` | `/ai-assistant` |
|
||
| jog-frontend | `views/AiAssistant.vue` | 左右分栏主页面 |
|
||
| jog-frontend | `components/AiChatSidebar.vue`（可选拆分）| 左侧列表 + 新会话 |
|
||
| jog-frontend | `components/AiChatPanel.vue`（可选拆分） | 右侧消息 + 输入 |
|
||
| jog-frontend | `api/aiChat.js` | 会话与 chat API 封装 |
|
||
|
||
---
|
||
|
||
## 6. 非功能性需求
|
||
|
||
| 编号 | 类型 | 需求说明 |
|
||
| :----- | :------- | :----------------------------------------------------------------------- |
|
||
| NFR-01 | 性能 | 95 分位 ≤ 15s；5 轮上下文受 `max-input` 截断保护 |
|
||
| NFR-02 | 可用性 | AI 不可用时仍可回看已存历史；失败可重试当前轮 |
|
||
| NFR-03 | 安全性 | 会话严格按 `user_id` 隔离；API Key 不入库/日志/仓库；HTTPS 传输 |
|
||
| NFR-04 | 隐私 | 对话正文存业务库，仅本人可读；管理后台 **不提供** 查看他人工单（首版） |
|
||
| NFR-05 | 可扩展性 | 轮次上限、列表条数可配置化；预留流式 SSE、删除会话 |
|
||
| NFR-06 | 容量 | 首版会话列表 **仅分页加载**（默认每页 50 条），不设单用户数量硬上限，**不自动删除** 历史会话 |
|
||
| NFR-07 | 可观测性 | 记录 sessionId、轮次、耗时、token；日志不打印全文 |
|
||
|
||
---
|
||
|
||
## 7. 范围外（后续迭代）
|
||
|
||
| 项 | 说明 |
|
||
| :----------- | :----------------------------------------- |
|
||
| 流式输出 | SSE 逐字展示回复 |
|
||
| 删除会话 | 前端删除 + 逻辑删除接口 |
|
||
| 未登录试用 | 公开 API + IP 限流 |
|
||
| Markdown渲染 | AI 回复富文本（需 XSS 防护） |
|
||
| 会话重命名 | 用户自定义左侧标题 |
|
||
| 导出对话 | 导出 Markdown/PDF |
|
||
|
||
---
|
||
|
||
## 8. 风险与缓解
|
||
|
||
| 风险 | 影响 | 缓解措施 |
|
||
| :------------------- | :---------------- | :-------------------------------------------- |
|
||
| 5 轮上下文 Token 过大 | 超时/费用 | `max-input` 截断最早轮次 |
|
||
| 历史表数据增长 | 存储成本 | 分页列表；后续归档策略 |
|
||
| 满 5 轮体验断裂 | 用户困惑 | 明确提示 +「新会话」一键 |
|
||
| 失败重试重复 user | 轮次与展示错乱 | BE-15 幂等重试约定 |
|
||
|
||
---
|
||
|
||
## 9. 产品约定（已确认）
|
||
|
||
以下约定已于 **2026-05-23** 与产品方确认，作为 V1.1 正式需求的一部分，开发与测试须按此实现。
|
||
|
||
| 编号 | 约定项 | 需求说明 |
|
||
| :--- | :----- | :------- |
|
||
| D-01 | 左侧列表按 **会话** 聚合 | 每会话占列表一行；标题取首条用户提问前 30 字；点选后右侧展示该会话下 **全部** 问答全文（非按单条提问分行） |
|
||
| D-02 | 历史会话可继续对话 | `roundCount < 5` 的会话：加载历史后 **可继续发送**；`roundCount >= 5` 的会话：**只读回看**，输入区禁用并引导「新会话」 |
|
||
| D-03 | 新会话不删除旧数据 | 点击「新会话」仅创建并切换至新 `sessionId`，清空右侧编辑区；**不删除、不覆盖** 已有会话数据 |
|
||
| D-04 | 首版不提供删除与重命名 | 前端无删除会话、无重命名入口；`ai_chat_session.deleted` 字段预留供后续迭代（见 §7） |
|
||
| D-05 | 失败不计轮、支持同轮重试 | 模型调用失败时不插入 assistant、不增加 `round_count`；允许对未配对的 user 消息重试，**不重复插入** user（见 FR-AI-CHAT-BE-15） |
|
||
| D-06 | 进入页默认最近会话 | 已登录用户进入 `/ai-assistant` 时，默认选中 **最近更新** 的会话并加载其消息；无任何会话时展示空状态，等同待「新会话」 |
|
||
| D-07 | 会话保留策略 | 历史会话 **仅分页展示**（默认每页 50 条），**不设** 单用户数量硬上限，**不自动删除** 最旧会话（与 NFR-06 一致） |
|
||
|
||
---
|
||
|
||
**编写人：** AI 助手
|
||
**评审人：** 已确认（产品约定 D-01～D-07）
|
||
**生效日期：** 2026-05-23
|