feat: add P6 frontend console integration

docs/P6-前端界面集成-开发落地说明.md

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