# Compliance & Governance API Documentation

## Overview

The Compliance & Governance module provides comprehensive functionality for managing regulatory compliance, evidence collection, retention policies, and export capabilities for auditors and regulators. This module supports major compliance frameworks including GDPR, HIPAA, SOX, and ISO 27001.

## Features

- **Regulatory Frameworks**: Manage compliance frameworks (GDPR, HIPAA, SOX, ISO 27001)
- **Compliance Requirements**: Track individual compliance requirements and their status
- **Regulatory Workflows**: Define and execute compliance workflows
- **Evidence Collection**: Collect and manage evidence linked to incidents
- **Retention Policies**: Implement data retention policies with auto-archive/delete
- **Export APIs**: Generate exports for regulators and auditors
- **Compliance Reports**: Create and manage compliance assessment reports
- **Legal Holds**: Manage legal holds to prevent data deletion

## API Endpoints

### Base URL
```
/api/compliance/
```

### Regulatory Frameworks

#### List Frameworks
```http
GET /api/compliance/frameworks/
```

**Query Parameters:**
- `framework_type`: Filter by framework type (GDPR, HIPAA, SOX, ISO27001, etc.)
- `is_active`: Filter by active status (true/false)
- `effective_date_after`: Filter frameworks effective after date
- `effective_date_before`: Filter frameworks effective before date
- `search`: Search in name, description, regions, or sectors

**Response:**
```json
{
  "count": 4,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "uuid",
      "name": "GDPR Compliance Framework",
      "framework_type": "GDPR",
      "framework_type_display": "General Data Protection Regulation",
      "version": "1.0",
      "description": "GDPR compliance framework...",
      "applicable_regions": ["EU", "EEA", "UK"],
      "industry_sectors": ["Technology", "Healthcare"],
      "is_active": true,
      "effective_date": "2018-05-25",
      "review_date": "2024-05-25",
      "requirements_count": 12,
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z"
    }
  ]
}
```

#### Get Framework Details
```http
GET /api/compliance/frameworks/{id}/
```

#### Get Framework Requirements
```http
GET /api/compliance/frameworks/{id}/requirements/
```

**Query Parameters:**
- `compliance_status`: Filter by compliance status
- `priority`: Filter by priority level

#### Get Framework Compliance Summary
```http
GET /api/compliance/frameworks/{id}/compliance_summary/
```

**Response:**
```json
{
  "total_requirements": 12,
  "compliant": 8,
  "partially_compliant": 2,
  "non_compliant": 1,
  "not_assessed": 1,
  "implemented": 10,
  "overdue_assessments": 2,
  "compliance_percentage": 80.0
}
```

### Compliance Requirements

#### List Requirements
```http
GET /api/compliance/requirements/
```

**Query Parameters:**
- `framework`: Filter by framework ID
- `compliance_status`: Filter by compliance status
- `requirement_type`: Filter by requirement type
- `priority`: Filter by priority level
- `is_implemented`: Filter by implementation status
- `assigned_to`: Filter by assigned user
- `overdue`: Filter overdue assessments (true/false)
- `search`: Search in title, description, or requirement ID

#### Update Compliance Status
```http
POST /api/compliance/requirements/{id}/update_status/
```

**Request Body:**
```json
{
  "compliance_status": "COMPLIANT"
}
```

#### Schedule Assessment
```http
POST /api/compliance/requirements/{id}/schedule_assessment/
```

**Request Body:**
```json
{
  "assessment_date": "2024-06-01"
}
```

### Regulatory Workflows

#### List Workflows
```http
GET /api/compliance/workflows/
```

**Query Parameters:**
- `workflow_type`: Filter by workflow type
- `status`: Filter by workflow status
- `is_template`: Filter templates (true/false)
- `applicable_frameworks`: Filter by framework ID
- `search`: Search in name or description

#### Create Workflow Instance
```http
POST /api/compliance/workflows/{id}/create_instance/
```

**Request Body:**
```json
{
  "title": "GDPR Breach Response - Incident #12345",
  "description": "Response to data breach incident",
  "related_incident": "incident-uuid",
  "assigned_to": "user-uuid",
  "due_date": "2024-02-01T00:00:00Z"
}
```

### Workflow Instances

#### List Workflow Instances
```http
GET /api/compliance/workflow-instances/
```

**Query Parameters:**
- `workflow`: Filter by workflow ID
- `status`: Filter by instance status
- `assigned_to`: Filter by assigned user
- `related_incident`: Filter by related incident
- `overdue`: Filter overdue instances (true/false)
- `search`: Search in title, description, or current step

#### Advance Workflow Step
```http
POST /api/compliance/workflow-instances/{id}/advance_step/
```

**Request Body:**
```json
{
  "next_step": "assess",
  "step_data": {
    "risk_level": "HIGH",
    "affected_records": 1000
  }
}
```

