## 00 - 开发前后端格式

### 1. 项目概述

**MangTool** 是一个基于 **Java Spring Boot + Vue 3** 的个人开发工具箱，专注于音乐库管理和日志处理两大核心模块，特点是：**开箱即用、模块化扩展、安全可靠**。

- **后端技术栈**：Spring Boot、WebSocket、异步任务、文件处理引擎（FFmpeg、Jaudiotagger、SVNKit 等）
- **前端技术栈**：Vue 3、Vite、Element Plus、组合式 API、基于组件的单页应用

### 1.1 开发环境版本

- **Node.js**：v20.19.5
- **npm**：10.8.2
- **Java**：1.8.0_472（OpenJDK 64-Bit Server VM）
- **Maven**：Apache Maven 3.8.7

### 2. 前后端整体架构

```mermaid
graph TB
    subgraph "前端 (Vue 3)"
        A[前端组件] --> B[API 封装层]
        B --> C[WebSocket 客户端]
    end

    subgraph "后端 (Spring Boot)"
        D[REST 控制器] --> E[业务服务层]
        E --> F[文件处理引擎]
        E --> G[WebSocket 服务]
        F --> H[FFmpeg 集成]
        F --> I[Jaudiotagger]
        F --> J[SVNKit]
    end

    C -- WebSocket 实时进度 --> G
    B -- HTTP REST API --> D
    F --> K[本地文件系统]
```

- **HTTP API**：前端通过 axios 封装的请求模块调用后端 REST 接口
- **WebSocket**：用于长时间批处理任务的实时进度推送
- **文件系统访问**：所有音频、日志等文件操作都集中在后端完成，前端只处理路径和参数

### 3. 项目目录结构

```text
mangtool/
├── backend/                    # Spring Boot 后端
│   ├── src/main/java/com/music/
│   │   ├── config/            # 配置类 (CORS, WebSocket, Async)
│   │   ├── controller/        # REST 控制器
│   │   ├── service/           # 业务服务层（核心逻辑）
│   │   ├── dto/               # 数据传输对象
│   │   ├── common/            # 通用工具 (Result, ErrorCode)
│   │   └── exception/         # 全局异常处理
│   └── pom.xml                # Maven 依赖配置
├── frontend/                   # Vue 3 前端
│   ├── src/
│   │   ├── components/        # 功能模块组件 (*Tab.vue)
│   │   ├── api/               # API 模块化封装
│   │   ├── composables/       # 组合式函数 (useWebSocket)
│   │   └── App.vue            # 主界面与导航
│   └── vite.config.js         # Vite 配置
└── docker/                    # 容器化部署配置
```

### 4. 统一后端返回格式

- **强制要求**：所有后端接口统一返回 `Result<T>`，禁止直接返回实体类或 `ResponseEntity`。

```java
public class Result<T> {
    private int code;      // 0=成功，非0=错误
    private String message; // 提示信息
    private T data;        // 业务数据
}
```

- **全局异常处理**：通过 `GlobalExceptionHandler` 捕获 `BusinessException`，并转换为统一的 `Result` 响应

### 5. 前端 API 调用规范

- **模块划分**：`frontend/src/api/` 下按功能拆分：`aggregate.js`, `convert.js`, `dedup.js` 等
- **统一请求实例**：所有 API 模块都通过封装好的 axios 实例 `request` 发送请求

**响应拦截器约定**：

- 后端只返回 `Result<T>` 格式
- 前端拦截器自动判断 `code`：
  - `code === 0`：直接返回 `data`
  - 其他：弹出错误信息，并返回 `Promise.reject`

### 6. WebSocket 进度推送规范

**消息结构（ProgressMessage DTO）**：

```java
public class ProgressMessage {
    private String taskId;      // 任务 ID
    private String type;        // 任务类型
    private int total;          // 总数
    private int processed;      // 已处理
    private int success;        // 成功数
    private int failed;         // 失败数
    private String currentFile; // 当前处理文件
    private String message;     // 进度消息
    private boolean completed;  // 是否完成
}
```

- **服务端**:通过 WebSocket 节流推送进度,避免频繁推送导致前端卡顿
- **前端**:统一封装 `useWebSocket` 组合式函数,在各个 Tab 组件中复用,用于展示进度条 / 当前文件 / 完成状态

### 7. 测试用例需求

#### 7.1 后端测试

**单元测试**:
- 测试统一返回格式 `Result<T>` 的构建与序列化
- 测试全局异常处理器对 `BusinessException` 的捕获与转换
- 测试 WebSocket 消息推送的节流机制
- 测试路径验证拦截器的安全规则

**集成测试**:
- 测试完整的 HTTP 请求响应流程(包含正常与异常情况)
- 测试 WebSocket 连接建立、消息推送、断开重连
- 测试 CORS 配置是否正确允许前端跨域访问

#### 7.2 前端测试

**单元测试**:
- 测试 API 响应拦截器对不同 code 值的处理逻辑
- 测试 `useWebSocket` 组合式函数的连接管理与消息接收
- 测试各个组件的参数校验与错误提示

**集成测试**:
- 测试前后端联调:完整的任务提交、进度推送、结果展示流程
- 测试异常场景:网络断开、后端服务异常、超时等情况的用户提示

**E2E 测试**:
- 模拟真实用户操作,验证完整的业务流程
- 测试不同浏览器的兼容性