Files
java-word-pdf/docs/agent/doc-bridge.md
T
Pjandro eabc2b0e0d
PR checks / web (pull_request) Successful in 38s
PR checks / java (pull_request) Successful in 1m31s
Main: tests, deploy, autotests / web (push) Successful in 33s
Main: tests, deploy, autotests / java (push) Successful in 1m7s
Main: tests, deploy, autotests / images-web (push) Successful in 32s
Main: tests, deploy, autotests / images-app (push) Successful in 43s
Main: tests, deploy, autotests / deploy (push) Failing after 2m55s
Main: tests, deploy, autotests / autotests (push) Has been skipped
Main: tests, deploy, autotests / rollback (push) Failing after 3m4s
docs(standards): restructure into ooxml/binary, add MS-XLS/MS-XLSX for .xls/.xlsx
2026-11-02 22:21:23 +00:00

26 KiB
Raw Blame History

Извлечение из AGENTS.md; читать при правке моста internal/doc. Авторитетно наравне с AGENTS.md.

Нормативный источник — [MS-DOC] в docs/standards/doc/, общее OLE-окружение ([MS-CFB], [MS-OLEPS], [MS-ODRAW]) в docs/standards/binary/, [MS-ODRAWXML] в docs/standards/ooxml/, ссылки — с номерами секций. Новых runtime-зависимостей нет (POI остаётся test-scope; POIFS — только в тестах для упаковки крафтовых CFB). Публичные точки: DocToDocx.convert(byte[]) (вызывает WordPdfConverter) и DocToDocx.countPages(byte[]) (вызывает WordPdfValidator.checkPageCountDoc); общий разбор — DocFile (CFB → потоки WordDocument / 0Table|1Table / Data + FIB + piece table). 16 из 18 классов package-private; наружу — DocToDocx и CfbReader (public, публичный член — static readStreams(byte[])).

