# Reporting System

Reference documentation for user reporting, appeals, reputation management, and
human review workflows.

## Overview

The Moderation Service reporting system provides:

- **Appeal Process**: Challenge moderation decisions
- **User History**: Track moderation events per user
- **Reputation System**: Trust levels based on behavior
- **Human Review Workflow**: Queue-based moderator workflow
- **Reviewer Management**: Capacity tracking and performance metrics

## Appeals Process

Users can appeal moderation decisions through the appeals API.

### Submit Appeal

```http
POST /v1/appeals
Content-Type: application/json

{
  "moderation_id": "mod_1704067200_abc123",
  "user_id": "user123",
  "reason": "This was educational content about history",
  "additional_context": "Discussing historical events in an academic context"
}
```

**Required Fields**:

| Field           | Type   | Description                     |
| --------------- | ------ | ------------------------------- |
| `moderation_id` | string | Original moderation decision ID |
| `user_id`       | string | User submitting the appeal      |
| `reason`        | string | Justification for appeal        |

**Optional Fields**:

| Field                | Type   | Description            |
| -------------------- | ------ | ---------------------- |
| `additional_context` | string | Supporting information |

### Appeal Response

```json
{
  "appeal_id": "appeal_1704067200_xyz789",
  "original_decision": {
    "moderation_id": "mod_1704067200_abc123",
    "flagged": true,
    "action": "block",
    "categories": { "hate_speech": true }
  },
  "appeal_reason": "This was educational content about history",
  "additional_context": "Discussing historical events in an academic context",
  "status": "approved",
  "new_action": "allow_with_warning",
  "created_at": "2025-01-15T10:30:00.000Z"
}
```

### Appeal Status Values

| Status           | Description                             |
| ---------------- | --------------------------------------- |
| `pending_review` | Awaiting moderator review               |
| `approved`       | Appeal granted, action revised          |
| `rejected`       | Appeal denied, original decision stands |

### Automatic Approval

Appeals containing educational or research justification keywords may be
automatically approved:

```typescript
// Automatic approval keywords
if (reason.includes('educational') || reason.includes('research')) {
  reevaluation.status = 'approved';
  reevaluation.new_action = 'allow_with_warning';
}
```

## User History

Track all moderation events for a specific user.

### Get User History

```http
GET /v1/users/:userId/history?limit=50&offset=0
```

**Query Parameters**:

| Parameter | Type   | Default | Description           |
| --------- | ------ | ------- | --------------------- |
| `limit`   | string | "100"   | Max records to return |
| `offset`  | string | "0"     | Skip N records        |

**Response**:

```json
{
  "user_id": "user123",
  "total": 47,
  "flagged_count": 3,
  "history": [
    {
      "moderation_id": "mod_1704067200_abc123",
      "timestamp": "2025-01-15T10:30:00.000Z",
      "content_length": 256,
      "flagged": false,
      "categories": {},
      "scores": {},
      "action": "allow"
    }
  ]
}
```

### History Sorting

Results are sorted by timestamp in descending order (newest first).

## Reputation System

User reputation is calculated based on moderation history.

### Get User Reputation

```http
GET /v1/users/:userId/reputation
```

**Response**:

```json
{
  "total_content": 150,
  "flagged_content": 3,
  "violations": {
    "profanity": 2,
    "harassment": 1
  },
  "reputation_score": 98,
  "trust_level": "trusted",
  "last_flagged": "2025-01-10T15:20:00.000Z"
}
```

### Reputation Score Calculation

```typescript
reputation_score = max(0, 100 - (flagged_content / total_content) * 100);
```

### Trust Levels

| Trust Level  | Score Threshold | Description                            |
| ------------ | --------------- | -------------------------------------- |
| `trusted`    | ≥ 90            | Excellent history, priority moderation |
| `standard`   | ≥ 70            | Normal user, standard moderation       |
| `limited`    | ≥ 50            | Some violations, stricter moderation   |
| `restricted` | < 50            | Multiple violations, most restrictive  |

### Reputation Thresholds

```typescript
const REPUTATION_THRESHOLDS = {
  HIGH: 90, // trusted
  MEDIUM: 70, // standard
  LOW: 50, // limited threshold
};
```

