feat(parser): 重构 ABC 解析器以优化解析逻辑和增强可维护性

- 移除冗余的解析函数，简化 AbcParser 的结构，提升代码的清晰度。
- 引入专门的解析器（AbcHeaderParser, AbcMeasureParser, AbcLyricParser）以分离不同解析逻辑，增强模块化。
- 更新 parseRoot 和 parseScore 方法，确保文件头和乐谱内容的解析更加准确和灵活。
- 优化声部和小节的处理逻辑，确保解析结果的准确性和一致性。

该变更提升了 ABC 解析器的可维护性和扩展性，确保乐谱解析的准确性和灵活性。

Author: Encaik

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

@@ -0,0 +1,81 @@
+/**
+ * ABC 解析错误定义
+ *
+ * 提供统一的错误类型体系，便于错误追踪和处理
+ */
+
+/**
+ * ABC 解析错误基类
+ *
+ * @example
+ * ```typescript
+ * throw new AbcParseError('解析失败', 'PARSE_ERROR', { line: 1, column: 5 });
+ * ```
+ */
+export class AbcParseError extends Error {
+  constructor(
+    message: string,
+    public readonly code: string,
+    public readonly position?: { line?: number; column?: number },
+    public readonly context?: string,
+  ) {
+    super(message);
+    this.name = 'AbcParseError';
+  }
+}
+
+/**
+ * 元素解析错误
+ *
+ * 当无法解析音符、休止符等元素时抛出
+ */
+export class ElementParseError extends AbcParseError {
+  /** 原始错误（如果有） */
+  public readonly cause?: Error;
+
+  constructor(
+    elementData: string,
+    position?: { line?: number; column?: number },
+    cause?: Error,
+  ) {
+    super(
+      `无法解析元素: ${elementData}`,
+      'ELEMENT_PARSE_ERROR',
+      position,
+      elementData,
+    );
+    this.cause = cause;
+  }
+}
+
+/**
+ * 头部解析错误
+ *
+ * 当无法解析头部字段时抛出
+ */
+export class HeaderParseError extends AbcParseError {
+  constructor(fieldName: string, fieldValue: string, reason: string) {
+    super(
+      `无法解析头部字段 ${fieldName}: ${reason}`,
+      'HEADER_PARSE_ERROR',
+      undefined,
+      `${fieldName}: ${fieldValue}`,
+    );
+  }
+}
+
+/**
+ * 小节解析错误
+ *
+ * 当小节时值不匹配等问题时抛出
+ */
+export class MeasureParseError extends AbcParseError {
+  constructor(measureIndex: number, reason: string, context?: string) {
+    super(
+      `小节 ${measureIndex} 解析错误: ${reason}`,
+      'MEASURE_PARSE_ERROR',
+      undefined,
+      context,
+    );
+  }
+}

packages/simple-notation/src/data/parser/abc/errors/index.ts

@@ -0,0 +1,9 @@
+/**
+ * ABC 解析器模块
+ *
+ * 提供完整的 ABC 格式解析能力
+ */
+
+export * from './errors';
+export * from './utils';
+export * from './parsers';

packages/simple-notation/src/data/parser/abc/index.ts

