# Rating & Comments API

> **Prefix:** `/api/v1/rate`, `/api/v1/comment`, `/api/v1/like`

---

## POST `/api/v1/rate`

Submit a rating for a doctor.

**Permission:** `AUTH` — any authenticated user (typically after a completed appointment)

### Request Body (`application/json`)
```json
{
  "doctor_uuid": "550e8400-...",
  "score": 5
}
```

| Field | Type | Required | Validation |
|-------|------|----------|------------|
| `doctor_uuid` | string (UUID) | ✅ | Must exist |
| `score` | integer | ✅ | 1–5 |

### Response `201`
```json
{
  "success": true,
  "data": {
    "uuid": "rate-uuid-...",
    "doctor_uuid": "...",
    "score": 5,
    "created_at": 1717000000
  }
}
```

### Errors
| Code | HTTP | Description |
|------|------|-------------|
| `ERR_AUTH_001` | 401 | Missing token |
| `ERR_NOT_FOUND_001` | 404 | Doctor not found |
| `ERR_VALIDATION_001` | 422 | Score out of range |

---

## GET `/api/v1/rate/{doctorUuid}`

Get average rating for a doctor.

**Permission:** `PUBLIC`

### Path Parameters
| Param | Type | Description |
|-------|------|-------------|
| `doctorUuid` | string (UUID) | Doctor UUID |

### Response `200`
```json
{
  "success": true,
  "data": {
    "average": 4.3,
    "total": 47
  }
}
```

### Errors
| Code | HTTP | Description |
|------|------|-------------|
| `ERR_NOT_FOUND_001` | 404 | Doctor not found |

---

## POST `/api/v1/comment`

Submit a comment/review for a doctor.

**Permission:** `AUTH`

> Comments require admin approval before appearing publicly.

### Request Body (`application/json`)
```json
{
  "doctor_uuid": "550e8400-...",
  "body": "پزشک بسیار مؤدب و متخصص بودند"
}
```

| Field | Type | Required | Validation |
|-------|------|----------|------------|
| `doctor_uuid` | string (UUID) | ✅ | Must exist |
| `body` | string | ✅ | Min 10 chars |

### Response `201`
```json
{
  "success": true,
  "data": {
    "uuid": "comment-uuid-...",
    "body": "پزشک بسیار مؤدب و متخصص بودند",
    "status": "pending",
    "created_at": 1717000000
  }
}
```

**Comment Status Values:**
| Value | Description |
|-------|-------------|
| `pending` | Awaiting admin review |
| `approved` | Visible to public |
| `rejected` | Not visible |

### Errors
| Code | HTTP | Description |
|------|------|-------------|
| `ERR_AUTH_001` | 401 | Missing token |
| `ERR_NOT_FOUND_001` | 404 | Doctor not found |
| `ERR_VALIDATION_001` | 422 | Body too short |

---

## GET `/api/v1/comments/{doctorUuid}`

Get approved comments for a doctor.

**Permission:** `PUBLIC`

### Path Parameters
| Param | Type | Description |
|-------|------|-------------|
| `doctorUuid` | string (UUID) | Doctor UUID |

### Response `200`
```json
{
  "success": true,
  "data": [
    {
      "uuid": "...",
      "body": "پزشک بسیار مؤدب...",
      "user": { "uuid": "...", "real_name": "علی" },
      "likes": 3,
      "status": "approved",
      "created_at": 1717000000
    }
  ]
}
```

### Errors
| Code | HTTP | Description |
|------|------|-------------|
| `ERR_NOT_FOUND_001` | 404 | Doctor not found |

---

## DELETE `/api/v1/comment/{uuid}`

Delete a comment.

**Permission:** `AUTH` — must be the comment author or `ROLE_ADMIN`

### Response `200`
```json
{ "success": true, "data": { "message": "نظر حذف شد" } }
```

### Errors
| Code | HTTP | Description |
|------|------|-------------|
| `ERR_AUTH_001` | 401 | Missing token |
| `ERR_FORBIDDEN_001` | 403 | Not the author |
| `ERR_NOT_FOUND_001` | 404 | Comment not found |

---

## GET `/api/v1/admin/comments/pending`

Get all pending comments waiting for review.

**Permission:** `ROLE_ADMIN`

### Response `200`
```json
{
  "success": true,
  "data": [
    {
      "uuid": "...",
      "body": "...",
      "doctor": { "uuid": "...", "title": "دکتر علی احمدی" },
      "user": { "uuid": "...", "real_name": "..." },
      "status": "pending",
      "created_at": 1717000000
    }
  ]
}
```

### Errors
| Code | HTTP | Description |
|------|------|-------------|
| `ERR_AUTH_001` | 401 | Missing token |
| `ERR_AUTH_006` | 403 | Not admin |

---

## POST `/api/v1/admin/comment/{uuid}/approve`

Approve a pending comment (makes it public).

**Permission:** `ROLE_ADMIN`

### Response `200`
Updated comment object with `status: "approved"`.

### Errors
| Code | HTTP | Description |
|------|------|-------------|
| `ERR_AUTH_001` | 401 | Missing token |
| `ERR_AUTH_006` | 403 | Not admin |
| `ERR_NOT_FOUND_001` | 404 | Comment not found |

---

## POST `/api/v1/admin/comment/{uuid}/reject`

Reject a pending comment.

**Permission:** `ROLE_ADMIN`

### Response `200`
Updated comment object with `status: "rejected"`.

### Errors
| Code | HTTP | Description |
|------|------|-------------|
| `ERR_AUTH_001` | 401 | Missing token |
| `ERR_AUTH_006` | 403 | Not admin |
| `ERR_NOT_FOUND_001` | 404 | Comment not found |

---

## POST `/api/v1/like/{commentUuid}`

Toggle like on a comment (like if not liked, unlike if already liked).

**Permission:** `AUTH`

### Path Parameters
| Param | Type | Description |
|-------|------|-------------|
| `commentUuid` | string (UUID) | Comment UUID |

### Response `200` (unlike) or `201` (new like)
```json
{
  "success": true,
  "data": {
    "liked": true,
    "likes": 4
  }
}
```

### Errors
| Code | HTTP | Description |
|------|------|-------------|
| `ERR_AUTH_001` | 401 | Missing token |
| `ERR_NOT_FOUND_001` | 404 | Comment not found |