feat: ticket comments

docs/api/ticket-comments/FRONTEND.md

@@ -0,0 +1,441 @@
+# Ticket Comments - Frontend Quick Reference
+
+## 🎯 6 Endpoints You Need
+
+### 1. Create Comment
+```typescript
+POST /api/v1/tickets/{ticketId}/comments
+
+// Send this:
+{
+  comment_text: string,        // Required, 1-5000 chars
+  is_internal: boolean,        // true = team only, false = client sees
+  comment_type: string,        // "note" | "issue" | "resolution" | "question" | "update"
+  parent_comment_id?: string,  // For replies, null for top-level
+  mentioned_user_ids?: string[],
+  attachment_document_ids?: string[]
+}
+
+// Get this:
+{
+  id: string,
+  ticket_id: string,
+  user_id: string,
+  user_name: string,
+  comment_text: string,
+  is_internal: boolean,
+  comment_type: string,
+  parent_comment_id: string | null,
+  mentioned_user_ids: string[],
+  attachment_document_ids: string[],
+  is_edited: boolean,
+  edited_at: string | null,
+  edited_by_user_id: string | null,
+  edited_by_user_name: string | null,
+  created_at: string,
+  updated_at: string,
+  reply_count: number
+}
+```
+
+---
+
+### 2. List Comments
+```typescript
+GET /api/v1/tickets/{ticketId}/comments?page=1&page_size=50&is_internal=true&parent_only=false
+
+// Get this:
+{
+  comments: Comment[],  // Array of comments (see structure above)
+  total: number,        // Total count
+  page: number,         // Current page
+  page_size: number,    // Items per page
+  pages: number         // Total pages
+}
+```
+
+**Query Params:**
+- `page` (default: 1)
+- `page_size` (default: 50, max: 100)
+- `is_internal` (optional: true/false)
+- `comment_type` (optional: "note" | "issue" | "resolution" | "question" | "update")
+- `parent_only` (default: false) - Set true to get only top-level comments
+
+---
+
+### 3. Get Replies
+```typescript
+GET /api/v1/comments/{commentId}/replies
+
+// Get this:
+Comment[]  // Array of replies, sorted oldest first
+```
+
+---
+
+### 4. Update Comment
+```typescript
+PUT /api/v1/comments/{commentId}
+
+// Send this:
+{
+  comment_text: string  // Required, 1-5000 chars
+}
+
+// Get this:
+Comment  // Updated comment with is_edited=true
+```
+
+**Auth:** Only comment author can update
+
+---
+
+### 5. Delete Comment
+```typescript
+DELETE /api/v1/comments/{commentId}
+
+// Get this:
+{
+  success: true,
+  message: "Comment deleted successfully",
+  comment_id: string
+}
+```
+
+**Auth:** Comment author OR Project Manager
+
+---
+
+### 6. Get Single Comment
+```typescript
+GET /api/v1/comments/{commentId}
+
+// Get this:
+Comment  // Single comment object
+```
+
+---
+
+## 🎨 UI Patterns
+
+### Pattern 1: Simple List (Mobile)
+```typescript
+// Load all comments, newest first
+const { comments } = await api.get(`/tickets/${ticketId}/comments`, {
+  params: { page_size: 50 }
+});
+
+// Display flat list
+comments.forEach(comment => {
+  renderComment(comment);
+});
+```
+
+---
+
+### Pattern 2: Threaded View (Web)
+```typescript
+// Step 1: Load top-level comments
+const { comments: topLevel } = await api.get(`/tickets/${ticketId}/comments`, {
+  params: { parent_only: true }
+});
+
+// Step 2: Load replies for comments with reply_count > 0
+for (const comment of topLevel) {
+  if (comment.reply_count > 0) {
+    const replies = await api.get(`/comments/${comment.id}/replies`);
+    comment.replies = replies;
+  }
+}
+
+// Step 3: Render nested
+renderThreadedComments(topLevel);
+```
+
+---
+
+### Pattern 3: Create Reply
+```typescript
+// Reply to a comment
+await api.post(`/tickets/${ticketId}/comments`, {
+  comment_text: "I'll handle this",
+  parent_comment_id: parentCommentId,  // Link to parent
+  is_internal: true,
+  comment_type: "note"
+});
+```
+
+---
+
+### Pattern 4: Edit Comment
+```typescript
+// Update comment text
+await api.put(`/comments/${commentId}`, {
+  comment_text: "Updated text"
+});
+
+// UI shows "edited" badge
+```
+
+---
+
+### Pattern 5: Pagination
+```typescript
+const [page, setPage] = useState(1);
+
+const loadComments = async () => {
+  const data = await api.get(`/tickets/${ticketId}/comments`, {
+    params: { page, page_size: 20 }
+  });
+  
+  setComments(data.comments);
+  setTotalPages(data.pages);
+};
+
+// Load more button
+<button onClick={() => setPage(page + 1)}>Load More</button>
+```
+
+---
+
+## 🚨 Error Handling
+
+```typescript
+try {
+  await api.post(`/tickets/${ticketId}/comments`, data);
+} catch (error) {
+  if (error.status === 404) {
+    // Ticket not found
+  } else if (error.status === 403) {
+    // Not authorized (e.g., editing someone else's comment)
+  } else if (error.status === 400) {
+    // Validation error (e.g., mentioned user doesn't exist)
+  }
+}
+```
+
+---
+
+## 💡 Quick Tips
+
+### For Mobile (Field Agents)
+```typescript
+// Simple flat list, internal only
+const { comments } = await api.get(`/tickets/${ticketId}/comments`, {
+  params: { 
+    is_internal: true,  // Hide external comments
+    page_size: 20 
+  }
+});
+```
+
+### For Web (Dispatchers/PMs)
+```typescript
+// Threaded view with all comments
+const { comments } = await api.get(`/tickets/${ticketId}/comments`, {
+  params: { 
+    parent_only: true,  // Get top-level first
+    page_size: 50 
+  }
+});
+```
+
+### Show "Edited" Badge
+```typescript
+{comment.is_edited && (
+  <span>Edited {formatDate(comment.edited_at)}</span>
+)}
+```
+
+### Show Reply Count
+```typescript
+{comment.reply_count > 0 && (
+  <button onClick={() => loadReplies(comment.id)}>
+    {comment.reply_count} replies
+  </button>
+)}
+```
+
+### Mention Users
+```typescript
+// Extract @mentions from text
+const mentions = comment.comment_text.match(/@\w+/g);
+
+// Highlight mentions in UI
+const highlightedText = comment.comment_text.replace(
+  /@(\w+)/g, 
+  '<span class="mention">@$1</span>'
+);
+```
+
+---
+
+## 📱 Component Examples
+
+### React: Comment List
+```tsx
+function CommentList({ ticketId }) {
+  const [comments, setComments] = useState([]);
+  
+  useEffect(() => {
+    api.get(`/tickets/${ticketId}/comments`)
+      .then(data => setComments(data.comments));
+  }, [ticketId]);
+  
+  return (
+    <div>
+      {comments.map(comment => (
+        <CommentItem key={comment.id} comment={comment} />
+      ))}
+    </div>
+  );
+}
+```
+
+### React: Create Comment
+```tsx
+function CommentForm({ ticketId, parentId = null }) {
+  const [text, setText] = useState('');
+  
+  const handleSubmit = async () => {
+    await api.post(`/tickets/${ticketId}/comments`, {
+      comment_text: text,
+      parent_comment_id: parentId,
+      is_internal: true,
+      comment_type: 'note'
+    });
+    setText('');
+  };
+  
+  return (
+    <form onSubmit={handleSubmit}>
+      <textarea value={text} onChange={e => setText(e.target.value)} />
+      <button type="submit">Post</button>
+    </form>
+  );
+}
+```
+
+### React: Threaded Comments
+```tsx
+function ThreadedComment({ comment }) {
+  const [replies, setReplies] = useState([]);
+  const [showReplies, setShowReplies] = useState(false);
+  
+  const loadReplies = async () => {
+    const data = await api.get(`/comments/${comment.id}/replies`);
+    setReplies(data);
+    setShowReplies(true);
+  };
+  
+  return (
+    <div className="comment">
+      <div className="comment-content">
+        <strong>{comment.user_name}</strong>
+        <p>{comment.comment_text}</p>
+        {comment.is_edited && <span className="edited">Edited</span>}
+      </div>
+      
+      {comment.reply_count > 0 && (
+        <button onClick={loadReplies}>
+          {showReplies ? 'Hide' : 'Show'} {comment.reply_count} replies
+        </button>
+      )}
+      
+      {showReplies && (
+        <div className="replies">
+          {replies.map(reply => (
+            <ThreadedComment key={reply.id} comment={reply} />
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}
+```
+
+---
+
+## 🎯 Common Use Cases
+
+### 1. Field Agent Adds Note
+```typescript
+await api.post(`/tickets/${ticketId}/comments`, {
+  comment_text: "Customer not home, will retry tomorrow",
+  is_internal: true,
+  comment_type: "update"
+});
+```
+
+### 2. Dispatcher Asks Question
+```typescript
+await api.post(`/tickets/${ticketId}/comments`, {
+  comment_text: "Can you verify the customer location?",
+  is_internal: true,
+  comment_type: "question"
+});
+```
+
+### 3. Agent Replies
+```typescript
+await api.post(`/tickets/${ticketId}/comments`, {
+  comment_text: "Location verified, proceeding",
+  parent_comment_id: questionCommentId,
+  is_internal: true,
+  comment_type: "resolution"
+});
+```
+
+### 4. PM Deletes Inappropriate Comment
+```typescript
+await api.delete(`/comments/${commentId}`);
+```
+
+---
+
+## ⚡ Performance Tips
+
+1. **Lazy load replies** - Don't load all replies upfront
+2. **Paginate** - Use page_size=20 for mobile, 50 for web
+3. **Cache** - Cache comments list, invalidate on create/update/delete
+4. **Optimistic updates** - Show comment immediately, sync in background
+5. **Debounce** - Debounce edit requests by 500ms
+
+---
+
+## 🔑 Key Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `comment_text` | string | The actual comment (1-5000 chars) |
+| `is_internal` | boolean | true = team only, false = client sees |
+| `comment_type` | string | note/issue/resolution/question/update |
+| `parent_comment_id` | string? | null = top-level, uuid = reply |
+| `reply_count` | number | How many replies this comment has |
+| `is_edited` | boolean | Was this comment edited? |
+| `edited_at` | string? | When was it edited? |
+
+---
+
+## ❌ Common Mistakes
+
+1. ❌ Forgetting `is_internal: true` for team comments
+2. ❌ Not filtering `parent_only: true` for threaded view
+3. ❌ Loading all replies upfront (performance issue)
+4. ❌ Not handling 403 errors (editing others' comments)
+5. ❌ Not showing "edited" badge when `is_edited: true`
+
+---
+
+## ✅ Checklist
+
+- [ ] Can create top-level comment
+- [ ] Can create reply (with parent_comment_id)
+- [ ] Can list comments with pagination
+- [ ] Can load replies separately
+- [ ] Can edit own comment
+- [ ] Can delete own comment
+- [ ] Show "edited" badge when is_edited=true
+- [ ] Show reply count
+- [ ] Handle 403/404 errors
+- [ ] Filter internal/external based on user role

docs/api/ticket-comments/IMPLEMENTATION.md

@@ -0,0 +1,291 @@
+# 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
+```python
+POST /tickets/{ticket_id}/comments
+{
+  "comment_text": "Customer not home, will retry tomorrow",
+  "is_internal": true,
+  "comment_type": "update"
+}
+```
+
+### Dispatcher: Ask Question
+```python
+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
+```python
+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
+```python
+# 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)
+```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
+
+- [x] Create comment on valid ticket
+- [x] Create reply to comment
+- [x] Update own comment
+- [x] Delete own comment
+- [x] List comments with pagination
+- [x] Get comment replies
+- [x] Filter by is_internal
+- [x] Filter by comment_type
+- [x] Filter parent_only
+- [x] Validate ticket exists
+- [x] Validate parent comment exists
+- [x] Validate mentioned users exist
+- [x] Prevent editing others' comments
+- [x] Allow PM to delete any comment
+- [x] Soft delete preserves data
+- [x] Reply count accurate
+- [x] 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](./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)

