Jog/doc/文章标签自动推荐功能技术实施文档.md

文章标签自动推荐功能技术实施文档

前提条件

数据安全规则：

• 联调和测试过程中如需创建测试数据，测试完成后必须删除
• 数据库中存在一篇名为 "hello" 的文章，此文章不允许任何修改或删除操作

---

1. 功能概述

基于 AI 模型根据文章内容自动推荐 3-5 个合适标签，博主可一键确认添加。

2. 核心实现思路

2.1 复用现有 AI 能力

项目已有 AiSummaryService 调用阿里云 DashScope 模型的能力，标签推荐功能将完全复用该服务：

• 复用 DashScopeProperties 配置（API Key、超时、限流等）
• 复用模型调用逻辑（HTTP 请求、响应解析、错误处理）
• 复用 Rate Limit 限流机制

2.2 差异化实现

与摘要生成的主要差异：

特性	摘要生成	标签推荐
System Prompt	生成摘要的专业提示词	提取标签的专业提示词
User Prompt	标题 + 正文	标题 + 正文（需要提取标签）
响应解析	截取摘要文本	解析逗号分隔的标签列表
返回格式	SummaryResultVO	推荐标签列表

2.3 实现方案

后端：新建 TagRecommendService 服务类，复用 AiSummaryServiceImpl 的模型调用能力

前端：在文章编辑页标签区域添加推荐按钮，展示推荐标签并支持一键添加

---

3. 改动项清单

3.1 后端改动

3.1.1 新增 DTO

文件	说明
dto/RecommendTagsDTO.java	请求 DTO，包含 title、content 字段

3.1.2 新增 VO

文件	说明
dto/TagRecommendResultVO.java	返回 VO，包含 tags 列表、model、costMillis 等

3.1.3 新增服务接口

文件	说明
service/TagRecommendService.java	标签推荐服务接口

3.1.4 新增服务实现

文件	说明
service/impl/TagRecommendServiceImpl.java	复用 AiSummaryServiceImpl 的 callModel 方法，实现标签推荐逻辑

3.1.5 新增 Controller 接口

文件	说明
controller/ArticleController.java	新增 /recommend-tags POST 接口

3.1.6 错误码（如需要）

文件	说明
common/exception/ErrorCode.java	可能需要新增错误码（如 AI_CONTENT_TOO_SHORT 已存在可复用）

---

3.2 前端改动

3.2.1 新增 API 方法

文件	说明
src/api/article.js	新增 recommendTags(data) 方法

3.2.2 修改文章编辑器

文件	说明
src/views/app/ArticleEditor.vue	在标签区域添加"智能推荐"按钮及交互逻辑

---

4. 核心逻辑说明

4.1 后端核心逻辑

// TagRecommendServiceImpl.java

// 专用提示词
private static final String SYSTEM_PROMPT =
    "你是一名专业的博客编辑，请根据用户提供的标题与正文，" +
    "提取 3-5 个最合适的标签。只返回标签词，用逗号分隔，不要有其他内容。";

private static final int TAG_RECOMMEND_MIN_LENGTH = 10;

// 1. 构建请求（复用 AiSummaryServiceImpl.callModel）
Map<String, Object> requestBody = Map.of(
    "model", properties.getModel(),
    "messages", List.of(
        Map.of("role", "system", "content", SYSTEM_PROMPT),
        Map.of("role", "user", "content", buildUserPrompt(dto.getTitle(), plainContent))
    ),
    "temperature", 0.5  // 标签推荐可以稍高一些，增加多样性
);

// 2. 调用模型（复用 AiSummaryServiceImpl.callModel）
Map<String, Object> response = callModel(requestBody);

// 3. 解析响应（解析逗号分隔的标签）
List<String> tags = parseTagsFromResponse(response);

4.2 前端核心逻辑

<!-- ArticleEditor.vue 标签区域 -->
<el-form-item label="标签">
  <el-select v-model="form.tagIds" multiple ...>
    <el-option v-for="tag in tags" ... />
  </el-select>
  <!-- 新增推荐按钮 -->
  <el-button
    type="primary"
    size="small"
    :loading="recommending"
    @click="handleRecommendTags"
  >
    智能推荐
  </el-button>
</el-form-item>

<!-- 推荐结果展示 -->
<div v-if="recommendedTags.length" class="tag-recommend-result">
  <el-checkbox-group v-model="selectedRecommendedTags">
    <el-checkbox
      v-for="tag in recommendedTags"
      :key="tag"
      :label="tag"
    />
  </el-checkbox-group>
  <el-button @click="confirmAddTags">确认添加</el-button>
</div>

---

5. 待办事项

序号	待办项	状态
1	后端：创建 RecommendTagsDTO.java	✅ 已完成
2	后端：创建 TagRecommendResultVO.java	✅ 已完成
3	后端：创建 TagRecommendService 接口	✅ 已完成
4	后端：创建 TagRecommendServiceImpl 实现类	✅ 已完成
5	后端：在 ArticleController 添加 /recommend-tags 接口	✅ 已完成
6	前端：在 article.js 添加 recommendTags API 方法	✅ 已完成
7	前端：在 ArticleEditor.vue 添加智能推荐按钮和交互	✅ 已完成
8	后端：单元测试（18 个用例，P0+P1）	✅ 已完成
9	前后端联调测试（LiveIT 真实 AI 调用验证）	✅ 已完成
10	功能验收测试（API + 前端静态资源验证）	✅ 已完成

---

6. 实施顺序建议

1. 先做后端：DTO → VO → Service → Controller
2. 再做前端：API 方法 → 页面交互
3. 最后联调：前后端对接、bug 修复、验收

---

7. 风险与注意事项

1. 模型响应格式：需处理模型返回格式不稳定的情况（如多余空格、换行）
2. 标签去重：推荐标签可能与已有标签重复，需前端过滤
3. 内容过短：正文少于 10 字符时不调用 AI，直接提示用户
4. 限流复用：复用现有 Rate Limit 机制，避免额外开发