mini-software
diff --git a/‎.github/workflows/rust.yml‎
Lines changed: 31 additions & 0 deletions b/‎.github/workflows/rust.yml‎
Lines changed: 31 additions & 0 deletions
diff --git a/‎Cargo.lock‎
Lines changed: 11 additions & 0 deletions b/‎Cargo.lock‎
Lines changed: 11 additions & 0 deletions
diff --git a/‎Cargo.toml‎
Lines changed: 1 addition & 0 deletions b/‎Cargo.toml‎
Lines changed: 1 addition & 0 deletions
diff --git a/‎README.md‎
Lines changed: 22 additions & 0 deletions b/‎README.md‎
Lines changed: 22 additions & 0 deletions
diff --git a/‎README.zh-CN.md‎
Lines changed: 21 additions & 0 deletions b/‎README.zh-CN.md‎
Lines changed: 21 additions & 0 deletions
diff --git a/‎docs/compatibility.md‎
Lines changed: 3 additions & 0 deletions b/‎docs/compatibility.md‎
Lines changed: 3 additions & 0 deletions
diff --git a/‎docs/compatibility.zh-CN.md‎
Lines changed: 3 additions & 0 deletions b/‎docs/compatibility.zh-CN.md‎
Lines changed: 3 additions & 0 deletions
diff --git a/‎docs/dotnet-feature-gaps.md‎
Lines changed: 9 additions & 9 deletions b/‎docs/dotnet-feature-gaps.md‎
Lines changed: 9 additions & 9 deletions
@@ -132,6 +132,37 @@ jobs:
           --filter "FullyQualifiedName~MiniExcelOpenXmlTableTests"
           --verbosity minimal
 
+  comments-parity:
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - name: Checkout MiniExcel .NET
+        uses: actions/checkout@v4
+        with:
+          repository: mini-software/MiniExcel
+          ref: b9a76d7af62142e0e38545b6905b01a06e8d160e
+          path: dotnet-source
+      - name: Install Rust 1.85.0
+        uses: dtolnay/rust-toolchain@1.85.0
+      - uses: Swatinem/rust-cache@v2
+        with:
+          key: comments-parity-${{ matrix.os }}
+      - name: Setup .NET
+        uses: actions/setup-dotnet@v4
+        with:
+          dotnet-version: 10.0.x
+      - name: Run Rust comments tests
+        run: cargo +1.85.0 test -p miniexcel --test comments --locked
+      - name: Run MiniExcel .NET comments tests
+        run: >-
+          dotnet test dotnet-source/tests/MiniExcel.OpenXml.Tests/MiniExcel.OpenXml.Tests.csproj
+          --framework net10.0
+          --filter "FullyQualifiedName~CommentsRetrievalTests"
+          --verbosity minimal
+
   msrv:
     runs-on: ubuntu-latest
     steps:
 
@@ -30,6 +30,7 @@ serde_json = "1.0.145"
 sha2 = "0.10.9"
 tempfile = "3.23.0"
 thiserror = "2.0.17"
+uuid = "1.18.1"
 wasm-bindgen = "0.2.127"
 zip = { version = "7.2.0", default-features = false, features = ["deflate"] }
 
 
@@ -222,6 +222,28 @@ the first worksheet is searched. Column names come from table metadata, the phys
 skipped unless `headerRowCount="0"`, and the complete declared range is returned, including totals
 rows. Path queries retain the existing bounded-memory two-pass worksheet pipeline.
 
