Add OWASP compliance mapping and security test case templates, and document version control implementation phases

docs/version_control_api.md

@@ -0,0 +1,320 @@
+# Version Control System API Documentation
+
+## Overview
+The version control system provides a comprehensive API for managing content versioning, branching, and merging across different models in the system.
+
+## Core Models
+
+### VersionBranch
+Represents a branch in the version control system.
+
+```python
+class VersionBranch:
+    name: str           # Branch name (unique)
+    metadata: JSONField # Branch metadata
+    is_active: bool    # Branch status
+    created_at: datetime
+    updated_at: datetime
+```
+
+### ChangeSet
+Represents a set of changes to a versioned object.
+
+```python
+class ChangeSet:
+    branch: ForeignKey      # Reference to VersionBranch
+    content_type: ForeignKey # ContentType of the changed object
+    object_id: int         # ID of the changed object
+    data: JSONField        # Change data
+    status: str           # Status (pending, applied, conflict)
+    created_at: datetime
+    applied_at: datetime
+```
+
+## API Endpoints
+
+### Branch Management
+
+#### Create Branch
+```http
+POST /api/v1/version-control/branches/
+```
+
+Request body:
+```json
+{
+    "name": "feature/new-branch",
+    "metadata": {
+        "type": "feature",
+        "description": "New feature branch"
+    }
+}
+```
+
+Response:
+```json
+{
+    "id": 1,
+    "name": "feature/new-branch",
+    "metadata": {
+        "type": "feature",
+        "description": "New feature branch"
+    },
+    "is_active": true,
+    "created_at": "2025-02-07T09:00:00Z"
+}
+```
+
+#### Switch Branch
+```http
+POST /api/v1/version-control/branches/{branch_id}/switch/
+```
+
+Response:
+```json
+{
+    "status": "success",
+    "branch": {
+        "id": 1,
+        "name": "feature/new-branch"
+    }
+}
+```
+
+### Change Management
+
+#### Create Change
+```http
+POST /api/v1/version-control/changes/
+```
+
+Request body:
+```json
+{
+    "branch_id": 1,
+    "content_type": "parks.park",
+    "object_id": 123,
+    "data": {
+        "name": "Updated Name",
+        "description": "Updated description"
+    }
+}
+```
+
+Response:
+```json
+{
+    "id": 1,
+    "branch": 1,
+    "status": "pending",
+    "created_at": "2025-02-07T09:05:00Z"
+}
+```
+
+#### Apply Change
+```http
+POST /api/v1/version-control/changes/{change_id}/apply/
+```
+
+Response:
+```json
+{
+    "status": "success",
+    "change": {
+        "id": 1,
+        "status": "applied",
+        "applied_at": "2025-02-07T09:06:00Z"
+    }
+}
+```
+
+### Merge Operations
+
+#### Merge Branch
+```http
+POST /api/v1/version-control/branches/{source_id}/merge/
+```
+
+Request body:
+```json
+{
+    "target_branch_id": 2
+}
+```
+
+Response:
+```json
+{
+    "status": "success",
+    "conflicts": []
+}
+```
+
+#### Resolve Conflicts
+```http
+POST /api/v1/version-control/merge/resolve/
+```
+
+Request body:
+```json
+{
+    "merge_id": 1,
+    "resolutions": [
+        {
+            "field": "name",
+            "value": "Resolved Name"
+        }
+    ]
+}
+```
+
+Response:
+```json
+{
+    "status": "success",
+    "merge": {
+        "id": 1,
+        "status": "completed"
+    }
+}
+```
+
+## Model Integration
+
+### Adding Version Control to Models
+
+To make a model version-controlled, inherit from `HistoricalModel`:
+
+```python
+from history_tracking.models import HistoricalModel
+
+class YourModel(HistoricalModel):
+    name = models.CharField(max_length=255)
+    
+    def save(self, *args, **kwargs):
+        # Get the branch from context
+        current_branch = get_current_branch()
+        
+        if current_branch:
+            # Save in branch context
+            super().save(*args, **kwargs)
+        else:
+            # Save in main branch
+            with ChangesetContextManager(branch=main_branch):
+                super().save(*args, **kwargs)
+```
+
+### Version Control Methods
+
+Each versioned model has access to these methods:
+
+#### get_version_info()
+Returns version control information for the object:
+```python
+info = model.get_version_info()
+# Returns:
+{
+    'latest_changes': [ChangeSet],
+    'active_branches': [VersionBranch],
+    'current_branch': VersionBranch,
+    'total_changes': int
+}
+```
+
+#### get_changes()
+Returns all changes for the object:
+```python
+changes = model.get_changes()
+# Returns QuerySet of ChangeSet objects
+```
+
+## JavaScript Integration
+
+### Version Control UI
+
+Initialize version control UI:
+```javascript
+import { initVersionControl } from 'version-control.js';
+
+initVersionControl({
+    container: '#version-control-panel',
+    onChange: (branch) => {
+        // Handle branch change
+    }
+});
+```
+
+### Branch Operations
+
+Switch branches:
+```javascript
+import { switchBranch } from 'version-control.js';
+
+switchBranch(branchId).then(response => {
+    if (response.status === 'success') {
+        // Handle successful branch switch
+    }
+});
+```
+
+### Merge Operations
+
+Handle merge conflicts:
+```javascript
+import { handleMergeConflicts } from 'version-control.js';
+
+handleMergeConflicts(conflicts).then(resolutions => {
+    // Handle conflict resolutions
+});
+```
+
+## Error Handling
+
+The API uses standard HTTP status codes:
+
+- 200: Success
+- 400: Bad Request
+- 401: Unauthorized
+- 403: Forbidden
+- 404: Not Found
+- 409: Conflict (merge conflicts)
+- 500: Internal Server Error
+
+Error responses include detailed information:
+```json
+{
+    "status": "error",
+    "message": "Detailed error message",
+    "code": "ERROR_CODE",
+    "details": {
+        // Additional error details
+    }
+}
+```
+
+## Rate Limiting
+
+API endpoints are rate-limited:
+- Authenticated users: 100 requests per minute
+- Anonymous users: 20 requests per minute
+
+Rate limit headers are included in responses:
+```http
+X-RateLimit-Limit: 100
+X-RateLimit-Remaining: 95
+X-RateLimit-Reset: 1623456789
+```
+
+## Monitoring
+
+Monitor version control operations through the monitoring dashboard:
+```http
+GET /version-control/monitoring/
+```
+
+The dashboard provides real-time metrics for:
+- Branch operations
+- Merge success rates
+- Change tracking overhead
+- Error rates
+- System health