117 lines
4.4 KiB
Markdown
117 lines
4.4 KiB
Markdown
# P0 基础架构开发落地说明
|
||
|
||
## 1. 阶段定位
|
||
|
||
P0 阶段的目标是完成后端基础工程、数据库底座、统一异常与响应规范建设，形成一个可编译、可启动、可落盘、可继续承接后续 P1/P2 业务开发的项目骨架。
|
||
|
||
本阶段不追求业务闭环，而是为后续目录扫描、元数据解析、失败文件管理、归档等能力提供稳定的运行基础。
|
||
|
||
## 2. 阶段目标
|
||
|
||
- 搭建基于 Spring Boot 3.2.6 + Java 21 的后端工程
|
||
- 集成 MyBatis-Plus 与 H2，完成单机可运行的数据存储底座
|
||
- 完成核心基础表 DDL、Entity、Mapper、Service、ServiceImpl
|
||
- 建立统一响应结构与全局异常处理机制
|
||
- 预留 GraalVM Native Image 编译能力
|
||
|
||
## 3. 已完成内容
|
||
|
||
### 3.1 工程骨架
|
||
|
||
- 已创建 Maven 项目 `music-metadata-system`
|
||
- 已接入 `spring-boot-starter-web`
|
||
- 已配置 `@SpringBootApplication` 与 `@MapperScan`
|
||
- 项目启动入口：`music-metadata-system/src/main/java/com/music/metadata/MusicMetadataSystemApplication.java`
|
||
|
||
### 3.2 数据库与配置基线
|
||
|
||
- 已集成 H2 `2.2.224`
|
||
- 已采用文件模式数据库：`jdbc:h2:file:./data/music_metadata_db`
|
||
- 启动后可在本地生成数据库文件，满足单机部署要求
|
||
- 已配置 H2 Console、SQL 初始化、MyBatis-Plus 驼峰映射与主键策略
|
||
|
||
关键配置文件：
|
||
|
||
- `music-metadata-system/src/main/resources/application.yml`
|
||
- `music-metadata-system/src/main/resources/schema.sql`
|
||
|
||
### 3.3 基础表落地
|
||
|
||
P0 阶段已完成 4 张基础核心表：
|
||
|
||
- `t_process_task`：处理任务主表
|
||
- `t_file_process`：文件处理记录表
|
||
- `t_fail_file`：失败文件记录表
|
||
- `t_system_config`：系统配置表
|
||
|
||
这些表已经在 `music-metadata-system/src/main/resources/schema.sql` 中以初始化 DDL 形式落地。
|
||
|
||
### 3.4 持久化层建设
|
||
|
||
已为 P0 阶段 4 张基础表建立完整的持久化访问层，包括：
|
||
|
||
- Entity
|
||
- Mapper
|
||
- Service 接口
|
||
- ServiceImpl 实现
|
||
|
||
对应代码位于：
|
||
|
||
- `music-metadata-system/src/main/java/com/music/metadata/infrastructure/entity/`
|
||
- `music-metadata-system/src/main/java/com/music/metadata/infrastructure/mapper/`
|
||
- `music-metadata-system/src/main/java/com/music/metadata/service/`
|
||
- `music-metadata-system/src/main/java/com/music/metadata/service/impl/`
|
||
|
||
### 3.5 统一响应与异常处理
|
||
|
||
已完成接口层基础治理能力，为后续 Controller 与前后端联调做准备：
|
||
|
||
- 统一返回结构：`ApiResponse<T>`
|
||
- 业务异常类型：`BusinessException`
|
||
- 全局异常处理：`GlobalExceptionHandler`
|
||
|
||
关键文件：
|
||
|
||
- `music-metadata-system/src/main/java/com/music/metadata/common/api/ApiResponse.java`
|
||
- `music-metadata-system/src/main/java/com/music/metadata/common/exception/BusinessException.java`
|
||
- `music-metadata-system/src/main/java/com/music/metadata/common/handler/GlobalExceptionHandler.java`
|
||
|
||
### 3.6 原生编译基础能力
|
||
|
||
- 已引入 `org.graalvm.buildtools:native-maven-plugin`
|
||
- 当前已具备后续 GraalVM Native Image 适配与扩展基础
|
||
- P0 阶段只完成插件接入，不包含完整 native 兼容性治理
|
||
|
||
## 4. 关键交付物
|
||
|
||
- 后端项目目录：`music-metadata-system/`
|
||
- 核心构建文件：`music-metadata-system/pom.xml`
|
||
- 配置文件：`music-metadata-system/src/main/resources/application.yml`
|
||
- 初始化脚本：`music-metadata-system/src/main/resources/schema.sql`
|
||
- 启动入口：`music-metadata-system/src/main/java/com/music/metadata/MusicMetadataSystemApplication.java`
|
||
- 通用 API 与异常处理：`music-metadata-system/src/main/java/com/music/metadata/common/`
|
||
|
||
## 5. 验收结果
|
||
|
||
P0 阶段已完成并通过验收，结果如下：
|
||
|
||
| 验收项 | 结果 | 说明 |
|
||
|--------|------|------|
|
||
| `mvn clean compile` 编译通过 | 通过 | 项目具备可编译性 |
|
||
| `mvn spring-boot:run` 能正常启动 | 通过 | Spring Boot 服务可启动 |
|
||
| H2 数据库文件能在本地生成 | 通过 | 可生成 `data/music_metadata_db.mv.db` |
|
||
| 不引入业务流程代码 | 通过 | P0 保持基础设施就绪定位 |
|
||
|
||
## 6. 阶段边界
|
||
|
||
为保持 P0 聚焦，本阶段未包含以下内容：
|
||
|
||
- 未生成业务 Controller
|
||
- 未实现目录扫描、元数据解析、校验、归档等业务流程
|
||
- 未实现前端页面与接口联调
|
||
- 未实现音频元数据读写与测试资源建设
|
||
|
||
## 7. 阶段结论
|
||
|
||
P0 阶段已经完成“基础设施就绪”的目标，项目具备继续承接业务开发的能力。P1 可以在此基础上直接进入元数据解析、校验、快照存储与扫描去重能力建设。
|