乐谱渲染引擎重构工作计划

版本：1.1
创建日期：2026-01-30
最后更新：2026-01-30
关联文档：ARCHITECTURE_DESIGN.md
状态：计划中

1. 项目概述

1.1 项目目标

构建一个通用的乐谱渲染引擎，支持：

MusicXML 解析与通用数据模型
简谱渲染（首调 + 固定调）
五线谱渲染
运行时模式切换（五线谱 ↔ 首调简谱 ↔ 固定调简谱）

1.2 当前状态

模块	状态	说明
简谱渲染器	🟢 已有	基于 OSMD 数据，需重构
固定调模式	🟢 已实现	当前默认模式
首调模式	🔴 未实现	核心待开发功能
五线谱渲染器	🔴 未实现	规划中
通用数据模型	🔴 未实现	需要新建
MusicXML 独立解析	🔴 未实现	当前依赖 OSMD

1.3 预估总工时

阶段	预估工时	优先级	说明
阶段零：MusicXML 规范学习	3-5 天	P0（最高）	必须首先完成
阶段一：核心数据模型	5-7 天	P0	依赖阶段零
阶段二：简谱重构+首调	4-6 天	P0	依赖阶段一
阶段三：五线谱渲染器	8-12 天	P1	依赖阶段一
阶段四：完善优化	3-5 天	P2	依赖阶段二、三
总计	23-35 天	-	-

⚠️ 关键提醒：阶段零是一切的基础，必须完整学习 MusicXML 规范后才能开始编码。否则将导致：

数据模型设计不完整

遗漏关键业务逻辑（如循环、跳跃等）

后期大量返工

2. 里程碑规划

┌──────────────────────────────────────────────────────────────────────────────────────┐
│                                    项目里程碑                                          │
├──────────────────────────────────────────────────────────────────────────────────────┤
│                                                                                      │
│  M0          M0.5            M1              M2              M3              M4      │
│   │           │               │               │               │               │      │
│   ▼           ▼               ▼               ▼               ▼               ▼      │
│ 项目       规范学习        核心模型        简谱重构        五线谱          项目       │
│ 启动        完成            完成            完成            完成            交付       │
│   │           │               │               │               │               │      │
│   └───────────┴───────────────┴───────────────┴───────────────┴───────────────┘      │
│      阶段零        阶段一          阶段二          阶段三          阶段四              │
│     (3-5天)       (5-7天)        (4-6天)        (8-12天)        (3-5天)              │
│    【最高优先】                                                                       │
│                                                                                      │
└──────────────────────────────────────────────────────────────────────────────────────┘

里程碑定义

里程碑	名称	交付物	验收标准
M0	项目启动	工作计划文档	计划评审通过
M0.5	规范学习完成	MusicXML 知识文档	所有标签学习完成，知识文档评审通过
M1	核心模型完成	music-core 模块	能独立解析 MusicXML
M2	简谱重构完成	首调/固定调切换	业务层切换功能正常
M3	五线谱完成	完整五线谱渲染	基本乐谱渲染正确
M4	项目交付	完整引擎	所有验收测试通过

3. 阶段零：MusicXML 规范学习与知识沉淀

目标：完整学习 MusicXML 4.0 规范，理解所有标签的含义、作用和业务影响
预估工时：3-5 天
优先级：P0（最高，必须首先完成）
依赖：无

3.1 为什么必须先学习规范？

在开始编写任何代码之前，必须完整理解 MusicXML 规范。原因如下：

避免数据模型设计不完整
- MusicXML 包含数百个元素和属性
- 不了解全貌会导致数据模型遗漏关键字段
- 后期补充会导致大量代码重构
理解业务逻辑的影响
- 很多标签不仅仅是"渲染"问题，更是"播放逻辑"问题
- 例如循环标记、跳跃标记会直接影响 times 数组的生成
- 不理解这些标签会导致业务功能错误
避免重复造轮子
- 了解规范可以知道哪些信息是标准提供的
- 避免自己设计已经标准化的结构

3.2 学习资源

资源	链接	说明
MusicXML 4.0 官方规范	W3C MusicXML 4.0	官方规范文档，最权威
元素完整列表	Element Tree	所有元素的层级结构
元素详细定义	Elements A-Z	每个元素的详细定义
数据类型	Data Types	所有数据类型定义
示例文件	MusicXML Examples	官方教程和示例

