feat(data): 增强 ABC 解析器以支持时间单位配置和元数据冗余存储

- 在 SNMusicProps 中新增 timeUnit 属性，用于统一音符、休止符、歌词等在时间序列上的位置对齐
- 引入 SNTimeUnit 接口，定义基本时间单位和每拍的时值
- 更新 SNSectionMeta 接口，支持冗余存储的通用信息（如标题、创作者）和 ABC 特有字段
- 在 AbcParser 中实现 noteLength 到 SNTimeUnit 的转换，确保布局计算的准确性
- 改进 parseSectionHeader 方法，支持从 ABC 格式提取并存储时间单位信息

该变更提升了 ABC 解析器的灵活性和兼容性，为多记谱法支持奠定基础。

Author: Encaik

packages/simple-notation/src/core/model/base.ts

@@ -39,6 +39,13 @@ export interface SNPitch {
   accidental: SNAccidental;
 }
 
+/**
+ * 持续时间（以基本时间单位为单位的数值）
+ * 例如：如果 baseTimeUnit = 1/32，则：
+ *   - 全音符 = 32 个单位
+ *   - 四分音符 = 8 个单位
+ *   - 八分音符 = 4 个单位
+ */
 export type SNDuration = number;
 
 export enum SNAccidental {
@@ -49,6 +56,32 @@ export enum SNAccidental {
   DOUBLE_FLAT = 'doubleFlat',
 }
 
+/**
+ * 时间单位配置
+ * 用于定义基本时间单位，统一不同记谱法的时间对齐计算
+ */
+export interface SNTimeUnit {
+  /**
+   * 基本时间单位（相对于全音符的比例）
+   * 例如：
+   *   - 1/32: 将全音符分为 32 个单位，最小精度为三十二分音符
+   *   - 1/64: 将全音符分为 64 个单位，最小精度为六十四分音符
+   *   - 1/96: 将全音符分为 96 个单位（支持三连音的精确对齐）
+   *
+   * 所有音符、休止符、歌词等的 duration 都用这个单位表示
+   */
+  baseUnit: number; // 例如：1/32, 1/64, 1/96
+
+  /**
+   * 每拍的时值（相对于全音符的比例）
+   * 由拍号的 denominator 决定，用于将时间单位转换为拍数
+   * 例如：
+   *   - 4/4 拍：beatUnit = 1/4（一拍是四分音符）
+   *   - 3/8 拍：beatUnit = 1/8（一拍是八分音符）
+   */
+  beatUnit?: number; // 自动根据 timeSignature 计算，也可以手动设置
+}
+
 /**
  * 音乐属性（所有层级都可能有的，参与布局渲染）
  * score、section、measure 等层级都可能有这些属性
@@ -57,6 +90,11 @@ export interface SNMusicProps {
   timeSignature?: SNTimeSignature; // 拍号（如 4/4）
   keySignature?: SNKeySignature; // 调号（如 C大调）
   tempo?: SNTempo; // 速度（如 120 BPM）
+  /**
+   * 时间单位配置（通用方案）
+   * 用于确定最小时间单位，计算音符、休止符、歌词等在时间序列上的位置对齐
+   */
+  timeUnit?: SNTimeUnit;
 }
 
 /**

packages/simple-notation/src/data/model/abc.ts

@@ -26,7 +26,8 @@ export interface SNRootMeta {
  *    - meta 中：数据层追溯来源，知道这些字段来自 ABC 的 T:、C: 等字段
  *
  * 2. ABC 特有的元数据仅存储在 meta 中（不参与布局渲染）：
- *    - origin, area, notes, copyright, noteLength 等
+ *    - origin, area, notes, copyright 等
+ *    - noteLength（冗余存储，用于追溯 ABC 来源，同时在 props 中用于布局计算）
  *
  * 根据 ABC 标准 v2.1
  * @see https://abcnotation.com/wiki/abc:standard:v2.1
@@ -47,8 +48,38 @@ export interface SNScoreMeta {
   notes?: string;
   /** 版权信息（S: 字段在头部时）- ABC 特有 */
   copyright?: string;
-  /** 默认音符长度（L: 字段，如 "1/4", "1/8"）- ABC 特有 */
+  /** 默认音符长度（L: 字段，如 "1/4", "1/8"）- ABC 特有，存储在 meta 中以便追溯来源，已转换为 timeUnit 存储在 props 中 */
   noteLength?: string;
   /** 其他 ABC 特有的字段（H:, G:, R:, Z:, D:, F:, B: 等） */
   [key: string]: unknown;
 }
