nojava/Jog
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
284ecf4be85525a9ab015a249cdd951c44e21426
Jog/doc/jog-system-ai-summary-requirements.md
T
nojava 14c3f98449 集成AI摘要
2026-05-21 16:01:34 +08:00

220 lines
18 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# AI 智能摘要生成功能 - 需求规格说明书
| 文档版本 | 修订日期 | 修订人 | 修订内容 |
| :------- | :--------- | :----- | :-------------------------------------- |
| V1.0 | 2026-05-21 | — | 初始版本，定义 AI 摘要生成功能完整需求 |
---
## 1. 项目概述
### 1.1 功能背景
为提升博客创作者的写作效率与文章发布质量，在 Jog 博客系统的"文章发布"页面新增 **AI 智能摘要生成** 功能。用户在撰写完文章正文后，可一键调用大模型自动生成一段高质量的文章摘要，无需手动撰写。
### 1.2 功能目标
- 降低创作者撰写摘要的时间成本，提升发布效率
- 通过 AI 自动提炼文章核心内容，提升摘要质量与一致性
- 完成与阿里云百炼（DashScope）大模型平台的对接，为后续 AI 能力（如智能标签、文章润色、相关推荐）打下基础
### 1.3 适用范围
| 角色 | 涉及范围 |
| :------------- | :-------------------------------------------------------- |
| 产品经理 | 验证功能形态与交互流程 |
| 前端开发工程师 | 实现"生成摘要"按钮与调用流程 |
| 后端开发工程师 | 接入阿里云百炼大模型，封装统一接口 |
| 测试工程师 | 编写自动化测试与回归用例 |
| 运维工程师 | 维护 `dashscope.api-key` 等敏感配置项 |
---
## 2. 名词解释
| 术语 | 说明 |
| :------------------ | :------------------------------------------------------------------------------------- |
| 阿里云百炼 | 阿里云推出的一站式大模型服务平台，提供 Qwen 系列等模型的统一 API（DashScope） |
| DashScope | 阿里云百炼对外暴露的 API 服务名，本系统对接其 OpenAI 兼容模式 |
| OpenAI 兼容模式 | DashScope 兼容 OpenAI ChatCompletion 协议的接入方式，便于切换底层模型与生态工具复用 |
| Qwen-Turbo | 通义千问 Turbo 系列模型，速度快、成本低，适合文本摘要等轻量任务，本功能默认使用该模型 |
| 文章发布位置 | 指 `jog-frontend/src/views/app/ArticleEditor.vue` 中"摘要"字段所在的表单区域 |
---
## 3. 功能需求清单
### 3.1 入口与按钮交互（前端）
#### 3.1.1 功能描述
在文章编辑器页面（`/app/editor` 与 `/app/editor/:id`）的"摘要"输入框旁边新增 **"生成摘要"** 按钮。用户点击按钮后，系统自动根据已输入的标题与正文调用后端大模型接口，将返回的摘要回填到摘要输入框中。
#### 3.1.2 业务规则
| 编号 | 规则项 | 业务规则说明 |
| :------------------- | :--------------- | :---------------------------------------------------------------------------------------------------------------------- |
| FR-AI-SUMMARY-FE-01 | 按钮位置 | 按钮显示在"摘要"输入框下方右侧（与`textarea`同一表单项内），文案为"AI 生成摘要"，主色调使用 Element Plus `type="primary"` |
| FR-AI-SUMMARY-FE-02 | 触发前置条件 | 点击按钮时，正文（去除 HTML 标签后纯文本）字符数 ≥ 20 才允许调用；否则提示"正文过短，无法生成摘要" |
| FR-AI-SUMMARY-FE-03 | Loading 状态 | 按钮在请求期间显示 `loading` 态并禁用，防止用户重复点击 |
| FR-AI-SUMMARY-FE-04 | 已有摘要确认 | 若摘要框已有内容，点击按钮前需弹出确认框："已有摘要，确认覆盖？"；用户确认后才发起调用 |
| FR-AI-SUMMARY-FE-05 | 成功回填 | 接口返回成功后，将生成的摘要自动填充到摘要输入框，并提示"摘要生成成功" |
| FR-AI-SUMMARY-FE-06 | 失败提示 | 接口返回失败时，提示后端返回的 `message`，按钮恢复可点击状态 |
| FR-AI-SUMMARY-FE-07 | 超时提示 | 请求超过 30 秒未返回，提示"AI 服务响应超时，请稍后再试" |
#### 3.1.3 验收标准
| 编号 | 验证场景 | 预期结果 |
| :------------------- | :---------------------------------------------------- | :-------------------------------------------------------------------------------- |
| AC-AI-SUMMARY-FE-01 | 正文为空时点击"AI 生成摘要" | 提示"正文过短，无法生成摘要"，不发起后端请求 |
| AC-AI-SUMMARY-FE-02 | 正文字符数 ≥ 20，点击按钮 | 按钮进入 loading 态，请求成功后摘要框被自动填充 |
| AC-AI-SUMMARY-FE-03 | 摘要框已有内容时点击按钮 | 弹出"已有摘要，确认覆盖？"对话框；取消则不调用接口，确定则继续调用并覆盖 |
| AC-AI-SUMMARY-FE-04 | 后端返回 5001 错误码（AI 服务异常） | 提示"AI 服务暂时不可用，请稍后再试"，按钮恢复可用 |
| AC-AI-SUMMARY-FE-05 | 在编辑文章（带 `:id`）页面同样可使用该按钮 | 行为与新建文章一致 |
---
### 3.2 AI 摘要生成接口（后端）
#### 3.2.1 功能描述
后端新增 **`POST /api/app/article/summary`** 接口，接收文章标题与正文，调用阿里云百炼大模型生成摘要后返回给前端。
#### 3.2.2 业务规则
| 编号 | 规则项 | 业务规则说明 |
| :------------------- | :---------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------ |
| FR-AI-SUMMARY-BE-01 | 接口路径与方法 | `POST /api/app/article/summary`，需登录用户调用（继承 `/api/app/**` 的 `USER`/`ADMIN` 权限校验） |
| FR-AI-SUMMARY-BE-02 | 请求参数 | `title`（可选，最长 200）、`content`（必填，最长 50000，提交前已去除 HTML 标签） |
| FR-AI-SUMMARY-BE-03 | 入参校验 | `content` 为空或去除 HTML 后字符数 < 20，返回 `400 BAD_REQUEST` 与提示"正文过短，无法生成摘要" |
| FR-AI-SUMMARY-BE-04 | 内容截断 | 若 `content` 字符数 > 8000，仅取前 8000 字符送入大模型，避免超过模型输入限制 |
| FR-AI-SUMMARY-BE-05 | 模型与平台 | 默认调用阿里云百炼（DashScope）OpenAI 兼容模式：<br>Endpoint: `https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions`<br>模型: `qwen-turbo` |
| FR-AI-SUMMARY-BE-06 | 提示词（Prompt） | System：你是一名专业的博客编辑，请根据用户提供的标题与正文生成 100~150 字的中文摘要，要求语言精炼、概括核心观点，不使用第一人称<br>User：标题：xxx 正文：xxx |
| FR-AI-SUMMARY-BE-07 | 摘要长度限制 | 返回前端的摘要在 80~200 字之间；若模型返回过长则截断到 200 字并以 `…` 结尾 |
| FR-AI-SUMMARY-BE-08 | 鉴权方式 | 调用 DashScope 时通过 `Authorization: Bearer ${dashscope.api-key}` 传递 API Key |
| FR-AI-SUMMARY-BE-09 | 配置项 | 在 `application.yml` 中提供 `dashscope.api-key`、`dashscope.base-url`、`dashscope.model`、`dashscope.timeout` 四个配置项，支持环境变量覆盖 |
| FR-AI-SUMMARY-BE-10 | 超时与重试 | 单次调用超时 30 秒，不做自动重试；超时返回 `5002` 错误码 |
| FR-AI-SUMMARY-BE-11 | 限流 | 同一用户每分钟最多调用 5 次（基于 `@RateLimit`），超出返回 `429 RATE_LIMITED` |
| FR-AI-SUMMARY-BE-12 | 异常处理 | DashScope 返回非 2xx 或 JSON 结构异常时，统一抛出 `BusinessException`，错误码 `5001 AI 服务暂时不可用` |
| FR-AI-SUMMARY-BE-13 | 日志记录 | 记录请求耗时、模型名称、token 消耗（若响应中含 `usage` 字段）、是否成功；不记录请求与响应的完整文本，避免日志膨胀 |
| FR-AI-SUMMARY-BE-14 | 敏感配置 | `dashscope.api-key` 不允许写入仓库的 `application.yml`，需通过环境变量 `DASHSCOPE_API_KEY` 或本地未提交的 `application-local.yml` 覆盖 |
#### 3.2.3 响应数据结构
```json
{
"code": 200,
"message": "success",
"data": {
"summary": "本文系统介绍了…（80~200 字）",
"model": "qwen-turbo",
"promptTokens": 1024,
"completionTokens": 96,
"costMillis": 1832
},
"timestamp": 1716268800000
}
```
#### 3.2.4 错误码扩展
| 错误码 | 描述 | 触发条件 |
| :----- | :-------------------- | :--------------------------------------------- |
| 5001 | AI 服务暂时不可用 | DashScope HTTP 非 2xx 或返回内容不可解析 |
| 5002 | AI 服务响应超时 | DashScope 调用超过 30 秒未返回 |
| 5003 | AI 内容审核未通过 | DashScope 返回内容被审核拦截（保留扩展） |
#### 3.2.5 验收标准
| 编号 | 验证场景 | 预期结果 |
| :------------------- | :-------------------------------------------------------------- | :-------------------------------------------------------------------------------- |
| AC-AI-SUMMARY-BE-01 | 未登录调用接口 | 返回 `401 UNAUTHORIZED` |
| AC-AI-SUMMARY-BE-02 | 登录用户传入合法正文 | 返回 200，`data.summary` 长度在 80~200 字符之间 |
| AC-AI-SUMMARY-BE-03 | 正文 < 20 字符 | 返回 `400 BAD_REQUEST`，提示"正文过短，无法生成摘要" |
| AC-AI-SUMMARY-BE-04 | `dashscope.api-key` 未配置 | 返回 `5001`，提示"AI 服务未配置 API Key" |
| AC-AI-SUMMARY-BE-05 | DashScope 返回 401（API Key 无效） | 返回 `5001`，记录 ERROR 日志 |
| AC-AI-SUMMARY-BE-06 | 单用户 1 分钟内连续调用 6 次 | 第 6 次返回 `429 RATE_LIMITED` |
| AC-AI-SUMMARY-BE-07 | 输入正文 9000 字符 | 后端截断至 8000 字符送入模型，正常返回摘要 |
---
### 3.3 配置与部署
#### 3.3.1 配置项清单
| 配置项 | 默认值 | 说明 |
| :----------------------- | :------------------------------------------------------------------ | :-------------------------------------------------------------- |
| `dashscope.api-key` | （留空） | 阿里云百炼平台获取的 API Key，**生产必须通过环境变量传入** |
| `dashscope.base-url` | `https://dashscope.aliyuncs.com/compatible-mode/v1` | DashScope OpenAI 兼容模式 BaseURL |
| `dashscope.model` | `qwen-turbo` | 默认使用的模型 |
| `dashscope.timeout` | `30000` | 调用超时（毫秒） |
| `dashscope.max-input` | `8000` | 单次输入正文字符上限 |
#### 3.3.2 环境变量映射
| 环境变量 | 对应配置项 |
| :------------------- | :-------------------- |
| `DASHSCOPE_API_KEY` | `dashscope.api-key` |
| `DASHSCOPE_BASE_URL` | `dashscope.base-url` |
| `DASHSCOPE_MODEL` | `dashscope.model` |
#### 3.3.3 部署步骤
1. 在阿里云百炼控制台创建 API Key：<https://bailian.console.aliyun.com/?apiKey=1>
2. 启动服务前设置环境变量：
```bash
export DASHSCOPE_API_KEY=sk-xxxxx
```
3. 启动 `jog-admin` 服务，访问文章编辑页面，点击"AI 生成摘要"按钮验证
---
## 4. 非功能性需求
| 编号 | 类型 | 需求说明 |
| :------ | :-------- | :------------------------------------------------------------------------- |
| NFR-01 | 性能 | 95 分位响应时间 ≤ 10 秒（取决于 DashScope 服务，由超时 + 限流保护） |
| NFR-02 | 可用性 | DashScope 不可用时，前端仍可手动撰写摘要，业务不受阻塞 |
| NFR-03 | 安全性 | API Key 不入库、不入日志、不入仓库；前端不感知 Key 任何信息 |
| NFR-04 | 可扩展性 | 后端通过 `AiSummaryService` 抽象，未来可平滑替换为本地模型或其他平台 |
| NFR-05 | 可观测性 | 关键节点输出 INFO/ERROR 日志，包含耗时、模型、tokens |
---
## 5. 接口与代码对齐
### 5.1 后端涉及代码
| 模块 | 文件 | 变更说明 |
| :---------------- | :------------------------------------------------------------------------------------ | :------------------------------------ |
| jog-module-blog | `dto/GenerateSummaryDTO.java` | 新增请求 DTO |
| jog-module-blog | `dto/SummaryResultVO.java` | 新增响应 VO |
| jog-module-blog | `config/DashScopeProperties.java` | 新增配置 Properties |
| jog-module-blog | `service/AiSummaryService.java` + `service/impl/AiSummaryServiceImpl.java` | 新增摘要服务 |
| jog-module-blog | `controller/ArticleController.java` | 新增 `POST /api/app/article/summary` |
| jog-admin | `resources/application.yml` | 新增 `dashscope.*` 配置块 |
### 5.2 前端涉及代码
| 模块 | 文件 | 变更说明 |
| :----------- | :---------------------------------------------------- | :------------------------------------ |
| jog-frontend | `src/api/article.js` | 新增 `generateArticleSummary(data)` |
| jog-frontend | `src/views/app/ArticleEditor.vue` | 在摘要表单项内新增"AI 生成摘要"按钮 |
---
## 6. 风险与缓解
| 风险 | 影响 | 缓解措施 |
| :---------------------------- | :---------------------------------- | :------------------------------------------------------------------ |
| DashScope 服务限流或宕机 | 摘要无法生成 | 设置超时与降级，前端允许用户手动撰写 |
| API Key 泄露 | 账单异常 | 强制环境变量注入；定期巡检 GitHub/日志中的 Key |
| 模型返回内容包含敏感词 | 内容安全风险 | 接入 DashScope 内容审核（后续迭代）；保留 `5003` 错误码占位 |
| 单次输入过长导致超时 | 用户等待过久 | 后端 8000 字符截断 + 30s 超时熔断 |
---
**编写人：** AI 助手
**评审人：** 待评审
**生效日期：** 2026-05-21
Reference in New Issue View Git Blame Copy Permalink