Add strict in-place XLSX worksheet replacement

Author: shps951023

README.md

@@ -271,7 +271,7 @@ let counts = MiniExcel::save_as_sheets(
 
 Configure final sheet names as visible, hidden, or very hidden with `with_sheet_visibility(name, SheetVisibility::...)`. Matching is case-insensitive, the first visible sheet becomes active, and unknown names or an all-hidden workbook are rejected before output is created. Hidden states are UI organization, not data protection; hidden worksheets remain queryable.
 
-## Append To An Existing Workbook
+## Append Or Replace A Worksheet
 
 Use `MiniExcel::insert()` to atomically append a visible worksheet. A missing path creates a new workbook with the same row-count semantics:
 
@@ -291,7 +291,7 @@ assert_eq!(count, 1);
 
 `insert_with_schema()` accepts a fallible, one-pass dynamic iterator. Source rows are disk-spooled and the constant-memory backend retains only the current row while generating the donor workbook; style rebasing currently materializes the generated worksheet XML. `insert_serialized()` accepts Serde structs. Existing unrelated ZIP entries, worksheet identities, formulas, and cached values are preserved, and an existing workbook is replaced only after the rewritten package validates and syncs.
 
-The default `ExistingSheetPolicy::Reject` rejects duplicate worksheet names case-insensitively. `ExistingSheetPolicy::Replace` and `TargetRelationshipPolicy::RemoveSupported` are reserved for the replacement milestone and currently return an error before output is created. Insert writes XLSX packages, rejects macro-enabled `.xlsm` paths, creates visible worksheets, and rejects `WriteOptions::with_overwrite_file(true)` because workbook replacement is controlled by the insert policy.
+The default `ExistingSheetPolicy::Reject` rejects duplicate worksheet names case-insensitively. Use `ExistingSheetPolicy::Replace` to replace a worksheet in place while preserving its workbook order, ID, relationship/path, visibility, and active state. The default `TargetRelationshipPolicy::Reject` accepts only a plain target with no worksheet relationships. `RemoveSupported` can remove target-owned tables, drawings with exclusively owned images, comments, VML drawings, and external hyperlinks; pivots, external links, unknown relationships, and shared/global parts are rejected or preserved conservatively. Insert writes XLSX packages, rejects macro-enabled `.xlsm` paths, and rejects `WriteOptions::with_overwrite_file(true)` because workbook replacement is controlled by the insert policy.
 
 ## Typed Writing
 

README.zh-CN.md

@@ -271,7 +271,7 @@ let counts = MiniExcel::save_as_sheets(
 
 使用 `with_sheet_visibility(name, SheetVisibility::...)` 可按最终 sheet name 配置 visible、hidden 或 very hidden，名称匹配不区分大小写。第一个 visible sheet 自动成为 active；未知名称或全部隐藏的 workbook 会在创建输出前报错。隐藏状态只用于 UI 组织，不是数据保护，隐藏 worksheet 仍可查询。
 
-## 向现有工作簿追加 Worksheet
+## 追加或替换 Worksheet
 
 使用 `MiniExcel::insert()` 原子追加一张 visible worksheet。路径不存在时会新建 workbook，并保持相同的数据 row count 语义：
 
@@ -291,7 +291,7 @@ assert_eq!(count, 1);
 
 `insert_with_schema()` 接受可返回错误、只消费一次的动态 iterator。源 row 会先落盘 spool，constant-memory backend 在生成 donor workbook 时只保留当前 row；style rebase 当前仍会物化生成的 worksheet XML。`insert_serialized()` 接受 Serde struct。现有无关 ZIP entry、worksheet identity、formula 和 cached value 均会保留；只有重写 package 完成验证并同步后，才原子替换现有 workbook。
 
-默认的 `ExistingSheetPolicy::Reject` 会不区分大小写地拒绝重复 worksheet name。`ExistingSheetPolicy::Replace` 与 `TargetRelationshipPolicy::RemoveSupported` 预留给后续 replacement 里程碑，当前会在创建输出前返回错误。Insert 写入 XLSX package，拒绝 macro-enabled `.xlsm` path，只创建 visible worksheet，并拒绝 `WriteOptions::with_overwrite_file(true)`，因为 workbook replacement 由 Insert policy 控制。
+默认的 `ExistingSheetPolicy::Reject` 会不区分大小写地拒绝重复 worksheet name。使用 `ExistingSheetPolicy::Replace` 可原位替换 worksheet，并保留其 workbook 顺序、ID、relationship/path、visibility 与 active state。默认 `TargetRelationshipPolicy::Reject` 只接受没有 worksheet relationship 的 plain target。`RemoveSupported` 可删除 target-owned table、drawing 及其独占 image、comment、VML drawing 和 external hyperlink；pivot、external link、未知 relationship 与 shared/global part 会被拒绝或保守保留。Insert 写入 XLSX package，拒绝 macro-enabled `.xlsm` path，并拒绝 `WriteOptions::with_overwrite_file(true)`，因为 workbook replacement 由 Insert policy 控制。
 
 ## 类型化写入
 

docs/compatibility.md

@@ -47,7 +47,7 @@ The latest `calamine 0.36` and `rust_xlsxwriter 0.97` require Rust 1.88. The MVP
 | Dynamic export | `save_as()` / `save_as_with_schema()` | Map serialization is implemented internally |
 | Typed export | `save_as_serialized<T>()` | Uses Serde mapping internally |
 | Multi-sheet export | `save_as_sheets()` / `save_as_serialized_sheets()` | Preserves input sheet order and returns data-row counts |
-| `InsertSheet` append | `insert()` / `insert_with_schema()` / `insert_serialized()` | Atomically appends a visible worksheet; missing paths create a workbook; replacement is deferred |
+| `InsertSheet` append/replace | `insert()` / `insert_with_schema()` / `insert_serialized()` | Atomic append; strict in-place replacement preserves sheet identity and has an explicit relationship policy |
 | Per-sheet visibility | `WriteOptions::with_sheet_visibility()` | Visible, hidden, and very hidden; first visible sheet is active |
 | `overwriteFile` | `WriteOptions::with_overwrite_file()` | Defaults to `false`; existing paths require explicit opt-in |
 | `FreezeRowCount` / `FreezeColumnCount` | `WriteOptions::with_freeze_row_count()` / `with_freeze_column_count()` | Defaults to one frozen row and zero frozen columns |
@@ -174,12 +174,12 @@ The contract covers only the current common surface: dynamic/typed path queries,
 | Addressed JSONL/Markdown/manifest RAG export | Rust research extension | No |
 | Async APIs, DataReader, stream ownership | Deferred | No |
 | Append worksheet to existing `.xlsx` workbook | Implemented and atomically committed | Rust tests; shared parity contract not yet extended |
-| Replace/edit existing worksheets | Deferred | No |
+| Strict worksheet replacement | Implemented for plain targets and supported target-owned closures | Rust tests; calculation policy remains deferred |
 | CSV and legacy formats | Deferred | No |
 | Advanced templates, pictures, merges, comments | Deferred | No |
 
 This matrix is the coverage claim: Rust does not yet provide complete API parity with the current .NET packages.
 
 ## Deferred Work
 
-SQL text parsing, `HAVING`, `ORDER BY`, joins, windows, pivots, disk-spill aggregation, vector indexing, model calls, CSV providers, old Excel formats, advanced template directives and sheet cloning, images, merged-cell APIs, formula calculation/dependency expansion, formula authoring, general styling, replacing/editing existing worksheets, async I/O, and streaming from caller-owned readers require separate design and acceptance milestones.
+SQL text parsing, `HAVING`, `ORDER BY`, joins, windows, pivots, disk-spill aggregation, vector indexing, model calls, CSV providers, old Excel formats, advanced template directives and sheet cloning, image authoring, merged-cell APIs, formula calculation/dependency expansion, formula authoring, general styling, replacement calculation-chain policy, async I/O, and streaming from caller-owned readers require separate design and acceptance milestones.

docs/compatibility.zh-CN.md

@@ -47,7 +47,7 @@ Rust MVP 在统一的 `MiniExcel` facade 后实现最小但实用的 MiniExcel 
 | 动态导出 | `save_as()` / `save_as_with_schema()` | map 序列化在内部实现 |
 | 类型化导出 | `save_as_serialized<T>()` | 内部使用 Serde 映射 |
 | 多工作表导出 | `save_as_sheets()` / `save_as_serialized_sheets()` | 保留输入工作表顺序并返回数据行数 |
-| `InsertSheet` append | `insert()` / `insert_with_schema()` / `insert_serialized()` | 原子追加 visible worksheet；路径不存在时创建 workbook；replacement 延后 |
+| `InsertSheet` append/replace | `insert()` / `insert_with_schema()` / `insert_serialized()` | 原子 append；严格原位 replacement 保留 sheet identity，并使用显式 relationship policy |
 | 每表 visibility | `WriteOptions::with_sheet_visibility()` | visible、hidden、very hidden；第一个 visible sheet 为 active |
 | `overwriteFile` | `WriteOptions::with_overwrite_file()` | 默认 `false`；已有路径需要显式允许覆盖 |
 | `FreezeRowCount` / `FreezeColumnCount` | `WriteOptions::with_freeze_row_count()` / `with_freeze_column_count()` | 默认冻结一行、零列 |
@@ -174,12 +174,12 @@ Rust workflow 会在 Linux 和 Windows 上运行 Rust 契约。其 .NET parity j
 | 带地址 JSONL/Markdown/manifest RAG 导出 | Rust 研究扩展 | 否 |
 | Async API、DataReader、stream ownership | 延后 | 否 |
 | 向现有 `.xlsx` workbook 追加 worksheet | 已实现并原子提交 | Rust 测试；共享 parity contract 尚未扩展 |
-| 替换/编辑现有 worksheet | 延后 | 否 |
+| 严格 worksheet replacement | 已支持 plain target 与受支持的 target-owned closure | Rust 测试；calculation policy 仍延后 |
 | CSV 和旧格式 | 延后 | 否 |
 | 高级 template、picture、merge、comment | 延后 | 否 |
 
 此矩阵就是覆盖声明：Rust 目前尚未提供与当前 .NET package 完整的 API 等价性。
 
 ## 延后工作
 
-SQL 文本解析、`HAVING`、`ORDER BY`、join、window、pivot、磁盘 spill 聚合、向量索引、模型调用、CSV provider、旧 Excel 格式、高级 template 指令与 sheet 克隆、image、merged-cell API、公式计算/依赖展开、公式编写、通用 style、替换/编辑现有 worksheet、async I/O，以及从调用方拥有的 reader 流式读取，都需要独立的设计与验收里程碑。
+SQL 文本解析、`HAVING`、`ORDER BY`、join、window、pivot、磁盘 spill 聚合、向量索引、模型调用、CSV provider、旧 Excel 格式、高级 template 指令与 sheet 克隆、image authoring、merged-cell API、公式计算/依赖展开、公式编写、通用 style、replacement calculation-chain policy、async I/O，以及从调用方拥有的 reader 流式读取，都需要独立的设计与验收里程碑。

docs/insert-existing-workbook-plan.md

@@ -278,12 +278,14 @@ Acceptance:
 
 Depends on Task 6.
 
-- [ ] Preserve the target sheet element's order, `sheetId`, relationship ID, target path, visibility, and active state.
-- [ ] Inspect the target worksheet relationship closure before replacement.
-- [ ] Under default `TargetRelationshipPolicy::Reject`, reject tables, drawings, comments, hyperlinks, pivots, external links, and unknown relationship types.
-- [ ] Under `RemoveSupported`, remove only explicitly supported target-owned parts and their content-type entries; never delete shared/global parts.
-- [ ] Replace only the target worksheet XML and its local AutoFilter defined name.
-- [ ] Reject case-insensitive duplicate ambiguity.
+- [x] Preserve the target sheet element's order, `sheetId`, relationship ID, target path, visibility, and active state.
+- [x] Inspect the target worksheet relationship closure before replacement.
+- [x] Under default `TargetRelationshipPolicy::Reject`, reject tables, drawings, comments, hyperlinks, pivots, external links, and unknown relationship types.
+- [x] Under `RemoveSupported`, remove only explicitly supported target-owned parts and their content-type entries; never delete shared/global parts.
+- [x] Replace only the target worksheet XML and its local AutoFilter defined name.
+- [x] Reject case-insensitive duplicate ambiguity.
+
+Completed on 2026-08-24. Focused test: `cargo +1.85.0 test -p miniexcel --test insert replace_sheet --locked`.
 
 Acceptance:
 

docs/insert-existing-workbook-plan.zh-CN.md

@@ -278,12 +278,14 @@ Donor-workbook 方案复用经过测试的 `XlsxWriter`，避免重复实现 ser
 
 依赖 Task 6。
 
-- [ ] 保留目标 sheet element 的顺序、`sheetId`、relationship ID、target path、visibility 与 active 状态。
-- [ ] replacement 前检查目标 worksheet relationship closure。
-- [ ] 默认 `TargetRelationshipPolicy::Reject` 拒绝 table、drawing、comment、hyperlink、pivot、external link 和未知 relationship type。
-- [ ] `RemoveSupported` 只删除明确支持的 target-owned part 与 content-type entry，绝不删除 shared/global part。
-- [ ] 只替换目标 worksheet XML 与其 local AutoFilter defined name。
-- [ ] 拒绝大小写不敏感时产生的 duplicate ambiguity。
+- [x] 保留目标 sheet element 的顺序、`sheetId`、relationship ID、target path、visibility 与 active 状态。
+- [x] replacement 前检查目标 worksheet relationship closure。
+- [x] 默认 `TargetRelationshipPolicy::Reject` 拒绝 table、drawing、comment、hyperlink、pivot、external link 和未知 relationship type。
+- [x] `RemoveSupported` 只删除明确支持的 target-owned part 与 content-type entry，绝不删除 shared/global part。
+- [x] 只替换目标 worksheet XML 与其 local AutoFilter defined name。
+- [x] 拒绝大小写不敏感时产生的 duplicate ambiguity。
+
+已于 2026-08-24 完成。聚焦测试：`cargo +1.85.0 test -p miniexcel --test insert replace_sheet --locked`。
 
 验收：
 

miniexcel/src/facade.rs

@@ -474,9 +474,13 @@ impl MiniExcel {
             writer.save(path, false)?;
             return Ok(rows.len());
         }
-        crate::insert::atomic::append_to_path(path, options.write_options().sheet_name(), || {
-            crate::insert::donor::DonorBuilder::from_dynamic(rows, options.write_options())
-        })
+        crate::insert::atomic::insert_to_path(
+            path,
+            options.write_options().sheet_name(),
+            options.existing_sheet_policy(),
+            options.target_relationship_policy(),
+            || crate::insert::donor::DonorBuilder::from_dynamic(rows, options.write_options()),
+        )
     }
 
     /// Inserts a one-pass dynamic row iterator using an explicit schema.
@@ -506,13 +510,19 @@ impl MiniExcel {
                 options.write_options(),
             );
         }
