格式 profile：importOfficial 以固定路徑讀取 styles／theme／fontTable，不依 relationship

[kiki830621]

Problem

importOfficial 讀取 styles、theme、fontTable 時，一律使用固定路徑（word/styles.xml 等），不看 word/_rels/document.xml.rels 裡的 relationship 實際指向哪個 part。

3.10.0 已經在匯入、套用、寫出三條路徑拒絕「同一 Type 出現兩筆 Target 不同的 relationship」（#196）。但如果範本只有一筆合法的 styles／theme／fontTable relationship，而它指向非預設路徑（OPC 允許），import 就會讀到過期的 part，或誤報「缺少」。

Expected

依 relationship 解析實際的 part 路徑，找不到時才報錯；或者明確拒絕非預設路徑，並在錯誤訊息裡說明。加上 Target 指向 word/customStyles.xml 之類 part 的測試。

Refs #196

---

Current Status

Phase: closed
Last updated: 2026-09-24 by /idd-close

Key Decisions

• importOfficial 依 relationship 解析 styles／theme／fontTable；DocxReader 端留給 ooxml-swift#173

Scope Changes

• (none)

Blocking

• (none)

Commits

• ooxml-swift 1688fa6、d0aa7b5（v3.11.0）；macdoc 5a31f56；CLI 0.11.0

[kiki830621]

Implementation Complete

隨 ooxml-swift v3.11.0 發布（PR PsychQuant/ooxml-swift#170，rebase merge），下游 che-word-mcp 4.3.0 與 macdoc CLI 0.11.0 已升級。

Commits（ooxml-swift main）：

• 1688fa6 importOfficial 依 relationship 解析 styles／theme／fontTable 的實際 part
• d0aa7b5 CHANGELOG 註明沒有 rels part 的最小合成範本會被拒絕

根因

importOfficial 的 read("word/styles.xml")、read("word/theme/theme1.xml")、read("word/fontTable.xml") 都寫死路徑。3.10.0 雖然已經檢查 relationship 是否重複，但從來沒有用 relationship 去找 part。numbering 的拒絕檢查也同樣寫死 word/numbering.xml。

決定與理由

照定案，改依 relationship 解析。新增 ProfileXML.implicitPart(of:in:)，沿用 normalizedRelationshipTarget 的詞法正規化，以及重複、結尾斜線的檢查，再以解析出來的名稱精確比對 ZIP entry。整個過程都在記憶體裡完成，不解壓到磁碟，也不會讀到套件外的檔案。

• styles：沒有 relationship（包括整個 rels part 不存在）→ missingRequiredFormatting("word/_rels/document.xml.rels 沒有 styles relationship")。
• relationship 指向不存在的 part → missingRequiredFormatting("<type> relationship 的 Target「…」指向不存在的 part …")。
• TargetMode="External" → invalidSnapshot。這裡刻意不沿用 invalidRelationshipTarget，因為那個 case 的說明文字寫的是「結尾斜線」。
• theme／fontTable 是選用的：沒有 relationship 就視為不存在，預設路徑上的孤立 part 不讀。如果樣式仍引用 theme 字型，會照舊以 theme used by styles 拒絕。
• numbering（範圍稍微擴大，理由如下）：同一個函式裡也有固定路徑的假設，不改的話，放在非預設路徑的 numbering 會繞過第一版的拒絕規則。numbering 只用來判斷要不要拒絕、不會存進快照，所以採保守做法：relationship 指向的 part 和預設的 word/numbering.xml 都檢查。這樣做只可能多拒絕一些範本，不會改變快照內容，既有的 testImportRejectsNumberingMissingRequiredDataAndMalformedXML 也維持有效。
• 主 part 仍固定是 word/document.xml，沒有去讀 _rels/.rels。

套用與寫出路徑

writer 一律把格式 part 發布到預設路徑，並把同 Type 的每一筆 relationship 都改指向它。這是 3.10.0 的決策，已有 old-styles.xml 修復測試鎖住，所以寫出的套件本身是一致的。仍然存在的固定路徑假設在讀取端：DocxReader 以固定路徑讀進既有文件的 styles／theme／fontTable／numbering，effectiveFormattingPartData 也從 archive 的固定路徑回退讀取。因此如果一份既有文件的 relationship 指向非預設 part，套用 profile 或做 typed style 編輯時，會以預設路徑上的內容（或空白）為準，改指之後原本的 part 就成了孤立 part。這一點已寫在 writeFormattingParts 的註解與 CHANGELOG。

Checklist

• importOfficial 依 word/_rels/document.xml.rels 解析 styles／theme／fontTable 的實際 part
• 沿用 3.10.0 的詞法正規化與同 Type 重複檢查（另加 External 拒絕）
• 測試：Target 指向 word/customStyles.xml（四種拼法，包含 ../formatting/styles.xml），預設路徑上有過期 part 也不會被讀到
• 測試：只有非預設 part、沒有預設路徑 part 的範本可以匯入（3.10.0 會誤報缺少）
• 測試：styles／theme／fontTable／numbering 的 relationship 指向不存在的 part 時拒絕
• 測試：沒有 styles relationship、沒有 rels part 時拒絕；孤立的 theme／fontTable 不讀
• numbering 依 relationship 檢查，同時保留預設路徑檢查；重複、結尾斜線、External 都拒絕
• 真實範本：implicitPart 在兩份 Word 範本上都解析到預設 part
• 套用與寫出的固定路徑假設已檢查，說明寫在註解與 CHANGELOG