### User Flags Update

Flags are automatically updated on each moderation event:

```typescript
function updateUserFlags(userFlags, userId, moderationResult) {
  const flags = userFlags.get(userId) || initialFlags;
  flags.total_content++;

  if (moderationResult.flagged) {
    flags.flagged_content++;
    flags.last_flagged = new Date().toISOString();

    // Track violations by category
    Object.keys(moderationResult.categories).forEach((category) => {
      flags.violations[category] = (flags.violations[category] || 0) + 1;
    });
  }

  userFlags.set(userId, flags);
}
```

## Human Review Workflow

Comprehensive queue-based system for human moderators.

### Review Types

| Type                 | Description                 | Est. Review Time |
| -------------------- | --------------------------- | ---------------- |
| `content_moderation` | Standard content review     | 5 min            |
| `appeal_review`      | User appeal review          | 15 min           |
| `policy_violation`   | Policy violation assessment | 10 min           |
| `edge_case`          | Ambiguous/complex cases     | 20 min           |

### Submit for Review

```http
POST /v1/reviews
Content-Type: application/json

{
  "type": "content_moderation",
  "content_id": "content_abc123",
  "content_type": "comment",
  "reason": "Automated moderation flagged potential harassment",
  "severity": "medium",
  "priority": "high",
  "submitted_by": "system",
  "context": {
    "channel": "forum",
    "thread_id": "thread_xyz"
  },
  "auto_moderation_result": {
    "flagged": true,
    "categories": { "harassment": true },
    "scores": { "harassment": 0.78 }
  }
}
```

**Response**:

```json
{
  "review_id": "review_1704067200_def456",
  "status": "pending",
  "queue_position": 3,
  "estimated_review_time": 5
}
```

### Review Priority

| Priority   | SLA (minutes) | Queue Order |
| ---------- | ------------- | ----------- |
| `critical` | 30            | First       |
| `high`     | 120           | Second      |
| `medium`   | 480           | Third       |
| `low`      | 1440          | Last        |

### Review Severity

| Severity   | Description              |
| ---------- | ------------------------ |
| `critical` | Immediate safety concern |
| `high`     | Significant violation    |
| `medium`   | Moderate violation       |
| `low`      | Minor issue              |

### Get Review Queues

```http
GET /v1/review-queues
```

**Response**:

```json
{
  "queues": {
    "content_moderation": {
      "type": "content_moderation",
      "pending_items_count": 15,
      "in_review_items_count": 3,
      "completed_items_count": 127,
      "escalated_items_count": 5,
      "total_capacity": 100,
      "active_reviewers": 4,
      "average_review_time": 5.2,
      "sla_breach_count": 2
    }
  },
  "total_pending": 25,
  "total_in_review": 5,
  "total_active_reviewers": 6
}
```

### Get Available Reviews

```http
GET /v1/reviews/available?reviewer_id=reviewer_abc&types=content_moderation,appeal_review&limit=10
```

**Response**:

```json
{
  "available_reviews": [
    {
      "id": "review_1704067200_def456",
      "type": "content_moderation",
      "content_id": "content_abc123",
      "reason": "Automated moderation flagged content",
      "severity": "medium",
      "priority": "high",
      "status": "pending",
      "queue_position": 1,
      "created_at": "2025-01-15T10:30:00.000Z"
    }
  ],
  "total_available": 15,
  "reviewer_capacity": 7,
  "queue_types": ["content_moderation", "appeal_review"]
}
```

### Assign Review

```http
POST /v1/reviews/:reviewId/assign
Content-Type: application/json

{
  "reviewer_id": "reviewer_abc123"
}
```

**Response**:

```json
{
  "assignment_id": "assign_1704067200_xyz",
  "review_id": "review_1704067200_def456",
  "assigned_to": "reviewer_abc123",
  "assigned_at": "2025-01-15T10:35:00.000Z",
  "sla_deadline": "2025-01-15T12:35:00.000Z"
}
```

### Assignment Validation

Assignment is rejected if:

- Review is not in `pending` status
- Reviewer is not active
- Reviewer has reached daily capacity
- Reviewer cannot review this type

