Initial commit

2026-05-19 22:20:29 +02:00
commit 0fbe856dce
173 changed files with 38316 additions and 0 deletions
@@ -0,0 +1,523 @@
+The current architecture has a conceptual problem around:
+
+* shots
+* tasks
+* versions
+* approvals
+* client review visibility
+
+We need to refactor the production/review workflow so that TASKS become the true operational and review unit.
+
+IMPORTANT:
+Do NOT redesign the whole app.
+This is a workflow/data relationship correction and cleanup.
+
+The goal is:
+
+* clearer production flow
+* correct review behavior
+* correct client review visibility
+* correct kanban behavior
+* proper task-based versioning
+
+---
+
+# CORE ARCHITECTURAL DECISION
+
+A SHOT is:
+
+* a container/grouping
+* a production entity
+* NOT directly reviewable
+
+A TASK is:
+
+* the actual work unit
+* the review unit
+* the approval unit
+* the kanban unit
+* the upload/version unit
+
+This means:
+
+```plaintext id="b89ah6"
+Shot
+ ├── Track Task
+ │     └── Versions
+ │
+ ├── Roto Task
+ │     └── Versions
+ │
+ └── Comp Task
+       └── Versions
+```
+
+NOT:
+
+```plaintext id="6fjlwm"
+Shot
+ └── Versions
+```
+
+That old structure is incorrect.
+
+---
+
+# REQUIRED REFACTOR
+
+## 1. VERSIONS MUST BELONG TO TASKS
+
+Currently:
+
+```plaintext id="y7txg8"
+Shot -> Versions
+```
+
+Refactor to:
+
+```plaintext id="dh4mf6"
+Task -> Versions
+```
+
+A version upload must ALWAYS belong to:
+
+* exactly one task
+
+Remove the concept of:
+
+* "shot latest version"
+
+Instead:
+
+* each task has its own latest version
+
+Examples:
+
+```plaintext id="hskx5e"
+SH010
+ ├── Track Task
+ │     └── latest: v003
+ │
+ ├── Roto Task
+ │     └── latest: v005
+ │
+ └── Comp Task
+       └── latest: v008
+```
+
+This is the correct production model.
+
+---
+
+# 2. SHOTS SHOULD NOT DIRECTLY DRIVE CLIENT REVIEW
+
+Currently:
+
+* shot status = CLIENT_REVIEW
+* portal shows latest uploaded version
+* task context lost
+
+This is incorrect.
+
+Client review should be TASK-BASED.
+
+---
+
+# NEW CLIENT REVIEW RULE
+
+The client portal should display:
+
+```plaintext id="rlazoz"
+Tasks
+  where latest version is marked:
+    isClientVisible = true
+```
+
+NOT:
+
+```plaintext id="cr7j27"
+Shots where shot.status = CLIENT_REVIEW
+```
+
+This fixes:
+
+* incorrect versions
+* missing task context
+* review ambiguity
+
+---
+
+# CLIENT PORTAL SHOULD SHOW
+
+Instead of:
+
+```plaintext id="l3l0xr"
+SH010
+```
+
+Show:
+
+```plaintext id="1e2dn4"
+SH010 — COMP
+v008
+```
+
+Or:
+
+```plaintext id="nyc0h4"
+SH010 — ROTO
+v005
+```
+
+Clients review TASK DELIVERABLES.
+
+Not abstract shots.
+
+---
+
+# 3. SHOT STATUS SHOULD BE DERIVED, NOT MANUALLY DRIVEN
+
+Current shot statuses:
+
+```plaintext id="5f9n1d"
+WAITING
+IN_PROGRESS
+INTERNAL_REVIEW
+CLIENT_REVIEW
+REVISIONS
+APPROVED
+FINAL
+```
+
+This is creating confusion because:
+
+* shots are containers
+* tasks are actual workflow units
+
+Refactor shot statuses to be:
+
+* simplified
+* mostly derived automatically from task states
+
+---
+
+# NEW SHOT STATUS MODEL
+
+Reduce shot statuses to:
+
+```ts id="8km4hh"
+WAITING
+IN_PROGRESS
+IN_REVIEW
+REVISIONS
+COMPLETE
+```
+
+Definitions:
+
+## WAITING
+
+No active tasks started.
+
+## IN_PROGRESS
+
+At least one task is:
+
+* TODO
+* IN_PROGRESS
+
+## IN_REVIEW
+
+At least one task is:
+
+* INTERNAL_REVIEW
+* CLIENT_REVIEW
+
+## REVISIONS
+
+At least one task is:
+
+* CHANGES
+
+## COMPLETE
+
+All tasks are:
+
+* DONE
+
+IMPORTANT:
+Shot status should mostly be AUTO-CALCULATED from tasks.
+
+NOT manually set constantly.
+
+---
+
+# 4. REMOVE "FINAL"
+
+The current:
+
+```plaintext id="qmv5ps"
+APPROVED
+FINAL
+```
+
+is redundant/confusing.
+
+Recommendation:
+REMOVE `FINAL`.
+
+Use:
+
+```plaintext id="tyf56q"
+DONE
+```
+
+at task level.
+
+And:
+
+```plaintext id="7u6wvp"
+COMPLETE
+```
+
+at shot level.
+
+Cleaner.
+Much easier mentally.
+
+---
+
+# 5. TASK STATUS IS THE TRUE KANBAN STATUS
+
+Task statuses should drive:
+
+* kanban columns
+* review state
+* client review state
+
+Task statuses:
+
+```ts id="l0m39n"
+TODO
+IN_PROGRESS
+INTERNAL_REVIEW
+CLIENT_REVIEW
+CHANGES
+DONE
+```
+
+These statuses represent:
+
+* actual workflow state
+* actual review state
+
+---
+
+# 6. REVIEW FLOW RULES
+
+## Upload Version
+
+When artist uploads new version:
+
+```plaintext id="0q6qzx"
+Task → INTERNAL_REVIEW
+```
+
+Kanban card moves automatically:
+
+```plaintext id="ym9x1s"
+IN_PROGRESS
+→ INTERNAL_REVIEW
+```
+
+---
+
+## Supervisor Shares With Client
+
+When clicking:
+
+```plaintext id="rxry5f"
+Share With Client
+```
+
+System should:
+
+* mark latest version:
+  isClientVisible = true
+* set task status:
+  CLIENT_REVIEW
+
+Kanban updates automatically:
+
+```plaintext id="7j69vz"
+INTERNAL_REVIEW
+→ CLIENT_REVIEW
+```
+
+---
+
+## Client Approves
+
+Client approval should:
+
+* approve ONLY the task
+* NOT the entire shot
+
+System:
+
+```plaintext id="xcl9sy"
+Task.status = DONE
+Version.approvalStatus = APPROVED
+```
+
+Kanban:
+
+```plaintext id="p1m31i"
+CLIENT_REVIEW
+→ DONE
+```
+
+---
+
+## Client Requests Changes
+
+System:
+
+```plaintext id="z5fprm"
+Task.status = CHANGES
+Version.approvalStatus = NEEDS_CHANGES
+```
+
+Kanban:
+
+```plaintext id="r6phfx"
+CLIENT_REVIEW
+→ CHANGES
+```
+
+---
+
+# 7. SHOT COMPLETION RULE
+
+A shot becomes:
+
+```plaintext id="l16lq6"
+COMPLETE
+```
+
+ONLY when:
+
+```plaintext id="t62l6n"
+ALL TASKS == DONE
+```
+
+Example:
+
+```plaintext id="0b2b7h"
+SH010
+ ├── Track → DONE
+ ├── Roto → DONE
+ └── Comp → DONE
+
+=> Shot COMPLETE
+```
+
+---
+
+# 8. CLIENT PORTAL STRUCTURE
+
+Refactor client portal to show:
+
+```plaintext id="t1qn79"
+Project
+ ├── Shot
+ │     ├── Task
+ │     │     └── Latest Shared Version
+```
+
+Example UI:
+
+```plaintext id="mjgr1k"
+SH010
+  COMP — v008
+  ROTO — v005
+
+SH020
+  COMP — v003
+```
+
+This is MUCH clearer.
+
+---
+
+# 9. TASK DETAIL PAGE SHOULD BECOME PRIMARY REVIEW HUB
+
+Task page should become:
+
+* upload page
+* review page
+* approval page
+* history page
+
+Structure:
+
+```plaintext id="e2bd4f"
+/tasks/[taskId]
+```
+
+Contains:
+
+* task info
+* latest version
+* version history
+* comments
+* annotations
+* approvals
+* review actions
+
+---
+
+# 10. IMPORTANT IMPLEMENTATION NOTES
+
+DO NOT:
+
+* rewrite comment system
+* rewrite annotation system
+* rewrite player
+
+JUST:
+
+* move relationships from Shot → Task
+* update logic
+* update queries
+* update review flow
+
+This is mostly:
+
+* schema cleanup
+* workflow cleanup
+* state cleanup
+
+---
+
+# IMPORTANT PRODUCT PRINCIPLE
+
+The production hierarchy should now be:
+
+```plaintext id="crkxfm"
+Project
+ → Shot
+   → Task
+     → Version
+       → Comments / Annotations / Approvals
+```
+
+NOT:
+
+```plaintext id="zebvlz"
+Project
+ → Shot
+   → Version
+```
+
+That distinction fixes nearly all current workflow inconsistencies.