Party Relationship Schema

ID of the PERSON party

ID of the ORGANIZATION party

Function/role at this organization (e.g. IT-Leiter, Geschäftsführer)

Structured function/role slugs from FUNCTION_ROLES taxonomy. Enables recipient-resolver for campaigns (e.g. "IT_LEAD", "MANAGING_DIRECTOR"). Free-text "function" field remains for descriptive context.

Free-text role description used when functionRoles contains "OTHER".

DSGVO/§7 UWG marketing consent on the contact-relationship level. Required for newsletter and sales-outreach campaigns.

Organization-specific email address

Organization-specific landline phone number

Organization-specific mobile phone number

Whether this person is a primary contact (Hauptansprechpartner) OF THE ORGANIZATION. Read from the organization side everywhere (customer list column, campaign recipients, DQ score); several primaries per organization are allowed (ADR 0545). NOT "the primary organization of this person" — that reading led the weclapp sync and the email contact wizard to flag every created contact until 2026-09-15. Only an explicit user choice sets it; imports, syncs and pre-filled create dialogs leave it false.

Whether this person is an emergency contact for the organization

Standard-CC: this contact is put on CC of every outbound mail to this organization, even when the sender did not add them (typically the IT lead on the customer side who wants to see all correspondence). Resolved by `resolveDefaultCcRecipients()` (apps/api/src/services/email/default-cc.service.ts) and enforced on the message DRAFT->SENT send path; the compose dialog pre-fills the same addresses as removable chips. Only triggers when a recipient actually belongs to this organization - the entity context alone (e.g. a ticket of this customer) is not enough, so a mail to a supplier on that ticket does not silently CC the customer. Runtime fallback: missing/null counts as false - no backfill needed.

Whether this contact relationship is still active. Set to false when the person has left the organization ("ausgetreten"): the contact is greyed out with an "inactive" badge in the CRM and is no longer offered in contact pickers, so it cannot be linked to new tickets/activities. Existing links are untouched. Runtime fallback: a missing field counts as active (isActive !== false) — no backfill needed for pre-existing relationships.

Emergency phone number

Role slug determining permissions for this person at this organization

Optional FK to shop_roles. Determines which customer-portal capabilities and product visibility this person has at this organization.

Free-text notes about this relationship

Traffic-light importance of the contact note (`notes`). NONE = neutral grey italic (default, matches the rendering before this field existed), GREEN = uncritical, YELLOW = attention, RED = important. Drives the colour of the note on the contact card and in the "important contacts" hero cards. Runtime fallback: a missing or null field counts as NONE — no backfill needed for pre-existing relationships.

Optional start of the contact note's validity window (YYYY-MM-DD, inclusive — same semantics as party.notices[].validFrom). Before this date the note is hidden on the contact card and the "important contacts" hero cards; the edit dialogs always show it. Missing/null = valid immediately — no backfill needed for pre-existing relationships.

Optional end of the contact note's validity window (YYYY-MM-DD, inclusive). After this date the note disappears from the display surfaces automatically without anyone having to clear it (e.g. "on parental leave until …"). Missing/null = valid indefinitely — no backfill needed.

True when this relationship was created solely as part of a portal-invite flow and the user never accepted. Used by the revoke handler to soft-delete the stub when the pending invitation gets cancelled, so cancelled invites do not leave orphan CRM contacts in the Portal-Zugänge list.

FK to a customer_org_unit. Only valid when organizationPartyId references a customer ORGANIZATION party — the referenced OU must have customerOrgUnit.customerPartyId === organizationPartyId. Used by the customer org chart and the CUSTOMER_OU_HEAD approver-DSL node (ADR 0130a).

Site the contact actually works at: the `_id` of an entry in the ORGANIZATION party's `addresses[]` (same id space as `ticket.partyAddressId`). Independent of `workLocationMode` — a contact can be assigned to "Niederlassung Berlin" and still work HOME_OFFICE most of the time. Runtime fallback: missing/null = unknown site, the contact card simply shows no site chip — no backfill needed.

Where the contact primarily works: ON_SITE (at `workAddressId`), HOME_OFFICE (predominantly from home), HYBRID (split between site and home), REMOTE (mobile / no fixed site). Runtime fallback: missing/null = no statement made — no backfill needed.

PERSON party-id of the disciplinary manager inside the same customer organization. The referenced person must have an active party_relationship with the same organizationPartyId. Used by the CUSTOMER_MANAGER approver-DSL node (ADR 0130a). Self-reference is rejected; cycles are detected at resolve time, not on write.