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

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

**与其它 AI 功能**：标签推荐使用 `properties.getModel()`，**不接入** 助手模型表；实施助手模型管理时 **无需改动** `TagRecommendServiceImpl`。参见《文章标签自动推荐功能需求》§6 及《AI助手模型管理功能需求》D-10。

## 前提条件

**数据安全规则**：
- 联调和测试过程中如需创建测试数据，测试完成后必须删除
- **数据库中存在一篇名为 "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 后端核心逻辑

```java
// 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 前端核心逻辑

```vue
<!-- 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 机制，避免额外开发