+### Comments And Notes
+
+Read threaded comments and legacy notes without reading worksheet rows:
+
+```rust
+let comments = MiniExcel::get_comments("book.xlsx", Some("Data"))?;
+
+for thread in comments.threaded_comments() {
+    println!("{}: {}", thread.cell(), thread.text());
+    for reply in thread.replies() {
+        println!("  {}", reply.text());
+    }
+}
+```
+
+`get_comments_from_bytes()` and `get_comments_from_reader()` provide the same metadata for
+in-memory and borrowed sources. Results include typed UUIDs and cell references, people, provider
+and user IDs, resolution state, local or offset timestamps, replies, and legacy note authors/text.
+Compatibility-shadow notes are suppressed only when their `tc={thread-id}` author marker and cell
+both match a threaded root; unrelated notes at the same cell remain visible. Comment metadata is
+materialized, while worksheet rows are never read.
+
 ## Typed Reading
 
 ```rust
 
@@ -221,6 +221,27 @@ let rows = MiniExcel::query_table("book.xlsx", "SalesTable", Some("Data"))?
 Column name 来自 table metadata；除非 `headerRowCount="0"`，否则会跳过物理 header row；
 返回完整声明 range，包括 totals row。Path query 继续使用既有有界内存两遍 worksheet pipeline。
 
+### Comments 与 Notes
+
+可在不读取 worksheet row 的情况下读取 threaded comment 与 legacy note：
+
+```rust
+let comments = MiniExcel::get_comments("book.xlsx", Some("Data"))?;
+
+for thread in comments.threaded_comments() {
+    println!("{}: {}", thread.cell(), thread.text());
+    for reply in thread.replies() {
+        println!("  {}", reply.text());
+    }
+}
+```
+
+`get_comments_from_bytes()` 与 `get_comments_from_reader()` 为内存和 borrowed source 提供
+相同 metadata。结果包含 typed UUID/cell reference、person、provider/user ID、resolved
+state、local 或 offset timestamp、reply，以及 legacy note author/text。只有 author marker
+为 `tc={thread-id}` 且 cell 同时匹配 threaded root 的 compatibility-shadow note 才会被
+抑制；同 cell 的无关 note 仍保留。Comment metadata 会物化，但不会读取 worksheet row。
+
 ## 类型化读取
 
 ```rust
 
@@ -23,6 +23,7 @@ The Rust MVP implements the smallest useful MiniExcel-style XLSX read/write surf
 | `serde_json` | 1.x | Query plans, analytics/RAG output, parity contracts, and CLI JSON | MIT OR Apache-2.0 | Checked with Rust 1.85 |
 | `sha2` | 0.10 | Streaming SHA-256 source identity for RAG manifests | MIT OR Apache-2.0 | Checked with Rust 1.85 |
 | `thiserror` | 2.x | Public error composition | MIT OR Apache-2.0 | Resolved by the workspace lockfile |
+| `uuid` | 1.x | Typed threaded-comment, reply, person, and legacy-note identifiers | MIT OR Apache-2.0 | Resolved by the workspace lockfile |
 | `zip` | 7.2 | Incremental worksheet entry decompression | MIT | Locked and checked with Rust 1.85 |
 
 The latest `calamine 0.36` and `rust_xlsxwriter 0.97` require Rust 1.88. The MVP pins the preceding API lines so the declared Rust 1.85 MSRV is executable rather than aspirational.
@@ -43,6 +44,7 @@ The latest `calamine 0.36` and `rust_xlsxwriter 0.97` require Rust 1.88. The MVP
 | `GetSheetDimensions` | `MiniExcel::get_sheet_dimensions()` | Returns used ranges in workbook order with 1-based indices |
 | `GetColumns` | `MiniExcel::get_columns()` | Returns selected dynamic keys or an empty vector |
 | `QueryTable` | `query_table()` / `query_table_as()` / byte and borrowed-reader variants | Case-insensitive table-name lookup, metadata headers, and inclusive table bounds |
+| Retrieve comments and notes | `get_comments()` / bytes / borrowed-reader variants | Thread roots, replies, people, resolution/timestamps, and legacy notes |
 | `startCell` | `ReadOptions::with_start_cell()` | A1 start coordinate |
 | `IgnoreEmptyRows` | `ReadOptions::with_ignore_empty_rows()` | Defaults to `false` for MiniExcel compatibility |
 | `FillMergedCells` | `ReadOptions::with_fill_merged_cells()` | Defaults to `false`; applies to dynamic, typed, and byte queries |
