# DOCX 批注（Word 原生 comment）插入 — 纯 zipfile+lxml

实战来源：南通新东方校外培训服务合同独立审查（2026-06-17）。Maggie 要求"用修订**和批注**的形式"。`ContractEditor` 没有批注方法（`dir()` 确认无 comment/annot/note），批注必须手写 OOXML。已验证可在 OnlyOffice 正常显示。

## 何时用 DOCX 批注 vs PDF 批注
- **docx 合同** → 用本文方法（Word 原生 comment，OnlyOffice 显示为右侧批注气泡）。
- **PDF 合同** → 用 pymupdf(fitz) 高亮+comment annotation（见 SKILL.md「PDF合同直接批注」）。两者不通用。

## 批注内容铁律（与 SKILL.md 一致，复述强调）
- 只写"建议……"，给方案；**不写理由/原因/因为**；**不加【新增】【建议】等标签**。
- 批注仅限两类：①需客户确认（名称空白、标准未定义需明示）；②建议增加条款且内容较长。**选择题/勾选项不处理（2026-07-08废止）。**
- 能直接修订的一律修订，批注是最后手段。

## 五个改动点（缺一不可，否则 Word 报"无法打开/需修复"）
1. **新增 `word/comments.xml`**：定义每条批注的 id/author/date/initials + 内容。
2. **`word/document.xml`**：在锚点文本范围**前**插 `w:commentRangeStart`、**后**插 `w:commentRangeEnd` + 一个带 `w:commentReference` 的 run。
3. **`[Content_Types].xml`**：加 `Override` 声明 comments.xml 的 content-type。
4. **`word/_rels/document.xml.rels`**：加 `Relationship` 指向 comments.xml。
5. 三处 id（rangeStart/rangeEnd/commentReference）与 comments.xml 的 `w:comment/@w:id` **必须全部一致**。

## 锚点定位（关键陷阱）
- 锚点文本要按**接受修订后**的文本匹配（遍历 w:t 时**跳过 w:del 内的**），否则被删字符会让匹配错位。
- commentRangeStart 必须插在段落第一个 `w:r` **或 `w:ins`** 之前（不能只找 w:r——修订后段首可能是 ins）。
- 先验证每个锚点在全文**唯一命中**（命中数==1）再插，多处命中会挂错段落。

