PowGrade.FileConverters.DocToDocx 0.1.1

PowGrade.FileConverters.DocToDocx

PowGrade.FileConverters.DocToDocx 是一个面向 .NET 的 DOC -> DOCX 转换库，定位为“生产可集成 + 边界透明”的 best-effort 转换引擎：优先保证输出 DOCX 合法、可打开、可继续编辑，在此基础上尽可能恢复结构与语义。

代码审查结论（2026-03-30）

本次按“源码实现 + 测试 + 可执行验证”做了完整检查，结论如下：

• 核心主链路已完成并稳定：CFB/FIB/CLX/FKP/SPRM 到段落与 run 的恢复链路完整。
• 工程化可用性高：同步/异步、流式 API、取消、进度、结构化诊断、质量评分、批处理、CLI 均可运行。
• 当前阶段定位准确：常见文档可商用迁移（891/891 测试通过，17 个真实样本回归），但复杂版式对象（SmartArt/WordArt/ActiveX 等）仍以启发式重建和降级路径为主，不宜承诺像素级还原。详见 docs/功能完整性分析报告.md 与根目录 plan.md。

已执行的验证命令：

dotnet restore PowGrade.FileConverters.DocToDocx.sln
dotnet build PowGrade.FileConverters.DocToDocx.sln -c Release --no-restore
dotnet vstest src/PowGrade.FileConverters.DocToDocx.Tests/bin/Release/net8.0/PowGrade.FileConverters.DocToDocx.Tests.dll '/Logger:Console;Verbosity=minimal'
dotnet pack src/PowGrade.FileConverters.DocToDocx/PowGrade.FileConverters.DocToDocx.csproj -c Release --no-build

验证结果：

• build 通过
• test 通过：863/863
• pack 通过

功能完成度评估

整体完成度建议：约 80%（生产可用，边界明确）。

缺失与不完整项

以下项来自当前代码中的明确信号，不是推测：

1. 宏仅元数据层面保留，未进入可执行语义转换
   • WriteVbaProject 仍是占位方法，未实现宏启用文档语义写出。
2. 图片颜色调整尚未实现
   • WriteColorAdjustments 明确标注为未来实现占位。
3. SmartArt/WordArt/ActiveX/连接符主要为启发式恢复
   • 相关 reader 位于 StubReaders.cs，以形状和文本推断对象语义，不是原生对象等价重建。
4. 表格平铺恢复启发式被禁用
   • NeedsFlatTableRecovery 当前固定返回 false，说明该恢复通道因误报风险仍关闭。
5. 表格空单元格语义刚完成首轮补齐
   • 当前已为“行内后续空单元格”补齐占位段落模型并增加测试，后续仍需继续覆盖复杂嵌套与合并边界。
6. 风险模型明确提示多个高风险特性仍依赖 fallback
   • 宏、保护、OLE、图表、SmartArt、WordArt、ActiveX、复杂布局均在 BuildRecoveryPaths 中被归类为风险恢复路径。
7. 文档与代码语义存在历史遗留命名
   • ImageReader 头注释仍写“Phase 1 stub”，但当前实现已包含多阶段提取逻辑，文档表达不一致。

改进计划（建议执行顺序）

P0（优先解决：影响可用性和可信度）

1. 补齐图表高保真链路

   • 目标：减少 chart-data-reconstruction 触发率，提升复杂 BIFF 图表可编辑性。
   • 交付：新增复杂图表样本 + 回归断言（轴/系列/图例/数据标签） + 质量分提升基线。

2. 加强表格边界处理

   • 目标：解决空单元格与复杂嵌套下的误恢复/过降级。
   • 交付：完成空单元格逻辑、对平铺恢复引入可控开关和误报保护测试。

P1（优先增强：提升复杂文档保真）

3. 推进 OLE/公式对象语义化

   • 目标：减少文本占位与图像占位，提升可编辑对象比例。
   • 交付：细化 OLE 类型映射，补齐更多公式来源解析（字段 + OLE + 预览联合判定）。

4. 补齐图片效果链路

   • 目标：实现颜色调整与常见图像效果落地写出。
   • 交付：实现 WriteColorAdjustments，增加视觉回归样本与效果比对测试。

P2（中期建设：实验性能力转“部分可用”）