@@ -172,6 +174,7 @@ The contract covers only the current common surface: dynamic/typed path queries,
 | `GetSheetInformations` ID/index/name/type/visibility/active | Implemented | Rust tests against .NET fixtures |
 | `GetSheetDimensions` | Implemented | Rust tests against .NET fixtures |
 | Named OpenXML `QueryTable` | Implemented | Rust and .NET focused tests against `TestQueryTable.xlsx` |
+| Threaded comments and legacy notes | Implemented | Rust and .NET focused tests against `TestCommentsAndNotes.xlsx` |
 | New-workbook `SaveAs`, including multiple sheets | Implemented and roundtrip-tested | Not yet |
 | Basic `SaveAsTemplate` scalar/list fill | Implemented and roundtrip-tested | Not yet |
 | Byte-array query/write for WASM | Implemented | Rust/browser tests |
 
@@ -23,6 +23,7 @@ Rust MVP 在统一的 `MiniExcel` facade 后实现最小但实用的 MiniExcel
 | `serde_json` | 1.x | Query plan、分析/RAG 输出、等价契约和 CLI JSON | MIT OR Apache-2.0 | 已使用 Rust 1.85 检查 |
 | `sha2` | 0.10 | 为 RAG manifest 流式计算 SHA-256 源身份 | MIT OR Apache-2.0 | 已使用 Rust 1.85 检查 |
 | `thiserror` | 2.x | 公共 error 组合 | MIT OR Apache-2.0 | 由 workspace lockfile 解析 |
+| `uuid` | 1.x | Typed threaded-comment、reply、person 与 legacy-note identifier | MIT OR Apache-2.0 | 由 workspace lockfile 解析 |
 | `zip` | 7.2 | 增量 worksheet entry 解压 | MIT | 已锁定并使用 Rust 1.85 检查 |
 
 最新的 `calamine 0.36` 和 `rust_xlsxwriter 0.97` 需要 Rust 1.88。MVP 固定使用前一条 API 版本线，使声明的 Rust 1.85 MSRV 可实际执行，而不只是目标。
@@ -43,6 +44,7 @@ Rust MVP 在统一的 `MiniExcel` facade 后实现最小但实用的 MiniExcel
 | `GetSheetDimensions` | `MiniExcel::get_sheet_dimensions()` | 按 workbook 顺序返回使用范围，index 从 1 开始 |
 | `GetColumns` | `MiniExcel::get_columns()` | 返回选中的动态 key，或空 vector |
 | `QueryTable` | `query_table()` / `query_table_as()` / byte 和 borrowed-reader variants | 大小写不敏感 table-name lookup、metadata header 与包含端点的 table bounds |
+| 读取 comments 与 notes | `get_comments()` / bytes / borrowed-reader variants | Thread root、reply、person、resolved/timestamp 与 legacy note |
 | `startCell` | `ReadOptions::with_start_cell()` | A1 起始坐标 |
 | `IgnoreEmptyRows` | `ReadOptions::with_ignore_empty_rows()` | 为兼容 MiniExcel，默认值为 `false` |
 | `FillMergedCells` | `ReadOptions::with_fill_merged_cells()` | 默认 `false`；适用于动态、类型化和 byte query |
@@ -172,6 +174,7 @@ Rust workflow 会在 Linux 和 Windows 上运行 Rust 契约。其 .NET parity j
 | `GetSheetInformations` ID/index/name/type/visibility/active | 已实现 | Rust 使用 .NET fixture 测试 |
 | `GetSheetDimensions` | 已实现 | Rust 使用 .NET fixture 测试 |
 | 命名 OpenXML `QueryTable` | 已实现 | Rust/.NET 使用 `TestQueryTable.xlsx` 的 focused test |
+| Threaded comments 与 legacy notes | 已实现 | Rust/.NET 使用 `TestCommentsAndNotes.xlsx` 的 focused test |
 | 新 workbook `SaveAs`（含多工作表） | 已实现并完成 roundtrip 测试 | 尚未 |
 | 基础 `SaveAsTemplate` 标量/列表填充 | 已实现并完成 roundtrip 测试 | 尚未 |
 | 用于 WASM 的字节数组 query/write | 已实现 | Rust/browser 测试 |
 