docs/api/ticket-comments/QUICK-REF.md

@@ -0,0 +1,60 @@
+# Ticket Comments - API Quick Reference
+
+## Endpoints
+
+```
+POST   /api/v1/tickets/{ticketId}/comments          Create comment
+GET    /api/v1/tickets/{ticketId}/comments          List comments
+GET    /api/v1/comments/{commentId}                 Get comment
+GET    /api/v1/comments/{commentId}/replies         Get replies
+PUT    /api/v1/comments/{commentId}                 Update comment
+DELETE /api/v1/comments/{commentId}                 Delete comment
+```
+
+## Request/Response
+
+### Create
+```json
+// POST /tickets/{id}/comments
+{
+  "comment_text": "string",
+  "is_internal": true,
+  "comment_type": "note",
+  "parent_comment_id": null
+}
+→ Returns Comment object
+```
+
+### List
+```json
+// GET /tickets/{id}/comments?page=1&page_size=50
+→ {
+  "comments": Comment[],
+  "total": 100,
+  "page": 1,
+  "pages": 2
+}
+```
+
+### Comment Object
+```json
+{
+  "id": "uuid",
+  "comment_text": "string",
+  "user_name": "string",
+  "is_internal": true,
+  "comment_type": "note",
+  "parent_comment_id": null,
+  "reply_count": 0,
+  "is_edited": false,
+  "created_at": "2025-11-30T12:00:00Z"
+}
+```
+
+## Comment Types
+`note` | `issue` | `resolution` | `question` | `update`
+
+## Auth
+- Create: All users
+- Update: Author only
+- Delete: Author or PM

docs/api/ticket-comments/README.md

