Select team information on statement template

• The Contacts module exists and is accessible to the user.
• User has permission to create/edit contacts.

• The contact record is saved with a value in the "Contact Type" field.
• The contact becomes available for selection in downstream modules (e.g., Agreements) if its type matches the expected filter.

1. User navigates to the Contacts module.

2. User creates a new contact or opens an existing one for editing.

3. User selects a value from the "Contact Type" dropdown (e.g., "Team Contact").

4. User completes other required contact fields (First Name, Last Name, Phone, Email, etc.).

5. User saves the contact.

6. System stores the contact with the selected Contact Type.

• 3a. User leaves "Contact Type" unselected (if not mandatory): contact is saved without a type and will not appear in type-filtered dropdowns elsewhere.
• 3b. User changes Contact Type on an existing contact already linked to an agreement (see Open Questions — impact on existing links).

• 5a. Save fails due to system/network/database error → system displays error message, no data is persisted.

• Dropdown must be extensible so new Contact Types can be added by an administrator without a code deployment (ideally configurable in a settings/admin area).
• Field must be filterable/searchable in the Contacts list view.

• What happens to existing agreement links if a contact's type is changed away from "Team Contact" after being linked?
• Who manages the list of available Contact Types (admin-configurable vs. hardcoded)?

• At least one contact exists in the Contacts module with Contact Type = "Team Contact" (US-1 completed).
• User has permission to create/edit agreements.
• The Agreements module's Details tab and "Invoice Contact" section already exist.

• The agreement is saved with a reference (link) to the selected Team Contact.
• The linked contact's data becomes available for use in placeholder resolution (US-3) at invoice generation time (US-5).

 1. User opens a new or existing agreement.

2. User navigates to the Details tab.

3. User scrolls to the "Invoice Contact" section.

4. System displays a "Team Contact" dropdown field, populated with all contacts where Contact Type = "Team Contact".

5. User selects a contact from the dropdown.

6. User saves the agreement.

7. System stores the link between the agreement and the selected Team Contact.

• 4a. No contacts exist with Contact Type = "Team Contact" → dropdown is empty, with a message such as "No team contacts available."
• 5a. User changes the previously selected Team Contact on an existing agreement → system updates the link on save.

• 6a. Agreement save fails due to missing other mandatory fields → validation error shown, Team Contact selection is retained on the form (not lost).

• Show contact identifying info (e.g., Full Name) in the dropdown label rather than an internal ID.
• The dropdown should be scoped by Entity

"Team Contact"

"Invoicing Team"

• The placeholder engine/templating system used for invoice generation already exists and supports adding new placeholder types.
• US-2 is implemented so agreements have a linked Team Contact to resolve placeholder values from.

• Four new placeholders are available system-wide for use in any template: First Name, Last Name, Phone Number, Email.
• Placeholders correctly resolve to the linked Team Contact's data when a pdf document is generated.

 1. Developer defines new placeholder keys within the placeholder configuration (e.g., {{team_contact.first_name}}).

2. Placeholders are registered in the system's placeholder library/catalog.

3. Placeholders are made selectable within the Template Settings UI (see US-4).

4. At generation time, system resolves each placeholder using the Team Contact linked to the agreement (from US-2).

• 4a. Linked contact record was deleted after being linked → system should handle gracefully (blank value + log/warning) rather than fail generation entirely.

• Placeholder naming convention should be consistent and documented (e.g., team_contact.<field>) to support future contact types cleanly (e.g., billing_contact.<field>).
• Placeholder resolution logic must be centralized so it can be reused by both PDF and ZUGFeRD generation engines.

"Team"

"+49 89 2489 2092"

"invoicing-team@meag.com"

• Placeholders from US-3 exist and are registered in the system.
• The Entities module and its Template Settings feature already support inserting placeholders into defined sections.
• User has administrative permission to edit template settings.

• The entity's invoice template contains the new placeholders positioned in the desired section (e.g., "Invoicing Team" box).
• Future invoices generated for that entity render the resolved contact data in that location.

1. User navigates to Entities module → selects an entity → opens Template Settings.

2. User locates the relevant section of the template (e.g., "Right" box).

3. User inserts the placeholders: First Name, Last Name, Phone Number, Email — in the desired order/format.

4. User saves the template settings.

5. System stores the updated template layout for that entity.

• 4a. Save fails due to malformed placeholder tag → system shows a validation error and does not save.

• Placeholder insertion should ideally use a visual or guided picker rather than requiring the admin to manually type placeholder syntax, to reduce errors.
• Template settings should be configurable per entity, since different entities may have different letterhead layouts.

• The agreement has a Team Contact linked (US-2).
• The entity's template includes the Contact placeholders in the correct section (US-4).
• Placeholder resolution logic is implemented (US-3).

• The generated PDF visually displays the correct Team Contact details in the designated section.
• The generated ZUGFeRD file contains the same data, both visually (PDF/A layer) and structurally (XML data), if required.

1. User triggers invoice generation (PDF and/or ZUGFeRD) for a given agreement.

2. System retrieves the agreement's linked Team Contact.

3. System resolves each placeholder (First Name, Last Name, Phone, Email) using that contact's data.

4. System renders the PDF with resolved values in the correct template section.

5. System generates the ZUGFeRD XML with corresponding structured contact data (if applicable per ZUGFeRD schema).

6. System outputs the final invoice document(s) to the user/downstream process.

• 2a. Agreement has no linked Team Contact → system applies fallback behavior as defined (blank, default contact, or blocks generation — per Open Question in US-3).
• 5a. ZUGFeRD schema field mapping requires specific structured tags (e.g., SellerContact, BuyerContact) → system maps Contact fields accordingly.

• 3a. Linked contact was deleted after linking, and no fallback is defined → generation fails or logs a data-integrity warning; process should not silently produce incorrect data.
• 5a. ZUGFeRD structured data fails schema validation due to missing/invalid Contact field format (e.g., invalid email) → system flags an error before finalizing the invoice file.