easystream/docs/COMMENTS.md

# Enhanced Comment System

Threaded comments with reactions, mentions, and moderation features.

## Features

- 💬 **Threaded Replies** - Nested comment threads (up to 5 levels deep)
- 👍 **Reactions** - Like, heart, laugh, thinking, sad, angry
- 📢 **Mentions** - Tag users with @username
- 📌 **Pinned Comments** - Video owners can pin top comments
- ✏️ **Edit Support** - Edit comments with edit indicator
- 🛡️ **Moderation** - Approve, reject, delete, flag comments
- 🔔 **Notifications** - Get notified when mentioned
- 🔢 **Reaction Counts** - Cached aggregated counts for performance

## Database Setup

```bash
docker-compose exec db mysql -u easystream -peasystream easystream < __install/migrations/006_enhance_comments.sql
```

## API Endpoints

### List Comments (Threaded)

```http
GET /api/comments_enhanced.php?action=list&video_id=123&sort=top&limit=50&offset=0
```

**Sort options:** `top` (most reactions), `newest`, `oldest`

**Response:**
```json
{
  "success": true,
  "comments": [
    {
      "comment_id": 1,
      "usr_user": "john",
      "comment": "Great video! @mary check this out",
      "depth": 0,
      "is_pinned": 1,
      "is_edited": 0,
      "like_count": 42,
      "total_reactions": 55,
      "reply_count": 3,
      "replies": [...]
    }
  ]
}
```

### Post Comment/Reply

```http
POST /api/comments_enhanced.php?action=post
Content-Type: application/json

{
  "video_id": 123,
  "comment": "Great video!",
  "parent_comment_id": null
}
```

### Add Reaction

```http
POST /api/comments_enhanced.php?action=react
Content-Type: application/json

{
  "comment_id": 456,
  "reaction_type": "heart"
}
```

**Reaction types:** `like`, `heart`, `laugh`, `thinking`, `sad`, `angry`

### Remove Reaction

```http
POST /api/comments_enhanced.php?action=unreact
Content-Type: application/json

{
  "comment_id": 456,
  "reaction_type": "heart"
}
```

### Edit Comment

```http
POST /api/comments_enhanced.php?action=edit
Content-Type: application/json

{
  "comment_id": 456,
  "comment": "Updated comment text"
}
```

### Pin Comment

```http
POST /api/comments_enhanced.php?action=pin
Content-Type: application/json

{
  "comment_id": 456
}
```

Only video owners can pin comments.

## Usage

### PHP Backend

```php
require_once 'f_core/f_classes/class.comments_enhanced.php';
$comments = new VCommentsEnhanced();

// Post a comment
$comment_id = $comments->postComment($video_id, $user_id, "Great video!", $parent_id);

// Add a reaction
$comments->addReaction($comment_id, $user_id, 'like');

// Get threaded comments
$data = $comments->getThreadedComments($video_id, 50, 0, 'top');

// Pin a comment (as video owner)
$comments->pinComment($comment_id, $video_owner_id);

// Edit a comment
$comments->editComment($comment_id, $user_id, "Updated text");

// Moderate a comment
$comments->moderateComment($comment_id, $moderator_id, 'delete', 'Spam');
```

## Features Explained

### Threading

Comments support unlimited nesting, but depth is limited to 5 levels for UI/UX:

```
Comment (depth 0)
└─ Reply (depth 1)
   └─ Reply to reply (depth 2)
      └─ ... (up to depth 5)
```

### Mentions

Use `@username` to mention users:
- System automatically detects mentions
- Creates notification for mentioned user
- Highlights mentioned users in UI

### Reactions

Six reaction types with aggregated counts:
- Counts cached in `db_comment_reaction_counts` for performance
- One reaction per user per type
- Updating a reaction changes the type

### Pinning

- Only video owners can pin comments
- Only one pinned comment per video
- Pinned comments appear first

### Editing

- Users can edit their own comments
- Edited comments show "(edited)" indicator
- Edit timestamp tracked

### Moderation

Actions tracked in `db_comment_moderation`:
- **Approve** - Approve pending comment
- **Reject** - Hide comment (not deleted)
- **Delete** - Permanently remove comment
- **Flag** - Mark for review
- **Unflag** - Clear flag

## Performance

- Reaction counts pre-aggregated
- Top-level comments fetched separately from replies
- Indexes on `video_id`, `parent_comment_id`, `is_pinned`
- Depth limiting prevents deep recursion

## Database Schema

### db_comments (enhanced)

Added columns:
- `parent_comment_id` - Parent comment for threading
- `depth` - Nesting level (0-5)
- `is_pinned` - Pinned by video owner
- `is_edited` - Comment was edited
- `edited_at` - Edit timestamp

### db_comment_reactions

| Column | Type | Description |
|--------|------|-------------|
| reaction_id | INT | Primary key |
| comment_id | INT | Comment ID |
| usr_id | INT | User who reacted |
| reaction_type | ENUM | like/heart/laugh/thinking/sad/angry |
| created_at | DATETIME | Reaction timestamp |

### db_comment_mentions

| Column | Type | Description |
|--------|------|-------------|
| mention_id | INT | Primary key |
| comment_id | INT | Comment with mention |
| mentioned_user_id | INT | User who was mentioned |

### db_comment_moderation

| Column | Type | Description |
|--------|------|-------------|
| moderation_id | INT | Primary key |
| comment_id | INT | Moderated comment |
| moderator_id | INT | Moderator user |
| action | ENUM | approve/reject/delete/flag/unflag |
| reason | TEXT | Moderation reason |

## Future Enhancements

- [ ] Rich text formatting (markdown)
- [ ] GIF/emoji picker
- [ ] Comment sorting (controversial, best)
- [ ] Spam detection (ML-based)
- [ ] Comment search
- [ ] User blocking
- [ ] Shadow banning
- [ ] Auto-moderation rules
- [ ] Report abuse workflow
- [ ] Moderator dashboard