+
+/**
+ * Section 级别的元数据（ABC 特有的 section 元数据）
+ *
+ * 设计理念：支持冗余存储（与 Score 层一致）
+ * 1. 通用布局渲染信息（title, subtitle, contributors）同时存储在：
+ *    - props 中：布局层统一访问，不关心具体记谱法格式
+ *    - meta 中：数据层追溯来源，知道这些字段来自 ABC 的 T:、C: 等字段
+ *
+ * 2. ABC 特有的元数据仅存储在 meta 中（不参与布局渲染）：
+ *    - 其他 ABC 特有字段
+ *
+ * 根据 ABC 标准 v2.1，Section 可以有自己的标题、拍号、调号、速度等
+ * @see https://abcnotation.com/wiki/abc:standard:v2.1
+ */
+export interface SNSectionMeta {
+  /** 标题（T: 字段）- ABC 特有，冗余存储在 meta 中以便追溯来源 */
+  title?: string;
+  /** 副标题（第二个 T: 字段）- ABC 特有，冗余存储在 meta 中以便追溯来源 */
+  subtitle?: string;
+  /** 创作者列表（C: 字段）- ABC 特有，冗余存储在 meta 中以便追溯来源 */
+  contributors?: Array<{ name: string; role?: string }>;
+
+  /** 默认音符长度（L: 字段，如 "1/4", "1/8"）- ABC 特有 */
+  noteLength?: string;
+  /** Section 标识符（S: 字段的值）- ABC 特有 */
+  sectionId?: string;
+  /** 其他 ABC 特有的字段 */
+  [key: string]: unknown;
+}

packages/simple-notation/src/data/node/measure.ts

@@ -9,6 +9,7 @@ import { SNParserNode } from '@data/node';
  *    - timeSignature（拍号，小节内可能有变化）
  *    - keySignature（调号，小节内可能有转调）
  *    - tempo（速度，小节内可能有速度变化）
+ *    - timeUnit（时间单位配置，通用方案，用于确定音符、休止符、歌词等在时间序列上的位置对齐）
  *
  * 注意：Measure 只使用 SNMusicProps（不包含 title, subtitle, contributors），
  *       因为这些元信息只在 score/section 层级存在

packages/simple-notation/src/data/node/score.ts

@@ -10,6 +10,7 @@ import type { SNScoreMeta } from '@data/model/abc';
  *      - timeSignature（拍号）
  *      - keySignature（调号）
  *      - tempo（速度）
+ *      - timeUnit（时间单位配置，通用方案，用于确定音符、休止符、歌词等在时间序列上的位置对齐）
  *    - 元信息属性（只在 score/section 层级有）：
  *      - title, subtitle（标题、副标题）
  *      - contributors（创作者信息）
@@ -21,7 +22,7 @@ import type { SNScoreMeta } from '@data/model/abc';
  *      - origin, area（来源、地区）
  *      - notes（注释）
  *      - copyright（版权）
- *      - noteLength（默认音符长度）
+ *      - noteLength（ABC 特有的 L: 字段，冗余存储在 meta 中以便追溯来源，已转换为 timeUnit 存储在 props 中）
  *      - 其他 ABC 特有字段
  *
  * 设计理念：

packages/simple-notation/src/data/node/section.ts

@@ -1,19 +1,35 @@
-import { SNParserMeta } from '@data/model';
 import { SNParserNode } from '@data/node';
+import type { SNSectionMeta } from '@data/model/abc';
 
 /**
  * Section（篇章）节点
  *
- * 数据分类：
+ * 数据分类（支持冗余存储）：
  * 1. 通用布局渲染信息 → 存放在 props 中（类型：SNScoreProps）
- *    - 音乐属性（timeSignature, keySignature, tempo）
- *    - 元信息属性（title, subtitle, contributors）
+ *    - 音乐属性（所有层级都可能有）：
+ *      - timeSignature（拍号）
+ *      - keySignature（调号）
+ *      - tempo（速度）
+ *      - timeUnit（时间单位配置，通用方案，用于确定音符、休止符、歌词等在时间序列上的位置对齐）
+ *    - 元信息属性（只在 score/section 层级有）：
+ *      - title, subtitle（标题、副标题）
+ *      - contributors（创作者信息）
  *
- * 2. ABC 特有的元数据 → 存放在 meta 中
+ * 2. ABC 特有的元数据 → 存放在 meta 中（类型：SNSectionMeta）
+ *    - 冗余存储的通用信息（同时也在 props 中）：
+ *      - title, subtitle, contributors（用于追溯 ABC 来源）
+ *    - ABC 特有的元数据（仅存在 meta 中）：
+ *      - noteLength（默认音符长度）
+ *      - sectionId（S: 字段的值）
+ *      - 其他 ABC 特有字段
+ *
+ * 设计理念：
+ * - props：布局层统一访问，不关心具体记谱法格式
+ * - meta：数据层追溯来源，知道字段来自 ABC 的哪个字段（T:, M:, K: 等）
  *
  * 注意：Section 可以有自己的标题和音乐属性（如转调），继承或覆盖 Score 的设置
  */
-export class SNParserSection extends SNParserNode<SNParserMeta> {
+export class SNParserSection extends SNParserNode<SNSectionMeta> {
   constructor({ id, originStr }: Pick<SNParserNode, 'id' | 'originStr'>) {
     super({ id, originStr, type: 'section' });
   }