feat: add revision history timeline and feedback action items for enhanced review process
This commit is contained in:
Leivur R. Djurhuus
parent
42ad52fc46
commit
693fc99d4c
1 changed files with 240 additions and 10 deletions
250
UPGRADE_PLAN.md
250
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** |
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue