Another attempt at clarifying Geonetwork workflow

ecospheres_migrator/geonetwork.py

@@ -23,27 +23,34 @@ class WorkflowStatus(IntEnum):
 
 
 class WorkflowStage(StrEnum):
-    # A workflow can be in one of the following stages:
-    # 1. NEVER_APPROVED: At record creation, the new record goes through initial approval,
-    #    i.e. at least the following status changes: DRAFT -> ... -> APPROVED.
-    # 2. Once approved a first time, the record then cycles through two possible states:
-    #    2.1. APPROVED: Record has no ongoing working copy.
-    #    2.2. WORKING_COPY: Record has an ongoing working copy.
-    # Note: There doesn't seem to be a way to "unapprove" a record, so it doesn't seem
-    #       possible to revert back to NEVER_APPROVED from other states.
-    # The distinction between these three possible states is important because a record
-    # and its optional working copy share the same UUID, and updates through the API
-    # (keyed on UUID) behave differently:
-    # - NEVER_APPROVED: Updating a never-approved record updates the record itself.
-    # - APPROVED: Updating an approved-record creates a working copy with the update.
-    # - WORKING_COPY: Updating a record with working copy updates the working copy.
     NEVER_APPROVED = auto()
     APPROVED = auto()
     WORKING_COPY = auto()
 
 
 @dataclass
 class WorkflowState:
+    # Record life-cycle:
+    #
+    # [Stage]  NEVER_APPROVED -------> APPROVED <--> WORKING_COPY (WC)
+    # [Status] DRAFT -> SUBMITTED? --> APPROVED ---> DRAFT -> SUBMITTED? -|
+    #                -> REJECTED -|                        -> REJECTED -| |
+    #                <------------|                        <------------| |
+    #                                           <--- WC applied ----------|
+    #                                           <--- WC dropped ----------|
+    #
+    # Each of those stages require a different treatment:
+    #
+    # - NEVER_APPROVED:
+    #   - Status is reported in `medatadata.mdStatus`.
+    #   - Updating a never-approved record updates the record itself.
+    # - APPROVED:
+    #   - Status is reported in `metadata.mdStatus` (= APPROVED).
+    #   - Updating an approved-record creates a working copy containing the update.
+    # - WORKING_COPY:
+    #   - Working copy status must be queried from `/records/{uuid}/status (since
+    #     `metadata.mdStatus` reports the record status, which stays APPROVED).
+    #   - Updating a record with a working copy MUST update the working copy.
     stage: WorkflowStage
     status: WorkflowStatus  # working copy status in WORKING_COPY stage, otherwise record status