Cross-instance contact match and role mapping

Objective

• Ensure contacts on cross-instance quotes are matched or created in the destination company with correct contact roles, including user-visible mapping when roles do not align across brands.

Background

• Parent epic: pending quote in destination from source inspection.
• API child creates people[] on the quote; this child deepens role mapping and UX for mismatches.
• Action flow migration already solves cross-company contact role and required info mapping in ActionFlowMigrationClient.tsx with backend support in contactRoleFlowMigration.ts and copyActionFlowToCompany.ts — reuse patterns where possible, scoped to quote handoff.

Scope

Backend

• Extend cross-instance handoff to accept optional contactRoleMapping (source role id → target role id), similar to flow.ts copy body shape.
• Suggest target roles for unmapped source roles (endpoint or included in preview response — decision needed).
• Match-or-create contacts by email/phone; never persist source _contactId on destination quote.
• Handle primary contact flag and multiple people on source inspection.

Frontend

• When source and target roles differ, present mapping UI before create (or on preview step) — patterns from attik-frontend/src/app/admin/settings/instance-management/action-flow-migration/ActionFlowMigrationClient.tsx (crSuggestions, crUserMapping).
• Surface unmapped roles clearly; block submit until required mappings resolved or decision needed for optional roles.

Out of scope

• Service/charge mapping.
• Report attachments.

References

• attik-backend/src/util/functions/actionFlows/contactRoleFlowMigration.ts
• attik-backend/src/util/functions/spectora/findSpectoraContactMatches.ts
• attik-frontend/src/app/admin/settings/instance-management/action-flow-migration/ActionFlowMigrationClient.tsx