276 lines
5.3 KiB
Markdown
276 lines
5.3 KiB
Markdown
# 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 |
|