173 lines
5.3 KiB
Markdown
173 lines
5.3 KiB
Markdown
# Milestone 4: Collaboration Features
|
|
|
|
**Duration:** 2 weeks
|
|
**Goal:** Comments, notifications, email integration, and conflict resolution
|
|
|
|
## Tasks
|
|
|
|
### Week 7: Comments & Notifications
|
|
|
|
- [x] Comment system (backend complete, UI partial)
|
|
- [x] Comment creation endpoint (web)
|
|
- [x] Comment threading (parent/child) - schema supports it
|
|
- [x] Line/section anchoring (hash-based)
|
|
- [x] Comment resolution (mark as resolved)
|
|
- [ ] Comment display in the Go-served browser UI (JS exists but needs wiring)
|
|
|
|
- [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 (backend complete, JS partial)
|
|
- [x] Notification bell with unread count - API exists
|
|
- [x] Notification list dropdown - API exists
|
|
- [x] Mark as read functionality - API exists
|
|
- [ ] Notification preferences page
|
|
|
|
### Week 8: Email Integration & Conflict Resolution
|
|
|
|
- [ ] Postmark integration
|
|
- [x] SMTP sender stub (NoOp + SMTP implementations)
|
|
- [ ] Postmark adapter
|
|
- [ ] Plain-text email templates
|
|
- [ ] Outgoing email queue with retry
|
|
- [ ] Webhook endpoint for inbound email
|
|
|
|
- [ ] Email notification types
|
|
- [ ] File changed notification
|
|
- [ ] New comment notification
|
|
- [ ] Mention notification (@username)
|
|
- [ ] Conflict alert notification
|
|
- [ ] 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) (schema supports it)
|
|
- [x] Users can watch files or folders for changes (API exists)
|
|
- [ ] Email notifications sent within 1 minute of event (NoOp sender currently)
|
|
- [ ] Replying to notification email creates a comment
|
|
- [ ] Digest emails batch notifications by time window
|
|
- [x] Conflicts display side-by-side diff (M2 sync)
|
|
- [x] Users can resolve conflicts via web UI (M2 sync)
|
|
- [ ] Resolved comments are hidden but accessible in history
|
|
|
|
### Non-Functional
|
|
- [ ] Emails are plain-text only (no HTML)
|
|
- [ ] Email threading works in Gmail, Outlook, Apple Mail
|
|
- [ ] Webhook signature verified for inbound email
|
|
- [ ] Failed emails retried 3 times with exponential backoff
|
|
- [ ] Email queue doesn't block web requests (async processing)
|
|
|
|
### 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
|
|
- [ ] 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
|