@@ -0,0 +1,286 @@
+import { SNTimeUnit } from '@core/model/ticks';
+import { SNAccidental } from '@core/model/music';
+import { SNParserElement } from '@data/model';
+import {
+  SNParserNote,
+  SNParserRest,
+  SNParserTie,
+  SNParserTuplet,
+  SNParserNode,
+} from '@data/node';
+import { noteValueToDuration } from '@core/utils/time-unit';
+import { AbcTokenizer } from '../utils';
+import { ElementParseError } from '../errors';
+
+/**
+ * ABC 元素解析器
+ *
+ * 职责：解析小节内的音乐元素
+ * - 音符（Note）
+ * - 休止符（Rest）
+ * - 连音（Tuplet）
+ * - 连音线（Tie）
+ */
+export class AbcElementParser {
+  /**
+   * 获取下一个ID的回调函数
+   */
+  private getNextId: (prefix: string) => string;
+
+  constructor(getNextId: (prefix: string) => string) {
+    this.getNextId = getNextId;
+  }
+
+  /**
+   * 解析单个元素
+   *
+   * @param elementData - 元素数据字符串
+   * @param timeUnit - 时间单位（可选）
+   * @param defaultNoteLength - 默认音符长度（可选）
+   * @returns 解析后的元素节点
+   * @throws {ElementParseError} 当无法解析元素时抛出
+   *
+   * @example
+   * ```typescript
+   * // 解析音符
+   * parser.parseElement('C');     // SNParserNote
+   * parser.parseElement('C#');    // SNParserNote (升C)
+   * parser.parseElement('C4');    // SNParserNote (四分音符C)
+   *
+   * // 解析休止符
+   * parser.parseElement('z');     // SNParserRest
+   * parser.parseElement('z4');    // SNParserRest (四分休止符)
+   *
+   * // 解析连音线
+   * parser.parseElement('-');     // SNParserTie
+   *
+   * // 解析连音
+   * parser.parseElement('(3ABC'); // SNParserTuplet (三连音)
+   * ```
+   */
+  parseElement(
+    elementData: string,
+    timeUnit?: SNTimeUnit,
+    defaultNoteLength?: number,
+  ): SNParserElement {
+    const trimmed = elementData.trim();
+
+    if (!trimmed) {
+      throw new ElementParseError(elementData);
+    }
+
+    // 1. 解析连音线
+    if (trimmed === '-') {
+      return new SNParserTie({
+        id: this.getNextId('tie'),
+        style: 'slur',
+        originStr: elementData,
+      });
+    }
+
+    // 2. 解析连音（Tuplet）
+    const tupletMatch = trimmed.match(/^\((\d+)([\s\S]*?)\)?$/);
+    if (tupletMatch) {
+      return this.parseTuplet(
+        tupletMatch,
+        elementData,
+        timeUnit,
+        defaultNoteLength,
+      );
+    }
+
+    // 3. 解析休止符
+    if (trimmed.startsWith('z')) {
+      return this.parseRest(trimmed, elementData, timeUnit, defaultNoteLength);
+    }
+
+    // 4. 解析音符
+    const noteMatch = trimmed.match(
+      /^(\^+\/?|_+\/?|=?)([A-Ga-g])([,']*)(\d*)(\.*)$/,
+    );
+    if (noteMatch) {
+      return this.parseNote(noteMatch, trimmed, timeUnit, defaultNoteLength);
+    }
+
+    throw new ElementParseError(elementData);
+  }
+
+  /**
+   * 解析连音（Tuplet）
+   */
+  private parseTuplet(
+    match: RegExpMatchArray,
+    elementData: string,
+    timeUnit?: SNTimeUnit,
+    defaultNoteLength?: number,
+  ): SNParserTuplet {
+    const [, , innerNotesStr] = match;
+    const innerNotes = AbcTokenizer.tokenize(innerNotesStr);
+
+    return new SNParserTuplet({
+      id: this.getNextId('tuplet'),
+      originStr: elementData,
+    }).addChildren(
+      innerNotes.map(
+        (noteStr): SNParserNote =>
+          this.parseElement(
+            noteStr,
+            timeUnit,
+            defaultNoteLength,
+          ) as SNParserNote,
+      ),
+    );
+  }
+
+  /**
+   * 解析休止符
+   */
+  private parseRest(
+    trimmed: string,
+    elementData: string,
+    timeUnit?: SNTimeUnit,
+    defaultNoteLength?: number,
+  ): SNParserRest {
+    let duration: number;
+
+    if (timeUnit) {
+      const restStr = trimmed.slice(1);
+      const durationStr = restStr.match(/^(\d+)/)?.[1];
+      const dotCount = (restStr.match(/\./g) || []).length;
+
+      const noteValue = durationStr
+        ? 1 / parseInt(durationStr, 10)
+        : defaultNoteLength || 1 / 4;
+
+      const dottedNoteValue = this.calculateDottedNoteValue(
+        noteValue,
+        dotCount,
+      );
+      duration = noteValueToDuration(dottedNoteValue, timeUnit);
+    } else {
+      duration = parseInt(trimmed.slice(1), 10) || 1;
+    }
+
+    return new SNParserRest({
+      id: this.getNextId('rest'),
+      duration,
+      originStr: elementData,
+    });
+  }
+
+  /**
+   * 解析音符
+   */
+  private parseNote(
+    match: RegExpMatchArray,
+    trimmed: string,
+    timeUnit?: SNTimeUnit,
+    defaultNoteLength?: number,
+  ): SNParserNote {
+    const [, accidentalStr, letter, octaveSymbols, durationStr] = match;
+
+    // 解析变音记号
+    const accidental = this.parseAccidental(accidentalStr);
+
+    // 解析八度
+    const baseOctave: number = letter === letter.toUpperCase() ? 3 : 4;
+    const octaveOffset = octaveSymbols.split('').reduce((offset, sym) => {
+      return sym === ',' ? offset - 1 : sym === "'" ? offset + 1 : offset;
+    }, 0);
+    const octave = baseOctave + octaveOffset;
+
+    // 解析时值
+    let duration: number;
+    if (timeUnit) {
+      const noteValue = durationStr
+        ? 1 / parseInt(durationStr, 10)
+        : defaultNoteLength || 1 / 4;
+
+      const dotCount = (trimmed.match(/\./g) || []).length;
+      const dottedNoteValue = this.calculateDottedNoteValue(
+        noteValue,
+        dotCount,
+      );
+      duration = noteValueToDuration(dottedNoteValue, timeUnit);
+    } else {
+      duration = durationStr ? parseInt(durationStr, 10) : 1;
+    }
+
+    return new SNParserNote({
+      id: this.getNextId('note'),
+      originStr: trimmed,
+      pitch: {
+        letter: letter.toUpperCase(),
+        octave,
+        accidental,
+      },
+      duration,
+    });
+  }
+
+  /**
+   * 解析变音记号
+   *
+   * @param accidentalStr - 变音记号字符串
+   * @returns 变音记号枚举值
+   */
+  private parseAccidental(accidentalStr: string): SNAccidental {
+    if (!accidentalStr) return SNAccidental.NATURAL;
+
+    switch (accidentalStr) {
+      case '^':
+        return SNAccidental.SHARP;
+      case '^^':
+        return SNAccidental.DOUBLE_SHARP;
+      case '_':
+        return SNAccidental.FLAT;
+      case '__':
+        return SNAccidental.DOUBLE_FLAT;
+      case '=':
+        return SNAccidental.NATURAL;
+      default:
+        return SNAccidental.NATURAL;
+    }
+  }
+
+  /**
+   * 计算带附点的音符时值
+   *
+   * @param noteValue - 基础音符时值
+   * @param dotCount - 附点数量
+   * @returns 带附点的音符时值
+   */
+  private calculateDottedNoteValue(
+    noteValue: number,
+    dotCount: number,
+  ): number {
+    if (dotCount === 0) return noteValue;
+    return noteValue * (1 + 0.5 * (1 - Math.pow(0.5, dotCount)));
+  }
+
+  /**
+   * 获取默认音符长度
+   *
+   * 从父节点的 meta 中查找 noteLength 字段
+   *
+   * @param node - 当前节点（可选）
+   * @returns 默认音符长度
+   */
+  static getDefaultNoteLength(node?: SNParserNode): number {
+    if (node) {
+      let current: SNParserNode | undefined = node.parent;
+      while (current) {
+        const meta = current.meta as { noteLength?: string } | undefined;
+        if (meta?.noteLength) {
+          const match = meta.noteLength.match(/^(\d+)\/(\d+)$/);
+          if (match) {
+            const [, num, den] = match.map(Number);
+            return num / den;
+          }
+        }
+        current = current.parent;
+      }
+    }
+    return 1 / 4; // 默认四分音符
+  }
+}