@@ -0,0 +1,399 @@
+# Ticket Comments API
+
+Team collaboration system for tickets with threading, mentions, and attachments.
+
+## Overview
+
+The ticket comments system enables team members to collaborate on tickets through:
+- **Internal comments** (team only) and **external comments** (client-visible)
+- **Threading** (replies to comments)
+- **Mentions** (tag team members)
+- **Attachments** (link documents)
+- **Edit tracking** (audit trail)
+
+---
+
+## API Endpoints
+
+### 1. Create Comment
+```http
+POST /api/v1/tickets/{ticket_id}/comments
+```
+
+**Request Body:**
+```json
+{
+  "comment_text": "Customer prefers morning visits between 9-11am",
+  "is_internal": true,
+  "comment_type": "note",
+  "parent_comment_id": null,
+  "mentioned_user_ids": [],
+  "attachment_document_ids": []
+}
+```
+
+**Response:** `201 Created`
+```json
+{
+  "id": "uuid",
+  "ticket_id": "uuid",
+  "user_id": "uuid",
+  "user_name": "John Doe",
+  "comment_text": "Customer prefers morning visits between 9-11am",
+  "is_internal": true,
+  "comment_type": "note",
+  "parent_comment_id": null,
+  "mentioned_user_ids": [],
+  "attachment_document_ids": [],
+  "is_edited": false,
+  "edited_at": null,
+  "edited_by_user_id": null,
+  "edited_by_user_name": null,
+  "additional_metadata": {},
+  "created_at": "2025-11-30T12:00:00Z",
+  "updated_at": "2025-11-30T12:00:00Z",
+  "reply_count": 0
+}
+```
+
+---
+
+### 2. Update Comment
+```http
+PUT /api/v1/comments/{comment_id}
+```
+
+**Authorization:** Comment author only
+
+**Request Body:**
+```json
+{
+  "comment_text": "Updated: Customer now prefers afternoon visits"
+}
+```
+
+**Response:** `200 OK`
+```json
+{
+  "id": "uuid",
+  "comment_text": "Updated: Customer now prefers afternoon visits",
+  "is_edited": true,
+  "edited_at": "2025-11-30T12:05:00Z",
+  "edited_by_user_id": "uuid",
+  "edited_by_user_name": "John Doe",
+  ...
+}
+```
+
+---
+
+### 3. Delete Comment
+```http
+DELETE /api/v1/comments/{comment_id}
+```
+
+**Authorization:** Comment author or Project Manager
+
+**Response:** `200 OK`
+```json
+{
+  "success": true,
+  "message": "Comment deleted successfully",
+  "comment_id": "uuid"
+}
+```
+
+---
+
+### 4. List Comments
+```http
+GET /api/v1/tickets/{ticket_id}/comments?page=1&page_size=50&is_internal=true&parent_only=false
+```
+
+**Query Parameters:**
+- `page` (int): Page number (default: 1)
+- `page_size` (int): Items per page (default: 50, max: 100)
+- `is_internal` (bool): Filter by internal/external
+- `comment_type` (string): Filter by type (note, issue, resolution, question, update)
+- `parent_only` (bool): Show only top-level comments (default: false)
+
+**Response:** `200 OK`
+```json
+{
+  "comments": [...],
+  "total": 25,
+  "page": 1,
+  "page_size": 50,
+  "pages": 1
+}
+```
+
+---
+
+### 5. Get Comment Replies
+```http
+GET /api/v1/comments/{comment_id}/replies
+```
+
+**Response:** `200 OK`
+```json
+[
+  {
+    "id": "uuid",
+    "parent_comment_id": "parent-uuid",
+    "comment_text": "I'll handle this",
+    "user_name": "Jane Smith",
+    ...
+  }
+]
+```
+
+---
+
+## Comment Types
+
+| Type | Description | Use Case |
+|------|-------------|----------|
+| `note` | General note | "Customer prefers morning visits" |
+| `issue` | Problem/blocker | "Customer location is incorrect" |
+| `resolution` | Solution/fix | "Updated customer address" |
+| `question` | Question for team | "Should we reschedule?" |
+| `update` | Status update | "Work 50% complete" |
+
+---
+
+## Threading (Replies)
+
+### Create a Reply
+```json
+{
+  "comment_text": "I'll handle the rescheduling",
+  "parent_comment_id": "parent-comment-uuid",
+  "is_internal": true,
+  "comment_type": "note"
+}
+```
+
+### Load Thread
+1. **List top-level comments:** `GET /tickets/{id}/comments?parent_only=true`
+2. **Load replies:** `GET /comments/{comment_id}/replies`
+
+---
+
+## Mentions
+
+### Tag Team Members
+```json
+{
+  "comment_text": "@john Can you check the customer location?",
+  "mentioned_user_ids": ["john-uuid"],
+  "is_internal": true,
+  "comment_type": "question"
+}
+```
+
+**Future:** Mentioned users will receive notifications
+
+---
+
+## Attachments
+
+### Link Documents
+```json
+{
+  "comment_text": "See attached site survey photos",
+  "attachment_document_ids": ["doc-uuid-1", "doc-uuid-2"],
+  "is_internal": true,
+  "comment_type": "note"
+}
+```
+
+---
+
+## Internal vs External Comments
+
+### Internal Comments (Team Only)
+```json
+{
+  "comment_text": "Customer is difficult, be patient",
+  "is_internal": true
+}
+```
+- Visible to: Team members only
+- Use for: Internal notes, issues, coordination
+
+### External Comments (Client-Visible)
+```json
+{
+  "comment_text": "Installation scheduled for tomorrow 10am",
+  "is_internal": false
+}
+```
+- Visible to: Team + Client
+- Use for: Customer updates, status changes
+
+---
+
+## Edit Tracking
+
+When a comment is edited:
+- `is_edited` → `true`
+- `edited_at` → timestamp
+- `edited_by_user_id` → editor's ID
+- `edited_by_user_name` → editor's name
+
+**Original text is NOT preserved** (consider adding version history if needed)
+
+---
+
+## Authorization
+
+| Action | Who Can Do It |
+|--------|---------------|
+| Create comment | All authenticated users |
+| Update comment | Comment author only |
+| Delete comment | Comment author OR Project Manager |
+| View comments | All authenticated users |
+
+---
+
+## Error Handling
+
+### 404 Not Found
+```json
+{
+  "detail": "Ticket not found"
+}
+```
+
+### 403 Forbidden
+```json
+{
+  "detail": "You can only edit your own comments"
+}
+```
+
+### 400 Bad Request
+```json
+{
+  "detail": "One or more mentioned users not found"
+}
+```
+
+---
+
+## Best Practices
+
+### For Field Agents
+- Use `note` type for general observations
+- Use `issue` type for problems encountered
+- Keep comments concise and actionable
+- Always mark as `is_internal: true`
+
+### For Dispatchers
+- Use `question` type when asking agents
+- Use `update` type for status changes
+- Tag relevant team members with mentions
+- Use external comments for customer updates
+
+### For Project Managers
+- Review external comments before posting
+- Use `resolution` type for solutions
+- Delete inappropriate comments if needed
+- Monitor comment activity for team collaboration
+
+---
+
+## Frontend Integration
+
+### Mobile App (Field Agents)
+```typescript
+// List comments
+const comments = await api.get(`/tickets/${ticketId}/comments`, {
+  params: { is_internal: true, page_size: 20 }
+});
+
+// Create comment
+await api.post(`/tickets/${ticketId}/comments`, {
+  comment_text: "Customer not home, will retry tomorrow",
+  is_internal: true,
+  comment_type: "update"
+});
+
+// Reply to comment
+await api.post(`/tickets/${ticketId}/comments`, {
+  comment_text: "Okay, I'll reschedule",
+  parent_comment_id: parentCommentId,
+  is_internal: true,
+  comment_type: "note"
+});
+```
+
+### Web Dashboard (Dispatchers/PMs)
+```typescript
+// Load threaded comments
+const topLevel = await api.get(`/tickets/${ticketId}/comments`, {
+  params: { parent_only: true }
+});
+
+// Load replies for each comment
+for (const comment of topLevel.comments) {
+  if (comment.reply_count > 0) {
+    const replies = await api.get(`/comments/${comment.id}/replies`);
+    comment.replies = replies;
+  }
+}
+```
+
+---
+
+## Database Schema
+
+```sql
+CREATE TABLE ticket_comments (
+    id UUID PRIMARY KEY,
+    ticket_id UUID NOT NULL REFERENCES tickets(id),
+    user_id UUID REFERENCES users(id),
+    comment_text TEXT NOT NULL,
+    is_internal BOOLEAN DEFAULT TRUE,
+    comment_type VARCHAR(50) DEFAULT 'note',
+    parent_comment_id UUID REFERENCES ticket_comments(id),
+    mentioned_user_ids UUID[],
+    attachment_document_ids UUID[],
+    is_edited BOOLEAN DEFAULT FALSE,
+    edited_at TIMESTAMP WITH TIME ZONE,
+    edited_by_user_id UUID REFERENCES users(id),
+    additional_metadata JSONB DEFAULT '{}',
+    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
+    updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
+    deleted_at TIMESTAMP WITH TIME ZONE
+);
+```
+
+---
+
+## Future Enhancements
+
+1. **Notifications**
+   - Notify mentioned users
+   - Notify ticket assignees on external comments
+   - Real-time updates via SSE
+
+2. **Rich Text**
+   - Markdown support
+   - Code blocks
+   - Formatting
+
+3. **Reactions**
+   - Like/emoji reactions
+   - Quick acknowledgments
+
+4. **Version History**
+   - Track all edits
+   - View previous versions
+   - Restore old versions
+
+5. **Search**
+   - Full-text search across comments
+   - Filter by author
+   - Date range filtering

