221 lines
6.3 KiB
Markdown
221 lines
6.3 KiB
Markdown
# 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 与后续优化项，不影响本阶段交付范围内的实现与构建验证结果。
|