nojava/Jog

Files

T

2026-05-24 00:39:10 +08:00

22 KiB

Raw Permalink Blame History

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：你是一名专业的文字编辑，请润色用户提供的中文文本。修正语法错误、优化表达方式、规范标点符号，保持原意不变，使文本更流畅专业。直接输出润色后的文本，不要添加任何解释或标记。 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 响应数据结构

{
  "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 次/用户

8. 与其它 AI 功能的关系

本功能所用模型由配置项 dashscope.model（环境变量 DASHSCOPE_MODEL，默认 qwen-turbo）指定，经 DashScopeProperties 注入润色接口，不使用《AI助手模型管理功能需求》中的 ai_assistant_model 表。助手侧模型的新增、禁用、用户选模 不影响 润色行为。

与 文章标签自动推荐、文章摘要 同属编辑器 / 写作类一次性调用，共用 API Key 与底层 callModel 能力，限流 key 与 AI 助手对话 相互独立。若需全站统一按模型管理额度，属后续迭代（见助手模型需求 §7「其它 AI 功能共用模型表」），不在润色本期范围。

编写人： AI 助手
评审人： 待评审
生效日期： 2026-05-23

22 KiB Raw Permalink Blame History Unescape Escape