@@ -8,7 +8,7 @@ This report compares observable public capabilities in the local checkouts below
 
 | Project | Revision |
 | --- | --- |
-| MiniExcel-Rust | `1e3167222142a86710e05269f9fcbbba11185d22` (`0.3.0`) |
+| MiniExcel-Rust | `23bba2d448bc4fab14baf750152a7c83cb6ececc` (`0.3.0`) |
 | MiniExcel .NET | `b9a76d7af62142e0e38545b6905b01a06e8d160e` |
 
 The comparison uses the .NET public APIs, their controlling implementations, and focused tests under the sibling `../MiniExcel` checkout. Rust status is based on the public `MiniExcel` facade, options, integration tests, and [compatibility boundary](compatibility.md).
@@ -38,12 +38,12 @@ Rust already implements dynamic and Serde-typed XLSX path queries, inclusive A1
 | Templates | Partial | Rust fills path/byte templates with scalar values and single-row arrays while preserving package parts. Streams, grouping, conditions, parametrized sheets, `$=` formulas, formula-reference updates, and calculation-chain handling remain unsupported. |
 | Pictures and merge processing | Missing | Add anchored pictures and merge adjacent identical cells through the templater surface. Structured reads do not provide authoring parity. |
 | CSV | Missing | Dynamic/typed CSV query and save, append, columns, DataReader/DataTable, delimiter/newline/encoding/quoting configuration, and CSV/XLSX conversion. |
-| Comments and notes | Missing | Retrieve threaded comments, replies, people/authors, resolution state, timestamps, and legacy notes. |
+| Comments and notes | Implemented | Path/bytes/borrowed APIs return threaded roots, replies, unresolved person IDs, people/provider/user IDs, resolution state, typed timestamps, and legacy notes. |
 | Fluent mapping | Missing | Address-based object mapping, formula/format mappings, collection start cells and spacing, nested collections, and mapped import/export/template APIs. |
 | Attribute-based mapping | Partial | Column index/name attributes, localized headers, formula metadata, custom dynamic formatters, field mapping, and dynamic column ordering/filtering remain. Serde covers rename, alias, defaults, skips, options, and custom serializers; `WriteOptions` covers width/hidden layout by final header name. |
 | Read configuration | Partial | Culture-aware conversion, buffer/fast modes, and some null/empty-string behavior. Merged-cell filling and shared-string disk caching are implemented. |
 | Write configuration and style | Partial | OOXML tables, shared versus inline strings, and broader cell styling remain. Rust exposes default/minimal cell style modes, header output/style, AutoFilter, right-to-left views, frozen rows/columns, bounded AutoWidth, body wrapping/alignment, and number formats. |
-| Sheet metadata/workflow | Partial | Table metadata, comment metadata, dynamic sheet aliases, class-level sheet selection, and traversing all sheets through one reader. Rust already covers names, order, dimensions, visibility, and active state. |
+| Sheet metadata/workflow | Partial | Dynamic sheet aliases, class-level sheet selection, and traversing all sheets through one reader remain. Rust covers names, order, dimensions, visibility, active state, table metadata, and comments/notes. |
 | Provider/package model | Different by design | .NET composes OpenXML, CSV, templating, and fluent-mapping providers. Rust has a single XLSX crate plus CLI and WASM adapters; those adapters do not replace the missing provider capabilities. |
 
 ## Evidence Map
@@ -52,23 +52,23 @@ Rust already implements dynamic and Serde-typed XLSX path queries, inclusive A1
 | --- | --- | --- |
 | Public read/write boundary | `miniexcel/src/facade.rs`, `miniexcel/src/options.rs` | `src/MiniExcel.OpenXml/Api/OpenXmlImporter.cs`, `OpenXmlExporter.cs` |
 | Tables | `MiniExcel::query_table*`; Rust focused tests use the exact `TestQueryTable.xlsx` fixture (SHA-256 `04F719BF9F9E99D9B437A8FB32F8111FD92580A1D29ACAD10B6ED128C0564501`) | `OpenXmlImporter.QueryTableAsync`; `tests/MiniExcel.OpenXml.Tests/Tables/` |