#### Assign Stakeholder
```http
POST /api/compliance/workflow-instances/{id}/assign_stakeholder/
```

**Request Body:**
```json
{
  "stakeholder_id": "user-uuid"
}
```

### Evidence Collection

#### List Evidence
```http
GET /api/compliance/evidence/
```

**Query Parameters:**
- `incident`: Filter by incident ID
- `evidence_type`: Filter by evidence type
- `status`: Filter by evidence status
- `collected_by`: Filter by collector
- `compliance_requirement`: Filter by requirement ID
- `search`: Search in title, description, or notes

#### Add Custody Record
```http
POST /api/compliance/evidence/{id}/add_custody_record/
```

**Request Body:**
```json
{
  "action": "TRANSFERRED",
  "notes": "Transferred to legal team for review"
}
```

#### Verify Evidence
```http
POST /api/compliance/evidence/{id}/verify_evidence/
```

**Request Body:**
```json
{
  "verification_notes": "Evidence verified and authenticated"
}
```

### Retention Policies

#### List Retention Policies
```http
GET /api/compliance/retention-policies/
```

**Query Parameters:**
- `policy_type`: Filter by policy type
- `is_active`: Filter by active status
- `applicable_frameworks`: Filter by framework ID
- `search`: Search in name or description

### Export Requests

#### List Export Requests
```http
GET /api/compliance/export-requests/
```

**Query Parameters:**
- `request_type`: Filter by request type
- `status`: Filter by request status
- `requester_email`: Filter by requester email
- `overdue`: Filter overdue requests (true/false)
- `search`: Search in title, description, or requester info

#### Approve Export Request
```http
POST /api/compliance/export-requests/{id}/approve/
```

**Request Body:**
```json
{
  "approval_notes": "Approved for regulatory submission"
}
```

#### Execute Export Request
```http
POST /api/compliance/export-requests/{id}/execute/
```

### Compliance Reports

#### List Compliance Reports
```http
GET /api/compliance/reports/
```

**Query Parameters:**
- `framework`: Filter by framework ID
- `report_type`: Filter by report type
- `status`: Filter by report status
- `prepared_by`: Filter by preparer
- `search`: Search in title, description, or summary

### Legal Holds

#### List Legal Holds
```http
GET /api/compliance/legal-holds/
```

**Query Parameters:**
- `status`: Filter by hold status
- `active`: Filter active holds (true/false)
- `search`: Search in case name, number, or description

#### Add Incident to Legal Hold
```http
POST /api/compliance/legal-holds/{id}/add_incident/
```

**Request Body:**
```json
{
  "incident_id": "incident-uuid"
}
```

#### Add Evidence to Legal Hold
```http
POST /api/compliance/legal-holds/{id}/add_evidence/
```

**Request Body:**
```json
{
  "evidence_id": "evidence-uuid"
}
```

## Data Models

### Regulatory Framework
- **id**: UUID primary key
- **name**: Framework name
- **framework_type**: Type (GDPR, HIPAA, SOX, ISO27001, etc.)
- **version**: Framework version
- **description**: Framework description
- **applicable_regions**: List of applicable regions
- **industry_sectors**: List of applicable sectors
- **compliance_requirements**: List of requirements
- **is_active**: Active status
- **effective_date**: Effective date
- **review_date**: Review date

### Compliance Requirement
- **id**: UUID primary key
- **framework**: Related framework
- **requirement_id**: Unique identifier within framework
- **title**: Requirement title
- **description**: Requirement description
- **requirement_type**: Type (TECHNICAL, ADMINISTRATIVE, etc.)
- **priority**: Priority level (CRITICAL, HIGH, MEDIUM, LOW)
- **compliance_status**: Status (COMPLIANT, PARTIALLY_COMPLIANT, etc.)
- **is_implemented**: Implementation status
- **assigned_to**: Assigned user
- **next_assessment_date**: Next assessment date

### Evidence Collection
- **id**: UUID primary key
- **incident**: Related incident
- **title**: Evidence title
- **description**: Evidence description
- **evidence_type**: Type (LOG_FILE, SCREENSHOT, DOCUMENT, etc.)
- **status**: Status (COLLECTED, VERIFIED, ANALYZED, etc.)
- **file_path**: File path
- **file_hash**: SHA-256 hash for integrity
- **collected_by**: Collector user
- **custody_chain**: Chain of custody records
- **retention_period**: Retention period

### Retention Policy
- **id**: UUID primary key
- **name**: Policy name
- **policy_type**: Type (INCIDENT_DATA, AUDIT_LOGS, etc.)
- **retention_period**: Retention period value
- **retention_unit**: Unit (DAYS, WEEKS, MONTHS, YEARS)
- **auto_archive**: Auto-archive flag
- **auto_delete**: Auto-delete flag
- **data_classification_levels**: Applicable classification levels
- **incident_categories**: Applicable incident categories
- **legal_hold_override**: Legal hold override flag

