PSA/ee/docs/plans/2026-03-09-multiple-contact-phone-numbers/PRD.md

PRD — Multiple Contact Phone Numbers

• Slug: multiple-contact-phone-numbers
• Date: 2026-03-09
• Status: Draft

Summary

Replace the single contacts.phone_number field with a normalized multi-number model that supports one or more phone numbers per contact, fixed canonical types, tenant-scoped custom type suggestions, and an explicit default number. Update the contact creation/editing/import flows and the main dependent GUI surfaces so the new model is first-class everywhere the current scalar phone number is shown or edited.

Problem

Contacts currently expose only one scalar phone_number, which is too limited for real-world usage. MSP users need to store multiple numbers per client contact, distinguish those numbers by type, and choose which number should be treated as the default. The current shape also makes integrations like Entra sync lossy because multiple external phone values are collapsed into one field.

Goals

• Support multiple phone numbers on a contact with an explicit default number.
• Keep a small canonical type set: work, mobile, home, fax, other.
• Support tenant-scoped custom phone type labels with autocomplete/deduplication behavior similar to tags.
• Replace all contact-domain create/edit/read code paths so they work against the normalized model instead of contacts.phone_number.
• Update the key GUI surfaces that display or edit contact phone numbers.
• Preserve practical list/search behavior by defining a default-phone display rule and searchable normalized phone values.
• Map Entra mobile/business phones into the new contact phone model instead of discarding extra values.

Non-goals

• Refactoring client company phone fields, client location phone fields, tenant support phone fields, or portal profile phone fields in this plan.
• Introducing an admin-managed settings UI for custom phone type definitions.
• Shipping a long-lived compatibility layer that keeps contacts.phone_number as an application field after the cutover.
• Designing a generalized reusable multi-phone component for every entity in the product; this plan only requires the contact-domain surfaces.
• Adding metrics, feature flags, or operational rollout tooling beyond normal migration sequencing and validation.

Users and Primary Flows

Primary users

• MSP staff managing contacts in the contact directory or client detail screens.
• MSP staff creating contacts quickly from the contacts area or while creating a client.
• MSP staff viewing a contact phone from ticket and related-detail screens.
• Admins/operators relying on contact import and Entra synchronization.

Primary flows

1. Open a contact in the contacts area, add multiple phone numbers, assign canonical or custom types, and choose exactly one default.
2. Create a new contact from quick-add and enter one or more phone numbers before save.
3. Create a client with an inline primary contact and capture multiple phone numbers for that new contact.
4. View contacts in list/table form and see the default phone number rendered consistently.
5. Search contacts by any stored phone number, not just the default one.
6. Import contacts from CSV with one primary/default phone number in v1, then manage additional numbers in the UI after import.
7. Sync a contact from Entra and retain both mobile and business phone values where present.

UX / UI Notes

Contact authoring/editing surfaces in scope

• packages/clients/src/components/contacts/ContactDetails.tsx
• packages/clients/src/components/contacts/ContactDetailsEdit.tsx
• packages/clients/src/components/contacts/ContactDetailsView.tsx
• packages/clients/src/components/contacts/QuickAddContact.tsx
• packages/clients/src/components/clients/QuickAddClient.tsx (inline contact subsection)

Contact display surfaces in scope

• packages/clients/src/components/contacts/Contacts.tsx
• packages/clients/src/components/contacts/ClientContactsList.tsx
• packages/tickets/src/components/ticket/TicketProperties.tsx
• packages/clients/src/components/interactions/InteractionDetails.tsx via ContactDetailsView

Contact import surfaces in scope

• packages/clients/src/components/contacts/ContactsImportDialog.tsx
• Export/query behavior in packages/clients/src/actions/contact-actions/contactActions.tsx

UX assumptions

• Contact forms should use a repeater/list UI for phone numbers with add/remove controls.
• Each phone row should let the user:
  • enter a phone number
  • pick a canonical type or choose/create a custom type
  • mark the row as default
• When numbers exist, the form must enforce exactly one default.
• List/table/detail surfaces that previously showed one phone_number should render the default phone number only.
• Where useful, the default phone label/type may be shown as a badge or secondary text, but v1 does not require a redesign of list layouts.
• CSV import/export remains intentionally simpler than the full UI:
  • v1 import/export handles one default phone number and its type
  • multi-number bulk CSV shape is out of scope for this first cut

Requirements

Functional Requirements

