nojava
259 lines
21 KiB
Markdown
259 lines
21 KiB
Markdown
# AI 文章润色与拼写检查功能 - 需求规格说明书
|
||
|
||
| 文档版本 | 修订日期 | 修订人 | 修订内容 |
|
||
| :------- | :--------- | :----- | :---------------------------------------- |
|
||
| V1.0 | 2026-05-23 | — | 初始版本，定义 AI 文章润色功能完整需求 |
|
||
|
||
---
|
||
|
||
## 1. 项目概述
|
||
|
||
### 1.1 功能背景
|
||
|
||
在博客写作过程中，创作者常面临语法不通顺、用词不当、标点不规范等问题。手动校对耗时且容易遗漏。为提升写作效率与文章质量，在 Jog 博客系统的文章编辑器中新增 **AI 润色** 功能，一键优化文本表达，并提供原文与润色结果的对比视图，允许用户灵活采纳。
|
||
|
||
### 1.2 功能目标
|
||
|
||
- 降低创作者校对与润色的时间成本
|
||
- 通过 AI 自动优化语法、表达和标点，提升文章专业性
|
||
- 提供原文与润色结果的对比视图，让用户掌控修改粒度
|
||
- 支持段落级润色，避免一次性替换全文带来的风险
|
||
- 复用现有 DashScope 大模型接入能力，降低开发成本
|
||
|
||
### 1.3 适用范围
|
||
|
||
| 角色 | 涉及范围 |
|
||
| :------------- | :---------------------------------------------------- |
|
||
| 产品经理 | 验证功能形态与对比交互流程 |
|
||
| 前端开发工程师 | 实现"AI 润色"按钮、对比视图、采纳/撤销交互 |
|
||
| 后端开发工程师 | 新增润色 API，复用 DashScope 调用链路 |
|
||
| 测试工程师 | 编写自动化测试与回归用例 |
|
||
| 运维工程师 | 无需额外配置（复用已有 `dashscope.*` 配置项） |
|
||
|
||
---
|
||
|
||
## 2. 名词解释
|
||
|
||
| 术语 | 说明 |
|
||
| :----------------- | :------------------------------------------------------------------------------------- |
|
||
| 润色 | 对文本进行语法修正、表达优化、标点规范化，保持原意不变 |
|
||
| 对比视图 | 左侧展示原文、右侧展示润色结果的并排布局，方便用户逐段比对 |
|
||
| 采纳 | 用户确认使用润色后的文本替换原文 |
|
||
| 部分采纳 | 用户仅替换选定段落，而非全文替换 |
|
||
| DashScope | 阿里云百炼对外暴露的 API 服务名，本系统对接其 OpenAI 兼容模式 |
|
||
| Qwen-Turbo | 通义千问 Turbo 系列模型，速度快、成本低，适合文本润色等任务 |
|
||
|
||
---
|
||
|
||
## 3. 功能需求清单
|
||
|
||
### 3.1 入口与按钮交互（前端）
|
||
|
||
#### 3.1.1 功能描述
|
||
|
||
在文章编辑器页面（`/app/editor` 与 `/app/editor/:id`）的富文本工具栏右侧新增 **"AI 润色"** 按钮。用户选中需要润色的文本段落后，点击按钮调用后端润色接口，系统展示原文与润色结果的对比视图供用户决策。
|
||
|
||
#### 3.1.2 业务规则
|
||
|
||
| 编号 | 规则项 | 业务规则说明 |
|
||
| :-------------------- | :--------------- | :---------------------------------------------------------------------------------------------------------------------- |
|
||
| FR-AI-POLISH-FE-01 | 按钮位置 | 按钮显示在富文本编辑器工具栏右侧，文案为"AI 润色"，可配图标（如钢笔图标），使用 Element Plus `type="warning"` 区分现有按钮 |
|
||
| FR-AI-POLISH-FE-02 | 触发前置条件 | 用户需在编辑器中选中文本（纯文本长度 ≥ 20 字符）；未选中或选中过短时提示"请先选中至少 20 个字符的文本" |
|
||
| FR-AI-POLISH-FE-03 | Loading 状态 | 按钮在请求期间显示 `loading` 态并禁用，防止重复点击 |
|
||
| FR-AI-POLISH-FE-04 | 对比视图 | 润色完成后，在编辑器下方弹出对比面板：左侧为"原文"（带浅红背景）、右侧为"润色后"（带浅绿背景），逐段展示差异 |
|
||
| FR-AI-POLISH-FE-05 | 段落级操作 | 每段对比行提供"采纳"按钮，用户可逐段替换；面板顶部提供"全部采纳"按钮，一键替换所有段落 |
|
||
| FR-AI-POLISH-FE-06 | 采纳行为 | 点击"采纳"，将该段润色文本替换回编辑器对应位置；替换后该段高亮闪烁一次以提示用户 |
|
||
| FR-AI-POLISH-FE-07 | 关闭对比视图 | 提供"关闭"按钮关闭对比面板；关闭前若有未采纳段落，弹出确认"有未采纳的润色结果，确定关闭？" |
|
||
| FR-AI-POLISH-FE-08 | 失败提示 | 接口返回失败时，提示后端返回的 `message`，按钮恢复可点击状态 |
|
||
| FR-AI-POLISH-FE-09 | 超时提示 | 请求超过 30 秒未返回，提示"AI 服务响应超时，请稍后再试" |
|
||
| FR-AI-POLISH-FE-10 | 多次润色 | 用户可对同一段落多次润色；对比视图始终展示当前原文与最新润色结果的对比 |
|
||
|
||
#### 3.1.3 验收标准
|
||
|
||
| 编号 | 验证场景 | 预期结果 |
|
||
| :-------------------- | :---------------------------------------------------------- | :-------------------------------------------------------------------------------- |
|
||
| AC-AI-POLISH-FE-01 | 未选中文本时点击"AI 润色" | 提示"请先选中至少 20 个字符的文本"，不发起后端请求 |
|
||
| AC-AI-POLISH-FE-02 | 选中 ≥ 20 字符文本，点击按钮 | 按钮进入 loading 态，请求成功后显示对比视图 |
|
||
| AC-AI-POLISH-FE-03 | 对比视图中点击单段"采纳" | 该段原文被润色文本替换，编辑器光标跳转到替换位置 |
|
||
| AC-AI-POLISH-FE-04 | 对比视图中点击"全部采纳" | 所有段落被替换，面板自动关闭，提示"已全部采纳" |
|
||
| AC-AI-POLISH-FE-05 | 有未采纳段落时点击关闭 | 弹出确认对话框；取消则保持面板；确认则关闭面板 |
|
||
| AC-AI-POLISH-FE-06 | 后端返回 5001 错误 | 提示"AI 服务暂时不可用，请稍后再试"，按钮恢复可用 |
|
||
| AC-AI-POLISH-FE-07 | 在编辑文章（带 `:id`）页面同样可使用润色 | 行为与新建文章一致 |
|
||
|
||
---
|
||
|
||
### 3.2 AI 润色接口（后端）
|
||
|
||
#### 3.2.1 功能描述
|
||
|
||
后端新增 **`POST /api/app/article/polish`** 接口，接收用户选中的文本段落，调用阿里云百炼大模型进行润色后返回润色结果。
|
||
|
||
#### 3.2.2 业务规则
|
||
|
||
| 编号 | 规则项 | 业务规则说明 |
|
||
| :-------------------- | :---------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||
| FR-AI-POLISH-BE-01 | 接口路径与方法 | `POST /api/app/article/polish`，需登录用户调用（继承 `/api/app/**` 的 `USER`/`ADMIN` 权限校验） |
|
||
| FR-AI-POLISH-BE-02 | 请求参数 | `text`（必填，最长 10000，为去除 HTML 标签后的纯文本选中内容） |
|
||
| FR-AI-POLISH-BE-03 | 入参校验 | `text` 为空或去除 HTML 后字符数 < 20，返回 `400 BAD_REQUEST` 与提示"文本过短，无法润色" |
|
||
| FR-AI-POLISH-BE-04 | 内容截断 | 若 `text` 字符数 > 6000，仅取前 6000 字符送入大模型，避免超过模型输入限制 |
|
||
| FR-AI-POLISH-BE-05 | 模型与平台 | 复用现有 DashScope OpenAI 兼容模式调用，默认使用 `qwen-turbo` |
|
||
| FR-AI-POLISH-BE-06 | 提示词（Prompt） | System：你是一名专业的文字编辑，请润色用户提供的中文文本。修正语法错误、优化表达方式、规范标点符号，保持原意不变，使文本更流畅专业。直接输出润色后的文本，不要添加任何解释或标记。<br>User：请润色下面这段中文文本：{用户文本} |
|
||
| FR-AI-POLISH-BE-07 | 段落保持 | 润色后的文本应保持与原文相同的段落结构；若模型合并了段落，后端按原文段落数拆分后返回 |
|
||
| FR-AI-POLISH-BE-08 | 鉴权方式 | 复用 `dashscope.api-key`，通过 `Authorization: Bearer {key}` 传递 |
|
||
| FR-AI-POLISH-BE-09 | 超时与重试 | 单次调用超时 30 秒，不做自动重试；超时返回 `5002` 错误码 |
|
||
| FR-AI-POLISH-BE-10 | 限流 | 复用现有 Redis 限流机制，同一用户每分钟最多调用 5 次（与摘要、标签推荐共享配额）；超出返回 `429 RATE_LIMITED` |
|
||
| FR-AI-POLISH-BE-11 | 异常处理 | DashScope 返回非 2xx 或 JSON 结构异常时，统一抛出 `BusinessException`，错误码 `5001 AI 服务暂时不可用` |
|
||
| FR-AI-POLISH-BE-12 | 日志记录 | 记录请求耗时、文本长度、是否成功；不记录请求与响应的完整文本，避免日志膨胀 |
|
||
|
||
#### 3.2.3 响应数据结构
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"original": "这是需要润色的原文文本。",
|
||
"polished": "这是经过润色的原文文本。",
|
||
"diffSegments": [
|
||
{
|
||
"index": 0,
|
||
"original": "这是需要润色的原文文本。",
|
||
"polished": "这是经过润色的原文文本。"
|
||
}
|
||
],
|
||
"model": "qwen-turbo",
|
||
"promptTokens": 512,
|
||
"completionTokens": 256,
|
||
"costMillis": 1420
|
||
},
|
||
"timestamp": 1716268800000
|
||
}
|
||
```
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| :----------------- | :------------ | :------------------------------------------------ |
|
||
| original | String | 用户提交的原始文本 |
|
||
| polished | String | 润色后的完整文本 |
|
||
| diffSegments | Array | 逐段对比数据，前端据此渲染对比视图 |
|
||
| diffSegments[].index | int | 段落序号（从 0 开始） |
|
||
| diffSegments[].original | String | 该段原文 |
|
||
| diffSegments[].polished | String | 该段润色后文本 |
|
||
| model | String | 实际使用的模型名称 |
|
||
| promptTokens | Integer | 输入消耗的 token 数（可为 null） |
|
||
| completionTokens | Integer | 输出消耗的 token 数（可为 null） |
|
||
| costMillis | Long | 接口耗时（毫秒） |
|
||
|
||
#### 3.2.4 验收标准
|
||
|
||
| 编号 | 验证场景 | 预期结果 |
|
||
| :-------------------- | :---------------------------------------------------------- | :-------------------------------------------------------------------------------- |
|
||
| AC-AI-POLISH-BE-01 | 未登录调用接口 | 返回 `401 UNAUTHORIZED` |
|
||
| AC-AI-POLISH-BE-02 | 登录用户传入合法文本 | 返回 200，`data.polished` 为润色后文本，`diffSegments` 数组非空 |
|
||
| AC-AI-POLISH-BE-03 | 文本 < 20 字符 | 返回 `400 BAD_REQUEST`，提示"文本过短，无法润色" |
|
||
| AC-AI-POLISH-BE-04 | `dashscope.api-key` 未配置 | 返回 `5005`，提示"AI 服务未配置 API Key" |
|
||
| AC-AI-POLISH-BE-05 | DashScope 返回 401（API Key 无效） | 返回 `5001`，记录 ERROR 日志 |
|
||
| AC-AI-POLISH-BE-06 | 单用户 1 分钟内连续调用 6 次 | 第 6 次返回 `429 RATE_LIMITED` |
|
||
|
||
---
|
||
|
||
### 3.3 对比视图交互设计
|
||
|
||
#### 3.3.1 组件结构
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────┐
|
||
│ 工具栏 [B][I][H2][H3][列表][引用][分割线] [✨ AI 润色] │
|
||
├─────────────────────────────────────────────────────────┤
|
||
│ │
|
||
│ [富文本编辑器内容区] │
|
||
│ │
|
||
├─────────────────────────────────────────────────────────┤
|
||
│ AI 润色结果对比 [全部采纳] [✕] │
|
||
│ ┌─────────────────────┬─────────────────────────────┐ │
|
||
│ │ 原文 │ 润色后 │ │
|
||
│ │ 这是一段需要润色的 │ 这是一段经过润色的文本。 │ │
|
||
│ │ 文本。 │ [采纳] │ │
|
||
│ ├─────────────────────┼─────────────────────────────┤ │
|
||
│ │ 另一段原文... │ 另一段润色后... [采纳] │ │
|
||
│ └─────────────────────┴─────────────────────────────┘ │
|
||
└─────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
#### 3.3.2 交互规则
|
||
|
||
| 编号 | 规则项 | 说明 |
|
||
| :-------------------- | :--------------- | :---------------------------------------------------------------------- |
|
||
| FR-AI-POLISH-UI-01 | 差异高亮 | 原文与润色后之间的差异字符以不同颜色高亮（红色删除线 = 原文被删，绿色下划线 = 新增） |
|
||
| FR-AI-POLISH-UI-02 | 段落边框 | 已采纳的段落行变为灰色并禁用"采纳"按钮，显示"已采纳"标记 |
|
||
| FR-AI-POLISH-UI-03 | 全部采纳 | 点击"全部采纳"后，面板显示"全部已采纳"状态 2 秒后自动关闭 |
|
||
| FR-AI-POLISH-UI-04 | 快捷键 | `Escape` 键关闭对比面板（触发表 FR-AI-POLISH-FE-07 的确认逻辑） |
|
||
| FR-AI-POLISH-UI-05 | 空状态 | 若润色后文本与原文完全一致（无优化空间），展示提示"未发现需要润色的内容" |
|
||
|
||
---
|
||
|
||
## 4. 交互流程
|
||
|
||
```
|
||
1. 用户在编辑器中选中一段文本
|
||
2. 用户点击工具栏"AI 润色"按钮
|
||
3. 系统校验选中文本长度（≥ 20 字符）
|
||
4. 按钮进入 loading 态，调用后端润色 API
|
||
5. API 返回后，编辑器下方弹出对比视图
|
||
6. 用户查看逐段差异：
|
||
a. 点击某段"采纳" → 该段原文被润色文本替换
|
||
b. 点击"全部采纳" → 全文替换，面板关闭
|
||
c. 点击"关闭" → 若有未采纳段落，确认后关闭
|
||
7. 完成后，用户可继续编辑或保存文章
|
||
```
|
||
|
||
---
|
||
|
||
## 5. 接口与代码对齐
|
||
|
||
### 5.1 后端涉及代码
|
||
|
||
| 模块 | 文件 | 变更说明 |
|
||
| :-------------- | :---------------------------------------------------------------- | :-------------------------------------------- |
|
||
| jog-module-blog | `dto/PolishTextDTO.java` | 新增请求 DTO（`text` 字段 + `@NotBlank`） |
|
||
| jog-module-blog | `dto/PolishResultVO.java` | 新增响应 VO（含 `diffSegments` 对比数组） |
|
||
| jog-module-blog | `dto/DiffSegmentVO.java` | 新增段对比 VO（`index`、`original`、`polished`）|
|
||
| jog-module-blog | `service/TextPolishService.java` + `service/impl/TextPolishServiceImpl.java` | 新增润色服务 |
|
||
| jog-module-blog | `controller/ArticleController.java` | 新增 `POST /api/app/article/polish` |
|
||
|
||
### 5.2 前端涉及代码
|
||
|
||
| 模块 | 文件 | 变更说明 |
|
||
| :----------- | :------------------------------------ | :---------------------------------------------------- |
|
||
| jog-frontend | `src/api/article.js` | 新增 `polishArticleText(data)` |
|
||
| jog-frontend | `src/views/app/ArticleEditor.vue` | 工具栏新增"AI 润色"按钮、新增对比面板组件 |
|
||
| jog-frontend | `src/components/PolishDiffPanel.vue` | 新增对比面板组件（原文 vs 润色后，段落级采纳） |
|
||
|
||
---
|
||
|
||
## 6. 非功能性需求
|
||
|
||
| 编号 | 类型 | 需求说明 |
|
||
| :------ | :-------- | :------------------------------------------------------------------------- |
|
||
| NFR-01 | 性能 | 95 分位响应时间 ≤ 10 秒（取决于 DashScope 服务，由超时 + 限流保护） |
|
||
| NFR-02 | 可用性 | DashScope 不可用时，用户仍可手动编辑文本，业务不受阻塞 |
|
||
| NFR-03 | 安全性 | API Key 不入库、不入日志、不入仓库；前端不感知 Key 任何信息 |
|
||
| NFR-04 | 可扩展性 | 后端通过 `TextPolishService` 接口抽象，未来可扩展拼写检查等独立功能 |
|
||
| NFR-05 | 可观测性 | 关键节点输出 INFO/ERROR 日志，包含耗时、文本长度 |
|
||
|
||
---
|
||
|
||
## 7. 风险与缓解
|
||
|
||
| 风险 | 影响 | 缓解措施 |
|
||
| :---------------------------- | :---------------------------------- | :------------------------------------------------------------------ |
|
||
| 模型输出偏离原意 | 润色结果不可用 | 提示词强调"保持原意不变"；对比视图让用户逐段审核 |
|
||
| DashScope 服务限流或宕机 | 润色不可用 | 设置超时与降级，前端允许用户手动编辑 |
|
||
| 模型返回格式异常 | 对比视图渲染失败 | 后端对返回结果做段落对齐校验，失败时降级为全文对比 |
|
||
| 大量用户同时调用 | 超出 API 配额 | Redis 限流每分钟 5 次/用户 |
|
||
|
||
---
|
||
|
||
**编写人：** AI 助手
|
||
**评审人：** 待评审
|
||
**生效日期：** 2026-05-23
|