5. 高级对象分层推进

   • 目标：SmartArt/WordArt/ActiveX/连接符从“启发式可见”提升到“可编辑语义可控”。
   • 交付：按对象类型建立独立样本集、能力开关、风险诊断细分和质量评分权重。

6. 收敛注释与文档一致性

   • 目标：消除“stub/phase”历史注释与现状不一致，降低维护认知成本。
   • 交付：统一 README、支持矩阵、源码注释与风险术语。

计划执行进展

• 2026-03-30（第 1 步，P0-表格边界）：已完成 FlushCurrentCell 空单元格首轮补齐，实现“已有前序单元格时为空单元格注入占位段落模型”，并新增 2 个 TableReaderTests 用例验证行为。
• 2026-03-30（第 2 步，P0-图表链路）：已增强短序列多系列图（categories <= 3）的类型判定，对数值型类别可进入 scatter 启发式，同时保留对强名称信号（如 bar）的优先约束，避免错误覆盖；新增 1 个 BiffChartScannerTests 回归用例验证该路径。
• 2026-03-30（第 3 步，P0-图表链路）：已修复 CHARTFORMAT 图例元数据在后续布局阶段被覆盖的问题；当格式记录明确给出 legend 信息时，单系列自动隐藏图例与自动重定位将不再覆盖该元数据。新增 1 个 BiffChartScannerTests 用例验证“格式记录优先”的行为。
• 2026-03-30（第 4 步，P0-图表链路）：已新增对数坐标轴与数据范围冲突的保护；当值轴开启对数刻度但数据含非正值时，自动回退到线性刻度并记录恢复诊断，避免生成潜在无效轴配置。新增 2 个 BiffChartScannerTests 用例覆盖“回退/保留”两种路径。
• 2026-03-30（第 5 步，P0-图表链路）：已补齐轴范围归一化保护；当解析后出现 axisMax <= axisMin 时自动扩展范围并记录恢复诊断，避免输出不可用的轴区间。新增 2 个 BiffChartScannerTests 用例覆盖值轴与分类轴的常量场景。
• 2026-03-30（第 6 步，P0-图表链路）：已修复分类轴对数刻度的正值判定一致性；从“存在正值即可”调整为“全部为正值才允许保留对数刻度”，并新增 2 个 BiffChartScannerTests 用例覆盖“禁用/保留”路径。
• 2026-03-30（第 7 步，P0-图表链路）：已补齐轴主刻度步长归一化保护；当值轴或分类轴主刻度步长 <= 0 时自动清除并回退自动步长，避免写出无效轴刻度配置。新增 2 个 BiffChartScannerTests 用例覆盖值轴与分类轴路径。
• 2026-03-30（第 8 步，P0-图表链路）：已补齐轴主刻度步长上限归一化；当主刻度步长大于轴跨度时自动按跨度重算为合理步长，避免输出“单步跨越全轴”的不可读刻度。新增 2 个 BiffChartScannerTests 用例覆盖值轴与分类轴路径。
• 2026-03-30（第 9 步，P0-图表链路）：已补齐主刻度异常值防护；当主刻度为 NaN 或 Infinity 时自动清除并回退自动步长，避免写出非法数值。新增 2 个 BiffChartScannerTests 用例覆盖值轴与分类轴路径。
• 2026-03-30（第 10 步，P0-图表链路）：已升级矩阵方向识别为“双候选布局 + 保守切换”策略；同时构建 row/column 两套候选布局并记录评分，仅在高置信的 tall-matrix 场景切换到 column-categories，避免广泛误切换。新增 2 个 BiffChartScannerTests 用例覆盖“column 优先”和“row 保持”路径。
• 2026-03-30（第 11 步，P0-图表链路）：已重构名称信号匹配为“词边界 + CamelCase 边界”判定，避免 barcode、proxy 之类子串误命中图表关键词，同时保持 PieSalesChart 等命名可识别。新增 1 个 BiffChartScannerTests 用例验证误命中抑制路径。
• 2026-03-30（第 12 步，P0-图表链路）：已引入稀疏类别槽位清洗；当多个序列在同一类别位均无数值时自动同步裁剪类别与各序列值，减少解析噪声对类型判定和坐标范围的干扰。该策略仅在多序列场景启用，单序列保留缺失位以维持原有语义。新增 1 个 BiffChartScannerTests 用例覆盖该路径。
• 2026-03-30（第 13 步，P0-图表链路）：已补齐类型检测证据链结构化输出；新增按来源分层的 src: 摘要，并在“数值轴证据压制圆形名称信号”时输出 conflict:circular-name-damped 标记，提升误判可解释性。新增 1 个 BiffChartScannerTests 用例验证证据输出路径。
• 2026-03-30（第 14 步，P0-图表链路）：已加入弱名称信号回退门槛；当仅凭弱 line 命名信号且缺少数据侧支持时回退为默认 Column，降低边界场景误判，同时保留强名称场景（如 bar）既有行为。新增 1 个 BiffChartScannerTests 用例覆盖该路径。
• 2026-03-30（第 15 步，P0-图表链路）：已细化 Line/Column 同分冲突判别：在多序列分类场景中，按“类别槽位密度 vs 序列数”决定走 Column 还是 Line，并输出新的 tie-break 证据标记。新增 1 个 BiffChartScannerTests 用例覆盖 dense-column 分支，并同步更新原 line 分支断言。
• 2026-03-30（第 16 步，P0-图表链路）：已在 Line/Column 同分冲突中加入趋势连续性二级判别；当类别维度更宽且多数序列呈低拐点趋势时优先 Line，并输出 multi-series-trend-line-preferred 证据，降低宽时序数据被误判为 Column 的概率。新增 1 个 BiffChartScannerTests 用例覆盖该路径。
• 2026-03-30（第 17 步，P0-图表链路）：已补齐趋势判别抗噪声能力，并新增振荡型二级分流；方向变化统计引入按序列跨度计算的噪声阈值，降低小幅抖动误触发，同时在宽类别且多序列强振荡时优先 Column（multi-series-oscillating-column-preferred）。新增 1 个 BiffChartScannerTests 用例覆盖该路径。
• 2026-03-30（第 18 步，P0-图表链路）：已引入跨序列趋势一致性评分；在宽类别多序列同分冲突中，若序列整体方向一致且拐点受控，则优先 Line（multi-series-consistent-trend-line-preferred），并保持振荡分流优先级不变。新增 1 个 BiffChartScannerTests 用例覆盖该路径，并同步修正既有趋势用例断言。

