Initial setup of project files and directory structure.

2026-01-29 10:29:58 +08:00
parent b3488fa51a
commit 981b4ecf42
9 changed files with 1121 additions and 0 deletions
--- a/00-开发前后端格式.md
+++ b/00-开发前后端格式.md
@@ -0,0 +1,142 @@
+## 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 测试**:
+- 模拟真实用户操作,验证完整的业务流程
+- 测试不同浏览器的兼容性