測試（RED → GREEN）

RED 時 testImportReadsFormattingPartsNamedByRelationships 在四種拼法下都讀到「Stale」內容（24 個斷言失敗）。testImportSucceedsWhenFormattingPartsExistOnlyAtRelationshipTargets 丟出 missingRequiredFormatting("word/styles.xml")。missing-target、無 styles relationship、External、numbering 的各項測試都是「did not throw」。實作後全部 GREEN。

完整 swift test：1668 tests，0 failures（v3.10.0 為 1648，新增 20 個）。

已知限制

• 既有文件的讀取端（DocxReader）仍然用固定路徑。
• 主 part 固定為 word/document.xml。
• ZIP entry 以正規化後的名稱精確比對。Target 寫 %20、ZIP 內卻是字面空白的套件會被拒絕（fail closed）。

Follow-up

• DocxReader 讀取端仍以固定路徑讀 styles／theme／fontTable／numbering，主 part 固定為 word/document.xml：已開 DocxReader 以固定路徑讀 styles／theme／fontTable／numbering 與主 part，與 importOfficial 依 relationship 解析不一致 ooxml-swift#173 追蹤。

[kiki830621]

Verify: #213

Backend：Codex（gpt-6-astra），ooxml-swift 分支兩輪。

• 第一輪（diff：tmp/ooxml212-r1.patch，結果：tmp/ooxml212-r1-codex.md）：VERDICT: PASS。提出三點：

  • MEDIUM：宣告解析器太寬鬆。缺 version、Encoding= 大小寫不同、順序錯誤、pseudo-attribute 之間沒空白，都會被放行。
  • MEDIUM：宣告出現在註解或 PI 之後、重複宣告、寫成 <?XML，都被當成「沒有宣告」。
  • LOW：apply 路徑的 payload 檢查沒有直接測試。

  兩個 MEDIUM 都已在 19ef86a 修掉：改依 XMLDecl 文法驗證，並掃描其餘 prolog。修正前先補測試跑出 RED（22 個 failure），再改到 GREEN。LOW 的處理：公開 API 無法建出不合法的 profile（memberwise init 是 private，importOfficial 與 init(from:) 都會驗證），所以在測試註解寫明這個不變量，另外在 decode 補上 NUL、無法解析、位置不合法三種案例。

• 第二輪（diff：tmp/ooxml212-r2.patch，結果：tmp/ooxml212-r2-codex.md）：VERDICT: PASS，沒有新的問題，確認前一輪的修正正確，也沒有誤拒 Word 常見的宣告寫法。

測試：ooxml-swift 完整 swift test 1668 tests，0 failures（24 skipped；比 v3.10.0 多 20 個）；PR PsychQuant/ooxml-swift#170 的 build 與 CodeQL 全綠。

下游：沒有 rels part 的合成範本現在會被拒絕。che-word-mcp 與 macdoc 的 profile 測試 fixture 已補上 rels；未補時分別有 8／11、13／13 個測試失敗（RED），補上後全過。macdoc 兩個「缺欄位」的拒絕測試改為斷言錯誤指名的欄位，避免因錯的理由通過。che-word-mcp 4.3.0（415 tests）與 macdoc 0.11.0（完整測試全綠）都已隨 3.11.0 發布。

限制：Codex 做的是靜態審查。

[kiki830621]

Closing Summary

Problem

importOfficial 以固定路徑讀 styles／theme／fontTable，relationship 指向別處時讀到錯的 part，或誤報缺少。

Root Cause

read("word/styles.xml") 等寫死路徑，從來沒有用 relationship 找 part；numbering 的拒絕檢查同樣寫死。

Solution

新增 ProfileXML.implicitPart(of:in:)，依 word/_rels/document.xml.rels 解析實際 part（沿用 3.10.0 的正規化與重複檢查，另拒絕 External）；沒有 styles relationship 或 rels part 時拒絕；theme／fontTable 沒有 relationship 就視為不存在；numbering 依 relationship 與預設路徑都檢查。

Verification

Codex 兩輪 PASS；ooxml-swift 1668 tests、0 failures；四種 Target 拼法都讀到正確 part、預設路徑上的過期 part 不會被讀到。下游 fixture 補上 rels 前，che-word-mcp 8／11、macdoc 13／13 個 profile 測試失敗（RED），補上後全過。詳見 Verify。

Changes

ooxml-swift 1688fa6、d0aa7b5（v3.11.0，PR #170）；che-word-mcp 4.3.0、macdoc 5a31f56e／CLI 0.11.0。

Follow-up

PsychQuant/ooxml-swift#173：DocxReader 讀取端與主 part 仍用固定路徑。