+| Comments | `MiniExcel::get_comments*`; Rust focused tests use `TestCommentsAndNotes.xlsx` (SHA-256 `3A855CE896ED62DC27C91797432DD89EE081F07CD03AB05BF1B0CD745543A3FC`) | `OpenXmlImporter.RetrieveCommentsAsync`; `tests/MiniExcel.OpenXml.Tests/Comments/` |
 | DataReader/DataTable | Rust iterators and borrowed visitors are the native abstraction; no literal .NET tabular adapter is planned | `OpenXmlImporter.GetDataReader`, `GetAsyncDataReader`, `QueryAsDataTableAsync`; `tests/MiniExcel.OpenXml.Tests/DataReader/` |
 | Multi-sheet and workbook edits | Writer creates multiple sheets; existing workbooks support append and strict replacement with package preservation and bounded explicit-schema producers | `OpenXmlExporter.InsertSheetAsync`, `CopyAndAddSheetAsync`, `AlterSheetAsync`; `tests/MiniExcel.OpenXml.Tests/MultipleSheets/` and `AlterSheets/` |
 | Templates/pictures/merges | Basic template fill implemented; advanced directives and authoring remain deferred | `src/MiniExcel.OpenXml/Api/OpenXmlTemplater.cs`; `tests/MiniExcel.OpenXml.Tests/Templates/` |
 | CSV/conversion | XLSX-only core | `src/MiniExcel.Csv/Api/`; `src/MiniExcel/MiniExcelConverter.cs`; `tests/MiniExcel.Csv.Tests/` |
 | Mapping | Serde mapping only | `src/MiniExcel.Core/Attributes/MiniExcelColumnAttribute.cs`; `src/MiniExcel.OpenXml.FluentMapping/`; mapping tests |
-| Comments | No public comment model/API | `OpenXmlImporter.RetrieveCommentsAsync`; `src/MiniExcel.OpenXml/Models/Comments.cs`; comment tests |
+| Comments | `MiniExcel::get_comments*`; Rust focused tests use `TestCommentsAndNotes.xlsx` (SHA-256 `3A855CE896ED62DC27C91797432DD89EE081F07CD03AB05BF1B0CD745543A3FC`) | `OpenXmlImporter.RetrieveCommentsAsync`; `src/MiniExcel.OpenXml/Models/Comments.cs`; comment tests |
 | Configuration/style | Narrow `ReadOptions` and `WriteOptions` | `MiniExcelBaseConfiguration`, `OpenXmlConfiguration`, `OpenXmlStyleOptions`; exporter tests |
 
 The .NET APIs marked with `Async` also have generated synchronous counterparts through the repository's sync-version generation. The gap therefore concerns capability, not only method naming.
 
 ## Suggested Implementation Order
 
-1. **Comments and notes**: focused OpenXML read features with clear public result models.
-2. **CSV provider**: keep a separate format boundary rather than conditionals inside the XLSX parser.
-3. **Async query/export/template APIs**: extend runtime-neutral producer/cancellation patterns without presenting blocking ZIP work as async I/O.
-4. **Advanced templates and Fluent Mapping**: add grouped/conditional templates, parametrized sheets, and mapping through separate compatibility milestones.
-5. **Remaining workbook edits**: copy/add, rename, reorder, and standalone visibility mutation require their own preservation contracts.
+1. **CSV provider**: keep a separate format boundary rather than conditionals inside the XLSX parser.
+2. **Async query/export/template APIs**: extend runtime-neutral producer/cancellation patterns without presenting blocking ZIP work as async I/O.
+3. **Advanced templates and Fluent Mapping**: add grouped/conditional templates, parametrized sheets, and mapping through separate compatibility milestones.
+4. **Remaining workbook edits**: copy/add, rename, reorder, and standalone visibility mutation require their own preservation contracts.
 
 DataReader/DataTable are .NET ecosystem abstractions and are intentionally not literal Rust parity requirements. A Rust-native record-batch or tabular adapter is appropriate only when a concrete integration requires it.