docs: add P0 and P1 delivery notes

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

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

docs/P1-元数据解析与校验-开发落地说明.md

@@ -0,0 +1,259 @@
+# P1 元数据解析与校验开发落地说明
+
+## 1. 阶段定位
+
+P1 阶段聚焦“元数据解析与校验”核心能力落地，并同步补齐目录扫描、一级去重、二级疑似去重、断点续传、已归档跳过等与验收直接相关的基础处理流程。
+
+该阶段的核心目标是：系统能够读取音频文件元数据、生成原始快照、执行一票否决制校验，并用测试证明关键规则与真实文件读取能力已经落地。
+
+## 2. 阶段目标
+
+- 集成 Jaudiotagger，支持主流音频格式元数据读取
+- 集成 juniversalchardet，完成编码检测与乱码修复尝试
+- 实现 `MetadataReaderService`，读取标签、封面、编码并生成原始快照
+- 实现 `MetadataValidatorService`，执行核心字段一票否决校验与清洗规则
+- 建立 `t_metadata_snapshot` 快照存储能力
+- 为目录扫描、去重、断点续传提供落地实现与验收测试
+- 使测试覆盖率达到 80% 以上
+
+## 3. 技术落地概览
+
+### 3.1 依赖集成
+
+P1 阶段在 `music-metadata-system/pom.xml` 中新增：
+
+- `net.jthink:jaudiotagger:2.2.5`
+- `com.github.albfernandez:juniversalchardet:2.4.0`
+- `org.jacoco:jacoco-maven-plugin:0.8.12`
+
+说明：原始需求写的是 Jaudiotagger `2.2.7`，但实际 Maven 可解析并完成落地验证的版本为 `2.2.5`。当前功能已覆盖 MP3/FLAC/M4A/OGG/WAV 的读取需求，故以可稳定构建的版本为准。
+
+### 3.2 领域模型与接口
+
+新增元数据领域对象：
+
+- `music-metadata-system/src/main/java/com/music/metadata/domain/metadata/AudioMetadata.java`
+- `music-metadata-system/src/main/java/com/music/metadata/domain/metadata/CoverMetadata.java`
+- `music-metadata-system/src/main/java/com/music/metadata/domain/metadata/MetadataValidationResult.java`
+- `music-metadata-system/src/main/java/com/music/metadata/domain/metadata/ValidationFailure.java`
+- `music-metadata-system/src/main/java/com/music/metadata/domain/metadata/ValidationFailureType.java`
+
+新增核心服务接口：
+
+- `music-metadata-system/src/main/java/com/music/metadata/service/MetadataReaderService.java`
+- `music-metadata-system/src/main/java/com/music/metadata/service/MetadataValidatorService.java`
+- `music-metadata-system/src/main/java/com/music/metadata/service/MetadataSnapshotService.java`
+
+### 3.3 读取层实现
+
+读取相关实现由两层组成：
+
+1. `JaudiotaggerAudioTagExtractor`
+   - 负责调用 Jaudiotagger 读取底层标签与封面信息
+   - 读取核心字段：`title`、`artist`、`album_artist`、`album`、`track`、`year`、`genre`、`lyrics`、`disc`、`comment`
+   - 汇总全部可枚举标签字段到 `fields`
+   - 针对真实 FLAC 文件上 artwork/特殊字段抛异常的情况做了“尽力而为”兼容处理，避免整个读取流程失败
+
+2. `MetadataReaderServiceImpl`
+   - 将提取结果组装成 `AudioMetadata`
+   - 自动识别文件格式
+   - 检测原始编码并尝试对 GBK/GB18030 类乱码做修复
+   - 解析封面格式、尺寸、二进制数据
+   - 生成原始元数据 JSON 快照
+   - 将快照持久化到 `t_metadata_snapshot`
+
+关键文件：
+
+- `music-metadata-system/src/main/java/com/music/metadata/infrastructure/audio/AudioTagExtractor.java`
+- `music-metadata-system/src/main/java/com/music/metadata/infrastructure/audio/AudioTagExtractionResult.java`
+- `music-metadata-system/src/main/java/com/music/metadata/infrastructure/audio/JaudiotaggerAudioTagExtractor.java`
+- `music-metadata-system/src/main/java/com/music/metadata/service/impl/MetadataReaderServiceImpl.java`
+
+### 3.4 一票否决校验实现
+
+`MetadataValidatorServiceImpl` 实现了严格的一票否决制：
+
+- 编码非 UTF-8 且修复失败，立即返回 `ENCODING_ERROR`
+- 核心字段按顺序校验：
+  - `title`
+  - `artist`
+  - `album_artist`
+  - `album`
+  - `track`
+  - `cover`
+- 任一字段缺失、乱码或不合规，立即返回失败，不继续后续字段校验
+
+已落地规则包括：
+
+- 强制 UTF-8 编码门禁
+- `track` 必须为 `序号/总曲目数` 格式，例如 `01/12`
+- 封面必须存在，且格式为 JPG/PNG，分辨率不小于 `300x300`，比例必须 `1:1`
+- 清洗规则涵盖：
+  - 首尾空白与不可见字符处理
+  - 非法文件名字符替换
+  - 多歌手分隔符统一
+  - 英文字段大小写规范化
+  - 版本信息从 `title` 向 `comment` 迁移
+
+关键文件：
+
+- `music-metadata-system/src/main/java/com/music/metadata/service/impl/MetadataValidatorServiceImpl.java`
+
+### 3.5 元数据快照存储
+
+新增快照实体与持久化层：
+
+- `music-metadata-system/src/main/java/com/music/metadata/infrastructure/entity/MetadataSnapshotEntity.java`
+- `music-metadata-system/src/main/java/com/music/metadata/infrastructure/mapper/MetadataSnapshotMapper.java`
+- `music-metadata-system/src/main/java/com/music/metadata/service/impl/MetadataSnapshotServiceImpl.java`
+
+数据库脚本新增：
+
+- `t_metadata_snapshot`
+
+对应位置：
+
+- `music-metadata-system/src/main/resources/schema.sql`
+
+## 4. 同阶段补充完成的扫描与去重能力
+
+虽然本次文档主题是“元数据解析与校验”，但当前 P1 代码实际还同时落地了与目录扫描相关的验收能力：
+
+- 目录递归扫描
+- 一级哈希去重（`HASH_DUPLICATE`）
+- 二级特征疑似重复（`LEVEL2_SUSPECT`）
+- 扫描断点续传
+- 已归档文件再次扫描时自动跳过
+
+相关代码：
+
+- `music-metadata-system/src/main/java/com/music/metadata/service/impl/DirectoryScanServiceImpl.java`
+- `music-metadata-system/src/main/java/com/music/metadata/service/impl/ScanFileProcessorImpl.java`
+- `music-metadata-system/src/main/java/com/music/metadata/service/impl/DeduplicationServiceImpl.java`
+- `music-metadata-system/src/main/java/com/music/metadata/service/impl/Sha256FileHashServiceImpl.java`
+- `music-metadata-system/src/main/java/com/music/metadata/service/impl/JaudiotaggerAudioDurationServiceImpl.java`
+
+数据库脚本同步新增：
+
+- `t_duplicate_file`
+- `t_scan_item`
+- `t_file_process.dedup_key`
+
+## 5. 测试策略
+
+P1 阶段测试分为三层：
+
+### 5.1 纯单元测试
+
+用于验证 reader、validator 的规则与边界行为：
+
+- `music-metadata-system/src/test/java/com/music/metadata/service/impl/MetadataReaderServiceImplTest.java`
+- `music-metadata-system/src/test/java/com/music/metadata/service/impl/MetadataValidatorServiceImplTest.java`
+
+### 5.2 验收测试
+
+用于直接对应本阶段验收标准：
+
+- `music-metadata-system/src/test/java/com/music/metadata/service/impl/MetadataAcceptanceTest.java`
+
+覆盖内容：
+
+- 能正确读取测试音频文件元数据
+- 缺失 `title` 返回 `MISSING_FIELD`
+- GBK 中文标签修复成功或返回 `ENCODING_ERROR`
+- 无封面返回 `COVER_INVALID`
+
+### 5.3 真实音频集成测试
+
+为满足“真实数据验证”口径，额外新增：
+
+- `music-metadata-system/src/test/java/com/music/metadata/service/impl/RealAudioMetadataIntegrationTest.java`
+
+该测试会：
+
+- 从真实目录 `/home/liujingjing/下载/解压后2` 中选取 FLAC 文件
+- 复制到临时目录，避免污染原始音乐库
+- 直接使用 `JaudiotaggerAudioTagExtractor` 读取真实文件
+- 校验 `fileFormat`、`title`、`artist`、`album`、`snapshotJson`、`tagFields`、封面二进制与尺寸
+
+如果需要切换目录，也可通过环境变量 `REAL_AUDIO_DIR` 覆盖默认路径。
+
+### 5.4 覆盖率补强测试
+
+为满足覆盖率要求，补充了基础设施与低覆盖类测试：
+
+- `music-metadata-system/src/test/java/com/music/metadata/service/impl/CoverageSupportTest.java`
+- `music-metadata-system/src/test/java/com/music/metadata/service/impl/SimpleServiceImplCoverageTest.java`
+- `music-metadata-system/src/test/java/com/music/metadata/service/impl/JaudiotaggerAudioDurationServiceImplTest.java`
+
+### 5.5 测试资源说明
+
+当前仓库未直接提交真实音频二进制测试资源，而是采用两种方式：
+
+- 单元测试中使用 `byte[]` 与 mock extractor 快速构造边界场景
+- 在文档中说明真实 fixtures 的构造方式
+
+说明文件：
+
+- `music-metadata-system/src/test/resources/audio-fixtures/README.md`
+
+## 6. 验收结果
+
+### 6.1 P1 核心验收项
+
+| 验收项 | 结果 | 说明 |
+|--------|------|------|
+| 能正确读取测试音频文件的元数据 | 通过 | `RealAudioMetadataIntegrationTest` 直接读取真实 FLAC 文件通过 |
+| 缺失 `title` 字段返回 `MISSING_FIELD` | 通过 | `MetadataAcceptanceTest` 已覆盖 |
+| GBK 编码中文标签修复失败返回 `ENCODING_ERROR` | 通过 | `MetadataAcceptanceTest` 已覆盖“修复或失败”路径 |
+| 无封面文件返回 `COVER_INVALID` | 通过 | `MetadataAcceptanceTest` 已覆盖 |
+| 单元测试覆盖率 ≥ 80% | 通过 | 当前 JaCoCo 行覆盖率为 `88.60%` |
+
+### 6.2 目录扫描附加验收项
+
+| 验收项 | 结果 | 说明 |
+|--------|------|------|
+| 一级哈希去重 | 通过 | `DirectoryScanP1AcceptanceTest` 已覆盖 |
+| 二级疑似重复识别 | 通过 | `DirectoryScanP1AcceptanceTest` 已覆盖 |
+| 扫描中断后断点续传 | 通过 | `DirectoryScanP1AcceptanceTest` 已覆盖 1000 文件场景 |
+| 已归档文件再次扫描时跳过 | 通过 | `DirectoryScanP1AcceptanceTest` 已覆盖 |
+
+## 7. 验证命令
+
+推荐使用以下命令复验：
+
+```bash
+cd music-metadata-system
+mvn test
+```
+
+针对元数据与真实文件验证，也可执行：
+
+```bash
+mvn -q -Dtest=RealAudioMetadataIntegrationTest,MetadataAcceptanceTest,MetadataReaderServiceImplTest,MetadataValidatorServiceImplTest test
+```
+
+覆盖率报告输出位置：
+
+- `music-metadata-system/target/site/jacoco/index.html`
+- `music-metadata-system/target/site/jacoco/jacoco.csv`
+
+## 8. 偏差与说明
+
+### 8.1 Jaudiotagger 版本偏差
+
+需求中写明 `2.2.7`，但实际可解析并完成稳定构建、测试通过的版本为 `2.2.5`。当前以 `2.2.5` 落地，后续如必须升级，可再做版本可用性验证。
+
+### 8.2 编码修复策略说明
+
+编码检测与乱码修复采用 `juniversalchardet + 启发式修复` 组合策略。对于疑似 GBK/GB18030 的中文乱码，会尝试修复；修复失败时，严格返回 `ENCODING_ERROR`。
+
+### 8.3 真实数据与严格校验的关系
+
+真实音频集成测试当前验证的是“能读出来”，而不是“真实目录中的所有文件都能通过 validator”。这是因为真实库中的部分文件可能存在 `album_artist` 缺失、`track` 不为 `01/12` 等情况，属于数据质量问题，不代表读取能力失败。
+
+## 9. 阶段结论
+
+P1 阶段已经完成元数据读取、快照持久化、一票否决校验、编码检测与清洗规则的核心落地，并通过真实音频集成测试、验收测试和覆盖率报告证明当前能力可用。
+
+在此基础上，项目已经具备继续进入后续归档、失败文件人工兜底、权威 API 补全等更高层业务能力开发的条件。