## 可复用代码
```python
import zipfile, io
from lxml import etree
W = 'http://schemas.openxmlformats.org/wordprocessingml/2006/main'
Wq = '{' + W + '}'
DATE = "2026-06-17T10:00:00Z"

comments = [  # 站顾问单位立场，需确认/建议增加内容
    {"id":"201","anchor":"甲方扣除相应服务费后","text":"建议在合同或退费管理制度中明确“服务费”的扣费比例或计算方式，并在签约时向乙方明示。"},
    {"id":"202","anchor":"向甲方住所地人民法院提起诉讼","text":"本条约定甲方住所地法院管辖，建议签约时以加粗或单独提示方式向乙方说明，尽到格式条款提示义务。"},
]

def build_comments_xml(comments):
    p = ['<?xml version="1.0" encoding="UTF-8" standalone="yes"?>',
         f'<w:comments xmlns:w="{W}" xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships">']
    for c in comments:
        p.append(f'<w:comment w:id="{c["id"]}" w:author="WB" w:date="{DATE}" w:initials="WB">')
        # 批注文字字体随原文（本例宋体sz=18小一号），hint=eastAsia 必带
        p.append('<w:p><w:r><w:rPr><w:rFonts w:ascii="宋体" w:hAnsi="宋体" w:eastAsia="宋体" w:cs="宋体" w:hint="eastAsia"/><w:sz w:val="18"/><w:szCs w:val="18"/></w:rPr>')
        p.append(f'<w:t xml:space="preserve">{c["text"]}</w:t></w:r></w:p></w:comment>')
    p.append('</w:comments>')
    return ''.join(p)

comments_xml = build_comments_xml(comments)
with open('IN.docx','rb') as f: data=f.read()
bi, bo = io.BytesIO(data), io.BytesIO()
inserted = {c["id"]: False for c in comments}
with zipfile.ZipFile(bi) as zin, zipfile.ZipFile(bo,'w',zipfile.ZIP_DEFLATED) as zout:
    for it in zin.infolist():
        raw = zin.read(it.filename)
        if it.filename == 'word/document.xml':
            tree = etree.fromstring(raw); body = tree.find(f'{Wq}body')
            for para in body.findall(f'.//{Wq}p'):
                ptext = ''  # 接受修订后文本：跳过 del
                for t in para.findall(f'.//{Wq}t'):
                    if not any(a.tag==f'{Wq}del' for a in t.iterancestors()):
                        ptext += (t.text or '')
                for c in comments:
                    if not inserted[c["id"]] and c["anchor"] in ptext:
                        cid = c["id"]
                        first = next((ch for ch in para if ch.tag in (f'{Wq}r',f'{Wq}ins')), None)
                        if first is None: continue
                        crs = etree.Element(f'{Wq}commentRangeStart'); crs.set(f'{Wq}id',cid); first.addprevious(crs)
                        cre = etree.Element(f'{Wq}commentRangeEnd');   cre.set(f'{Wq}id',cid); para.append(cre)
                        rr = etree.SubElement(para,f'{Wq}r'); rp=etree.SubElement(rr,f'{Wq}rPr')
                        rs = etree.SubElement(rp,f'{Wq}rStyle'); rs.set(f'{Wq}val','CommentReference')
                        cref = etree.SubElement(rr,f'{Wq}commentReference'); cref.set(f'{Wq}id',cid)
                        inserted[cid] = True
            raw = etree.tostring(tree, xml_declaration=True, encoding='UTF-8', standalone=True)
        elif it.filename == '[Content_Types].xml':
            ct = etree.fromstring(raw); NS='http://schemas.openxmlformats.org/package/2006/content-types'
            ov = etree.SubElement(ct,f'{{{NS}}}Override')
            ov.set('PartName','/word/comments.xml')
            ov.set('ContentType','application/vnd.openxmlformats-officedocument.wordprocessingml.comments+xml')
            raw = etree.tostring(ct, xml_declaration=True, encoding='UTF-8', standalone=True)
        elif it.filename == 'word/_rels/document.xml.rels':
            rt = etree.fromstring(raw); RNS='http://schemas.openxmlformats.org/package/2006/relationships'
            r = etree.SubElement(rt,f'{{{RNS}}}Relationship')
            r.set('Id','rIdComments1')
            r.set('Type','http://schemas.openxmlformats.org/officeDocument/2006/relationships/comments')
            r.set('Target','comments.xml')
            raw = etree.tostring(rt, xml_declaration=True, encoding='UTF-8', standalone=True)
        zout.writestr(it, raw)
    zout.writestr('word/comments.xml', comments_xml.encode('utf-8'))
with open('OUT.docx','wb') as f: f.write(bo.getvalue())
assert all(inserted.values()), f"未全部挂靠: {inserted}"
```

## 交付前验证（缺一不可）
1. **id 四向一致**：`commentRangeStart` / `commentRangeEnd` / `commentReference` 三组 id 集合 == comments.xml 的 `w:comment/@w:id` 集合。
2. **python-docx 能打开**（XML 合法）。
3. **接受修订后锚点存在**：批注挂靠的文本在去 del 后仍在。
4. **OnlyOffice 渲染**（onlyoffice-render.sh）确认批注气泡正常显示，不破坏修订标记。

## 修订与批注可共存
同一份 docx 先用 ContractEditor 做完 tracked_replace/add_clause 并 save，再在产物上跑本脚本加批注。批注的 commentRangeStart 会落在修订后的段落结构里（段首可能是 w:ins），代码已用 `(w:r, w:ins)` 兼容。