Hugging Face's logo

Spaces:
kamau1
/
swiftops-backend
Sleeping

App Files Community
swiftops-backend / docs /api /ticket-comments /IMPLEMENTATION.md
kamau1's picture
kamau1
feat: ticket comments
495529d
preview code
|
raw
history blame contribute delete
7.71 kB

Ticket Comments - Implementation Summary

✅ What Was Implemented

1. Service Layer (ticket_comment_service.py)

  • ✅ create_comment() - Create comments with validation
  • ✅ update_comment() - Edit comments (author only)
  • ✅ delete_comment() - Soft delete (author or PM)
  • ✅ get_comment() - Get single comment
  • ✅ list_comments() - Paginated list with filtering
  • ✅ get_comment_replies() - Load threaded replies
  • ✅ _to_response() - Convert model to response schema

2. API Endpoints (ticket_comments.py)

  • ✅ POST /tickets/{ticket_id}/comments - Create comment
  • ✅ PUT /comments/{comment_id} - Update comment
  • ✅ DELETE /comments/{comment_id} - Delete comment
  • ✅ GET /comments/{comment_id} - Get comment
  • ✅ GET /tickets/{ticket_id}/comments - List comments
  • ✅ GET /comments/{comment_id}/replies - Get replies

3. Features

  • ✅ Threading - Reply to comments via parent_comment_id
  • ✅ Mentions - Tag users via mentioned_user_ids
  • ✅ Attachments - Link documents via attachment_document_ids
  • ✅ Edit Tracking - Track who edited and when
  • ✅ Soft Delete - Preserve data integrity
  • ✅ Pagination - Handle large comment lists
  • ✅ Filtering - By type, internal/external, parent-only
  • ✅ Authorization - Role-based access control

4. Validation

  • ✅ Ticket exists before creating comment
  • ✅ Parent comment exists for replies
  • ✅ Mentioned users exist
  • ✅ Only author can edit their comments
  • ✅ Author or PM can delete comments
  • ✅ Comment text not empty

5. Documentation

  • ✅ API documentation with examples
  • ✅ Testing guide with curl commands
  • ✅ Error handling documentation
  • ✅ Best practices guide

🔧 How It Works

Threading (Replies) 

Comment A (parent_comment_id: null)
├── Reply B (parent_comment_id: A)
│   └── Reply C (parent_comment_id: B)
└── Reply D (parent_comment_id: A)

Implementation:

  • Each comment has optional parent_comment_id
  • reply_count computed in _to_response()
  • Replies loaded separately via /comments/{id}/replies
  • Replies sorted by created_at ASC (oldest first)

Edit Tracking

When comment is edited:

  1. comment_text updated
  2. is_edited set to true
  3. edited_at set to current timestamp
  4. edited_by_user_id set to editor's ID
  5. updated_at updated

Original text NOT preserved (consider version history if needed)

Soft Delete

When comment is deleted:

  1. deleted_at set to current timestamp
  2. Comment excluded from all queries via deleted_at IS NULL
  3. Data preserved for audit trail
  4. Can be restored by setting deleted_at = NULL

🎯 Usage Examples

Field Agent: Add Note 

POST /tickets/{ticket_id}/comments
{
  "comment_text": "Customer not home, will retry tomorrow",
  "is_internal": true,
  "comment_type": "update"
}

Dispatcher: Ask Question 

POST /tickets/{ticket_id}/comments
{
  "comment_text": "@john Can you check the customer location?",
  "mentioned_user_ids": ["john-uuid"],
  "is_internal": true,
  "comment_type": "question"
}

PM: Reply to Question 

POST /tickets/{ticket_id}/comments
{
  "comment_text": "Location verified, proceed with installation",
  "parent_comment_id": "question-uuid",
  "is_internal": true,
  "comment_type": "resolution"
}

Load Threaded Conversation 

# 1. Get top-level comments
GET /tickets/{ticket_id}/comments?parent_only=true

# 2. For each comment with reply_count > 0:
GET /comments/{comment_id}/replies

🔒 Security

Authorization Matrix