### Unassign Review

```http
POST /v1/reviews/:reviewId/unassign
Content-Type: application/json

{
  "actor_id": "supervisor_abc"
}
```

### Submit Decision

```http
POST /v1/reviews/:reviewId/decision
Content-Type: application/json

{
  "action": "reject",
  "reasoning": "Content violates community guidelines for harassment",
  "reviewer_id": "reviewer_abc123",
  "confidence": 0.95,
  "tags": ["harassment", "targeted"],
  "notes": "Repeated pattern from this user",
  "escalation_requested": false
}
```

**Response**:

```json
{
  "decision_id": "decision_1704067200_abc",
  "review_id": "review_1704067200_def456",
  "action": "reject",
  "status": "completed",
  "completed_at": "2025-01-15T10:45:00.000Z"
}
```

### Review Actions

| Action            | Description                  |
| ----------------- | ---------------------------- |
| `approve`         | Content is acceptable        |
| `reject`          | Content violates policies    |
| `escalate`        | Requires senior review       |
| `request_changes` | Ask for content modification |
| `remove_content`  | Delete content entirely      |

### Get Review Details

```http
GET /v1/reviews/:reviewId
```

### Get Review History

```http
GET /v1/reviews/:reviewId/history
```

**Response**:

```json
{
  "review_id": "review_1704067200_def456",
  "events": [
    {
      "event_id": "evt_1704067200_001",
      "event_type": "submitted",
      "timestamp": "2025-01-15T10:30:00.000Z",
      "actor_id": "system",
      "details": { "reason": "Auto-flagged", "priority": "high" }
    },
    {
      "event_id": "evt_1704067200_002",
      "event_type": "assigned",
      "timestamp": "2025-01-15T10:35:00.000Z",
      "actor_id": "reviewer_abc123",
      "details": { "sla_deadline": "2025-01-15T12:35:00.000Z" }
    },
    {
      "event_id": "evt_1704067200_003",
      "event_type": "decision_made",
      "timestamp": "2025-01-15T10:45:00.000Z",
      "actor_id": "reviewer_abc123",
      "details": { "action": "reject", "confidence": 0.95 }
    },
    {
      "event_id": "evt_1704067200_004",
      "event_type": "completed",
      "timestamp": "2025-01-15T10:45:00.000Z",
      "actor_id": "reviewer_abc123"
    }
  ]
}
```

### Event Types

| Event           | Description         |
| --------------- | ------------------- |
| `submitted`     | Review created      |
| `assigned`      | Reviewer assigned   |
| `unassigned`    | Reviewer removed    |
| `decision_made` | Decision submitted  |
| `escalated`     | Escalated to senior |
| `completed`     | Review finished     |

## Reviewer Management

### Create Reviewer Profile

```http
POST /v1/reviewers
Content-Type: application/json

{
  "user_id": "user_abc123",
  "display_name": "Jane Smith",
  "email": "jane@example.com",
  "can_review_types": ["content_moderation", "appeal_review"],
  "daily_capacity": 15,
  "experience_level": "intermediate",
  "specialties": ["harassment", "hate_speech"]
}
```

**Response**:

```json
{
  "reviewer_id": "reviewer_1704067200_xyz",
  "status": "created",
  "profile": {
    "reviewer_id": "reviewer_1704067200_xyz",
    "user_id": "user_abc123",
    "display_name": "Jane Smith",
    "email": "jane@example.com",
    "can_review_types": ["content_moderation", "appeal_review"],
    "daily_capacity": 15,
    "current_assigned": 0,
    "total_completed": 0,
    "average_review_time": 0,
    "accuracy_score": 1.0,
    "experience_level": "intermediate",
    "specialties": ["harassment", "hate_speech"],
    "active": true,
    "created_at": "2025-01-15T10:30:00.000Z"
  }
}
```

### Experience Levels

| Level          | Description                 |
| -------------- | --------------------------- |
| `beginner`     | New reviewer, limited types |
| `intermediate` | Standard reviewer           |
| `advanced`     | Senior reviewer             |
| `expert`       | Senior + edge cases         |

### Get Reviewer Profile

