# P6 前端界面集成开发落地说明

## 概述

P6 已完成基于 Vue 3 + Vite + Element Plus + Pinia + Vue Router 的前端控制台落地，并接入现有 Spring Boot 工程的 `/app/` 静态资源托管链路。

本阶段实际交付聚焦：

- 独立 `frontend/` 前端工程
- 仪表盘、任务管理、文件上传、失败文件、元数据编辑、系统配置 6 个页面
- Axios 封装、Pinia 全局状态、前端 API 路径适配
- Spring Boot `/app/**` SPA 托管与真实构建产物集成

本阶段未纳入实现：

- GraalVM Native Image 真正适配与交付
- 真实登录/鉴权流程
- 独立日志页面

## 实现清单

### 前端工程与基础设施

- 新增 `frontend/package.json`
- 新增 `frontend/vite.config.ts`
- 新增 `frontend/src/main.ts`
- 新增 `frontend/src/router/index.ts`
- 新增 `frontend/src/router/routes.ts`
- 新增 `frontend/src/layouts/AppLayout.vue`
- 新增 `frontend/src/stores/user.ts`
- 新增 `frontend/src/stores/config.ts`
- 新增 `frontend/src/stores/app.ts`
- 新增 `frontend/src/api/request.ts`
- 新增 `frontend/src/api/modules/task.ts`
- 新增 `frontend/src/api/modules/failFile.ts`
- 新增 `frontend/src/api/modules/config.ts`
- 新增 `frontend/src/api/modules/log.ts`
- 新增 `frontend/src/api/modules/upload.ts`

### 页面与组件

- 仪表盘：`frontend/src/views/DashboardView.vue`
- 任务管理：`frontend/src/views/TaskManagementView.vue`
- 文件上传：`frontend/src/views/FileUploadView.vue`
- 失败文件：`frontend/src/views/FailFileView.vue`
- 元数据编辑：`frontend/src/views/MetadataEditorView.vue`
- 系统配置：`frontend/src/views/SystemConfigView.vue`

核心页面组件已落地到以下目录：

- `frontend/src/components/dashboard/`
- `frontend/src/components/task/`
- `frontend/src/components/upload/`
- `frontend/src/components/fail-file/`
- `frontend/src/components/metadata/`
- `frontend/src/components/config/`
- `frontend/src/components/common/`

### 后端集成

- 新增 `src/main/java/com/music/metadata/controller/WebAppController.java`
- 新增 `src/test/java/com/music/metadata/controller/WebAppControllerTest.java`
- `pom.xml` 新增 `frontend-build` profile
- 真实前端产物复制到 `src/main/resources/static/app/`

## 页面说明

### 1. 仪表盘

- 展示待处理任务数、已归档文件数、失败文件数
- 最近任务按创建时间倒序展示
- 使用 ECharts 展示处理分布图
- 提供到任务、上传、失败文件、系统配置的快捷入口

### 2. 任务管理

- 支持分页、状态筛选、进度展示
- 支持暂停、继续、终止
- 任务详情通过 Element Plus `Drawer` 展示
- 报告查看通过 Element Plus `Dialog` 展示
- 支持 CSV / JSON 导出

### 3. 文件上传

- 页面使用 `simple-uploader.js` 核心实例进行 Vue 3 下的分片队列接入
- 保留 `identifier`、`chunkNumber`、`totalChunks`、`filename`、`totalSize` 上传契约
- 支持自动创建任务开关
- 合并返回 `sourcePath` 时自动建任务，否则保留手动创建回退
- 自动建任务失败后保留已合并状态

说明：

- `vue-simple-uploader@0.7.6` 为 Vue 2 wrapper，无法直接接入当前 Vue 3.4
- 最终采用其底层依赖 `simple-uploader.js` 进行 Vue 3 可运行集成

### 4. 失败文件

- 支持 keyword / failType / status 筛选
- 支持分页
- 支持批量重处理，前端循环调用单条提交接口
- 可跳转到元数据编辑页，并在处理后恢复列表上下文

### 5. 元数据编辑

- 加载失败文件详情
- 支持标题、艺术家、专辑、流派、歌词编辑
- 支持封面上传输入与占位预览
- 支持草稿保存和提交重处理
- 缺少媒体 URL 时按占位状态展示

### 6. 系统配置

- 配置按分组展示
- 敏感值默认掩码展示，可切换编辑
- 目录型配置提供路径建议和绝对路径提示
- 保存后刷新 Pinia 配置缓存

## API 映射

前端按真实后端路径适配，页面层不感知差异。

### 任务接口

- `POST /api/tasks/create`
- `GET /api/tasks/list`
- `GET /api/tasks/{taskId}`
- `POST /api/tasks/{taskId}/pause`
- `POST /api/tasks/{taskId}/resume`
- `POST /api/tasks/{taskId}/terminate`
- `GET /api/tasks/{taskId}/report`
- `GET /api/tasks/{taskId}/report/csv`
- `GET /api/tasks/{taskId}/report/json`

### 失败文件接口

- `GET /api/v1/fail-file/list`
- `GET /api/v1/fail-file/{id}/detail`
- `PUT /api/v1/fail-file/{id}/edit`
- `POST /api/v1/fail-file/{id}/submit`

### 系统配置接口

- `GET /api/configs/list`
- `GET /api/configs/{configKey}`
- `PUT /api/configs/update`
- `PUT /api/configs/batch-update`

### 日志接口

- `POST /api/logs/query`
- `POST /api/logs/export`

### 上传接口

- `POST /api/v1/file/upload`
- `POST /api/v1/file/upload/merge`

## 验证命令

本阶段 fresh verification 使用了以下命令：

### 前端基础验证

```bash
cd frontend && npm install && npm run test -- --run src/tests/scaffold.spec.ts src/tests/router.spec.ts src/tests/config-store.spec.ts src/tests/request.spec.ts src/tests/task-utils.spec.ts src/tests/layout-shell.spec.ts
```

结果：通过，`6` 个 test files，`19` 个 tests。

### 前端功能与全量验证

```bash
cd frontend && npm install && npm run test -- --run
```

结果：通过，`8` 个 test files，`28` 个 tests。

### 前端构建验证

```bash
cd frontend && npm install && npm run build
```

结果：通过，生成 `dist/index.html` 与 `dist/assets/*`。

### 后端 `/app/**` 托管验证

```bash
mvn test -Dtest=WebAppControllerTest
```

结果：通过，`12` 个 tests。

### 前端构建集成验证

```bash
mvn -Pfrontend-build process-resources
```

结果：通过，可将 `frontend/dist` 复制到 `src/main/resources/static/app/`。

## 暂缓项

- GraalVM Native Image 真实可运行镜像交付
- 真实登录与 token 鉴权流程
- 独立日志管理页面
- 前端大包拆分优化
- 测试 warning 清理（Vue Router warning、Testing Library `fireEvent.change` warning）

## 验收结论

P6 当前已完成前端工程、核心页面、Spring Boot 静态资源托管、前端构建接入与基础验证链路。

基于 fresh verification：

- 前端全量测试通过（`28/28`）
- 前端构建通过
- 后端 `/app/**` 托管测试通过（`12/12`）

当前剩余问题主要为 warning 与后续优化项，不影响本阶段交付范围内的实现与构建验证结果。