# Milestone 4: Collaboration Features

**Duration:** 2 weeks  
**Goal:** Comments, notifications, email integration, and conflict resolution

## Tasks

### Week 7: Comments & Notifications

- [x] Comment system (backend + UI wired)
  - [x] Comment creation endpoint (web)
  - [x] Comment threading (parent/child) with nested browser replies
  - [x] Line/section anchoring (hash-based)
  - [x] Whole-thread resolution with resolved-history view
  - [x] Comment display in the Go-served browser UI (`c39c50b` dropdown menu + comment side panel, `comments.js` +330 lines)
   
- [x] Notification system (backend complete)
  - [x] Notification queue in database
  - [x] Per-file watcher subscriptions
  - [x] Per-folder watcher subscriptions
  - [ ] Global notification settings
  - [ ] Digest mode (hourly/daily batches)
   
- [x] Web notification UI
  - [x] Notification bell with unread count
  - [x] Notification list dropdown
  - [x] Mark one/all as read functionality
  - [ ] Notification preferences page

### Week 8: Email Integration & Conflict Resolution

- [x] Postmark integration
  - [x] SMTP sender stub (NoOp + SMTP implementations)
  - [x] Postmark adapter (`email/postmark.go`)
  - [x] Plain-text email templates (`email/templates.go`)
  - [x] Outgoing email queue with retry (`email/queue.go` + migration 000016)
  - [x] Cloudflare Email Service REST adapter (`email/cloudflare.go`)
  - [ ] Webhook endpoint for inbound email
    
- [x] Email notification types
  - [x] File changed notification
  - [x] New comment notification
  - [ ] Mention notification (@username) — template exists, mention detection not wired
  - [ ] Conflict alert notification — template exists, not triggered from sync flow
  - [ ] Digest summary email
   
- [ ] Email reply handling
  - [ ] Parse inbound email (from, subject, body)
  - [ ] Match to comment thread via In-Reply-To
  - [ ] Create comment from email body
  - [ ] Validate sender permission
   
- [x] Conflict resolution UI (M2 - exists in sync flow)
  - [x] Side-by-side diff view
  - [x] Accept local/server/merge options
  - [x] Manual merge editor
  - [ ] Conflict notification email

## Acceptance Criteria

### Functional
- [x] Users can add comments to specific lines in a document (API exists)
- [x] Comments are linked to document version (hash)
- [x] Comment threading works (reply to reply) in the browser and API
- [x] Users can watch files or folders for changes (document UI + APIs)
- [x] Email notifications queued within 1 minute of event (Postmark, Cloudflare, or SMTP sender)
- [ ] Replying to notification email creates a comment
- [ ] Digest emails batch notifications by time window
- [x] Conflicts display a unified diff (M2 sync)
- [x] Users can resolve conflicts via web UI (M2 sync)
- [x] Resolved comments are hidden but accessible in history

### Non-Functional
- [x] Emails are plain-text only (no HTML) — enforced by templates, verified by test
- [ ] Email threading works in Gmail, Outlook, Apple Mail
- [ ] Webhook signature verified for inbound email
- [x] Temporary email failures retried 3 times with exponential backoff; permanent provider rejections fail immediately
- [x] Email queue doesn't block web requests (async processing) — worker runs in goroutine

### Email Template Examples

**File Change Notification:**
```
Subject: [docs/api-reference.md] Updated by Alice

Alice updated "API Reference" at 2024-01-15 14:30 UTC.

Changed sections:
- Authentication
- Rate Limiting

View changes: https://example.com/docs/api-reference?v=abc123
Unsubscribe: https://example.com/unsubscribe/123
```

**Comment Notification:**
```
Subject: [docs/getting-started.md] Comment from Bob

Bob commented on "Getting Started":

> This step is unclear. Can we add an example?

Reply to this email to respond.

View online: https://example.com/docs/getting-started#comment-456
```

## Database Schema Additions

```sql
-- Comments
CREATE TABLE comments (
    id TEXT PRIMARY KEY,
    document_id TEXT NOT NULL REFERENCES documents(id),
    version_hash TEXT NOT NULL,
    parent_id TEXT REFERENCES comments(id),
    author_id TEXT NOT NULL REFERENCES users(id),
    content TEXT NOT NULL,
    anchor_line INTEGER, -- line number for anchoring
    anchor_hash TEXT, -- hash of specific content for anchoring
    created_at DATETIME NOT NULL,
    resolved_at DATETIME,
    resolved_by TEXT REFERENCES users(id)
);

-- Notifications
CREATE TABLE notifications (
    id TEXT PRIMARY KEY,
    user_id TEXT NOT NULL REFERENCES users(id),
    type TEXT NOT NULL, -- file_changed, comment, mention, conflict
    resource_type TEXT NOT NULL,
    resource_id TEXT NOT NULL,
    message TEXT NOT NULL,
    read_at DATETIME,
    emailed_at DATETIME,
    created_at DATETIME NOT NULL
);

-- Watcher subscriptions
CREATE TABLE watchers (
    user_id TEXT REFERENCES users(id),
    document_id TEXT REFERENCES documents(id),
    folder_path TEXT,
    created_at DATETIME NOT NULL,
    PRIMARY KEY (user_id, document_id, folder_path)
);
```

## Deliverables

1. Email template documentation
2. Webhook integration guide
3. Comment API documentation
4. Conflict resolution flow diagrams

## Risk Mitigation

| Risk | Mitigation |
|------|-----------|
| Email deliverability issues | Postmark reputation monitoring, SPF/DKIM setup |
| Comment spam | Rate limiting, auth required, moderation tools |
| Email parsing errors | Robust parser, fallback to plain text extraction |
| Conflict resolution UI confusion | Clear visual design, undo option, help text |

## Definition of Done

- [ ] All acceptance criteria pass
- [ ] Email flows tested with real Postmark account
- [x] Comment threading tested with 3+ levels
- [ ] Conflict resolution tested with 2+ concurrent editors
- [ ] Notification preferences persist across sessions
- [ ] Digest mode tested with 24-hour window