快速开始

基础转换

using PowGrade.FileConverters.DocToDocx;

DocToDocxConverter.Convert("input.doc", "output.docx");

异步 + 进度 + 取消

using PowGrade.FileConverters.DocToDocx;

var progress = new Progress<ConversionProgress>(p =>
{
    Console.WriteLine($"[{p.PercentComplete,3}%] {p.Stage}: {p.Message}");
});

await DocToDocxConverter.ConvertAsync(
    "input.doc",
    "output.docx",
    progress,
    password: null,
    enableHyperlinks: true,
    cancellationToken: CancellationToken.None);

读取诊断与质量评估

using PowGrade.FileConverters.DocToDocx;

var result = DocToDocxConverter.ConvertWithWarnings("input.doc", "output.docx");

Console.WriteLine($"quality={result.Metadata?.QualityAssessment.Score} grade={result.Metadata?.QualityAssessment.Grade} action={result.Metadata?.QualityAssessment.Recommendation}");

foreach (var path in result.Metadata?.RecoveryPaths ?? Array.Empty<ConversionRecoveryPath>())
{
    if (path.WasTriggered)
    {
        Console.WriteLine($"{path.FeatureId} => {path.RecoveryPath} ({path.RiskLevel}) x{path.TriggerCount}");
    }
}

CLI

doctodocx convert --input input.doc --output output.docx
doctodocx batch --files a.doc b.doc --output-dir out
doctodocx watch --watch-dir in --output-dir out
doctodocx validate --input input.doc
doctodocx history --stats
doctodocx config --show

样本与文档

• 真实样本目录：samples/
• 示例代码：examples/
• 支持矩阵：docs/支持矩阵.md
• 已知限制：docs/已知限制.md
• 完整性分析：docs/功能完整性分析报告.md
• 性能基线：docs/性能基线.md
• Reader 覆盖矩阵：docs/ms-doc-reader-coverage-matrix.md