58 lines
2.6 KiB
Markdown
58 lines
2.6 KiB
Markdown
# Address Quality And Reversible Merges
|
|
|
|
## Operator Workflow
|
|
|
|
Open the shield action for a selected address book to review its quality. The
|
|
dialog shows:
|
|
|
|
- the number of contacts and contact points in the bounded scan
|
|
- current invalid, returned, stale, and undeliverable contact points
|
|
- explainable duplicate suggestions with their score inputs
|
|
- active and recovered merge records
|
|
|
|
Each contact point also has a `Quality` action in the contact detail. Recording
|
|
a new state ends an overlapping current state and retains both entries in
|
|
history. Use a stable reason code and an evidence reference when the state came
|
|
from delivery, import, or correction evidence.
|
|
|
|
`valid` makes the point normally usable. `invalid`, `returned`, and
|
|
`undeliverable` make it invalid for recipient resolution. `stale` remains a
|
|
distinct status so a downstream workflow can warn, request confirmation, or
|
|
block according to Policy. A later `valid` decision is a correction; it does
|
|
not delete the earlier evidence.
|
|
|
|
## Duplicate Review
|
|
|
|
Suggestions do not merge automatically. The score is the bounded sum of named
|
|
exact-match features. The operator chooses the surviving contact and whether to
|
|
combine unique contact points or retain only the survivor's points. The API can
|
|
additionally select the source contact for each scalar field and rank source
|
|
kinds.
|
|
|
|
A successful merge:
|
|
|
|
- archives each duplicate and redirects its stable contact ID to the survivor
|
|
- records scalar and contact-point survivorship decisions
|
|
- carries field and contact-point source provenance forward
|
|
- copies applicable quality and communication-governance evidence
|
|
- repoints address-list entries to the survivor and mapped contact point
|
|
- stores deterministic before/after evidence hashes
|
|
- emits core change-sequence and audit evidence
|
|
|
|
The merge history offers `Undo` and `Split`. Both restore the exact recorded
|
|
pre-merge contacts and list memberships. Recovery is deliberately rejected when
|
|
the contact or membership evidence changed after the merge. Reconcile those
|
|
later edits before retrying; the system does not silently discard them.
|
|
|
|
## Consumer Contract
|
|
|
|
Consumers resolve live contacts through `addresses.contact_point_resolution` or
|
|
`distribution.recipient_channel_facts`. They receive quality status, stable
|
|
reason codes, evidence provenance, and the current source revision. Consumers
|
|
must not read Addresses tables or recreate quality rules. A workflow requiring
|
|
historical proof freezes a contact-point snapshot before delivery.
|
|
|
|
The duplicate and quality endpoints are bounded. `truncated=true` means the
|
|
operator should narrow the source or run a staged API review; it does not mean
|
|
that the unreturned contacts were found clean.
|