music-metadata-system/docs/P0-基础架构-开发落地说明.md

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 可以在此基础上直接进入元数据解析、校验、快照存储与扫描去重能力建设。