Класс Спецификация
CfbReader [MS-CFB] заголовок (секторы 512/4096, mini 64), FAT/DIFAT (лимиты секторов + защита от циклов), miniFAT + mini stream из root, directory; любой брак (цикл, ссылка за файл, обрезанный поток, битый заголовок) → ValidationException
FibHeader [MS-DOC §2.4.1/§2.6.1] FibBase (fWhichTblStm — бит 9 u16@10 → 1Table/0Table), FibRgLw97 (ccpText/ccpFtn/ccpHdd), пары FibRgFcLcb97: fcStshf=1, fcPlcfSed=6, fcPlcfHdd=11, fcPlcfBteChpx=12, fcPlcfBtePapx=13, fcSttbfFfn=15, fcClx=33, fcDggInfo=50, fcPlfLst=73, fcPlfLfo=74
PieceTable §2.9.135 Clx/Pcdt: куски compressed (FC/2, байт + CP1252-карта 0x80–0x9F) и uncompressed (UTF-16LE); FC за потоком → ValidationException
Grpprl §2.6.2 sprm'ы: CHPX — bold 0x0835, italic 0x0836, strike 0x0837, kul 0x2A3E, hps 0x4A43, hpsBi 0x4A61, ftc0 0x4A4F, ftc1 0x4A50, cv 0x6870 (4-й байт FF → auto), sprmCHighlight 0x2A0C (Ico §2.9.171 → w:highlight, член ST_HighlightColor §17.18.42 по RGB 1:1), sprmCShd 0xCA71/sprmCShd80 0x4866 (SHDOperand §2.9.177 = cb(1)=10 + cvFore/cvBack COLORREF + ipat §2.9.178; Shd80 u16 5+5+6 §2.9.176 → w:shd, форма Word w:val="clear": fill=cvFore при ipatSolid иначе cvBack; ipatAuto/оба цвета auto → не эмитится — FOP красит только w:fill, проверено экспериментально), sprmCIstd 0x4A30 (ссылка на символьный стиль §2.4.6.5 → Styles.charChain), sprmCFSpec 0x0875, rMarkDel 0x0800/rMarkIns 0x0801 (непринятые правки → w:del/w:ins), smallCaps 0x083A/caps 0x083B (апкейс текста в мосту), vanish 0x083C (фильтр рана — FO w:vanish не читает), hpsPos 0x4845 (со знаком, hps → w:position), sprmCPicLocation 0x6A03 (смещение BLIP в Data); PAPX — sprmPHugePapx 0x6646/sprmPTableProps 0x646B (указатели на PrcData в Data, разворачивает PrcData.resolve; Grpprl.scan сам их корректно пропускает по spra=3), jc 0x2461 (4→distribute, 5/7/8/9→both, 6 — игнор) и jc80 0x2403 (3/4/5 — justify-both с разной компрессией, distribute у jc80 нет), dxaLeft/dxaLeft1/dxaRight + 80-варианты 0x840F/0x8411/0x840E и sprmPNest 0x465F/sprmPNest80 0x4610 (XAS со знаком → hanging/firstLine; общий накопитель Grpprl.Indents: nest к своему dxaLeft, современное семейство вытесняет 80-е), pageBreakBefore 0x2407 (перед ним keepFollow 0x2406/keep 0x2405 → w:keepNext/w:keepLines), InTable 0x2416, sprmPFTtp 0x2417, sprmPShd 0xC64D/sprmPShd80 0x442D (тот же Shd/Shd80 → w:shd в pPr до w:tabs, CT_PPr §17.3.1.26), istd 0x8463, LSPD 0x6412 (dyaLine i16 + fMult), before/after 0xA413/0xA414, PChgTabs 0xC60D и sprmPChgTabs 0xC615 (табы стиля; PChgTabsDelClose §2.9.182 — радиус удаления из rgdxaClose, XAS_plusOne), ilvl 0x260A (u8; 0x0C — «пропустить, не нумеровать»), ilfo 0x460B (i16: 0/0xF801 — списока нет, 1..0x07FE — 1-базированный индекс rgLfo, 0xF802..0xFFFF — отрицание индекса с сохранением отступов); TAP — sprmTDefTable 0xD608, sprmTTableBorders 0xD613, sprmTTableBorders80 0xD605, sprmTJc 0x548A / sprmTJc90 0x5400 (u16 0/1/2 → left/center/right, единый маппинг: FOP complex-script не поддерживает, RTL вне контура), sprmTVertAlign 0xD62C (CellRangeVertAlign §2.9.30: cb=3 + itcFirst + itcLim + VerticalAlign 0/1/2 → w:vAlign; cb≠3 — операнд игнорируется), sprmTCellPadding 0xD632/sprmTCellPaddingDefault 0xD634 (CSSAOperand §2.9.209: cb(1)=6 + itc(2 ItcFirstLim) + grfbrc (top
ChpxIndex/PapxIndex §2.4.6: PlcfBte (aFc n+1 + pn 22 бита) → FKP-страницы 512 Б по pn·512 (rgfc (n+1)×4, rgbx n×1/×13, crun/cpara — последний байт); Chpx = cb + grpprl; PapxInFkp: cb≠0 → GrpPrlAndIstd 2cb−1, cb=0 → cb′ → 2cb′ (внутри istd(2) + grpprl, grpprl может быть пустым — istd без прямых Prl); bOffset=0 → свойств нет (дефолт), но граница rgfc[j+1] в индекс заносится — иначе дефолтный ран проглотил бы последующие CHPX-раны абзаца (регрессии ChpxIndexTest#zeroOffset_defaultPropsBoundaryKept, WordPdfConverterTest#docClassD_landscapeHiddenDelCaps); istd сохраняется (istdFor, вне диапазона −1) — по нему DocxBody применяет цепочку Styles
Styles §2.9.271 STSH по fcStshf: LPStshi (cbStshi, cstd, cbSTDBaseInFile) → LPStd на чётных границах → Std (stdf: sti/stk/istdBase/cupx + xstzName + LPUpx): stk=1 → UPX[0]=UpxPapx (istd(2)+grpprl), UPX[1]=UpxChpx; stk=3 (STCF — символьные стили Word 97+) — единственный UPX[0]=UpxChpx целиком, отдельная цепочка charChain(istd) (источник ссылки — sprmCIstd, §2.4.6.5); stk=2 (легаси STDC) не читается. Цепочка base-first (предок раньше потомка, last-wins при скане); istdBase 0x0FFF — без предка, цикл — обрыв на MAX_CHAIN=16. Разбор снисходительный (образец FontTable): битый/отсутствующий STSH → пустая таблица, конвертация на прямых свойствах, без ValidationException
Tables TAP TTP-абзаца (§2.6.3) → Grid(colWidths, indent, bordersXml, tblJc, cellVAlign, cellMargins): sprmTDefTable (§2.9.321, ncols 1..63, rgdxaCenter XAS со знаком — ширина = center[i+1]−center[i], первый center — сдвиг от поля); границы: sprmTTableBorders (§2.9.302, 6×Brc: cv fAuto, dptLineWidth 1/8pt, brcType §2.9.39) иначе sprmTTableBorders80 (§2.9.303, ico→цвет §2.9.171); brcType=0 не эмитится, ≥0x40 ширина ×8, sz<2 → 2; выравнивание: sprmTJc/sprmTJc90 (u16: 1→"center", 2→"right", прочее → null — элемент не эмитится), современный перекрывает 90-вариант (тот же приоритет, что у 0xD613 над 0xD605) → w:jc в tblPr (openTable; регрессия — WordPdfConverterTest#docFooterTableCentered_shiftedLikeWord); вертикальное выравнивание ячеек: sprmTVertAlign 0xD62C (CellRangeVertAlign §2.9.30) → cellVAlign[] по индексам колонок (диапазоны clamped к сетке, top/вне диапазона — не эмитится) → w:vAlign в w:tcPr после w:gridSpan (регрессии — TablesTest#vertAlign_, DocToDocxFormattingTest#cellVertAlign_); поля ячеек: sprmTCellPadding/…Default (CSSAOperand §2.9.209, только ftsDxa, wWidth ≤ 31680) → cellMargins[] (record CellMargin(itcFirst, itcLim, sideMask, width), Default — весь ряд) → w:tcMar в w:tcPr до w:vAlign (CT_TcMar §17.4.66; регрессии — TablesTest#cellPadding_*, DocToDocxFormattingTest#cellMargins_becomeTcMar, пайплайн — WordPdfConverterTest#tableTcMar_textInsetLikeWord). null (нет/битый TDefTable, неположительная ширина) → строка деградирует в плоские абзацы
Lists §2.9.200/.201 PlfLst/PlfLfo → word/numbering.xml: PlfLst — cLst SHORT (2 Б) при fc, rgLstf с fc+2 (§2.9.201, Figure 56); LSTF (28 Б, fSimpleList→1 LVL иначе 9, массив LVL приложен за fc+lcb) + LVL (LVLF 28 Б: iStartAt/nfc/jc/ixchFollow/cbGrpprl'ы; Xst: плейсхолдеры 0x00–0x08 → %{n+1}, литеральный % → %%) → w:abstractNum (MSONFC [MS-OSHARED §2.2.1.3] → ST_NumberFormat §17.18.59, общий numFmt с DocxBody.appendPgNumType, экзотика CJK → decimal — нет глифов в бандле; ixchFollow 1/2 → w:suff space/nothing, 0=tab не эмитится; grpprlPapx уровня → w:ind, grpprlChpx → w:rPr rFonts/b/sz); LFO (lsid→первый LSTF) + LFOLVL (fStartAt → w:startOverride, fFormatting → полный w:lvl) → w:num (numId = 1-базированный ilfo). Снисходительно (образец Styles): битая таблица/обрыв LVL → пустой/неполный результат; hasNum — numId разрешается в валидный abstractNum, иначе абзацы деградируют в плоские
Sections PlcfSed (§2.8.26): aCP n+1 + Sed n (12 Б) + Sepx (cb + секционные sprm) → list() — список record'ов Section (CP-диапазон, геометрия секции, continuous из sprmSBkc, landscape из sprmSBOrientation 0x301D (§2.9.236: 1/2), нумерация страниц — pgNumStart (0 = не задан; sprmSFPgnRestart 0x3011 + sprmSPgnStart97 0x501C, restart без start клампится к 1) и nfcPgn (sprmSNfcPgn 0x300E, MSONFC), колонки — sprmSCcolumns 0x500B (число − 1, кап 44), sprmSFEvenlySpaced 0x3005 (Bool8, дефолт true), sprmSDxaColumns 0x900C; при неравных колонках per-column ширины/зазоры из sprmSDxaColWidth 0xF203/sprmSDxaColSpacing 0xF204 (SDxaColWidthOperand/SDxaColSpacingOperand §2.9.241/.242: iCol+dxa)); titlePage из sprmSFTitlePage 0x300A (Bool8)); невозрастающие aCP → ValidationException; финальный aCP реальные файлы пишут за ccpText (PLC покрывает весь текстовый поток) — конец последней секции клампится к ccpText; pageWidth()/header()/footer() — геометрия последней секции (полоса набора для правила 7), continuousSectionEnds() — вычитание из подсчёта страниц (последняя секция не считается)
FontTable SttbfFfn (§2.9.147): индекс ftc → имя семейства в w:rFonts
SummaryInfo [MS-OLEPS §2.2] PropertySet-поток \x01SummaryInformation; offset'ы заголовка относительны начала PropertySet-потока (abs = Offset0 + offset); PIDSI_PAGECOUNT=0x0E
Headers Plcfhdd (§2.4.1): 6 разделителей + по 6 историй на секцию (even/odd/first × hdr/ftr); odd hdr/ftr каждой секции → своя часть headerN.xml/footerN.xml (нумерация независимая по типу) и headerReference/footerReference type="default" в её sectPr; first hdr/ftr (слоты 4/5 §2.8.22) — только когда у секции Sepx задал sprmSFTitlePage → type="first" (нумерация общая с first-частями; регрессия — DocToDocxFormattingTest#titlePage_emittedAfterCols, WordPdfConverterTest#docTitlePage_firstHeaderOnlyFirstPage); пустая история [x,x) → части нет, docx4j наследует колонтитук предыдущей секции; guard-¶ отрезается; PAGE/NUMPAGES/SECTIONPAGES → w:fldSimple (та же семантика, что FieldNormalizer в docx-пути)
OfficeArt [MS-ODRAW] PICF @ fcDggInfo/lcbDggInfo (Table-поток), delay-поток = WordDocument; DggContainer → BStoreContainer(0xF004)/BStoreContainerDelay(0xF007)/инлайн → FBSE → BLIP: 0xF01A EMF / 0xF01B WMF / 0xF01C PICT / 0xF01D JPEG (=0xF02A) / 0xF01E PNG / 0xF01F DIB; PNG/JPEG дословно, DIB → ImageIO → PNG, EMF/WMF/PICT → пропуск + warn (EMF-рендера в Java2D нет)
PrcData §2.9.210 PrcData в Data-потоке ([cbGrpprl:2][grpprl], капа cb 0x3FA2, поля next нет): resolve(data, grpprl) разворачивает grpprl абзаца, чьи свойства Word вынес за FKP-страницу PAPX, — одиночный Prl sprmPHugePapx (0x6646; в grpprl GrpPrlAndIstd — единственный Prl при istd=0, §2.6.2) и sprmPTableProps (0x646B — цепочка продолжается в указанном PrcData). Оба указателя разворачиваются на своей позиции без обрыва текущего массива, не-спец-спрмы сохраняются (union): spec §2.6.2 велит хвост за PTableProps игнорировать, но Word пишет в нём легаси-зеркало (в samples/ru-table-image.doc — единственный sprmTDefTable, Appendix A <9>), а sprmTInsert из PrcData конвертер не читает — замещение ломало бы сетку; спец-спрмов нет → тот же массив (по ссылке); любой брак (ptr за Data, cb вне [1, 0x3FA2], цикл A→B→A — бюджет 32 PrcData) → останов без исключения, снисходительно (образец Styles/Lists). Подключается единственной точкой — DocxBody.buildRange (покрывает тело, колонтитуки, TTP-ветку и обычные huge-PAPX абзацы). Регрессия — DocToDocxFormattingTest#hugePapxRowMark_closesRowWithGridFromPrcData
DocToDocx Оркестратор + вложенный DocxBody: текст → раны (CHPX+стилевой chpx-цепочка +chpx-цепочка символьного стиля по sprmCIstd (Styles.charChain — между стилевой цепочкой и прямыми, §2.4.6.5) → rPr (в т.ч. w:highlight/w:shd), прямой PAPX — после PrcData.resolve — +стилевая papx-цепочка (отступы через Grpprl.Indents, 80-варианты включительно; sprmPChgTabsPapx/sprmPChgTabs → w:tabs, у стилевого варианта радиус удаления из rgdxaClose) + sprmPIlfo/sprmPIlvl → pPr + w:numPr (между pageBreakBefore и tabs, CT_PPr §17.3.1.26; ilfo=0 перекрывает стилевой, ilvl=0x0C и неразрешённый numId → без numPr), base→derived→direct last-wins; флаги рана: vanish — мост фильтрует вывод рана (w:vanish в FO мёртв), caps/smallCaps — Character.toUpperCase в мосту (w:caps/w:smallCaps конвейер не читает, FOP без font-variant), rMarkIns/rMarkDel — ран оборачивается в w:ins/w:del+w:delText (шаблоны docx2fo рисуют правки — вид «Show Markup»), hpsPos → w:position (вендорный AUDIT-FIX → baseline-shift)), ¶ → <w:p>; TAB/0x0B → w:tab/w:br, 0x0E → w:br type="column" (конец колонки при sprmSCcolumns), 0x0C в ране → w:br type="page", 0x0C в конце абзаца — разрыв секции: sectPr соответствующей Sections.Section (матчинг по конечному CP) в pPr этого абзаца, внутри таблицы деградирует в w:br type="page"; body-level sectPr — последняя секция; w:type continuous из sprmSBkc; w:pgSz w:orient="landscape" со сменой w/h местами, w:pgNumType (w:start при restart, w:fmt только для числовых nfc — общий маппинг Lists.numFmt), w:cols (evenly → w:num+w:space, иначе per-column w:col; неравные/неполные ширины → деградация в одноколонную), w:titlePg из Section.titlePage (после w:cols, CT_SectPrBase §17.2.3) — DocxBody.sectPrXml/appendPgNumType/appendCols; pPr: w:shd из sprmPShd/…80 перед w:tabs (CT_PPr §17.3.1.26), w:keepNext/w:keepLines перед w:pageBreakBefore (CT_PPr §17.3.1.26); 0x1E → U+2011, 0x1F → U+00AD, 0x02/0x03/0x04 (сноски) → пропуск; U+0001/U+0008 со sprmCPicLocation → DrawingML pic (общий путь с картинками и OLE-fallback; 0x08 — якорь плавающей картинки §2.9.267, переносится inline-приближением: PlcfSpa не читается, позиция/обтекание теряются); field-символы в основном тексте: инструкция скрыта, кэшированный результат после разделителя видим; табличный автомат: абзац с 0x07 без TTP закрывает ячейку, 0x07+sprmPFTtp — конец строки (Tables.parse по TAP → w:tbl/w:tr/w:tc, сам маркер не эмитится), sprmPFInTable открывает ячейку; без корректного TDefTable строка деградирует в плоские абзацы (прежнее поведение); сетка первой строки действует на всю таблицу как tblGrid, ширины/объединение ячеек каждой строки — из её собственного TDefTable (горизонтальное слияние → w:gridSpan)
DocxWriter Мульти-частный zip: [Content_Types].xml (hdr/ftr/numbering/png/jpg), _rels/.rels, word/document.xml (посекционные sectPr + headerReference; tblPr таблиц: tblW → jc (из sprmTJc) → tblInd → tblBorders), word/_rels/document.xml.rels, word/numbering.xml, word/headerN.xml/footerN.xml (по одной на непустую историю секции), `word/media/imageN.(png

Остаток моста

Остаток моста (осознанный, вне контура): семантика рестартов списков не переносится (fNoRestart/ilvlRestartLim → w:lvlRestart — docx4j-Emulator применяет свой дефолт «рестарт на старшем уровне»), как и fLegal/isLgl, dxaIndentSav и LfoData.cp; sprmPIlvl=0x0C — абзац без numPr (не «в списке без номера»); AUTONUM-поля трактуются как обычные списки; отрицательный sprmPIlfo («сохранить отступы») — обычный numPr, отступы делает прямой w:ind абзаца; объединённые ячейки: вертикальное слияние (vertMerge) не переносится, горизонтальное — переносится собственной сеткой строки (TTP-абзац каждой строки несёт свой sprmTDefTable, §2.9.321 → w:gridSpan+суммарный w:tcW; регрессия — WordPdfConverterTest#docMergedTableRow_fullWidthNotSplit, юниты — DocToDocxFormattingTest#mergedRow_gridSpanAndWidth, #misalignedRow_fallsBackToColumnWidths), вложенные таблицы (sprmPFInnerTtp — разделитель ячейки/строки там ¶ 0x0D, не 0x07) и бордюры уровня ячейки (TC80/sprmTCellBorders) не переносятся — только сетка и строковые границы; строки, у которых сетка задана только sprmTInsert (в PrcData нет sprmTDefTable, а PAPX-зеркало отсутствует), деградируют в плоские абзацы (sprmTInsert конвертер не читает); DocFile.countPages (PapxIndex.countPageBreakBefore) цепочку PrcData не следует — свойства вне FKP в подсчёт страниц не попадают, 0x0C-разрывы считаются; сноски/концевые сноски/комментарии не рендерятся (метки ссылок пропускаются); плавающие объекты (якорь 0x08) — только inline-картинкой: позиция/плавание/обтекание (PlcfSpa) не переносятся; непринятые правки рендерятся как разметка (w:ins/w:del, вид «Show Markup»), эмуляция принятия правок не делается; скрытый текст вырезается мостом сам (.docx-путь чистит и его — правило 9, но мост не ждёт байтового прохода), ВСЕ ПРОПИСНЫЕ/малые капители — апкейс текста (FOP без font-variant); подсветка и затенения перенесены аудитом 2026-11: sprmCHighlight 0x2A0C → w:highlight (Ico→ST_HighlightColor по RGB), sprmCShd 0xCA71/sprmCShd80 0x4866/sprmPShd 0xC64D/sprmPShd80 0x442D → w:shd (форма w:val="clear" + цвет в w:fill — FOP закрашивает только w:fill, проверено экспериментально: w:val="solid" w:color=RRGGBB w:fill="auto" не рисует ничего; ipatSolid → fill=cvFore, иначе fill=cvBack — паттерны Ipat≥2 деградируют, [MS-DOC] Ipat: «lost if converted to ECMA-376»); затенение таблицы/ячеек (sprmTSetShd 0xD62D/sprmTSetShd80 0xD60F) мостом не переносится; тип подчёркивания не переносится: KUL любой → w:u val="single" (double/dotted деградируют, sprmCCvUl не читается); границы абзацев (хранятся sprm PAPX 0xC64E–0xC652, а не PlfBdx §2.9.8) не переносятся — и конвейер w:pBdr не рисует (в docx4j-export-fo 17.3.2 нет getPBdr, байткод 2026-11); не переносятся и не были бы нарисованы (в docx4j-export-fo 17.3.2 нет соответствующих getters — проверено байткодовым зондом): w:tcBorders (границы ячеек — TC80/sprmTCellBorders), w:trHeight (sprmTRheight), w:tblHeader (sprmTfHdrTbl), w:cantSplit (sprmTfCantSplit), w:widowControl (sprmPFWidowControl); отступы в символьных единицах sprmPDxcLeft/sprmPDxcRight/sprmPDxcLeft1 0x4456/0x4455/0x4457 не переносятся — операнд есть 1/100 ширины символа (§2.6.1), перевод в twips требует ширины глифа «0» разрешённого шрифта, коей у моста нет (guard fCharLineUnits §2.6.2: в обычных документах этих Prl нет вовсе); чётные варианты колонтитуков не переносятся (переносится только odd → type="default", FOP не различает чётность полос набора); first-page переносится аудитом 2026-11 — sprmSFTitlePage + type="first" (см. строку Headers); разрыв секции в абзаце со sprmPFInTable деградирует в разрыв страницы (w:sectPr в w:pPr внутри w:tc невалиден); error-флаги errorOnCharts/errorOnSmartArt/errorOnOle на .doc не срабатывают — диаграммы/SmartArt/OLE в бинарном формате существуют только как BLIP-плейсхолдеры, мост выдаёт их картинками (задокументировано в @Operation); stale-cache.doc конвертируется (кэш PageCount=5, концепта lastRenderedPageBreak в .doc нет) — семантика отличается от docx-фикстуры, запинено тестом.