Action Field Agent Dispatcher PM Platform Admin
Create comment ✅ ✅ ✅ ✅
View comments ✅ ✅ ✅ ✅
Edit own comment ✅ ✅ ✅ ✅
Edit others' comment ❌ ❌ ❌ ❌
Delete own comment ✅ ✅ ✅ ✅
Delete others' comment ❌ ❌ ✅ ✅

Validation Checks

  1. ✅ Ticket exists
  2. ✅ Parent comment exists (for replies)
  3. ✅ Mentioned users exist
  4. ✅ User owns comment (for edit)
  5. ✅ User is author or PM (for delete)
  6. ✅ Comment text not empty

📊 Database Impact

Indexes (Already in schema.sql) 

CREATE INDEX idx_ticket_comments_ticket ON ticket_comments(ticket_id, deleted_at);
CREATE INDEX idx_ticket_comments_parent ON ticket_comments(parent_comment_id);
CREATE INDEX idx_ticket_comments_user ON ticket_comments(user_id);
CREATE INDEX idx_ticket_comments_created ON ticket_comments(created_at DESC);

Storage Estimate

  • Average comment: ~200 bytes
  • 1000 comments: ~200 KB
  • 1 million comments: ~200 MB

🚀 Performance

Query Optimization

  • ✅ Use joinedload() for relationships
  • ✅ Filter deleted_at IS NULL in all queries
  • ✅ Paginate large result sets
  • ✅ Index on ticket_id, parent_comment_id, user_id

Expected Response Times

  • Create comment: < 100ms
  • List comments (50 items): < 200ms
  • Get replies: < 100ms
  • Update comment: < 100ms
  • Delete comment: < 100ms

🔮 Future Enhancements

Phase 2: Notifications

  • Notify mentioned users
  • Notify ticket assignees on external comments
  • Real-time updates via SSE

Phase 3: Rich Features

  • Markdown support
  • Code blocks
  • File attachments (not just links)
  • Emoji reactions

Phase 4: Advanced

  • Full-text search
  • Comment version history
  • Bulk operations
  • Comment templates

🐛 Known Limitations

  1. No version history - Edits overwrite original text
  2. No notifications - Mentions don't trigger notifications yet
  3. No rich text - Plain text only
  4. No reactions - Can't like/emoji comments
  5. No search - Must paginate to find comments

📝 Testing Checklist

  • Create comment on valid ticket
  • Create reply to comment
  • Update own comment
  • Delete own comment
  • List comments with pagination
  • Get comment replies
  • Filter by is_internal
  • Filter by comment_type
  • Filter parent_only
  • Validate ticket exists
  • Validate parent comment exists
  • Validate mentioned users exist
  • Prevent editing others' comments
  • Allow PM to delete any comment
  • Soft delete preserves data
  • Reply count accurate
  • Edit tracking works

🎓 Best Practices

For Developers

  1. Always filter deleted_at IS NULL
  2. Use joinedload() for relationships
  3. Validate foreign keys before creating
  4. Use transactions for data consistency
  5. Log all operations for debugging

For Users

  1. Keep comments concise and actionable
  2. Use appropriate comment types
  3. Mark sensitive info as internal
  4. Reply to comments for context
  5. Edit instead of delete when possible

📞 Support

Common Issues

Q: Comments not appearing? A: Check deleted_at IS NULL filter

Q: Can't edit comment? A: Only author can edit their own comments

Q: Reply count wrong? A: Ensure subquery counts deleted_at IS NULL

Q: Mentions not working? A: Notifications not implemented yet (Phase 2)

Contact

  • Backend issues: Check logs in src/app/services/ticket_comment_service.py
  • API issues: Check src/app/api/v1/ticket_comments.py
  • Database issues: Check indexes and constraints

👨‍💻 Frontend Team Guide

See FRONTEND.md for:

  • 6 endpoints with exact request/response formats
  • UI patterns (simple list, threaded view, pagination)
  • React component examples
  • Common use cases
  • Error handling
  • Performance tips
  • Quick reference (no fluff)