### Export Request
- **id**: UUID primary key
- **title**: Request title
- **request_type**: Type (REGULATORY, AUDIT, LEGAL, INTERNAL)
- **status**: Status (PENDING, APPROVED, IN_PROGRESS, etc.)
- **requester_name**: Requester name
- **requester_organization**: Requester organization
- **requester_email**: Requester email
- **data_scope**: Scope of data to export
- **date_range_start**: Start date for data
- **date_range_end**: End date for data
- **export_format**: Export format (JSON, CSV, XML, PDF)
- **include_evidence**: Include evidence flag
- **include_audit_trails**: Include audit trails flag
- **redaction_required**: Redaction required flag

## Authentication

All API endpoints require authentication. Use one of the following methods:

1. **Token Authentication**: Include `Authorization: Token <your-token>` header
2. **Session Authentication**: Use Django session authentication
3. **SSO Authentication**: Use configured SSO providers

## Permissions

The API uses role-based access control (RBAC) with the following permission levels:

- **View**: Read-only access to compliance data
- **Edit**: Modify compliance data
- **Admin**: Full administrative access
- **Auditor**: Special access for audit and export functions

## Error Handling

The API returns standard HTTP status codes:

- **200**: Success
- **201**: Created
- **400**: Bad Request
- **401**: Unauthorized
- **403**: Forbidden
- **404**: Not Found
- **500**: Internal Server Error

Error responses include detailed error messages:

```json
{
  "error": "Invalid compliance status",
  "details": "Status must be one of: COMPLIANT, PARTIALLY_COMPLIANT, NON_COMPLIANT, NOT_ASSESSED"
}
```

## Rate Limiting

API requests are rate-limited to prevent abuse:

- **Authenticated users**: 1000 requests per hour
- **Unauthenticated users**: 100 requests per hour

## Pagination

List endpoints support pagination:

- **page**: Page number (default: 1)
- **page_size**: Items per page (default: 20, max: 100)

## Filtering and Search

Most list endpoints support filtering and search:

- **Exact filters**: Use field names with exact values
- **Date ranges**: Use `_after` and `_before` suffixes
- **Search**: Use `search` parameter for text search across multiple fields

## Examples

### Creating a GDPR Compliance Framework

```bash
curl -X POST "https://api.example.com/api/compliance/frameworks/" \
  -H "Authorization: Token your-token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "GDPR Compliance Framework",
    "framework_type": "GDPR",
    "version": "1.0",
    "description": "GDPR compliance framework for EU data protection",
    "applicable_regions": ["EU", "EEA", "UK"],
    "industry_sectors": ["Technology", "Healthcare"],
    "is_active": true,
    "effective_date": "2018-05-25"
  }'
```

### Creating an Export Request

```bash
curl -X POST "https://api.example.com/api/compliance/export-requests/" \
  -H "Authorization: Token your-token" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "GDPR Data Export Request",
    "description": "Export of personal data for regulatory review",
    "request_type": "REGULATORY",
    "requester_name": "John Doe",
    "requester_organization": "EU Data Protection Authority",
    "requester_email": "john.doe@dpa.eu",
    "data_scope": {
      "incidents": true,
      "evidence": true,
      "audit_trails": true
    },
    "date_range_start": "2023-01-01T00:00:00Z",
    "date_range_end": "2023-12-31T23:59:59Z",
    "export_format": "JSON",
    "include_evidence": true,
    "include_audit_trails": true,
    "redaction_required": false
  }'
```

### Updating Compliance Status

```bash
curl -X POST "https://api.example.com/api/compliance/requirements/uuid/update_status/" \
  -H "Authorization: Token your-token" \
  -H "Content-Type: application/json" \
  -d '{
    "compliance_status": "COMPLIANT"
  }'
```

## Integration with Other Modules

The Compliance & Governance module integrates with:

- **Incident Intelligence**: Links evidence and workflows to incidents
- **Security**: Uses data classification and user permissions
- **Automation Orchestration**: Triggers compliance workflows
- **SLA & On-Call**: Manages compliance deadlines and escalations

## Setup and Configuration

1. **Install the module**: Add `compliance_governance` to `INSTALLED_APPS`
2. **Run migrations**: `python manage.py migrate`
3. **Create sample data**: `python manage.py setup_compliance_governance`
4. **Configure frameworks**: Set up your specific compliance frameworks
5. **Define workflows**: Create regulatory workflows for your processes
6. **Set retention policies**: Configure data retention policies

## Support

For technical support or questions about the Compliance & Governance API:

- **Documentation**: Check this documentation and inline API docs
- **Admin Interface**: Use Django admin for data management
- **Logs**: Check application logs for detailed error information
- **Support Team**: Contact your system administrator