```http
GET /v1/reviewers/:reviewerId
```

**Response includes**:

```json
{
  "reviewer_id": "reviewer_abc123",
  "display_name": "Jane Smith",
  "can_review_types": ["content_moderation", "appeal_review"],
  "daily_capacity": 15,
  "current_assigned": 5,
  "total_completed": 127,
  "average_review_time": 4.5,
  "accuracy_score": 0.98,
  "experience_level": "intermediate",
  "active": true,
  "current_assignments": 5,
  "utilization_rate": 0.333
}
```

### Update Reviewer Profile

```http
PUT /v1/reviewers/:reviewerId
Content-Type: application/json

{
  "daily_capacity": 20,
  "experience_level": "advanced",
  "can_review_types": ["content_moderation", "appeal_review", "policy_violation"]
}
```

## Metrics and Analytics

### Get Review Metrics

```http
GET /v1/review/analytics/metrics?period=24h&type=content_moderation
```

**Query Parameters**:

| Parameter     | Format      | Example              | Description        |
| ------------- | ----------- | -------------------- | ------------------ |
| `period`      | `{n}{unit}` | `24h`, `7d`, `4w`    | Time period        |
| `type`        | ReviewType  | `content_moderation` | Filter by type     |
| `reviewer_id` | string      | `reviewer_abc`       | Filter by reviewer |

**Response**:

```json
{
  "period": "24h",
  "total_reviews": 47,
  "completed_reviews": 42,
  "escalated_reviews": 5,
  "average_review_time": 5.3,
  "sla_compliance_rate": 0.94,
  "reviewer_performance": {
    "reviewer_abc": 15,
    "reviewer_xyz": 12,
    "reviewer_def": 20
  },
  "type_breakdown": {
    "content_moderation": 30,
    "appeal_review": 10,
    "policy_violation": 5,
    "edge_case": 2
  },
  "priority_breakdown": {
    "critical": 2,
    "high": 15,
    "medium": 25,
    "low": 5
  },
  "severity_breakdown": {
    "critical": 3,
    "high": 12,
    "medium": 27,
    "low": 5
  }
}
```

### Period Units

| Unit | Description |
| ---- | ----------- |
| `h`  | Hours       |
| `d`  | Days        |
| `w`  | Weeks       |
| `m`  | Months      |

## SLA Configuration

### Default SLA Times

| Priority   | SLA (minutes) |
| ---------- | ------------- |
| `critical` | 30            |
| `high`     | 120           |
| `medium`   | 480           |
| `low`      | 1440          |

### SLA Tracking

SLA deadline is calculated at assignment:

```typescript
const slaDeadline = new Date(
  now.getTime() + SLA_TIMES[review.priority] * 60000
);
```

### SLA Compliance

Compliance rate is tracked in metrics:

```typescript
sla_compliance_rate = sla_compliant / total_reviews;
```

## Integration Example

```typescript
// Submit content for moderation
const moderationResult = await fetch('/v1/moderate', {
  method: 'POST',
  body: JSON.stringify({ content: userContent, user_id: userId }),
}).then((r) => r.json());

// If flagged and requires review
if (moderationResult.queued_for_review) {
  // Content was automatically submitted to review queue
  console.log('Content submitted for human review');
}

// User appeals the decision
if (moderationResult.flagged) {
  const appeal = await fetch('/v1/appeals', {
    method: 'POST',
    body: JSON.stringify({
      moderation_id: moderationResult.moderation_id,
      user_id: userId,
      reason: 'This is educational content',
      additional_context: 'Teaching about historical events',
    }),
  }).then((r) => r.json());

  if (appeal.status === 'approved') {
    console.log('Appeal approved:', appeal.new_action);
  }
}

// Check user reputation
const reputation = await fetch(`/v1/users/${userId}/reputation`).then((r) =>
  r.json()
);

if (reputation.trust_level === 'restricted') {
  console.log('User has restricted access due to violations');
}
```

## Related Documentation

- [Moderation Policies](./moderation-policies.md) - Content filter categories
- [Safety Measures](./safety-measures.md) - Safety guardrails
- [API Documentation](../API.md) - Full API reference
