# Module: annotation-queue/annotation_queue_dto

## Purpose
Data transfer objects for the annotation queue consumer. Defines message types for annotation CRUD events received from a RabbitMQ Streams queue.

## Public Interface

### AnnotationClass (local copy)
Same as dto/annotationClass but reads `classes.json` from current working directory and adds `opencv_color` BGR field.

### AnnotationStatus (Enum)
| Member | Value |
|--------|-------|
| Created | 10 |
| Edited | 20 |
| Validated | 30 |
| Deleted | 40 |

### SourceEnum (Enum)
| Member | Value |
|--------|-------|
| AI | 0 |
| Manual | 1 |

### RoleEnum (Enum)
| Member | Value | Description |
|--------|-------|-------------|
| Operator | 10 | Regular annotator |
| Validator | 20 | Annotation validator |
| CompanionPC | 30 | Companion device |
| Admin | 40 | Administrator |
| ApiAdmin | 1000 | API-level admin |

`RoleEnum.is_validator() -> bool`: Returns True for Validator, Admin, ApiAdmin.

### Detection
| Field | Type |
|-------|------|
| `annotation_name` | str |
| `cls` | int |
| `x`, `y`, `w`, `h` | float |
| `confidence` | float (optional) |

### AnnotationCreatedMessageNarrow
Lightweight message with only `name` and `createdEmail` (from msgpack fields 1, 2).

### AnnotationMessage
Full annotation message deserialized from msgpack:
| Field | Type | Source |
|-------|------|--------|
| `createdDate` | datetime | msgpack field 0 (Timestamp) |
| `name` | str | field 1 |
| `originalMediaName` | str | field 2 |
| `time` | timedelta | field 3 (microseconds/10) |
| `imageExtension` | str | field 4 |
| `detections` | list[Detection] | field 5 (JSON string) |
| `image` | bytes | field 6 |
| `createdRole` | RoleEnum | field 7 |
| `createdEmail` | str | field 8 |
| `source` | SourceEnum | field 9 |
| `status` | AnnotationStatus | field 10 |

### AnnotationBulkMessage
Bulk operation message for validate/delete:
| Field | Type | Source |
|-------|------|--------|
| `annotation_names` | list[str] | msgpack field 0 |
| `annotation_status` | AnnotationStatus | field 1 |
| `createdEmail` | str | field 2 |
| `createdDate` | datetime | field 3 (Timestamp) |

## Internal Logic
- All messages are deserialized from msgpack binary using positional integer keys.
- Detections within AnnotationMessage are stored as a JSON string inside the msgpack payload.
- Module-level `annotation_classes = AnnotationClass.read_json()` is loaded at import time for Detection.__str__ formatting.

## Dependencies
- `msgpack` (external) — binary message deserialization
- `json`, `datetime`, `enum` (stdlib)

## Consumers
annotation-queue/annotation_queue_handler

## Data Models
AnnotationClass, AnnotationStatus, SourceEnum, RoleEnum, Detection, AnnotationCreatedMessageNarrow, AnnotationMessage, AnnotationBulkMessage.

## Configuration
Reads `classes.json` from current working directory.

## External Integrations
None (pure data classes).

## Security
None.

## Tests
None.