# Work Item Assignment Rules

## Overview

Every work item supports three types of user association:

| Type | Count | Purpose |
|------|-------|---------|
| **Assignee** | Exactly 1 | Single owner responsible for delivery |
| **Collaborators** | 0-N | Supporting contributors |
| **Watchers** | 0-N | Observers receiving notifications |

## Assignee Rules

### Definition

The assignee is the **single owner** responsible for delivering the work item.

### Constraints

1. **Exactly one** — a work item can have 0 or 1 assignee (never multiple)
2. **Must be a project member** — for project work items, the assignee must be in the project
3. **Must be active** — inactive users cannot be assigned
4. **Cannot be external** — users outside the company cannot be assigned

### Validation

When assigning a work item:

```php
// Validation logic
if ($ticket->project_id !== null) {
    $isOwner = $project->owner_user_id === $userId;
    $isMember = ProjectMember::where('project_id', $projectId)
        ->where('user_id', $userId)
        ->exists();
    
    if (!$isOwner && !$isMember) {
        throw new BusinessException('User must be added to the project before assignment.');
    }
}
```

### Error Message

When validation fails:
> "User must be added to the project before assignment."

## Collaborator Rules

### Definition

Collaborators are **supporting contributors** who work on the item alongside the assignee.

### Constraints

1. **Multiple allowed** — a work item can have any number of collaborators
2. **Must be project members** — for project work items
3. **Cannot be the assignee** — the primary assignee is automatically excluded
4. **Cannot be the requester** — the ticket creator is already a participant
5. **Must be active** — inactive users cannot collaborate

### Behavior

- Collaborators **can** work on the item
- Collaborators **receive notifications** for item updates
- Collaborators **appear** in the activity timeline
- Collaborators are **not counted** as owners for capacity purposes

### When Assignee Changes

If a collaborator becomes the assignee:
1. Collaborator record is automatically removed
2. User becomes the sole owner

## Watcher Rules

### Definition

Watchers are **observers** who receive notifications but don't own or work on the item.

### Constraints

1. **Multiple allowed** — any number of watchers
2. **Can be non-members** — watchers can be approved company observers
3. **Must have view permission** — watchers need ticket view access
4. **Cannot be the assignee** — assignees already receive notifications

### Behavior

- Watchers **receive notifications** only
- Watchers have **no capacity impact**
- Watchers have **no ownership** stake
- Watchers **can self-subscribe** or be added by others

### Notification Events for Watchers

Watchers are notified when:

| Event | Notified? |
|-------|-----------|
| Item assigned | ✓ |
| Item reassigned | ✓ |
| Moved to sprint | ✓ |
| Removed from sprint | ✓ |
| Sprint started | ✓ |
| Sprint completed | ✓ |
| Comment added | ✓ |
| Dependency blocked | ✓ |
| Risk linked | ✓ |
| Status changed | ✓ |
| Priority changed | ✓ |

## API Reference

### Assignee

Set via work item update:
```http
PATCH /api/v1/projects/{project}/work-items/{ticket}
{
  "current_assignee_id": "user-uuid"
}
```

Or via assign endpoint:
```http
POST /api/v1/tickets/{ticket}/assign
{
  "assignee_id": "user-uuid"
}
```

### Collaborators

```http
GET    /api/v1/tickets/{ticket}/collaborators
POST   /api/v1/tickets/{ticket}/collaborators
DELETE /api/v1/tickets/{ticket}/collaborators/{user}
```

### Watchers

```http
GET    /api/v1/tickets/{ticket}/watchers
POST   /api/v1/tickets/{ticket}/watchers
DELETE /api/v1/tickets/{ticket}/watchers/{user}
POST   /api/v1/tickets/{ticket}/watchers/toggle  # Self-watch toggle
GET    /api/v1/tickets/{ticket}/watchers/status  # Check if watching
```

## UI Display

### Card Display

Board and backlog cards show:

```
┌─────────────────────────────────────────┐
│ PROJ-123                                │
│ Implement user authentication           │
│                                         │
│ [Active] [High]                         │
│                                         │
│ ┌─────────────────────────────────────┐│
│ │ 👤 👤 👤   │  👥 3  │  👁 5         ││
│ │ Avatars    │ Collab │ Watchers      ││
│ └─────────────────────────────────────┘│
└─────────────────────────────────────────┘
```

### Avatar Stack

- First avatar: Assignee
- Additional avatars: Collaborators (max 3 shown)
- Overflow: "+N more" indicator

### Icons

- 👥 Collaborators count
- 👁 Watchers count

## Permissions

| Action | Owner | Manager | Member | Viewer |
|--------|-------|---------|--------|--------|
| Assign work | ✓ | ✓ | ✗ | ✗ |
| Add collaborators | ✓ | ✓ | ✗ | ✗ |
| Add watchers | ✓ | ✓ | ✗ | ✗ |
| Self-watch | ✓ | ✓ | ✓ | ✓ |
| View assignee | ✓ | ✓ | ✓ | ✓ |
| View collaborators | ✓ | ✓ | ✓ | ✓ |
| View watchers | ✓ | ✓ | ✓ | ✓ |

## Summary Comparison

| Aspect | Assignee | Collaborator | Watcher |
|--------|----------|--------------|---------|
| Count | 0-1 | 0-N | 0-N |
| Ownership | ✓ | ✗ | ✗ |
| Can work on item | ✓ | ✓ | ✗ |
| Capacity impact | ✓ | ✗ | ✗ |
| Receives notifications | ✓ | ✓ | ✓ |
| Must be project member | ✓ | ✓ | Optional |