172 lines
4.8 KiB
Markdown
172 lines
4.8 KiB
Markdown
# Milestone 4: Collaboration Features
|
|
|
|
**Duration:** 2 weeks
|
|
**Goal:** Comments, notifications, email integration, and conflict resolution
|
|
|
|
## Tasks
|
|
|
|
### Week 7: Comments & Notifications
|
|
|
|
- [ ] Comment system
|
|
- Comment creation endpoint (web)
|
|
- Comment threading (parent/child)
|
|
- Line/section anchoring (hash-based)
|
|
- Comment resolution (mark as resolved)
|
|
- Comment display in Preact UI
|
|
|
|
- [ ] Notification system
|
|
- Notification queue in database
|
|
- Per-file watcher subscriptions
|
|
- Per-folder watcher subscriptions
|
|
- Global notification settings
|
|
- Digest mode (hourly/daily batches)
|
|
|
|
- [ ] Web notification UI
|
|
- Notification bell with unread count
|
|
- Notification list dropdown
|
|
- Mark as read functionality
|
|
- Notification preferences page
|
|
|
|
### Week 8: Email Integration & Conflict Resolution
|
|
|
|
- [ ] Postmark integration
|
|
- Go adapter setup
|
|
- 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
|
|
|
|
- [ ] Conflict resolution UI
|
|
- Side-by-side diff view
|
|
- Accept local/server/merge options
|
|
- Manual merge editor
|
|
- Conflict notification email
|
|
|
|
## Acceptance Criteria
|
|
|
|
### Functional
|
|
- [ ] Users can add comments to specific lines in a document
|
|
- [ ] Comments are linked to document version (hash)
|
|
[ ] Comment threading works (reply to reply)
|
|
- [ ] Users can watch files or folders for changes
|
|
- [ ] Email notifications sent within 1 minute of event
|
|
- [ ] Replying to notification email creates a comment
|
|
- [ ] Digest emails batch notifications by time window
|
|
- [ ] Conflicts display side-by-side diff
|
|
- [ ] Users can resolve conflicts via web UI
|
|
- [ ] 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
|