3.3 学习任务分解

3.3.1 核心结构元素（0.5 天）

任务	元素	学习重点	状态
乐谱结构	`score-partwise`, `score-timewise`	两种组织方式的区别	⬜
声部定义	`part-list`, `score-part`, `part-group`	声部列表、分组、乐器定义	⬜
声部内容	`part`, `measure`	声部与小节的组织结构	⬜
作品信息	`work`, `identification`, `credit`	标题、作者、版权等元信息	⬜
页面设置	`defaults`, `page-layout`, `system-layout`	页面尺寸、边距、谱表间距	⬜

3.3.2 音符与休止符元素（1 天）

任务	元素	学习重点	业务影响	状态
音符基础	`note`, `pitch`, `rest`, `unpitched`	音高表示、休止符、打击乐	音符渲染	⬜
时值系统	`duration`, `divisions`, `type`, `dot`	时值计算方式、附点	`times` 计算	⬜
变音记号	`alter`, `accidental`	升降号、还原号、微分音	音高显示	⬜
和弦	`chord`	和弦音符的标记方式	同时发声	⬜
装饰音	`grace`, `cue`	装饰音、提示音符	渲染与播放	⬜
连音	`time-modification`, `tuplet`	三连音等不规则节奏	时值计算	⬜
符干符杠	`stem`, `beam`, `notehead`	符干方向、符杠连接	五线谱渲染	⬜
歌词	`lyric`, `syllabic`, `text`, `elision`	歌词文字、音节连接	歌词显示	⬜

3.3.3 属性元素（0.5 天）

任务	元素	学习重点	业务影响	状态
时值单位	`divisions`	每个四分音符的 divisions 数	时值计算基础	⬜
调号	`key`, `fifths`, `mode`	升降号数量、大小调	首调/固定调转换	⬜
拍号	`time`, `beats`, `beat-type`	拍号表示、复合拍号	小节时值计算	⬜
谱号	`clef`, `sign`, `line`	高音谱号、低音谱号等	五线谱渲染	⬜
谱表	`staves`, `staff-details`	多谱表声部	总谱渲染	⬜
移调	`transpose`	移调乐器	实际音高计算	⬜

3.3.4 ⚠️ 播放控制元素（1 天）—— 重点学习

这是最重要的部分：这些元素直接影响播放逻辑和 times 数组生成

任务	元素	学习重点	业务影响	状态
反复记号	`repeat`	`direction="forward/backward"`	循环播放，times 翻倍	⬜
跳房子	`ending`	`number`, `type` (start/stop/discontinue)	不同遍次播放不同内容	⬜
D.S. 记号	`segno`	Dal Segno，从记号处重复	跳转到特定位置	⬜
D.C. 记号	`sound dacapo="yes"`	Da Capo，从头重复	跳转到开头	⬜
Coda 记号	`coda`	尾声跳转	跳转到 Coda	⬜
Fine 记号	`sound fine="yes"`	终止标记	确定结束位置	⬜
小节线	`barline`, `bar-style`	双线、终止线、反复线	渲染与结构	⬜
速度标记	`metronome`, `sound tempo`	BPM 标记	播放速度	⬜

反复与跳跃的业务逻辑示例：

【简单反复】
||: A B C D :||
播放顺序：A B C D A B C D
times 需要生成两遍

