optimizations

docs/collections-v5-implementation-summary.md

@@ -0,0 +1,138 @@
+# Collections v5 Implementation Summary
+
+## Scope
+
+Collections v5 extends the existing collections platform with operational metadata, workflow controls, health scoring, search, canonicalization, merge support, programming assignments, and snapshot-based observability.
+
+## Schema additions
+
+The collections table now carries v5 state for:
+
+- workflow and readiness
+- health state and health flags
+- canonical and duplicate metadata
+- program, partner, trust, sponsorship, governance, and experiment metadata
+- ranking and search boost tiers
+- health component scores and refresh timestamps
+- placement eligibility
+
+Supporting tables were added for:
+
+- program assignments
+- daily quality snapshots
+- recommendation snapshots
+- merge actions
+- cross-entity links
+- saved notes
+
+## New services
+
+- CollectionHealthService: evaluates metadata completeness, freshness, engagement, readiness, health state, eligibility, and daily snapshots
+- CollectionRankingService: computes recommendation tier, ranking bucket, and search boost tier
+- CollectionWorkflowService: validates workflow transitions and runs quality refresh flows
+- CollectionSearchService: public and owner/staff search across collection metadata
+- CollectionCanonicalService: assigns canonical targets safely
+- CollectionMergeService: merges source collections into canonical targets without affecting artwork ownership
+- CollectionProgrammingService: manages assignments, previews, eligibility refresh, duplicate scans, and recommendation refreshes
+- CollectionBackgroundJobService: dispatches queued health, quality, recommendation, and duplicate maintenance jobs
+- CollectionPartnerProgramService: isolates protected partner/program metadata updates
+- CollectionObservabilityService: cache keys and collection diagnostics
+- CollectionLinkService: manages generic creator, story, and category links for collection context modules
+
+## Route coverage
+
+Public:
+
+- GET /collections/search
+
+Owner/staff:
+
+- GET /settings/collections/search
+- GET /settings/collections/{collection}/health
+- POST /settings/collections/{collection}/workflow
+- POST /settings/collections/{collection}/quality-refresh
+- POST /settings/collections/{collection}/canonicalize
+- POST /settings/collections/{collection}/merge
+
+Staff programming:
+
+- GET /staff/collections/programming
+- POST /staff/collections/programs
+- PATCH /staff/collections/programs/{program}
+- POST /staff/collections/surfaces/preview
+- POST /staff/collections/eligibility/refresh
+- POST /staff/collections/duplicate-scan
+- POST /staff/collections/recommendation-refresh
+
+Scheduled maintenance:
+
+- php artisan collections:dispatch-maintenance
+
+## Payload changes
+
+Collection card and detail payloads now expose v5 metadata so dashboard, search, programming, and health tooling can consume the same core shape without custom adapters.
+
+## Dashboard changes
+
+The owner dashboard now includes health-oriented summary counts and warning payloads alongside the existing lifecycle, campaign, analytics, and attention views.
+
+It also includes an internal search and filtering panel for workflow, lifecycle, health, visibility, and placement readiness.
+
+## Staff programming UI
+
+The staff programming route now renders a dedicated programming studio with:
+
+- assignment management
+- live program pool preview
+- queued eligibility diagnostics
+- queued duplicate scan tools
+- queued recommendation refresh tools
+- internal experiment and partner/program governance controls with observability diagnostics for the selected collection, including treatment, placement, ranking, pool-version, ownership, sponsorship, and review metadata
+- staff merge queue for pending duplicate review and recent merge decisions, including direct canonicalize, merge, and reject actions in the studio
+
+## Background jobs
+
+Collections v5 now dispatches queued jobs for:
+
+- owner quality refreshes
+- staff eligibility refreshes
+- staff recommendation refreshes
+- staff duplicate scans
+- scheduled maintenance sweeps for stale health, recommendation, and duplicate work
+
+## Merge review workflow
+
+Collection management now includes an internal merge-review surface with:
+
+- duplicate candidate comparison cards
+- canonical target designation
+- direct merge actions for manual targets
+- not-duplicate dismissal that suppresses rejected pairs from future review payloads
+
+## Saved library changes
+
+The saved collections area now supports lightweight private notes per saved collection.
+
+## Cross-entity linking
+
+Collections can now link to creators, public artworks, published stories, and active categories through a generic entity-link flow exposed in collection management and rendered on the public detail page.
+
+## Test coverage
+
+Existing collection feature coverage still passes after v5 integration.
+
+Additional focused tests now cover:
+
+- owner-only health access
+- owner search scoping
+- protected workflow/programming fields
+- canonicalization and merge flows
+- public canonical redirects for canonicalized collections
+- staff programming assignments and previews
+- staff programming studio access
+- public search safety
+- workflow transition validation
+- saved collection notes
+- collection entity links on owner and public pages, including artwork and tag links with public-only filtering
+- public program landing pages with explicit partner and sponsor surfacing on discovery cards and headers
+- dashboard search/filter wiring