docs/api/ticket-comments/TESTING.md

@@ -0,0 +1,290 @@
+# Ticket Comments - Testing Guide
+
+## Manual Testing Checklist
+
+### 1. Create Comment ✅
+```bash
+curl -X POST "http://localhost:7860/api/v1/tickets/{ticket_id}/comments" \
+  -H "Authorization: Bearer {token}" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "comment_text": "Customer prefers morning visits",
+    "is_internal": true,
+    "comment_type": "note"
+  }'
+```
+
+**Expected:** 201 Created with comment details
+
+---
+
+### 2. Create Reply (Threading) ✅
+```bash
+curl -X POST "http://localhost:7860/api/v1/tickets/{ticket_id}/comments" \
+  -H "Authorization: Bearer {token}" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "comment_text": "I will handle this",
+    "parent_comment_id": "{parent_comment_id}",
+    "is_internal": true,
+    "comment_type": "note"
+  }'
+```
+
+**Expected:** 201 Created with parent_comment_id set
+
+---
+
+### 3. List Comments ✅
+```bash
+curl -X GET "http://localhost:7860/api/v1/tickets/{ticket_id}/comments?page=1&page_size=20" \
+  -H "Authorization: Bearer {token}"
+```
+
+**Expected:** 200 OK with paginated list
+
+---
+
+### 4. Get Comment Replies ✅
+```bash
+curl -X GET "http://localhost:7860/api/v1/comments/{comment_id}/replies" \
+  -H "Authorization: Bearer {token}"
+```
+
+**Expected:** 200 OK with array of replies
+
+---
+
+### 5. Update Comment ✅
+```bash
+curl -X PUT "http://localhost:7860/api/v1/comments/{comment_id}" \
+  -H "Authorization: Bearer {token}" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "comment_text": "Updated: Customer prefers afternoon"
+  }'
+```
+
+**Expected:** 200 OK with is_edited=true
+
+---
+
+### 6. Delete Comment ✅
+```bash
+curl -X DELETE "http://localhost:7860/api/v1/comments/{comment_id}" \
+  -H "Authorization: Bearer {token}"
+```
+
+**Expected:** 200 OK with success message
+
+---
+
+## Error Cases to Test
+
+### 1. Create Comment on Non-Existent Ticket
+```bash
+curl -X POST "http://localhost:7860/api/v1/tickets/00000000-0000-0000-0000-000000000000/comments" \
+  -H "Authorization: Bearer {token}" \
+  -H "Content-Type: application/json" \
+  -d '{"comment_text": "Test", "is_internal": true, "comment_type": "note"}'
+```
+
+**Expected:** 404 Not Found - "Ticket not found"
+
+---
+
+### 2. Update Someone Else's Comment
+```bash
+# Create comment as User A
+# Try to update as User B
+curl -X PUT "http://localhost:7860/api/v1/comments/{comment_id}" \
+  -H "Authorization: Bearer {user_b_token}" \
+  -H "Content-Type: application/json" \
+  -d '{"comment_text": "Hacked!"}'
+```
+
+**Expected:** 403 Forbidden - "You can only edit your own comments"
+
+---
+
+### 3. Reply to Non-Existent Comment
+```bash
+curl -X POST "http://localhost:7860/api/v1/tickets/{ticket_id}/comments" \
+  -H "Authorization: Bearer {token}" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "comment_text": "Reply",
+    "parent_comment_id": "00000000-0000-0000-0000-000000000000",
+    "is_internal": true,
+    "comment_type": "note"
+  }'
+```
+
+**Expected:** 404 Not Found - "Parent comment not found"
+
+---
+
+### 4. Mention Non-Existent User
+```bash
+curl -X POST "http://localhost:7860/api/v1/tickets/{ticket_id}/comments" \
+  -H "Authorization: Bearer {token}" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "comment_text": "Test",
+    "mentioned_user_ids": ["00000000-0000-0000-0000-000000000000"],
+    "is_internal": true,
+    "comment_type": "note"
+  }'
+```
+
+**Expected:** 400 Bad Request - "One or more mentioned users not found"
+
+---
+
+### 5. Empty Comment Text
+```bash
+curl -X POST "http://localhost:7860/api/v1/tickets/{ticket_id}/comments" \
+  -H "Authorization: Bearer {token}" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "comment_text": "",
+    "is_internal": true,
+    "comment_type": "note"
+  }'
+```
+
+**Expected:** 422 Validation Error - "comment_text must be at least 1 character"
+
+---
+
+## Integration Testing
+
+### Scenario 1: Threaded Conversation
+1. User A creates comment: "Need help with this ticket"
+2. User B replies: "I can help"
+3. User A replies to B: "Thanks!"
+4. Verify reply_count increments
+5. Load replies and verify order (oldest first)
+
+### Scenario 2: Edit Tracking
+1. User creates comment
+2. User edits comment
+3. Verify is_edited=true, edited_at set, edited_by_user_id set
+4. Edit again
+5. Verify edited_at updated
+
+### Scenario 3: Soft Delete
+1. User creates comment
+2. User deletes comment
+3. Verify deleted_at set
+4. Try to list comments - deleted comment should not appear
+5. Try to get deleted comment by ID - should return 404
+
+### Scenario 4: Pagination
+1. Create 100 comments
+2. List with page_size=20
+3. Verify pages=5
+4. Load each page
+5. Verify no duplicates, no missing comments
+
+---
+
+## Performance Testing
+
+### Load Test: Create 1000 Comments
+```python
+import asyncio
+import aiohttp
+
+async def create_comment(session, ticket_id, token):
+    async with session.post(
+        f"http://localhost:7860/api/v1/tickets/{ticket_id}/comments",
+        headers={"Authorization": f"Bearer {token}"},
+        json={
+            "comment_text": "Load test comment",
+            "is_internal": True,
+            "comment_type": "note"
+        }
+    ) as response:
+        return await response.json()
+
+async def main():
+    async with aiohttp.ClientSession() as session:
+        tasks = [create_comment(session, ticket_id, token) for _ in range(1000)]
+        results = await asyncio.gather(*tasks)
+        print(f"Created {len(results)} comments")
+
+asyncio.run(main())
+```
+
+**Expected:** All 1000 comments created successfully in < 30 seconds
+
+---
+
+## Database Verification
+
+### Check Comment Count
+```sql
+SELECT COUNT(*) FROM ticket_comments WHERE deleted_at IS NULL;
+```
+
+### Check Threading
+```sql
+SELECT 
+    id,
+    comment_text,
+    parent_comment_id,
+    (SELECT COUNT(*) FROM ticket_comments c2 WHERE c2.parent_comment_id = c1.id) as reply_count
+FROM ticket_comments c1
+WHERE ticket_id = '{ticket_id}' AND deleted_at IS NULL
+ORDER BY created_at DESC;
+```
+
+### Check Edit History
+```sql
+SELECT 
+    id,
+    comment_text,
+    is_edited,
+    edited_at,
+    edited_by_user_id
+FROM ticket_comments
+WHERE is_edited = TRUE AND deleted_at IS NULL;
+```
+
+---
+
+## Common Issues & Solutions
+
+### Issue: 500 Internal Server Error
+**Cause:** Missing relationship loading
+**Solution:** Ensure all relationships use `joinedload()` in service layer
+
+### Issue: Comments not appearing
+**Cause:** Soft delete not filtered
+**Solution:** Always filter `deleted_at IS NULL`
+
+### Issue: Reply count incorrect
+**Cause:** Not counting replies properly
+**Solution:** Use subquery to count replies in `_to_response()`
+
+### Issue: Mentions not working
+**Cause:** User IDs not validated
+**Solution:** Query users table to verify all mentioned_user_ids exist
+
+---
+
+## Monitoring
+
+### Key Metrics to Track
+- Comment creation rate (comments/hour)
+- Average reply depth (threading level)
+- Edit frequency (edits/comments ratio)
+- Delete frequency (deletes/comments ratio)
+- Response time for list endpoint
+
+### Alerts to Set Up
+- Comment creation failures > 1%
+- List endpoint response time > 2 seconds
+- Database connection errors
+- Validation errors > 5%

