Document XSL-FO template migration v1.14.0 → v2.0.0 (Party + UserExtension address element changes)

[scaphilo]

Context

v2.0.0 (tracked under milestone via #198, cut over in #395 and #396) changes the XML shape the PDF worker emits into user-authored XSL-FO templates. PartyXmlBuilder already replaced the pre-v2.0.0 <contact> element with <party>, and #396 changes <user_extension>/<postal_address> / <phone_address> / <email_address> by dropping the legacy person-name fields.

Template authors currently have no written migration path for their .xsl / .fo files — only the Java builder javadoc ("see docs/migration-v1.14.0-to-v2.0.0.md") hints that a guide should exist, and docs/migration-v1.14.0-to-v2.0.0.md does not yet cover template changes.

This issue is NOT about solving the migration — the shape changes are already decided and partly implemented. This issue tracks adding the written migration instructions so template authors can fix up their templates when they deploy v2.0.0.

What needs documenting (append a new section to docs/migration-v1.14.0-to-v2.0.0.md)

A. <contact> → <party> (done in #394 / #395)

The pre-v2.0.0 ContactXmlBuilder emitted:

<contact id="...">
  <name>Acme AG</name>
  <postal_address>...</postal_address>
</contact>

v2.0.0 emits via PartyXmlBuilder:

<party id="..." type="organization">
  <display_name>Acme AG</display_name>
  <organization>
    <legal_name>Acme AG</legal_name>
    <legal_form>ag</legal_form>
    <registration_number>CHE-...</registration_number>
    <legal_seat_country>CH</legal_seat_country>
  </organization>
  <!-- OR, for natural-person parties: -->
  <contact>
    <prefix>...</prefix>
    <given_name>...</given_name>
    <family_name>...</family_name>
  </contact>
  <postal_address purpose="billing" ...>...</postal_address>
</party>

Template authors need a side-by-side table mapping old XPath → new XPath and a small XSLT snippet that handles both type="organization" and type="contact" branches.

B. <user_extension>/<postal_address> shape change (done in #396)

Dropped children:

• <prefix>
• <pre_name>
• <name>

Template authors who rendered the issuing user's name from these must now read it from <user_extension>/<user>/<first_name> + <last_name> instead. An XSLT snippet example would help.

Added / changed children:

• <is_primary> (new, boolean)
• <state> (new, may be blank)
• <subdivision_code> (new, ISO 3166-2 suffix, may be blank)
• <address_line_3>, <address_line_4> (new, usually blank)
• <valid_from>, <valid_to> (new, usually blank)
• <zip_code> — string now, not integer. Leading zeros preserved.

C. <phone_address> and <email_address> shape change

Same pattern: purpose and is_primary attributes/children carried through explicitly. <phone> → phone number is now the E.164 string from the Party-pattern PhoneNumber value; <email_address> → email string from PartyEmail.

D. How to adapt a template

Short recipe in prose:

1. Locate every <xsl:value-of select="contact/..." /> — rename path to party/... and pick the right sub-block based on @type.
2. Locate every <xsl:value-of select="user_extension/postal_address/(prefix|pre_name|name)"/> — point at user_extension/user/(first_name|last_name) instead.
3. If any template does arithmetic on zip_code, stop — it's a string now.
4. Optional: guard templates against missing valid_from / valid_to if you want to render only currently-valid assignments.

E. Smoke test

Provide a one-liner to re-render a fixture invoice after updating templates, pointing at pdf-export-service/src/test/java/net/koalix/pdf/support/DocumentFixtures.java.

Acceptance

• New section "Upgrading XSL-FO templates to v2.0.0" added to docs/migration-v1.14.0-to-v2.0.0.md.
• Section covers A, B, C, D, E above with concrete XPath before/after examples.
• Cross-linked from the PartyXmlBuilder and UserExtensionXmlBuilder javadocs (they already reference this file).
• Mentioned from the v2.0.0 changelog entry.

Relates to

• Reorganize the contact managment  #198 (Party data model parent)
• [Issue #198.4] Drop legacy contact models and finalize naming #395 (v2.0.0 Party cutover)
• Restructure non-legacy address satellites so PostalAddress / PhoneAddress / EmailAddress bases can be dropped #396 (UserExtension satellite restructure — introduces the UserExtension XML shape change)