【带跳房子的反复】
||: A B [1. C D :|| [2. E F ||
播放顺序：A B C D A B E F
第一遍：A B C D
第二遍：A B E F（跳过 C D，改走 E F）

【D.S. al Coda】
A B (Segno) C D (To Coda) E F | G H (D.S. al Coda) | (Coda) I J ||
播放顺序：A B C D E F G H C D I J
需要跳转到 Segno，在 To Coda 处跳到 Coda

3.3.5 连接与记号元素（0.5 天）

任务	元素	学习重点	业务影响	状态
延音线	`tie`, `tied`	音符时值延长	时值合并、渲染	⬜
圆滑线	`slur`	连奏标记	渲染	⬜
演奏技法	`articulations`	staccato, accent, tenuto 等	渲染	⬜
装饰记号	`ornaments`	trill, mordent, turn 等	渲染	⬜
力度记号	`dynamics`	p, f, mf, ff 等	渲染、播放力度	⬜
延音记号	`fermata`	延长音	渲染、播放时值	⬜
踏板	`pedal`	钢琴踏板	渲染	⬜

3.3.6 方向与文字元素（0.5 天）

任务	元素	学习重点	业务影响	状态
方向容器	`direction`, `direction-type`	方向标记的组织方式	渲染位置	⬜
文字标记	`words`	任意文字标记	渲染	⬜
渐强渐弱	`wedge`	crescendo, diminuendo	渲染	⬜
八度移位	`octave-shift`	8va, 8vb	音高显示	⬜
排练号	`rehearsal`	排练标记	渲染	⬜
括号	`bracket`, `dashes`	各种线型标记	渲染	⬜

3.3.7 和弦与和声元素（0.5 天）

任务	元素	学习重点	业务影响	状态
和弦符号	`harmony`, `root`, `kind`	和弦名称、类型	渲染	⬜
和弦低音	`bass`	转位和弦	渲染	⬜
和弦变化	`degree`	和弦变化音	渲染	⬜
数字低音	`figured-bass`	通奏低音	渲染	⬜

3.4 知识沉淀

学习过程中需要产出以下文档：

文档	路径	内容
MusicXML 完整标签手册	`docs/jianpu-renderer/MUSICXML_TAGS_MANUAL.md`	所有标签的中文说明、作用、示例
业务影响分析	`docs/jianpu-renderer/MUSICXML_BUSINESS_IMPACT.md`	哪些标签影响业务逻辑，如何影响
反复与跳跃逻辑	`docs/jianpu-renderer/MUSICXML_REPEAT_JUMP.md`	专门讲解反复、跳跃标记的处理逻辑
数据模型映射	`docs/jianpu-renderer/MUSICXML_MODEL_MAPPING.md`	MusicXML 元素与数据模型的对应关系

3.5 验收标准

完成 W3C MusicXML 4.0 规范的完整阅读
理解所有 P0/P1 元素的含义和作用
特别掌握反复、跳跃等影响播放逻辑的元素
产出 MusicXML 完整标签手册（中文）
产出业务影响分析文档
产出反复与跳跃逻辑处理文档
知识文档评审通过

3.6 交付物

docs/jianpu-renderer/
├── MUSICXML_TAGS_MANUAL.md      # 完整标签手册
├── MUSICXML_BUSINESS_IMPACT.md  # 业务影响分析
├── MUSICXML_REPEAT_JUMP.md      # 反复与跳跃逻辑
└── MUSICXML_MODEL_MAPPING.md    # 数据模型映射

4. 阶段一：核心数据模型与解析器

目标：建立完整的通用数据模型和独立的 MusicXML 解析器
预估工时：5-7 天
优先级：P0
依赖：阶段零（MusicXML 规范学习）完成

4.1 任务分解

4.1.1 目录结构搭建（0.5 天）

任务	说明	状态
创建 `src/music-core/` 目录	核心模块根目录	✅
创建 `src/music-core/models/`	数据模型目录	✅
创建 `src/music-core/parser/`	解析器目录	✅
创建 `src/music-core/utils/`	工具函数目录	✅
配置 tsconfig paths	设置 `@music-core` 别名	✅

4.1.2 核心数据模型实现（2 天）

任务	文件	说明	状态
Score 模型	`models/Score.ts`	乐谱顶层结构	✅
Part 模型	`models/Part.ts`	声部结构	✅
Measure 模型	`models/Measure.ts`	小节结构	✅
Note 模型	`models/Note.ts`	音符结构	✅
Pitch 模型	`models/Pitch.ts`	音高结构	✅
Attributes 模型	`models/Attributes.ts`	调号/拍号/谱号	✅
Direction 模型	`models/Direction.ts`	方向标记	✅
Barline 模型	`models/Barline.ts`	小节线	✅
Notations 模型	`models/Notations.ts`	记号（连线、演奏技法等）	✅
Harmony 模型	`models/Harmony.ts`	和弦符号	✅
导出索引	`models/index.ts`	统一导出	✅

4.1.3 MusicXML 解析器实现（2-3 天）

任务	文件	说明	状态
主解析器	`parser/MusicXMLParser.ts`	入口，协调各子解析器	✅
结构解析	`parser/StructureParser.ts`	解析 score/part/measure	✅
音符解析	`parser/NoteParser.ts`	解析 note/pitch/rest	✅
属性解析	`parser/AttributesParser.ts`	解析 key/time/clef	✅
方向解析	`parser/DirectionParser.ts`	解析 direction 标记	✅
小节线解析	`parser/BarlineParser.ts`	解析 barline/repeat/ending	✅
导出索引	`parser/index.ts`	统一导出	✅

4.1.4 工具函数实现（0.5 天）

任务	文件	说明	状态
音高工具	`utils/PitchUtils.ts`	音名转换、半音计算	✅
时值工具	`utils/DurationUtils.ts`	divisions 换算	✅
调号工具	`utils/KeyUtils.ts`	五度圈、调内音判断	✅
XML工具	`utils/XMLUtils.ts`	XML解析辅助函数	✅
导出索引	`utils/index.ts`	统一导出	✅

4.1.5 单元测试（1 天）

任务	说明	状态
模型测试	测试所有数据模型的创建和序列化	⬜
解析器测试	测试各解析器的正确性	⬜
集成测试	使用项目中的测试 XML 文件	⬜
覆盖率检查	确保 > 80%	⬜

4.2 验收标准

所有 P0 元素（结构、音符、属性）完整解析
所有 P1 元素（小节线、连接、歌词）完整解析
能解析项目中所有测试 XML 文件
单元测试覆盖率 > 80%
解析后数据可序列化为 JSON

4.3 交付物

src/music-core/
├── models/
│   ├── Score.ts
│   ├── Part.ts
│   ├── Measure.ts
│   ├── Note.ts
│   ├── Pitch.ts
│   ├── Attributes.ts
│   ├── Direction.ts
│   ├── Barline.ts
│   ├── Notations.ts
│   ├── Harmony.ts
│   └── index.ts
├── parser/
│   ├── MusicXMLParser.ts
│   ├── StructureParser.ts
│   ├── NoteParser.ts
│   ├── AttributesParser.ts
│   ├── DirectionParser.ts
│   ├── BarlineParser.ts
│   └── index.ts
├── utils/
│   ├── PitchUtils.ts
│   ├── DurationUtils.ts
│   ├── KeyUtils.ts
│   └── index.ts
├── __tests__/
│   └── ...
└── index.ts

5. 阶段二：简谱渲染器重构与首调支持

目标：将简谱渲染器迁移到新架构，实现首调/固定调切换
预估工时：4-6 天
优先级：P0
依赖：阶段一完成

5.1 任务分解

5.1.1 目录重组（0.5 天）

任务	说明	状态
创建 `src/renderers/` 目录	渲染层根目录	⬜
创建 `src/renderers/common/`	共享渲染工具	⬜
创建 `src/renderers/jianpu/`	简谱渲染器目录	⬜
迁移现有简谱代码	从 `jianpu-renderer` 迁移	⬜

5.1.2 模型转换器实现（1 天）

任务	文件	说明	状态
简谱转换器	`converter/JianpuConverter.ts`	通用模型 → 简谱模型	⬜
首调转换	`converter/MovableDoConverter.ts`	首调音高转换逻辑	⬜
固定调转换	`converter/FixedDoConverter.ts`	固定调音高转换逻辑	⬜
调号处理	`converter/KeySignatureHandler.ts`	调号映射、调内音判断	⬜

5.1.3 首调渲染核心实现（1.5 天）

任务	说明	状态
首调音高转换算法	实现 `toMovableDo()` 函数	⬜
首调升降号逻辑	调内音不显示升降号	⬜
首调八度计算	相对于主音重新计算八度	⬜
调号显示更新	首调显示 `1=G`，固定调显示 `1=C`	⬜
模式切换接口	`setSolfegeMode()` / `getSolfegeMode()`	⬜

5.1.4 渲染器重构（1 天）

任务	说明	状态
数据源切换	从 OSMD 数据切换到通用模型	⬜
配置更新	添加 `solfegeMode` 配置项	⬜
绘制逻辑更新	根据模式选择转换器	⬜
重渲染优化	模式切换时只重绘必要部分	⬜

5.1.5 兼容性适配（0.5 天）

任务	说明	状态
API 兼容	保持现有业务层 API 不变	⬜
适配器更新	更新 `OSMDCompatibilityAdapter`	⬜
times 数组兼容	保证播放、高亮功能正常	⬜

5.1.6 测试（0.5 天）

任务	说明	状态
首调渲染测试	各调号的首调渲染正确性	⬜
固定调渲染测试	确保固定调功能不受影响	⬜
模式切换测试	切换时渲染正确，无闪烁	⬜
可视化测试	`visual-test.html` 验证	⬜
业务集成测试	验证业务层切换功能	⬜

5.2 首调实现详细设计

5.2.1 音高转换流程

绝对音高 (MusicXML)
       │
       ▼
┌──────────────────┐
│ 获取当前调号      │
│ keySignature     │
└────────┬─────────┘
         │
    ┌────┴────┐
    │ 模式判断 │
    └────┬────┘
         │
   ┌─────┴─────┐
   ▼           ▼
首调模式    固定调模式
   │           │
   ▼           ▼
toMovableDo  toFixedDo
   │           │
   ▼           ▼
JianpuPitch  JianpuPitch

5.2.2 首调转换核心代码

// 核心转换函数
function toMovableDo(pitch: Pitch, keySignature: KeySignature): JianpuPitch {
  const STEP_ORDER = ['C', 'D', 'E', 'F', 'G', 'A', 'B'];
  
  // 获取主音位置
  const keyRoot = keySignature.key;  // 如 'G', 'D', 'F#' 等
  const keyIndex = STEP_ORDER.indexOf(keyRoot[0]);
  
  // 计算相对音级
  const stepIndex = STEP_ORDER.indexOf(pitch.step);
  const relativeDegree = (stepIndex - keyIndex + 7) % 7;
  const number = relativeDegree + 1;  // 1-7
  
  // 计算八度偏移（考虑主音位置）
  const octaveOffset = calculateOctaveForMovable(pitch, keySignature);
  
  // 计算升降号（只显示临时变化音）
  const accidental = calculateAccidentalForMovable(pitch, keySignature);
  
  return { number, octave: octaveOffset, accidental };
}

5.3 验收标准

首调模式渲染正确（各调号）
固定调模式渲染正确（与之前一致）
模式切换 API 可用
业务层切换功能正常
播放、高亮等功能不受影响
visual-test.html 测试通过

5.4 交付物

src/renderers/
├── common/
│   ├── SVGRenderer.ts
│   ├── LayoutEngine.ts
│   └── index.ts
├── jianpu/
│   ├── JianpuRenderer.ts
│   ├── converter/
│   │   ├── JianpuConverter.ts
│   │   ├── MovableDoConverter.ts
│   │   ├── FixedDoConverter.ts
│   │   ├── KeySignatureHandler.ts
│   │   └── index.ts
│   ├── drawer/
│   │   └── ... (现有代码迁移)
│   ├── layout/
│   │   └── ... (现有代码迁移)
│   ├── __tests__/
│   │   └── ...
│   └── index.ts
└── index.ts

6. 阶段三：五线谱渲染器

目标：实现完整的五线谱渲染能力
预估工时：8-12 天
优先级：P1
依赖：阶段一完成

6.1 任务分解

6.1.1 基础框架（1 天）

任务	说明	状态
创建 `src/renderers/staff/` 目录	五线谱渲染器目录	⬜
StaffRenderer 主类	入口类，协调各绘制器	⬜
配置定义	StaffRenderConfig	⬜
常量定义	音符间距、谱表高度等	⬜

6.1.2 布局引擎（2 天）

任务	文件	说明	状态
布局引擎	`layout/StaffLayoutEngine.ts`	计算位置、分行	⬜
谱表布局	`layout/StaveLayout.ts`	五线谱位置计算	⬜
音符布局	`layout/NoteLayout.ts`	音符 Y 位置计算	⬜
符杠布局	`layout/BeamLayout.ts`	符杠方向、角度	⬜

6.1.3 核心绘制器（3-4 天）

任务	文件	说明	状态
谱表绘制	`drawer/StaveDrawer.ts`	五线谱线条	⬜
谱号绘制	`drawer/ClefDrawer.ts`	高音/低音谱号	⬜
调号绘制	`drawer/KeySignatureDrawer.ts`	升降号序列	⬜
拍号绘制	`drawer/TimeSignatureDrawer.ts`	拍号数字	⬜
符头绘制	`drawer/NoteHeadDrawer.ts`	各类符头	⬜
符干绘制	`drawer/StemDrawer.ts`	符干方向、长度	⬜
符杠绘制	`drawer/BeamDrawer.ts`	连接符杠	⬜
符尾绘制	`drawer/FlagDrawer.ts`	单独符尾	⬜
附点绘制	`drawer/DotDrawer.ts`	附点位置	⬜
休止符绘制	`drawer/RestDrawer.ts`	各类休止符	⬜

6.1.4 辅助绘制器（2-3 天）

任务	文件	说明	状态
临时升降号	`drawer/AccidentalDrawer.ts`	升/降/还原号	⬜
连音线	`drawer/TieDrawer.ts`	延音线	⬜
圆滑线	`drawer/SlurDrawer.ts`	连音线	⬜
力度记号	`drawer/DynamicsDrawer.ts`	p, f, mf 等	⬜
歌词	`drawer/LyricDrawer.ts`	歌词文字	⬜
小节线	`drawer/BarlineDrawer.ts`	各类小节线	⬜

6.1.5 测试（1 天）

任务	说明	状态
单元测试	各绘制器测试	⬜
集成测试	完整乐谱渲染	⬜
对比测试	与 OSMD 渲染结果对比	⬜
可视化测试	`visual-test-staff.html`	⬜

6.2 验收标准

能渲染基本乐谱（单声部、无特殊记号）
谱号、调号、拍号显示正确
音符位置正确（Y 位置对应音高）
符干方向正确
符杠渲染正确
小节线正确
与简谱共享数据源

6.3 交付物

src/renderers/staff/
├── StaffRenderer.ts
├── config/
│   └── StaffRenderConfig.ts
├── layout/
│   ├── StaffLayoutEngine.ts
│   ├── StaveLayout.ts
│   ├── NoteLayout.ts
│   ├── BeamLayout.ts
│   └── index.ts
├── drawer/
│   ├── StaveDrawer.ts
│   ├── ClefDrawer.ts
│   ├── KeySignatureDrawer.ts
│   ├── TimeSignatureDrawer.ts
│   ├── NoteHeadDrawer.ts
│   ├── StemDrawer.ts
│   ├── BeamDrawer.ts
│   ├── FlagDrawer.ts
│   ├── DotDrawer.ts
│   ├── RestDrawer.ts
│   ├── AccidentalDrawer.ts
│   ├── TieDrawer.ts
│   ├── SlurDrawer.ts
│   ├── DynamicsDrawer.ts
│   ├── LyricDrawer.ts
│   ├── BarlineDrawer.ts
│   └── index.ts
├── __tests__/
│   └── ...
└── index.ts

7. 阶段四：完善与优化

目标：覆盖所有 MusicXML 元素，优化性能，完善文档
预估工时：3-5 天
优先级：P2
依赖：阶段二、三完成

7.1 任务分解

7.1.1 P2 元素实现（1-2 天）

任务	说明	状态
Direction 渲染	words, dynamics, wedge, metronome	⬜
Articulations 渲染	accent, staccato, tenuto 等	⬜
Ornaments 渲染	trill, turn, mordent 等	⬜
Fermata 渲染	延音记号	⬜

7.1.2 P3 元素实现（1 天）

任务	说明	状态
Harmony 渲染	和弦符号	⬜
Figured Bass	数字低音	⬜

7.1.3 性能优化（0.5 天）

任务	说明	状态
渲染性能分析	识别瓶颈	⬜
批量渲染优化	减少 DOM 操作	⬜
缓存策略	缓存计算结果	⬜
懒加载	可视区域外延迟渲染	⬜

7.1.4 文档完善（0.5 天）

任务	说明	状态
API 文档更新	更新 API.md	⬜
使用示例	添加更多示例	⬜
变更日志	更新 CHANGELOG	⬜
迁移指南	从旧版迁移说明	⬜

7.1.5 边缘情况处理（0.5 天）

任务	说明	状态
异常 XML 处理	格式不规范的 XML	⬜
大乐谱处理	数百小节的乐谱	⬜
多声部处理	复杂多声部乐谱	⬜
转调处理	乐曲中间转调	⬜

7.2 验收标准

P2 元素渲染正确
大型乐谱渲染性能可接受（< 3 秒）
文档完整、示例可运行
边缘情况有合理处理

8. 风险管理

8.1 风险识别

风险	可能性	影响	应对措施
规范学习不充分	中	极高	阶段零必须认真完成，不可跳过
遗漏业务关键标签	中	极高	重点学习反复、跳跃等标签
首调算法复杂度超预期	中	中	提前研究、参考开源实现
五线谱绘制难度大	高	高	可考虑先渲染简化版
与现有业务层不兼容	中	高	保持 API 兼容、增量迁移
MusicXML 解析遗漏元素	低	中	持续补充、用户反馈驱动
性能问题	中	中	持续性能测试、及时优化

8.2 应急预案

首调实现困难：可先完成固定调，首调作为后续迭代
五线谱进度延期：可减少 P2/P3 元素，先交付基础版本
兼容性问题：保留旧代码路径，逐步迁移

9. 质量保障

9.1 测试策略

测试类型	覆盖范围	执行时机
单元测试	所有解析器、转换器、绘制器	每次提交
集成测试	完整渲染流程	每个里程碑
可视化测试	渲染结果人工检查	每个功能完成
性能测试	大型乐谱渲染时间	每个里程碑
兼容性测试	业务层功能	阶段二完成后

9.2 代码质量

指标	目标
测试覆盖率	> 80%
TypeScript 严格模式	启用
ESLint 检查	0 错误
代码注释	关键函数 100% 注释

9.3 评审机制

评审类型	参与者	时机
设计评审	团队	每个阶段开始前
代码评审	同事	每个 PR
里程碑评审	团队 + 产品	每个里程碑完成

附录

A. 任务状态图例

图标	状态
⬜	未开始
🔄	进行中
✅	已完成
❌	已取消
⏸️	暂停

B. 相关文档

C. 更新记录

日期	版本	更新内容
2026-01-30	1.0	初始版本
2026-01-30	1.1	新增阶段零：MusicXML 规范学习与知识沉淀 - 调整优先级，规范学习为 P0 最高优先 - 新增播放控制元素的详细学习任务 - 新增知识沉淀文档要求 - 更新风险识别

文档结束

WORK_PLAN.md 30 KB История Исходник

乐谱渲染引擎重构工作计划

目录

1. 项目概述

1.1 项目目标

1.2 当前状态

1.3 预估总工时

2. 里程碑规划

里程碑定义

3. 阶段零：MusicXML 规范学习与知识沉淀

3.1 为什么必须先学习规范？

3.2 学习资源

3.3 学习任务分解

3.3.1 核心结构元素（0.5 天）

3.3.2 音符与休止符元素（1 天）

3.3.3 属性元素（0.5 天）

3.3.4 ⚠️ 播放控制元素（1 天）—— 重点学习

3.3.5 连接与记号元素（0.5 天）

3.3.6 方向与文字元素（0.5 天）

3.3.7 和弦与和声元素（0.5 天）

3.4 知识沉淀

3.5 验收标准

3.6 交付物

4. 阶段一：核心数据模型与解析器

4.1 任务分解

4.1.1 目录结构搭建（0.5 天）

4.1.2 核心数据模型实现（2 天）

4.1.3 MusicXML 解析器实现（2-3 天）

4.1.4 工具函数实现（0.5 天）

4.1.5 单元测试（1 天）

4.2 验收标准

4.3 交付物

5. 阶段二：简谱渲染器重构与首调支持

5.1 任务分解

5.1.1 目录重组（0.5 天）

5.1.2 模型转换器实现（1 天）

5.1.3 首调渲染核心实现（1.5 天）

5.1.4 渲染器重构（1 天）

5.1.5 兼容性适配（0.5 天）

5.1.6 测试（0.5 天）

5.2 首调实现详细设计

5.2.1 音高转换流程

5.2.2 首调转换核心代码

5.3 验收标准

5.4 交付物

6. 阶段三：五线谱渲染器

6.1 任务分解

6.1.1 基础框架（1 天）

6.1.2 布局引擎（2 天）

6.1.3 核心绘制器（3-4 天）

6.1.4 辅助绘制器（2-3 天）

6.1.5 测试（1 天）

6.2 验收标准

6.3 交付物

7. 阶段四：完善与优化

7.1 任务分解

7.1.1 P2 元素实现（1-2 天）

7.1.2 P3 元素实现（1 天）

7.1.3 性能优化（0.5 天）

7.1.4 文档完善（0.5 天）

7.1.5 边缘情况处理（0.5 天）

7.2 验收标准

8. 风险管理

8.1 风险识别

8.2 应急预案

9. 质量保障

9.1 测试策略

9.2 代码质量

9.3 评审机制

附录

A. 任务状态图例

B. 相关文档

C. 更新记录

WORK_PLAN.md 30 KB

История Исходник