Prompt Versioning

model Prompt {
  id      String @id @default(uuid())
  name    String
  version Int    @default(1)  // Current version
  // ... other fields
  
  versions PromptVersion[]  // Historical snapshots
  changes  PromptChange[]   // Audit trail
}

model PromptVersion {
  id       String @id @default(uuid())
  promptId String
  version  Int
  
  // Snapshot of all prompt fields at this version
  name               String
  section            AgentSection
  systemPrompt       String
  userPromptTemplate String
  // ... all other prompt fields
  
  createdAt DateTime @default(now())
  
  @@unique([promptId, version])
}

model PromptChange {
  id         String           @id @default(uuid())
  promptId   String
  version    Int
  changeType PromptChangeType // CREATE, UPDATE, DELETE, ACTIVATE, DEACTIVATE
  changes    Json             // { field: { old: value, new: value } }
  comment    String?
  authorId   String
  createdAt  DateTime         @default(now())
}

curl -X GET https://api.example.com/api/admin/prompts/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

curl -X GET "https://api.example.com/api/admin/prompts/550e8400-e29b-41d4-a716-446655440000?version=2" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Gap Detection — Market Risk v2",
    "version": 2,
    "systemPrompt": "You are an expert agricultural risk analyst...",
    // ... all prompt fields
    "createdAt": "2026-02-20T10:00:00.000Z",
    "updatedAt": "2026-03-01T14:30:00.000Z"
  }
}

curl -X GET https://api.example.com/api/admin/prompts/550e8400-e29b-41d4-a716-446655440000/history \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

{
  "data": [
    {
      "id": "change-uuid-3",
      "version": 3,
      "changeType": "UPDATE",
      "changes": {
        "systemPrompt": {
          "old": "You are an expert risk analyst.",
          "new": "You are an expert agricultural risk analyst with 15+ years of experience."
        },
        "tags": {
          "old": ["v2", "production"],
          "new": ["v3", "production", "reviewed"]
        }
      },
      "comment": "Enhanced system prompt with experience level",
      "author": {
        "id": "user-uuid-456",
        "email": "admin@example.com"
      },
      "createdAt": "2026-03-04T14:30:00.000Z"
    },
    {
      "id": "change-uuid-2",
      "version": 2,
      "changeType": "UPDATE",
      "changes": {
        "name": {
          "old": "Gap Detection — Market Risk v1",
          "new": "Gap Detection — Market Risk v2"
        },
        "userPromptTemplate": {
          "old": "Identify gaps for: {{categories}}",
          "new": "Given the following business plan section:\n\n{{document_excerpt}}\n\nIdentify gaps in risk coverage for the following categories: {{categories}}"
        }
      },
      "comment": null,
      "author": {
        "id": "user-uuid-123",
        "email": "editor@example.com"
      },
      "createdAt": "2026-03-01T10:00:00.000Z"
    },
    {
      "id": "change-uuid-1",
      "version": 1,
      "changeType": "CREATE",
      "changes": {},
      "comment": "Initial creation",
      "author": {
        "id": "user-uuid-123",
        "email": "editor@example.com"
      },
      "createdAt": "2026-02-20T10:00:00.000Z"
    }
  ]
}

// Prisma transaction:
1. Create prompt record with version: 1
2. Create initial version snapshot in prompt_versions
3. Create change record with changeType: CREATE

// Prisma transaction:
1. Read current prompt state
2. Snapshot current state to prompt_versions (preserves previous version)
3. Compute field-level diffs (old vs new)
4. Increment version number
5. Update prompt record with new values
6. Create change record with changeType: UPDATE and diffs

// Prisma transaction:
1. Snapshot current state to prompt_versions
2. Increment version
3. Flip isActive flag
4. Create change record with changeType: ACTIVATE or DEACTIVATE

// Option A: Delete entire prompt
1. Create change record with changeType: DELETE
2. Delete prompt (cascades to versions, comments, changes)

// Option B: Delete specific version
1. Delete version snapshot from prompt_versions
2. Create change record documenting version deletion

type ChangesDiff = {
  [field: string]: {
    old: any;
    new: any;
  }
};

// Example:
{
  "systemPrompt": {
    "old": "Original text...",
    "new": "Updated text..."
  },
  "tags": {
    "old": ["v1"],
    "new": ["v2", "reviewed"]
  },
  "isActive": {
    "old": false,
    "new": true
  }
}

// Fetch version 2
const { data: v2 } = await fetch('/api/admin/prompts/550e8400-e29b-41d4-a716-446655440000?version=2');

// Rollback by updating with v2 values
await fetch('/api/admin/prompts/550e8400-e29b-41d4-a716-446655440000/update', {
  method: 'PUT',
  body: JSON.stringify({
    name: v2.name,
    systemPrompt: v2.systemPrompt,
    userPromptTemplate: v2.userPromptTemplate,
    // ... all other fields
  })
});

// This creates version 4 (a copy of version 2)

// Pseudo-code in PromptsService.update():
const currentPrompt = await prisma.prompt.findUnique({ where: { id } });

if (currentPrompt.updatedAt > clientLastReadTimestamp) {
  throw new ConflictException('Prompt was modified by another user');
}

// Proceed with update...

✅ "Gap Detection — Market Risk v3"
❌ "Gap Detection — Market Risk (updated)"

await promptsService.update(id, dto, userId, {
  comment: 'Refined output format based on user feedback'
});

# Get change history
curl /api/admin/prompts/:id/history

# Compare current vs previous version
curl /api/admin/prompts/:id?version=2  # Old
curl /api/admin/prompts/:id             # New

# If satisfied, activate
curl -X POST /api/admin/prompts/:id/toggle-active

# Delete version 1 (keep versions 2-5)
curl -X DELETE "/api/admin/prompts/:id?version=1"