LiuMangMang/music-metadata-system
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
cd716ed2af115278d07936e24c2f85e221cc77d1
music-metadata-system/docs/P6-前端界面集成-开发落地说明.md

6.3 KiB
Raw Blame History

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 使用了以下命令：

前端基础验证

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。

前端功能与全量验证

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

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

前端构建验证

cd frontend && npm install && npm run build

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

后端 /app/** 托管验证

mvn test -Dtest=WebAppControllerTest

结果：通过，12 个 tests。

前端构建集成验证

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

Reference in New Issue View Git Blame Copy Permalink