# 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 兼容模式：
Endpoint: `https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions`
模型: `qwen-turbo` |
| FR-AI-SUMMARY-BE-06 | 提示词（Prompt） | System：你是一名专业的博客编辑，请根据用户提供的标题与正文生成 100~150 字的中文摘要，要求语言精炼、概括核心观点，不使用第一人称
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：
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