docs/devlogs/db/logs.sql

@@ -1 +1 @@
-INSERT INTO "public"."tickets" ("id", "project_id", "source", "source_id", "ticket_name", "ticket_type", "service_type", "work_description", "status", "priority", "scheduled_date", "scheduled_time_slot", "due_date", "sla_target_date", "sla_violated", "started_at", "completed_at", "is_invoiced", "invoiced_at", "contractor_invoice_id", "project_region_id", "work_location_latitude", "work_location_longitude", "work_location_accuracy", "work_location_verified", "dedup_key", "notes", "additional_metadata", "version", "created_at", "updated_at", "deleted_at", "required_team_size", "completion_data", "completion_photos_verified", "completion_data_verified") VALUES ('8f08ad14-df8b-4780-84e7-0d45e133f2a6', '0ade6bd1-e492-4e25-b681-59f42058d29a', 'sales_order', '5cb76cc5-3d9a-4ce0-87a8-43f912896c1f', 'Catherine Njoki', 'installation', 'ftth', 'Install Basic 10Mbps for Catherine Njoki', 'in_progress', 'normal', '2025-12-28', 'Afternoon 1PM-4PM', '2025-12-01 07:52:17.604326+00', '2025-12-01 07:52:17.604326+00', 'false', null, null, 'false', null, null, null, null, null, null, 'false', 'b2888f980ff72ea1192b21d6905e0825', null, '{}', '1', '2025-11-28 07:52:17.604326+00', '2025-11-28 10:04:37.59353+00', null, '1', '{}', 'false', 'false'), ('f59b29fc-d0b9-4618-b0d1-889e340da612', '0ade6bd1-e492-4e25-b681-59f42058d29a', 'sales_order', 'c93b28c0-d7bf-4f57-b750-d0c6864543b0', 'Elizabeth Muthoni', 'installation', 'ftth', 'Install Premium Fiber 100Mbps for Elizabeth Muthoni', 'completed', 'normal', '2025-12-11', null, '2025-11-29 13:24:19.212882+00', '2025-11-29 13:24:19.212882+00', 'true', null, '2025-11-30 12:08:38.793534+00', 'false', null, null, '4cd27765-5720-4cc0-872e-bf0da3cd1898', null, null, null, 'false', null, '[COMPLETION] we finished connection', '{}', '1', '2025-11-26 13:24:19.212882+00', '2025-11-30 12:08:38.858902+00', null, '1', '{"odu_serial": "jjhh", "ont_serial": "jhh"}', 'true', 'true');
+INSERT INTO "public"."tickets" ("id", "project_id", "source", "source_id", "ticket_name", "ticket_type", "service_type", "work_description", "status", "priority", "scheduled_date", "scheduled_time_slot", "due_date", "sla_target_date", "sla_violated", "started_at", "completed_at", "is_invoiced", "invoiced_at", "contractor_invoice_id", "project_region_id", "work_location_latitude", "work_location_longitude", "work_location_accuracy", "work_location_verified", "dedup_key", "notes", "additional_metadata", "version", "created_at", "updated_at", "deleted_at", "required_team_size", "completion_data", "completion_photos_verified", "completion_data_verified") VALUES ('8f08ad14-df8b-4780-84e7-0d45e133f2a6', '0ade6bd1-e492-4e25-b681-59f42058d29a', 'sales_order', '5cb76cc5-3d9a-4ce0-87a8-43f912896c1f', 'Catherine Njoki', 'installation', 'ftth', 'Install Basic 10Mbps for Catherine Njoki', 'in_progress', 'normal', '2025-12-28', 'Afternoon 1PM-4PM', '2025-12-01 07:52:17.604326+00', '2025-12-01 07:52:17.604326+00', 'false', null, null, 'false', null, null, null, null, null, null, 'false', 'b2888f980ff72ea1192b21d6905e0825', null, '{}', '1', '2025-11-28 07:52:17.604326+00', '2025-11-28 10:04:37.59353+00', null, '1', '{}', 'false', 'false'), ('f59b29fc-d0b9-4618-b0d1-889e340da612', '0ade6bd1-e492-4e25-b681-59f42058d29a', 'sales_order', 'c93b28c0-d7bf-4f57-b750-d0c6864543b0', 'Elizabeth Muthoni', 'installation', 'ftth', 'Install Premium Fiber 100Mbps for Elizabeth Muthoni', 'completed', 'normal', '2025-12-11', null, '2025-11-29 13:24:19.212882+00', '2025-11-29 13:24:19.212882+00', 'true', null, '2025-11-30 12:08:38.793534+00', 'false', null, null, '4cd27765-5720-4cc0-872e-bf0da3cd1898', null, null, null, 'false', null, '[COMPLETION] we finished connection', '{}', '1', '2025-11-26 13:24:19.212882+00', '2025-11-30 12:08:38.858902+00', null, '1', '{"odu_serial": "jjhh", "ont_serial": "jhh"}', 'true', 'true');                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                