-        crate::insert::atomic::append_to_path(path, options.write_options().sheet_name(), || {
-            crate::insert::donor::DonorBuilder::from_dynamic_iter(
-                schema,
-                rows,
-                options.write_options(),
-            )
-        })
+        crate::insert::atomic::insert_to_path(
+            path,
+            options.write_options().sheet_name(),
+            options.existing_sheet_policy(),
+            options.target_relationship_policy(),
+            || {
+                crate::insert::donor::DonorBuilder::from_dynamic_iter(
+                    schema,
+                    rows,
+                    options.write_options(),
+                )
+            },
+        )
     }
 
     /// Inserts Serde-serializable rows as a new worksheet.
@@ -536,9 +546,13 @@ impl MiniExcel {
             writer.save(path, false)?;
             return Ok(rows.len());
         }
-        crate::insert::atomic::append_to_path(path, options.write_options().sheet_name(), || {
-            crate::insert::donor::DonorBuilder::from_serialized(rows, options.write_options())
-        })
+        crate::insert::atomic::insert_to_path(
+            path,
+            options.write_options().sheet_name(),
+            options.existing_sheet_policy(),
+            options.target_relationship_policy(),
+            || crate::insert::donor::DonorBuilder::from_serialized(rows, options.write_options()),
+        )
     }
 
     /// Fills an existing XLSX template and writes a new workbook.
@@ -586,21 +600,12 @@ fn validate_insert_options(path: &Path, options: &InsertOptions) -> Result<()> {
             "overwrite_file does not apply to Insert; use ExistingSheetPolicy",
         ));
     }
-    match options.existing_sheet_policy() {
-        ExistingSheetPolicy::Reject => {}
-        ExistingSheetPolicy::Replace => {
-            return Err(crate::Error::unsupported_package_feature(
-                "worksheet replacement is not supported yet",
-            ));
-        }
-    }
-    match options.target_relationship_policy() {
-        TargetRelationshipPolicy::Reject => {}
-        TargetRelationshipPolicy::RemoveSupported => {
-            return Err(crate::Error::unsupported_package_feature(
-                "removing target worksheet relationships is not supported yet",
-            ));
-        }
+    if options.existing_sheet_policy() == ExistingSheetPolicy::Reject
+        && options.target_relationship_policy() != TargetRelationshipPolicy::Reject
+    {
+        return Err(crate::Error::invalid_write_options(
+            "target relationship removal requires ExistingSheetPolicy::Replace",
+        ));
     }
     validate_single_sheet_options(options.write_options())
 }