[D&T]文档，修改增强测试

Author: Starrah

README.md

@@ -3,8 +3,9 @@ MuConvert - 新一代多功能音游转谱器
 
 MuConvert 是一个多功能的音游转谱器。目前支持maimai、chunithm的谱面格式转换，未来还可能加入更多游戏/更多格式支持。
 - maimai：支持 Simai（自制谱社区最主流格式，[MajdataEdit](https://majdata.net/edit)、[Visual Maimai](https://github.com/CH3COOOHH/Visual-Maimai-Release)等都是这种格式）与 MA2（官方游戏格式）的双向互转。
-- chunithm：支持 UGC（[Umiguri](https://umgr.inonote.jp/en/)的格式）与 C2S（官方游戏格式）的双向互转；
+- CHUNITHM：支持 UGC（[Umiguri](https://umgr.inonote.jp/en/)的格式）与 C2S（官方游戏格式）的双向互转；
   - 此外，还实验性地支持SUS与上述格式的双向互转（注意目前支持还不太完善，可能有较多bug，如遇bug欢迎反馈）
+- Ongeki：由于这款游戏尚无普遍通用的社区自制谱格式，因此支持的是OGKR（官方游戏格式）的解析和生成逻辑，而非直接的谱面转换。详见下文[Ongeki游戏支持](#Ongeki游戏支持)部分所述。
 
 > Kind reminder: To reduce developers’ workload, this README is maintained only in Chinese. We recommend using an LLM to translate and read this document.
 
@@ -15,7 +16,7 @@ MuConvert 是一个多功能的音游转谱器。目前支持maimai、chunithm
 - 工具+基础库：既可以直接当作命令行工具使用，也可以把它作为一个C#依赖库嵌入到你的工程里。
 - 可扩展的架构设计：本项目以中间表示(Chart类)为核心，通过为每种语言编写parser、将语言解析为统一的中间表示对象，再为每种语言编写generator，实现任意两个语言间的互转。
   - 项目设计具有良好的可扩展性，您可轻松按照自己的需求定制自己的语言格式，也可直接把解析得到的Chart对象拿来服务于您自己的下游项目如谱面播放器等。
-- 多游戏支持：基于上述良好的可扩展性，本项目一套代码可提供对maimai、chunithm两款游戏共五种格式的支持，未来还可能加入ongeki等更多游戏。
+- 多游戏支持：基于上述良好的可扩展性，本项目一套代码可提供对maimai、CHUNITHM、Ongeki三款游戏共六种格式的支持，未来还可能加入更多游戏/更多格式。
 
 ## 使用文档
 本项目具有两种使用方式：
@@ -109,6 +110,8 @@ MuConvert "D:\charts\Song\0003_00.c2s"
 
 </details>
 
+> Ongeki游戏支持方面，目前仅支持对OGKR一种格式的解析和生成，不是直接两种格式间转换，因此没有直接调用CLI程序的入口，只能以代码调用的方式使用。详见下文[Ongeki游戏支持](#Ongeki游戏支持)部分所述。
+
 ### 2) 将本项目作为依赖库使用
 #### 导入依赖库
 - **推荐做法**：把本仓库作为 git submodule 引入你的工程仓库，然后把 `MuConvert.csproj` 加入你的 `.sln`/`.slnx`。
@@ -160,14 +163,43 @@ return maidataText; // maidataText即为转谱结果
 var (c2sChart, alerts) = new C2sParser().Parse(c2sText); // 解析 C2S 谱面字符串
 var (ugcChart, alerts) = new UgcParser().Parse(ugcText); // 解析 UGC 谱面字符串
 // 以上得到的c2sChart、ugcChart，都是ChuChart类型的谱面表示对象；
-// alerts是解析过程中可能产生的警告信息等，建议打印出来。
+// alerts是解析过程中可能产生的警告信息等，建议打印出来（直接对Alert对象调用ToString()即可）。
 
 var (c2sText, alerts) = new C2sGenerator().Generate(ugcChart);   // UGC -> C2S
 var (ugcText, alerts) = new UgcGenerator().Generate(c2sChart);   // C2S -> UGC
 // 各种Generator的Generate方法，均接受 ChuChart（可将任一 Parser 产出的 ChuChart 互相传入）。
 // 同上，alerts是生成过程中可能产生的警告信息等，建议打印出来。
 ```
 
+#### Ongeki游戏支持
+由于这款游戏尚无普遍通用的社区自制谱格式，因此目前MuConvert支持的仅有OGKR（官方游戏格式）这一种格式的解析和生成。  
+解析得到的谱面表示对象为`OgkChart`类，内含`Notes`（正键、侧键、bell等各种音符）、`Lanes`（轨道和引导线）、`Bullets`（子弹）等字段、足以表达一个谱面的所有信息。具体的含义和用法，`chart/ogk/OgkChart.cs`的代码中有丰富的注释，请参见代码中的注释。
+
+关于其用途，您可以考虑把本项目作为您其他Ongeki相关项目的一个依赖库，通过使用其中的OGKR解析和/或OGKR生成的代码逻辑，来简化/优化您的开发工作，避免关注Ongeki游戏谱面格式的繁杂细节，直接把精力放在您的项目的核心。  
+例如，如果您正在开发一个Ongeki的谱面播放器，您就可以直接使用`OgkrParser`得到`OgkChart`对象，该对象中内置了关于谱面的所有细节信息；其中的音符类型(`OgkNote`)等上面都实现了丰富的方法，如小节时间`Time`、绝对时间`ToSecond()`等，可以直接调用使用、以便播放器直接计算各个音符在某一时刻的位置，而不必自己去解析OGKR文本、处理各种复杂的谱面相关细节问题了。
+
+以下示例展示了如何解析OGKR文本为OgkChart对象，做一点小小的改动（本例中为把第一个Hold的时长加倍），再生成回OGKR格式的文本。
+> 以下 C# 示例中的各类均位于命名空间 `MuConvert.ogk`中，使用时需添加 `using MuConvert.ogk;`。
+```csharp
+// 首先使用File.ReadAllText等方法，将谱面整体读取为字符串
+var (ogkChart, alerts) = new OngekiParser().Parse(ogkrText); // 解析 OGKR 谱面字符串
+// ogkChart即为OgkChart类的对象，包含了谱面中的所有信息；alerts是解析过程中可能产生的警告信息等，建议打印出来（直接对Alert对象调用ToString()即可）。
+
+// 对ogkChart进行一些你想要的改动，例如把第一个Hold的时长加倍
+foreach (OgkNote note in ogkChart.Notes)
+{
+    if (note is Hold hold)
+    {
+        var originDuration = hold.EndTime - hold.StartTime; // 计算原始时长
+        hold.EndTime = originDuration * 2 + hold.StartTime; // 把第一个Hold的时长加倍
+        break;
+    }
+}
+
+var (ogkrText, alerts) = new OngekiGenerator().Generate(ogkChart); // 将 OgkChart 对象导出为 OGKR 文本
+// 同上，alerts是生成过程中可能产生的警告信息等，建议打印出来。
+```
+
 #### parser和generator的选项
 - 部分parser和generator，在其构造参数中带有可选的选项参数，可以控制转谱时的一些行为。
   - SimaiParser带有以下选项：
@@ -219,6 +251,8 @@ finally
 
 - **中间表示 IR（Chart）**：MuConvert 内部统一的谱面数据结构
   - 对maimai，类型为 `MuConvert.mai.MaiChart`
+  - 对CHUNITHM，类型为 `MuConvert.chu.ChuChart`
+  - 对Ongeki，类型为 `MuConvert.ogk.OgkChart`
   - 关键字段包括 `Chart.BpmList` 与 `Chart.Notes`，以及 `Touch/Hold/Slide` 等具体 `Note` 子类
 
 - **generator（生成器）**：把中间表示转回“目标格式文本”

chart/ogk/OgkChart.cs

@@ -8,7 +8,7 @@ public class OgkChart: BaseChart<OgkNote>
 {
     public string Designer { get; set; } = ""; // 谱师
 
-    public decimal ProgJudgeBpm = 240m; // 用于给Hold生成中间判定点的BPM值
+    public decimal ProgJudgeBpm = 240m; // 用于给Hold生成中间判定点的BPM值，绝大多数情况下不需要手动改动。
 
     // 全局声明的“子弹伤害类型与伤害数值的映射关系”。绝大多数情况下都是这个默认值，不需要做改动。
     public Dictionary<BulletDamage, decimal> BulletDamages = new() {

tests/ogk/Ogkr测试.cs

@@ -16,7 +16,7 @@ public class Ogkr测试
     public static IEnumerable<object[]> GetTestInputsOnlyLv3(string dataDir) => GetTestInputs(dataDir)
         .Where(x=>int.TryParse(((OgkrTestInput)x[0]).DifficultyId, out var id) && id == 3);
 
-    [Theory(Skip = "ogkr的解析和生成还没实现完，所以暂时跳过")]
+    [Theory]
     [MemberData(nameof(GetTestInputs), "官谱")]
     public void 解析Ogkr再生成回去(OgkrTestInput c)
     {
@@ -83,8 +83,11 @@ private void AssertOgkChartOk(OgkChart chart, IEnumerable<Alert> alerts)
 /// 1. [HEADER]：忽略 T_ 开头的统计量与 TUTORIAL，其余逐行严格比较。
 /// 2. [B_PALETTE]：不直接逐行比较；但要求 actual 内不存在两行“实质相同”
 ///    （除去 ID 之外其余字段全部相同）。
-/// 3. [COMPOSITION] / [LANE] / [LANE_BLOCK] / [BEAM] / [FLICK] / [NOTES]：逐行严格比较。
-/// 4. [BULLET] / [BELL]：逐行比较，但其中引用 B_PALETTE ID 的字段，比较的是
+/// 3. [COMPOSITION] / [LANE] / [BEAM] / [FLICK] / [NOTES]：逐行严格比较。
+/// 4. [LANE_BLOCK]：将每一行视为一个多重集元素进行比较（顺序不敏感）。
+///    这是因为官谱中观察到不同谱面对同一时刻的多条LBK使用了不同的排序约定，
+///    且其在游戏内并无实际顺序意义，故宽松比较以适应这一点。
+/// 5. [BULLET] / [BELL]：逐行比较，但其中引用 B_PALETTE ID 的字段，比较的是
 ///    所引用的 BPL 行的实质内容（去 ID 后的其余字段）是否相同，而非 ID 字面相等。
 ///
 /// 比较失败时，会打印差异所在 expected 中的行号（1-based）。
@@ -113,7 +116,7 @@ public static void AssertOgkrEqual(string expectedText, string actualText)
 
         CompareSimpleSection("COMPOSITION", expectedSections, actualSections);
         CompareSimpleSection("LANE", expectedSections, actualSections);
-        CompareSimpleSection("LANE_BLOCK", expectedSections, actualSections);
+        CompareUnorderedSection("LANE_BLOCK", expectedSections, actualSections);
         CompareSimpleSection("BEAM", expectedSections, actualSections);
         CompareSimpleSection("FLICK", expectedSections, actualSections);
         CompareSimpleSection("NOTES", expectedSections, actualSections);
@@ -176,6 +179,35 @@ private static void CompareSimpleSection(string section,
         CompareLinesStrict(section, expected, actual);
     }
 
+    /// <summary>
+    /// 把两个section内的所有行作为multiset做比较：只关心是否同时存在相同的行集合（含重数），不关心顺序。
+    /// </summary>
+    private static void CompareUnorderedSection(string section,
+        Dictionary<string, List<LineEntry>> expectedSections,
+        Dictionary<string, List<LineEntry>> actualSections)
+    {
+        var expected = expectedSections.TryGetValue(section, out var le) ? le : [];
+        var actual = actualSections.TryGetValue(section, out var la) ? la : [];
+
+        var expectedCounts = expected.GroupBy(e => e.Content).ToDictionary(g => g.Key, g => g.Count());
+        var actualCounts = actual.GroupBy(e => e.Content).ToDictionary(g => g.Key, g => g.Count());
+
+        var diffs = new List<string>();
+        foreach (var (k, ec) in expectedCounts)
+        {
+            actualCounts.TryGetValue(k, out var ac);
+            if (ac != ec) diffs.Add($"  missing/uneven in actual (expected x{ec}, actual x{ac}): {k}");
+        }
+        foreach (var (k, ac) in actualCounts)
+        {
+            if (!expectedCounts.ContainsKey(k)) diffs.Add($"  unexpected in actual (x{ac}): {k}");
+        }
+        if (diffs.Count > 0)
+        {
+            Assert.Fail($"[{section}] section (unordered) mismatch:{Environment.NewLine}{string.Join(Environment.NewLine, diffs)}");
+        }
+    }
+
     private static void CompareLinesStrict(string section, List<LineEntry> expected, List<LineEntry> actual)
     {
         var max = Math.Max(expected.Count, actual.Count);