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