From 693fc99d4cbcfe336390f3cf3a83ca9133679844 Mon Sep 17 00:00:00 2001 From: "Leivur R. Djurhuus" Date: Sun, 1 Mar 2026 12:06:24 -0600 Subject: [PATCH] feat: add revision history timeline and feedback action items for enhanced review process --- UPGRADE_PLAN.md | 250 ++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 240 insertions(+), 10 deletions(-) diff --git a/UPGRADE_PLAN.md b/UPGRADE_PLAN.md index 74f289f..beced05 100644 --- a/UPGRADE_PLAN.md +++ b/UPGRADE_PLAN.md @@ -147,7 +147,83 @@ between rounds. --- -### 5.4 — Review Sessions & Playlists +### 5.4 — Revision History Timeline & Version Control + +**What:** A dedicated panel within the review viewer that provides full version history +for every deliverable stage. Browse all revision rounds (v1, v2, v3...) with thumbnails, +see comments and annotations tied to each version, track the decision history per round, +and navigate between any version with a single click. + +**Why:** The core review loop in CG production is iterative — an artist submits, a +producer requests changes, the artist resubmits, and the cycle repeats multiple times. +Without a clear version timeline, it's easy to lose track of what feedback was given on +which round, what changed between versions, and who approved what and when. This is +the connective tissue between annotations (5.2), comparison (5.3), and review sessions +(5.5) — it provides the longitudinal view across all revision rounds. + +**Implementation:** +- Collapsible sidebar panel in the review viewer (right side or bottom drawer) +- Vertical timeline layout with each revision round as a node: + - **Thumbnail preview** of that round's submitted image (auto-generated via 8.2) + - **Round number + status badge** (Submitted, Changes Requested, Approved, Rejected) + - **Submitted by** (artist name + avatar) and **submission timestamp** + - **Annotation count** for that round (clickable to filter annotation layer) + - **Comment thread summary** — first line of feedback + total comment count + - **Decision record** — who approved/rejected, when, with what note + - **File metadata** — resolution, file size, format (useful for tracking resubmission quality) +- Click any round to load that version in the image viewer with its annotations +- "Latest" badge on the most recent round; "Current" badge on the one being viewed +- Diff indicators between rounds: visual markers showing which rounds had changes requested + vs. approved, building a clear progression narrative +- Keyboard navigation: up/down arrows to move through rounds, Enter to load +- Filtering: show all rounds, show only rounds with feedback, show only decision points +- Timeline integrates with comparison viewer (5.3): selecting two rounds from the timeline + opens them in side-by-side/overlay/wipe mode +- Export revision history as PDF report (round-by-round summary with thumbnails, feedback + notes, decisions, and timestamps) for stakeholder documentation + +**Comment threading per version:** +- Comments on the existing deliverable stage are already threaded (Phase 3) +- This feature extends the comment display to be **grouped by revision round** in the + timeline panel — each round's node expands to show its associated comments and annotations +- New comments can be posted against any historical round (not just the latest), enabling + back-references like "the fix from v2 introduced a new issue visible at..." +- Comments from external review links (10.3) and review sessions (5.5) also appear in the + timeline, attributed to the round they were made on + +**Annotation history per version:** +- Each annotation is already linked to a `revisionId` (5.2) +- The timeline panel shows annotation counts per round and toggles annotation visibility + per round on the image viewer +- "Show all annotations" mode overlays annotations from all rounds with color-coded borders + (e.g., v1 = blue, v2 = orange, v3 = green) for seeing the full feedback history at once +- "Show resolved" toggle to distinguish between addressed and still-open annotations + +**Decision audit trail:** +- Every approve/reject/changes-requested decision is logged with: who, when, note +- Displayed inline in the timeline at the relevant round +- Links to approval chain records (7.2) when multi-level approval is configured +- Exportable as part of the revision history PDF + +**No new data model required** — uses existing `Revision` (roundNumber, status, feedbackNotes, +internalNotes, attachments, timestamps), `Comment` (threaded, per stage), and `Annotation` +(per revision) models. The timeline is a read-only aggregation view over existing data. + +**Key files:** +- `src/components/review/revision-timeline.tsx` — Main timeline panel component +- `src/components/review/revision-node.tsx` — Individual round node with expandable details +- `src/components/review/revision-comments.tsx` — Per-round comment thread display +- `src/components/review/revision-annotations-summary.tsx` — Annotation count + filter toggles +- `src/components/review/revision-history-export.tsx` — PDF export generator +- `src/hooks/use-revision-history.ts` — TanStack Query hook aggregating revisions + comments + annotations +- Update `src/app/(app)/projects/[projectId]/deliverables/[deliverableId]/review/page.tsx` — Integrate timeline panel + +**Dependencies:** Requires 5.1 (Image Viewer) + 5.2 (Annotations). Enhanced by 5.3 (Comparison) +and 8.2 (Preview Generation for thumbnails). + +--- + +### 5.5 — Review Sessions & Playlists **What:** Curate a set of deliverables/revisions into a review session. Walk through them sequentially with per-item approve/request-changes/reject actions. Shareable via link. @@ -221,7 +297,159 @@ enum ReviewDecision { - `src/hooks/use-review-sessions.ts` — TanStack Query hooks - API routes: `/api/reviews/`, `/api/reviews/[sessionId]/`, `/api/reviews/[sessionId]/items/` -**Dependencies:** Requires 5.1 + 5.2 (Image Viewer + Annotations) +**Dependencies:** Requires 5.1 + 5.2 (Image Viewer + Annotations). Enhanced by 5.4 (Revision Timeline). + +--- + +### 5.6 — Feedback Action Items (Artist Checklist) + +**What:** Every annotation and review comment automatically becomes an actionable to-do +item on a checklist for the assigned artist. Artists see a clear, prioritized list of +everything they need to address for each revision round, and can check items off as they +work through them. When all items are resolved, the stage is ready for resubmission. + +**Why:** Without this, artists must mentally parse through comment threads and scan +annotations to build their own list of what needs fixing. Items get missed, context gets +lost, and producers have to manually verify whether feedback was addressed. A structured +checklist makes the feedback-to-fix loop explicit, trackable, and auditable. + +**How it works — the full feedback loop:** +1. **Reviewer creates feedback** — draws annotation or writes comment with actionable note +2. **System auto-creates a FeedbackItem** — linked to the annotation/comment, assigned to + the stage's artist(s), categorized by severity +3. **Artist sees checklist** — organized by priority, with direct links to the annotation + on the image +4. **Artist works through items** — checks each off as addressed, optionally adds a + resolution note ("Fixed — adjusted specular intensity by 15%") +5. **Artist submits new revision** — any unchecked items carry forward as still-open on + the next round with a warning +6. **Reviewer verifies** — can see which items were marked resolved, compare before/after, + and either confirm resolution or reopen + +**Where the checklist appears (3 locations):** + +**1. Review Viewer — Feedback Panel (primary)** +- Dedicated collapsible panel in the review viewer, alongside the revision timeline (5.4) +- Full checklist for the current revision round with: + - Checkbox + item summary (auto-generated from annotation/comment text) + - Severity indicator: Critical (red), Major (orange), Minor (yellow), Suggestion (blue) + - Thumbnail crop of the annotated region (click to zoom to that spot on the image) + - "Resolve" action with optional note field + - Status: Open, In Progress, Resolved, Verified (by reviewer), Reopened +- Filter by: status (open/resolved), severity, annotation type +- Progress bar at top: "4 of 7 items resolved" +- Grouped by revision round — see current round's items and carried-forward items from + previous rounds + +**2. My Work Page — Feedback Summary (artist's home base)** +- Each assignment card on the existing My Work page gets a feedback badge: "5 open items" +- Expandable section within each assignment showing the checklist inline +- Click any item to deep-link directly to the review viewer, zoomed to that annotation +- Aggregate counters at top of My Work page: "12 open feedback items across 3 assignments" +- Sort/filter assignments by: most feedback items, highest severity items first, oldest + unresolved items + +**3. Stage Card on Deliverable Detail — Progress Indicator (producer view)** +- Compact progress indicator on the stage card: "4/7 feedback items resolved" +- Color-coded: red if critical items are open, green if all resolved +- Hover popover showing breakdown by severity +- Producers can see at a glance which stages have outstanding feedback before approving + +**Auto-creation rules:** +- When an annotation is created → auto-create FeedbackItem linked to that annotation +- When a comment is posted and contains actionable language → auto-create FeedbackItem + (optional: reviewer can toggle "Mark as action item" checkbox when posting a comment, + default ON for annotations, default OFF for comments to avoid noise from discussion threads) +- Reviewers can also manually create standalone feedback items (not tied to an annotation) + for general notes like "Overall color temperature feels too warm" +- Bulk creation: reviewer can batch-create items from a review session (5.5) where each + "changes requested" decision auto-generates items from that session's annotations + +**Severity levels:** +- **Critical** — Must fix before resubmission (blocks approval). E.g., wrong product shown, + missing required element +- **Major** — Should fix, significant quality issue. E.g., visible artifacts, wrong lighting +- **Minor** — Nice to fix, small quality issue. E.g., minor texture seam, slight color shift +- **Suggestion** — Optional improvement, not required for approval. E.g., "Consider slightly + warmer fill light" + +**Data model additions:** +```prisma +model FeedbackItem { + id String @id @default(cuid()) + deliverableStageId String + deliverableStage DeliverableStage @relation(fields: [deliverableStageId], references: [id], onDelete: Cascade) + revisionId String + revision Revision @relation(fields: [revisionId], references: [id], onDelete: Cascade) + annotationId String? + annotation Annotation? @relation(fields: [annotationId], references: [id], onDelete: SetNull) + commentId String? + comment Comment? @relation(fields: [commentId], references: [id], onDelete: SetNull) + summary String // short description of what needs to be done + severity FeedbackSeverity @default(MAJOR) + status FeedbackStatus @default(OPEN) + sortOrder Int @default(0) + assignedToId String? + assignedTo User? @relation("FeedbackAssignee", fields: [assignedToId], references: [id]) + createdById String + createdBy User @relation("FeedbackCreator", fields: [createdById], references: [id]) + resolvedById String? + resolvedBy User? @relation("FeedbackResolver", fields: [resolvedById], references: [id]) + resolvedAt DateTime? + resolutionNote String? + verifiedById String? + verifiedBy User? @relation("FeedbackVerifier", fields: [verifiedById], references: [id]) + verifiedAt DateTime? + carriedFromId String? // if carried forward from a previous round + carriedFrom FeedbackItem? @relation("FeedbackCarryForward", fields: [carriedFromId], references: [id]) + carriedTo FeedbackItem[] @relation("FeedbackCarryForward") + createdAt DateTime @default(now()) + updatedAt DateTime @updatedAt + + @@index([deliverableStageId]) + @@index([revisionId]) + @@index([assignedToId]) + @@index([status]) + @@map("feedback_items") +} + +enum FeedbackSeverity { + CRITICAL + MAJOR + MINOR + SUGGESTION +} + +enum FeedbackStatus { + OPEN + IN_PROGRESS + RESOLVED + VERIFIED + REOPENED +} +``` + +**Key files:** +- `src/components/review/feedback-checklist.tsx` — Main checklist panel in review viewer +- `src/components/review/feedback-item.tsx` — Individual checklist item with resolve action +- `src/components/review/feedback-progress-bar.tsx` — Progress bar (4/7 resolved) +- `src/components/review/feedback-create-dialog.tsx` — Manual item creation +- `src/components/my-work/feedback-summary.tsx` — Inline checklist on My Work page +- `src/components/stages/feedback-indicator.tsx` — Compact badge for stage cards +- `src/lib/services/feedback-service.ts` — CRUD, auto-creation logic, carry-forward +- `src/lib/validators/feedback.ts` — Zod schemas +- `src/hooks/use-feedback-items.ts` — TanStack Query hook +- API routes: `/api/feedback/`, `/api/feedback/[itemId]/`, `/api/stages/[stageId]/feedback/` + +**Automation integration (Phase 7):** +- Auto-rule: "When all Critical + Major feedback items are resolved → notify producer + that stage is ready for re-review" +- Auto-rule: "When a new revision is submitted with unresolved Critical items → warn + artist and block submission" (configurable) +- Auto-rule: "When feedback item is unresolved for >3 days → escalate notification" + +**Dependencies:** Requires 5.2 (Annotations) + 5.4 (Revision Timeline). Enhanced by 7.1 +(Automation triggers). Integrates with existing My Work page and deliverable detail page. --- @@ -894,7 +1122,7 @@ brand team) to view specific deliverables without creating an account. - `src/lib/services/external-link-service.ts` — Token generation + validation - API routes: `/api/external-links/`, `/api/external-links/[token]/` -**Note:** Overlaps with 5.4 Review Sessions share functionality and 9.3 Client Portal. +**Note:** Overlaps with 5.5 Review Sessions share functionality and 9.3 Client Portal. These should share the underlying token/auth infrastructure but serve different use cases (bulk review vs. individual deliverable vs. project overview). @@ -1012,7 +1240,7 @@ file naming convention (e.g., `SKU-12345_catalog_v2.png` matches Catalog Images | Phase | New Models | Modified Models | |-------|-----------|----------------| -| 5 | Annotation, ReviewSession, ReviewSessionItem | Comment (add annotations relation) | +| 5 | Annotation, ReviewSession, ReviewSessionItem, FeedbackItem | Comment (add annotations + feedback relations) | | 6 | Skill, UserSkill, StageSkillRequirement | User (add maxCapacity, skills) | | 7 | AutomationRule, AutomationExecution, ApprovalChain, ApprovalStep, ApprovalRecord, ProjectTemplate, ProjectTemplateDeliverable | — | | 8 | AssetSpec, AssetValidationResult, AIReviewResult | Revision (add validation/AI relations) | @@ -1020,7 +1248,7 @@ file naming convention (e.g., `SKU-12345_catalog_v2.png` matches Catalog Images | 10 | ActivityEntry | — | | 11 | SavedView | — | -**Total new models: 20** +**Total new models: 21** --- @@ -1028,7 +1256,7 @@ file naming convention (e.g., `SKU-12345_catalog_v2.png` matches Catalog Images | Phase | Routes | |-------|--------| -| 5 | `/api/annotations/`, `/api/reviews/`, `/api/reviews/[id]/items/` | +| 5 | `/api/annotations/`, `/api/reviews/`, `/api/reviews/[id]/items/`, `/api/feedback/`, `/api/feedback/[id]/`, `/api/stages/[id]/feedback/` | | 6 | `/api/workload/`, `/api/skills/`, `/api/users/[id]/skills/` | | 7 | `/api/automations/`, `/api/automations/[id]/executions/`, `/api/approval-chains/`, `/api/stages/[id]/approve/`, `/api/templates/`, `/api/templates/[id]/instantiate/` | | 8 | `/api/asset-specs/`, `/api/revisions/[id]/validate/`, `/api/webhooks/ai-review/`, `/api/revisions/[id]/ai-review/` | @@ -1036,7 +1264,7 @@ file naming convention (e.g., `SKU-12345_catalog_v2.png` matches Catalog Images | 10 | `/api/projects/[id]/activity/`, `/api/external-links/` | | 11 | `/api/views/` | -**Total new API routes: ~22** +**Total new API routes: ~25** --- @@ -1078,7 +1306,9 @@ Phase 5 (Visual Review) ─── standalone, highest impact |-- 5.1 Image Viewer <-- foundation for everything |-- 5.2 Annotations <-- requires 5.1 |-- 5.3 Comparison <-- requires 5.1 - +-- 5.4 Review Sessions <-- requires 5.1 + 5.2 + |-- 5.4 Revision History Timeline <-- requires 5.1 + 5.2, enhanced by 5.3 + |-- 5.5 Review Sessions <-- requires 5.1 + 5.2, enhanced by 5.4 + +-- 5.6 Feedback Action Items <-- requires 5.2 + 5.4, integrates with My Work Phase 6 (Workload) ─── standalone, high impact for producers | @@ -1109,14 +1339,14 @@ Phase 11 (QoL) ─── standalone incremental improvements, can be interleaved | Phase | New Models | New Routes | New Pages | Components | |-------|-----------|-----------|-----------|------------| -| 5 | 4 | 3 | 3 | ~15 | +| 5 | 5 | 6 | 3 | ~32 | | 6 | 3 | 3 | 2 | ~8 | | 7 | 6 | 6 | 3 | ~10 | | 8 | 3 | 4 | 1 | ~8 | | 9 | 2 | 4 | 2 | ~8 | | 10 | 1 | 2 | 2 | ~6 | | 11 | 1 | 1 | 0 | ~8 | -| **Total** | **20** | **~23** | **~13** | **~63** | +| **Total** | **21** | **~26** | **~13** | **~80** | ---