• FR-001 Add a normalized contact phone storage model that supports multiple phone rows per contact.
• FR-002 Add a tenant-scoped custom phone type definition store for suggestion/deduplication of custom labels.
• FR-003 Keep canonical phone types fixed to work, mobile, home, fax, and other.
• FR-004 Require at most one default phone number per contact and exactly one default when a contact has at least one phone number.
• FR-005 Preserve display order for multiple phone numbers.
• FR-006 Store a searchable normalized phone value per phone row in addition to the displayed phone string.
• FR-007 Backfill existing contacts.phone_number values into the new normalized phone table as default work numbers unless empty.
• FR-008 Replace contact create and update contracts so they accept the new phone collection instead of the old scalar field.
• FR-009 Replace contact read contracts so callers receive ordered phone rows and can derive the default number without reading contacts.phone_number.
• FR-010 Update contact validation so phone collection writes validate number format, type shape, default uniqueness, and custom type deduplication.
• FR-011 Update ContactDetails to edit multiple phone numbers, custom types, and default selection.
• FR-012 Update ContactDetailsEdit and ContactDetailsView to render the normalized contact phone model.
• FR-013 Update QuickAddContact to capture the normalized contact phone model.
• FR-014 Update the inline contact section in QuickAddClient to capture the normalized contact phone model.
• FR-015 Update contacts list surfaces to display the default phone number in place of the old scalar phone.
• FR-016 Update contact search/filter behavior so phone search matches any stored contact phone number.
• FR-017 Update contact list sort behavior so phone sorting is based on the derived default phone number.
• FR-018 Update ticket/contact-related display surfaces to show the derived default contact phone number.
• FR-019 Update contact CSV import/export behavior to map a single imported/exported phone into the normalized model as the default number.
• FR-020 Update workflow/domain event payloads and API/service schemas that currently emit or validate phone_number.
• FR-021 Update Entra sync so mobile and business phones are mapped into the normalized contact phone model instead of collapsing to one scalar.
• FR-022 Remove application reliance on contacts.phone_number after the new model is in use.
• FR-023 Drop the legacy contacts.phone_number column in a follow-up migration after code has cut over.

Non-functional Requirements

• NFR-001 Migration sequencing must be operationally safe: add/backfill new tables before the code release that stops reading contacts.phone_number, then drop the old column afterward.
• NFR-002 Contact writes touching phone numbers must remain transactional so child rows and the parent contact cannot drift.
• NFR-003 Existing contacts with no phone number must remain valid and should simply hydrate with an empty phone list.
• NFR-004 Custom phone type deduplication must be case-insensitive at the tenant scope.
• NFR-005 Searchability of phone numbers must not depend on formatting characters in the stored display value.

Data / API / Integrations

Proposed tables

contact_phone_type_definitions

• tenant
• contact_phone_type_id
• label
• normalized_label
• created_at
• updated_at
• unique on (tenant, normalized_label)

contact_phone_numbers

• tenant
• contact_phone_number_id
• contact_name_id
• phone_number
• normalized_phone_number
• canonical_type nullable
• custom_phone_type_id nullable
• is_default
• display_order
• created_at
• updated_at

Table constraints

• Exactly one of canonical_type or custom_phone_type_id must be present.
• canonical_type is constrained to work | mobile | home | fax | other.
• Foreign key from contact_phone_numbers to contacts.
• Foreign key from contact_phone_numbers to contact_phone_type_definitions when custom type is used.
• Partial uniqueness for one default per contact.

Type/API shape

• Replace scalar phone_number on contact DTOs with a phone_numbers collection.
• Each phone row should expose:
  • contact_phone_number_id
  • phone_number
  • normalized_phone_number
  • canonical_type
  • custom_type
  • is_default
  • display_order
• Contact list/query responses may additionally expose a derived default_phone_number and default_phone_type for convenience.

Import/export shape

• CSV import v1 continues to accept one phone column and maps it to a single default work phone unless a type column is added in the same effort.
• CSV export v1 emits the default phone number only.

Entra mapping assumption

• mobilePhone maps to canonical mobile.
• businessPhones[] map to canonical work.
• If one or more business phones exist, the first business phone is the default.
• Otherwise the first mobile phone becomes the default.

Security / Permissions

• No new permission model is introduced.
• Existing contact create/update/read permissions continue to govern all affected flows.
• Custom phone type creation is implicit within existing contact edit/create permissions; no separate admin permission is added.

Observability

• No new observability scope is included in v1 beyond normal migration logging, validation errors, and test coverage.

Rollout / Migration

1. Migration A:
   • create contact_phone_type_definitions
   • create contact_phone_numbers
   • backfill existing contacts.phone_number into contact_phone_numbers
   • keep contacts.phone_number in place temporarily for deploy safety
2. Code release:
   • move all contact-domain reads/writes/UI to phone_numbers
   • stop reading or writing contacts.phone_number
3. Migration B:
   • drop contacts.phone_number
   • remove any remaining schema/index references to the old scalar field

This is still a breaking cutover at the application contract level, but the database rollout is intentionally split to avoid coupling schema removal to the same deploy that introduces the new readers/writers.

Open Questions

• Whether v1 CSV import/export should add an explicit phone-type column or stay with default work only.
• Whether contact list/table responses should expose derived default_phone_number fields from the server for convenience or let each caller derive them from phone_numbers.
• Whether the first version of the phone-number editor should be a contact-only local component or a reusable shared UI component.

Acceptance Criteria (Definition of Done)

• MSP users can add, remove, type, reorder, and default multiple phone numbers on a contact.
• MSP users can choose canonical phone types or enter a new custom type that becomes a tenant-scoped suggestion for future contacts.
• Contact detail, quick-add, and inline client-contact creation flows all work against the new model.
• Contact list and ticket display surfaces render the derived default phone consistently.
• Contact search finds a contact by any stored phone number.
• Existing scalar phone values are migrated into the normalized model.
• Entra sync preserves both mobile and business phone information in the normalized contact phone model.
• The application no longer relies on contacts.phone_number, and the legacy column can be removed cleanly.