Client Handover Route Reference

What this route is for

Client Handover owns customer-safe package assembly, readiness review, package publication, grant revocation, package revocation, and package activity review.

Visibility and capability notes

Item	Details
Route id	`client-handover`
Visibility	Customer-facing admin route for admin users.
Capability notes	Requires CRM capability. Scheduler-only users do not receive this route.
Direct inbound	Shell navigation, Data Quality handover package samples, and handover links from customer or site context where present.

Main regions, dialogs, and controls

Surface	What it does
Package list	Filters packages by status and site ID, then opens package detail.
New package dialog	Creates a package from a title, site ID, optional CRM account ID, source items JSON, and grants JSON.
Package detail	Shows source items, readiness, blockers, grants, expiry, access state, and activity.
Publish action	Publishes a draft package when it has no readiness blockers.
Revoke package	Revokes the package and current customer access.
Revoke grant	Revokes access for one grant without revoking the whole package.

Key actions

Create a package.
Filter package list by status or site.
Inspect package readiness.
Publish a draft package.
Revoke a package.
Revoke a recipient grant.
Review package activity.

Filters and URL state

Param	What it controls
`packageId`	Opens package detail.
`siteId`	Filters packages by site and pre-fills the create dialog.
`crmAccountId`	Pre-fills the create dialog.
`status`	Filters packages by draft, published, or revoked.
`create`	Opens create mode.

Source and permission model

Source or permission	Values
Source types	`generated_report`, `inspection`, `quote`, `work_order`
Grant permissions	`view`, `download`, `respond`
Package status	`draft`, `published`, `revoked`
Readiness states	`draft`, `needs_review`, `proof_ready`, `client_ready`, `blocked`, `not_assessed`

The current create dialog accepts source items and grants as JSON arrays. It does not yet provide a picker for reports, inspections, quotes, work orders, contacts, or customer users.

Outputs and side effects

Creates customer_handover_packages, package items, grants, and activity events.
Allows customer-facing package access only after publication.
Records customer views, downloads, denied access, expiry, acceptance, and revocation events.
Supports customer package portfolio and item-download endpoints for granted users.

Inbound links

Shell Client Handover navigation.
#/client-handover?packageId=...
Data Quality draft handover package samples.

Outbound links

Source records are represented by IDs in the package items table.
Customer activity returns context to the package detail.

Indirect handoffs

Report Writer and Reports quality affect whether generated report items are ready for customer handover.
Quote and work-order state affects whether commercial or remedial records are safe to include.
CRM contact and account quality affects customer access and follow-up.

Troubleshooting

Symptom	What to check
Publish is disabled	Resolve item readiness blockers or package blocked state.
A grant cannot be revoked	Check whether it was already revoked.
A package does not appear	Check status and site filters.
Customer access is denied	Check publication state, grant identity, expiry, and revocation.