SkinbaseNova/docs/collections-v5-implementation-summary.md

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