src/app/api/v1/router.py

@@ -6,7 +6,7 @@ from app.api.v1 import (
     auth, clients, contractors, organizations, invitations, profile, users,
     financial_accounts, asset_assignments, documents, otp, projects,
     customers, timesheets, payroll, tasks, inventory, finance, sales_orders, tickets,
-    ticket_assignments, ticket_completion, expenses, incidents, contractor_invoices, notifications, map, export, public_tracking, public_hub_tracking,
+    ticket_assignments, ticket_completion, ticket_comments, expenses, incidents, contractor_invoices, notifications, map, export, public_tracking, public_hub_tracking,
     audit_logs, analytics, progress_reports, incident_reports
 )
 
@@ -77,6 +77,9 @@ api_router.include_router(ticket_assignments.router, prefix="/ticket-assignments
 # Ticket Completion (Dynamic Checklists + Progressive Completion + Validation)
 api_router.include_router(ticket_completion.router, prefix="/tickets", tags=["Ticket Completion"])
 
+# Ticket Comments (Team Collaboration + Threading + Mentions)
+api_router.include_router(ticket_comments.router, tags=["Ticket Comments"])
+
 # Ticket Expenses (Expense Tracking + Approval + Payment Routing)
 api_router.include_router(expenses.router, prefix="/expenses", tags=["Expenses"])
 

src/app/api/v1/ticket_comments.py

@@ -0,0 +1,253 @@
+"""
+Ticket Comments API - Team Collaboration
+
+Endpoints for:
+1. Create comments on tickets
+2. Update comments (by author)
+3. Delete comments (by author or PM)
+4. List comments with filtering
+5. Get comment replies (threading)
+
+Authorization:
+- All authenticated users can create comments
+- Only author can edit their own comments
+- Author or PM can delete comments
+"""
+
+from fastapi import APIRouter, Depends, status, Query
+from sqlalchemy.orm import Session
+from typing import Optional, List
+from uuid import UUID
+
+from app.api.deps import get_db, get_current_user
+from app.models.user import User
+from app.services.ticket_comment_service import TicketCommentService
+from app.schemas.ticket_comment import (
+    TicketCommentCreate,
+    TicketCommentUpdate,
+    TicketCommentResponse,
+    TicketCommentListResponse,
+    COMMENT_TYPES
+)
+
+router = APIRouter()
+
+
+# ============================================
+# CREATE COMMENT
+# ============================================
+
+@router.post(
+    "/tickets/{ticket_id}/comments",
+    response_model=TicketCommentResponse,
+    status_code=status.HTTP_201_CREATED,
+    summary="Create comment on ticket",
+    description="""
+    Create a new comment on a ticket.
+    
+    **Features:**
+    - Internal comments (team only) or external (client-visible)
+    - Threading: Reply to other comments using parent_comment_id
+    - Mentions: Tag users with mentioned_user_ids
+    - Attachments: Link documents with attachment_document_ids
+    
+    **Comment Types:**
+    - note: General note or observation
+    - issue: Problem or blocker
+    - resolution: Solution or fix
+    - question: Question for team
+    - update: Status update
+    
+    **Authorization:** All authenticated users
+    """
+)
+def create_comment(
+    ticket_id: UUID,
+    data: TicketCommentCreate,
+    db: Session = Depends(get_db),
+    current_user: User = Depends(get_current_user)
+):
+    """Create a new comment on a ticket"""
+    return TicketCommentService.create_comment(
+        ticket_id=ticket_id,
+        data=data,
+        current_user=current_user,
+        db=db
+    )
+
+
+# ============================================
+# UPDATE COMMENT
+# ============================================
+
+@router.put(
+    "/comments/{comment_id}",
+    response_model=TicketCommentResponse,
+    summary="Update comment",
+    description="""
+    Update a comment (only by original author).
+    
+    **Edit Tracking:**
+    - is_edited flag set to true
+    - edited_at timestamp recorded
+    - edited_by_user_id tracked
+    
+    **Authorization:** Comment author only
+    """
+)
+def update_comment(
+    comment_id: UUID,
+    data: TicketCommentUpdate,
+    db: Session = Depends(get_db),
+    current_user: User = Depends(get_current_user)
+):
+    """Update a comment (author only)"""
+    return TicketCommentService.update_comment(
+        comment_id=comment_id,
+        data=data,
+        current_user=current_user,
+        db=db
+    )
+
+
+# ============================================
+# DELETE COMMENT
+# ============================================
+
+@router.delete(
+    "/comments/{comment_id}",
+    status_code=status.HTTP_200_OK,
+    summary="Delete comment",
+    description="""
+    Delete a comment (soft delete).
+    
+    **Authorization:** 
+    - Comment author can delete their own comments
+    - Project managers can delete any comment
+    - Platform admins can delete any comment
+    """
+)
+def delete_comment(
+    comment_id: UUID,
+    db: Session = Depends(get_db),
+    current_user: User = Depends(get_current_user)
+):
+    """Delete a comment (soft delete)"""
+    return TicketCommentService.delete_comment(
+        comment_id=comment_id,
+        current_user=current_user,
+        db=db
+    )
+
+
+# ============================================
+# GET SINGLE COMMENT
+# ============================================
+
+@router.get(
+    "/comments/{comment_id}",
+    response_model=TicketCommentResponse,
+    summary="Get comment by ID",
+    description="""
+    Get a single comment by ID.
+    
+    **Returns:**
+    - Comment details
+    - Author information
+    - Edit history
+    - Reply count
+    
+    **Authorization:** All authenticated users
+    """
+)
+def get_comment(
+    comment_id: UUID,
+    db: Session = Depends(get_db),
+    current_user: User = Depends(get_current_user)
+):
+    """Get a single comment"""
+    return TicketCommentService.get_comment(
+        comment_id=comment_id,
+        db=db
+    )
+
+
+# ============================================
+# LIST COMMENTS
+# ============================================
+
+@router.get(
+    "/tickets/{ticket_id}/comments",
+    response_model=TicketCommentListResponse,
+    summary="List ticket comments",
+    description="""
+    List all comments for a ticket with pagination and filtering.
+    
+    **Filtering:**
+    - is_internal: Show only internal or external comments
+    - comment_type: Filter by comment type (note, issue, resolution, etc.)
+    - parent_only: Show only top-level comments (exclude replies)
+    
+    **Pagination:**
+    - page: Page number (1-indexed)
+    - page_size: Items per page (default 50, max 100)
+    
+    **Sorting:**
+    - Comments sorted by created_at DESC (newest first)
+    
+    **Authorization:** All authenticated users
+    """
+)
+def list_comments(
+    ticket_id: UUID,
+    page: int = Query(1, ge=1, description="Page number"),
+    page_size: int = Query(50, ge=1, le=100, description="Items per page"),
+    is_internal: Optional[bool] = Query(None, description="Filter by internal/external"),
+    comment_type: Optional[str] = Query(None, description=f"Filter by type: {', '.join(COMMENT_TYPES)}"),
+    parent_only: bool = Query(False, description="Show only top-level comments"),
+    db: Session = Depends(get_db),
+    current_user: User = Depends(get_current_user)
+):
+    """List comments for a ticket"""
+    return TicketCommentService.list_comments(
+        ticket_id=ticket_id,
+        page=page,
+        page_size=page_size,
+        is_internal=is_internal,
+        comment_type=comment_type,
+        parent_only=parent_only,
+        db=db
+    )
+
+
+# ============================================
+# GET COMMENT REPLIES
+# ============================================
+
+@router.get(
+    "/comments/{comment_id}/replies",
+    response_model=List[TicketCommentResponse],
+    summary="Get comment replies",
+    description="""
+    Get all replies to a specific comment (threading).
+    
+    **Use Case:**
+    - Load replies when user expands a comment thread
+    - Show conversation history
+    
+    **Sorting:**
+    - Replies sorted by created_at ASC (oldest first)
+    
+    **Authorization:** All authenticated users
+    """
+)
+def get_comment_replies(
+    comment_id: UUID,
+    db: Session = Depends(get_db),
+    current_user: User = Depends(get_current_user)
+):
+    """Get all replies to a comment"""
+    return TicketCommentService.get_comment_replies(
+        comment_id=comment_id,
+        db=db
+    )

src/app/services/ticket_comment_service.py

@@ -0,0 +1,401 @@
+"""
+Ticket Comment Service - Team Collaboration on Tickets
+
+Handles:
+- Creating comments (with mentions and attachments)
+- Updating comments (with edit tracking)
+- Deleting comments (soft delete)
+- Threading (replies to comments)
+- Listing comments (with pagination and filtering)
+"""
+
+from sqlalchemy.orm import Session, joinedload
+from fastapi import HTTPException, status
+from typing import List, Optional, Dict, Any
+from uuid import UUID
+from datetime import datetime, timezone
+import logging
+
+from app.models.ticket_comment import TicketComment
+from app.models.ticket import Ticket
+from app.models.user import User
+from app.schemas.ticket_comment import (
+    TicketCommentCreate,
+    TicketCommentUpdate,
+    TicketCommentResponse,
+    TicketCommentListResponse
+)
+
+logger = logging.getLogger(__name__)
+
+
+class TicketCommentService:
+    """Service for managing ticket comments"""
+    
+    @staticmethod
+    def create_comment(
+        ticket_id: UUID,
+        data: TicketCommentCreate,
+        current_user: User,
+        db: Session
+    ) -> TicketCommentResponse:
+        """
+        Create a new comment on a ticket
+        
+        Args:
+            ticket_id: Ticket to comment on
+            data: Comment data
+            current_user: User creating comment
+            db: Database session
+            
+        Returns:
+            Created comment
+        """
+        # Verify ticket exists
+        ticket = db.query(Ticket).filter(
+            Ticket.id == ticket_id,
+            Ticket.deleted_at.is_(None)
+        ).first()
+        
+        if not ticket:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail="Ticket not found"
+            )
+        
+        # Verify parent comment exists if specified
+        if data.parent_comment_id:
+            parent_comment = db.query(TicketComment).filter(
+                TicketComment.id == data.parent_comment_id,
+                TicketComment.ticket_id == ticket_id,
+                TicketComment.deleted_at.is_(None)
+            ).first()
+            
+            if not parent_comment:
+                raise HTTPException(
+                    status_code=status.HTTP_404_NOT_FOUND,
+                    detail="Parent comment not found"
+                )
+        
+        # Verify mentioned users exist
+        if data.mentioned_user_ids:
+            mentioned_users = db.query(User).filter(
+                User.id.in_(data.mentioned_user_ids),
+                User.deleted_at.is_(None)
+            ).all()
+            
+            if len(mentioned_users) != len(data.mentioned_user_ids):
+                raise HTTPException(
+                    status_code=status.HTTP_400_BAD_REQUEST,
+                    detail="One or more mentioned users not found"
+                )
+        
+        # Create comment
+        comment = TicketComment(
+            ticket_id=ticket_id,
+            user_id=current_user.id,
+            comment_text=data.comment_text.strip(),
+            is_internal=data.is_internal,
+            comment_type=data.comment_type,
+            parent_comment_id=data.parent_comment_id,
+            mentioned_user_ids=data.mentioned_user_ids if data.mentioned_user_ids else None,
+            attachment_document_ids=data.attachment_document_ids if data.attachment_document_ids else None,
+            created_at=datetime.now(timezone.utc),
+            updated_at=datetime.now(timezone.utc)
+        )
+        
+        db.add(comment)
+        db.commit()
+        db.refresh(comment)
+        
+        logger.info(f"Comment {comment.id} created on ticket {ticket_id} by user {current_user.id}")
+        
+        # TODO: Send notifications to mentioned users
+        # TODO: Notify ticket assignees if external comment
+        
+        return TicketCommentService._to_response(comment, db)
+    
+    @staticmethod
+    def update_comment(
+        comment_id: UUID,
+        data: TicketCommentUpdate,
+        current_user: User,
+        db: Session
+    ) -> TicketCommentResponse:
+        """
+        Update a comment (only by original author)
+        
+        Args:
+            comment_id: Comment to update
+            data: Updated comment data
+            current_user: User updating comment
+            db: Database session
+            
+        Returns:
+            Updated comment
+        """
+        comment = db.query(TicketComment).filter(
+            TicketComment.id == comment_id,
+            TicketComment.deleted_at.is_(None)
+        ).first()
+        
+        if not comment:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail="Comment not found"
+            )
+        
+        # Only author can edit their own comment
+        if comment.user_id != current_user.id:
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail="You can only edit your own comments"
+            )
+        
+        # Update comment
+        comment.comment_text = data.comment_text.strip()
+        comment.is_edited = True
+        comment.edited_at = datetime.now(timezone.utc)
+        comment.edited_by_user_id = current_user.id
+        comment.updated_at = datetime.now(timezone.utc)
+        
+        db.commit()
+        db.refresh(comment)
+        
+        logger.info(f"Comment {comment_id} updated by user {current_user.id}")
+        
+        return TicketCommentService._to_response(comment, db)
+    
+    @staticmethod
+    def delete_comment(
+        comment_id: UUID,
+        current_user: User,
+        db: Session
+    ) -> Dict[str, Any]:
+        """
+        Delete a comment (soft delete, only by author or PM)
+        
+        Args:
+            comment_id: Comment to delete
+            current_user: User deleting comment
+            db: Database session
+            
+        Returns:
+            Success message
+        """
+        comment = db.query(TicketComment).filter(
+            TicketComment.id == comment_id,
+            TicketComment.deleted_at.is_(None)
+        ).first()
+        
+        if not comment:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail="Comment not found"
+            )
+        
+        # Only author or PM can delete
+        is_author = comment.user_id == current_user.id
+        is_pm = current_user.role in ['project_manager', 'platform_admin']
+        
+        if not (is_author or is_pm):
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail="You can only delete your own comments"
+            )
+        
+        # Soft delete
+        comment.deleted_at = datetime.now(timezone.utc)
+        db.commit()
+        
+        logger.info(f"Comment {comment_id} deleted by user {current_user.id}")
+        
+        return {
+            "success": True,
+            "message": "Comment deleted successfully",
+            "comment_id": str(comment_id)
+        }
+    
+    @staticmethod
+    def get_comment(
+        comment_id: UUID,
+        db: Session
+    ) -> TicketCommentResponse:
+        """
+        Get a single comment by ID
+        
+        Args:
+            comment_id: Comment ID
+            db: Database session
+            
+        Returns:
+            Comment details
+        """
+        comment = db.query(TicketComment).options(
+            joinedload(TicketComment.user),
+            joinedload(TicketComment.edited_by_user)
+        ).filter(
+            TicketComment.id == comment_id,
+            TicketComment.deleted_at.is_(None)
+        ).first()
+        
+        if not comment:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail="Comment not found"
+            )
+        
+        return TicketCommentService._to_response(comment, db)
+    
+    @staticmethod
+    def list_comments(
+        ticket_id: UUID,
+        page: int = 1,
+        page_size: int = 50,
+        is_internal: Optional[bool] = None,
+        comment_type: Optional[str] = None,
+        parent_only: bool = False,
+        db: Session = None
+    ) -> TicketCommentListResponse:
+        """
+        List comments for a ticket with pagination and filtering
+        
+        Args:
+            ticket_id: Ticket ID
+            page: Page number (1-indexed)
+            page_size: Items per page
+            is_internal: Filter by internal/external
+            comment_type: Filter by comment type
+            parent_only: Only show top-level comments (no replies)
+            db: Database session
+            
+        Returns:
+            Paginated list of comments
+        """
+        # Verify ticket exists
+        ticket = db.query(Ticket).filter(
+            Ticket.id == ticket_id,
+            Ticket.deleted_at.is_(None)
+        ).first()
+        
+        if not ticket:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail="Ticket not found"
+            )
+        
+        # Build query
+        query = db.query(TicketComment).options(
+            joinedload(TicketComment.user),
+            joinedload(TicketComment.edited_by_user)
+        ).filter(
+            TicketComment.ticket_id == ticket_id,
+            TicketComment.deleted_at.is_(None)
+        )
+        
+        # Apply filters
+        if is_internal is not None:
+            query = query.filter(TicketComment.is_internal == is_internal)
+        
+        if comment_type:
+            query = query.filter(TicketComment.comment_type == comment_type)
+        
+        if parent_only:
+            query = query.filter(TicketComment.parent_comment_id.is_(None))
+        
+        # Get total count
+        total = query.count()
+        
+        # Apply pagination
+        offset = (page - 1) * page_size
+        comments = query.order_by(
+            TicketComment.created_at.desc()
+        ).offset(offset).limit(page_size).all()
+        
+        # Convert to response
+        comment_responses = [
+            TicketCommentService._to_response(comment, db)
+            for comment in comments
+        ]
+        
+        pages = (total + page_size - 1) // page_size
+        
+        return TicketCommentListResponse(
+            comments=comment_responses,
+            total=total,
+            page=page,
+            page_size=page_size,
+            pages=pages
+        )
+    
+    @staticmethod
+    def get_comment_replies(
+        comment_id: UUID,
+        db: Session
+    ) -> List[TicketCommentResponse]:
+        """
+        Get all replies to a comment
+        
+        Args:
+            comment_id: Parent comment ID
+            db: Database session
+            
+        Returns:
+            List of reply comments
+        """
+        # Verify parent comment exists
+        parent = db.query(TicketComment).filter(
+            TicketComment.id == comment_id,
+            TicketComment.deleted_at.is_(None)
+        ).first()
+        
+        if not parent:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail="Comment not found"
+            )
+        
+        # Get replies
+        replies = db.query(TicketComment).options(
+            joinedload(TicketComment.user),
+            joinedload(TicketComment.edited_by_user)
+        ).filter(
+            TicketComment.parent_comment_id == comment_id,
+            TicketComment.deleted_at.is_(None)
+        ).order_by(TicketComment.created_at.asc()).all()
+        
+        return [
+            TicketCommentService._to_response(reply, db)
+            for reply in replies
+        ]
+    
+    @staticmethod
+    def _to_response(comment: TicketComment, db: Session) -> TicketCommentResponse:
+        """Convert comment model to response schema"""
+        
+        # Count replies
+        reply_count = db.query(TicketComment).filter(
+            TicketComment.parent_comment_id == comment.id,
+            TicketComment.deleted_at.is_(None)
+        ).count()
+        
+        return TicketCommentResponse(
+            id=comment.id,
+            ticket_id=comment.ticket_id,
+            user_id=comment.user_id,
+            user_name=comment.user.name if comment.user else None,
+            comment_text=comment.comment_text,
+            is_internal=comment.is_internal,
+            comment_type=comment.comment_type,
+            parent_comment_id=comment.parent_comment_id,
+            mentioned_user_ids=comment.mentioned_user_ids or [],
+            attachment_document_ids=comment.attachment_document_ids or [],
+            is_edited=comment.is_edited,
+            edited_at=comment.edited_at,
+            edited_by_user_id=comment.edited_by_user_id,
+            edited_by_user_name=comment.edited_by_user.name if comment.edited_by_user else None,
+            additional_metadata=comment.additional_metadata or {},
+            created_at=comment.created_at,
+            updated_at=comment.updated_at,
+            reply_count=reply_count
+        )