docs(roadmap): add v1.2 Session Attachments milestone
Add comprehensive roadmap for file attachment feature: - Update PROJECT.md with v1.2 milestone and requirements - Create REQUIREMENTS.md with 24 requirements across 7 categories - Add Phases 12-16 to ROADMAP.md (5 phases, 10 plans) - Update STATE.md with milestone v1.2 status Phases: - Phase 12: Attachment Research & Backend Validation (2 plans) - Phase 13: File Upload Infrastructure (3 plans) - Phase 14: Chat Integration & Display (2 plans) - Phase 15: Real-time Synchronization (1 plan) - Phase 16: Attachment Finalization (2 plans) Coverage: 24/24 requirements mapped (100%) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
Nuwan
parent
961c0e36bb
commit
631253d3f7
|
|
@ -1,36 +1,45 @@
|
|||
# JamKazam Media Features Modernization
|
||||
|
||||
**One-liner:** Modernize media opening features (Backing Track, JamTrack, Metronome) from legacy jQuery/Rails to React patterns in jam-ui
|
||||
**One-liner:** Modernize media features (Backing Track, JamTrack, Session Chat, Session Attachments) from legacy jQuery/Rails to React patterns in jam-ui
|
||||
|
||||
## Vision
|
||||
|
||||
Transform the media opening workflow from the legacy web project into modern React patterns in jam-ui. The features exist in the legacy codebase with jQuery dialogs and polling-based playback monitoring - we're bringing them into the React architecture with proper component structure, hooks, and Redux integration where appropriate.
|
||||
Transform media features from the legacy web project into modern React patterns in jam-ui. The features exist in the legacy codebase with jQuery dialogs and polling-based playback monitoring - we're bringing them into the React architecture with proper component structure, hooks, and Redux integration where appropriate.
|
||||
|
||||
**Target Features:**
|
||||
1. **Backing Track** - File-based audio playback with player controls (FIRST PRIORITY)
|
||||
2. **JamTrack** - Collaborative track loading with mixdown selection
|
||||
3. **Metronome** - Tempo/sound configuration and playback
|
||||
**Completed Features (v1.0, v1.1):**
|
||||
1. ✅ **Backing Track** - File-based audio playback with player controls
|
||||
2. ✅ **JamTrack** - Collaborative track loading with mixdown selection
|
||||
3. ✅ **Session Chat** - Real-time chat with message history and read/unread tracking
|
||||
|
||||
All three features are accessible via the "Open" menu in the session screen top navigation.
|
||||
**Current Milestone (v1.2):**
|
||||
4. 🚧 **Session Attachments** - File upload/download integration with chat window
|
||||
|
||||
**Future Work:**
|
||||
- **Metronome** - Tempo/sound configuration and playback (deferred)
|
||||
|
||||
## Context
|
||||
|
||||
### Current State
|
||||
|
||||
**Backing Track (Partially Implemented):**
|
||||
- ✓ Native file dialog integration via `jamClient.ShowSelectBackingTrackDialog()`
|
||||
- ✓ File opening via `jamClient.SessionOpenBackingTrackFile()`
|
||||
- ✓ Track display in session with VU meter, gain, pan controls
|
||||
- ✓ Basic player modal with play/pause/stop buttons
|
||||
- ✓ Volume control working
|
||||
- ✓ Loop toggle implemented
|
||||
- ✗ **Seek bar** - Exists but is placeholder (hardcoded value="0")
|
||||
- ✗ **Duration display** - Hardcoded to "0:00"
|
||||
- ✗ **Current time display** - Hardcoded to "0:00"
|
||||
**v1.0 Media Players (SHIPPED 2026-01-14):**
|
||||
- ✅ Backing Track - Complete with playback monitoring, seek controls, error handling
|
||||
- ✅ JamTrack - Complete with mixdown selection, player controls, download UI
|
||||
|
||||
**JamTrack:** Not yet implemented in jam-ui
|
||||
**v1.1 Music Session Chat (SHIPPED 2026-01-27):**
|
||||
- ✅ Redux state management with WebSocket integration
|
||||
- ✅ Modeless chat window with message list and auto-scroll
|
||||
- ✅ Message composition and real-time delivery
|
||||
- ✅ Read/unread status tracking with badge indicators
|
||||
- ✅ Error handling, accessibility, and edge cases
|
||||
|
||||
**Metronome:** Not yet implemented in jam-ui
|
||||
**v1.2 Session Attachments (IN PROGRESS):**
|
||||
- ⏳ File attachment capability from session toolbar
|
||||
- ⏳ Integration with existing chat window
|
||||
- ⏳ Real-time attachment notifications via WebSocket
|
||||
- ⏳ File viewing in new browser tab
|
||||
|
||||
**Deferred:**
|
||||
- **Metronome** - Tempo/sound configuration and playback
|
||||
|
||||
### Architecture Context
|
||||
|
||||
|
|
@ -49,53 +58,74 @@ All three features are accessible via the "Open" menu in the session screen top
|
|||
|
||||
## Requirements
|
||||
|
||||
### Validated
|
||||
### Validated (from v1.0, v1.1)
|
||||
|
||||
- ✓ Native file dialog for track selection - existing pattern works well
|
||||
- ✓ jamClient API integration - proven in current partial implementation
|
||||
- ✓ Redux state management architecture - validated in Phase 5 migration
|
||||
- ✓ Native file dialog for track selection - works well for media files
|
||||
- ✓ jamClient API integration - proven in Backing Track/JamTrack
|
||||
- ✓ Redux state management architecture - validated in media and chat features
|
||||
- ✓ WebSocket real-time communication - proven in chat feature
|
||||
- ✓ Modeless dialog pattern - established in chat window
|
||||
- ✓ Backend API integration - REST endpoints for chat/media working well
|
||||
|
||||
### Active
|
||||
### Active (v1.2 Session Attachments)
|
||||
|
||||
**Backing Track (Priority 1):**
|
||||
- [ ] Implement real-time playback monitoring with 500ms polling
|
||||
- [ ] Display current playback position (MM:SS format)
|
||||
- [ ] Display total track duration (MM:SS format)
|
||||
- [ ] Implement functional seek bar with drag-to-position
|
||||
- [ ] Integrate monitoring lifecycle with play/pause/stop controls
|
||||
- [ ] Add error handling for edge cases (duration=0, position>duration)
|
||||
- [ ] Optimize performance (prevent unnecessary re-renders)
|
||||
**File Upload:**
|
||||
- [ ] Attach button in session toolbar opens OS file dialog
|
||||
- [ ] Support file types: .pdf, .xml, .mxl, .txt, .png, .jpg, .jpeg, .gif, .mp3, .wav
|
||||
- [ ] Enforce 10 MB file size limit with validation
|
||||
- [ ] Upload progress indicator displayed in chat window
|
||||
- [ ] Upload to S3 via existing MusicNotation API
|
||||
- [ ] Error handling for upload failures (network, size limit, file type)
|
||||
|
||||
**JamTrack (Priority 2):**
|
||||
- [ ] Research legacy implementation patterns
|
||||
- [ ] Design React component structure
|
||||
- [ ] Implement file opening workflow
|
||||
- [ ] Implement mixdown selection (full track vs. specific mixes)
|
||||
- [ ] Implement player controls similar to Backing Track
|
||||
**Chat Integration:**
|
||||
- [ ] Display attachment as message in chat: "John attached Song.pdf"
|
||||
- [ ] Show attachment icon/indicator in message
|
||||
- [ ] Include attachment metadata (filename, size, uploader, timestamp)
|
||||
- [ ] Clickable link to view/download file
|
||||
- [ ] Attachment messages sortable with regular chat messages
|
||||
|
||||
**Metronome (Priority 3):**
|
||||
- [ ] Research legacy implementation patterns
|
||||
- [ ] Design React component structure
|
||||
- [ ] Implement tempo/sound/cricket configuration UI
|
||||
- [ ] Implement start/stop controls
|
||||
- [ ] Integrate with metronome mixer state
|
||||
**Real-time Sync:**
|
||||
- [ ] WebSocket broadcast of new attachments to all session participants
|
||||
- [ ] New attachment appears immediately in all users' chat windows
|
||||
- [ ] Chat history includes attachments when joining session
|
||||
- [ ] Attachment messages persist across page refreshes
|
||||
|
||||
**File Viewing:**
|
||||
- [ ] Click attachment opens file in new browser tab
|
||||
- [ ] Browser handles view/download based on file type
|
||||
- [ ] Attachment URLs use existing S3 file_url from MusicNotation model
|
||||
|
||||
**Error Handling:**
|
||||
- [ ] Toast notification for file size exceeded
|
||||
- [ ] Toast notification for invalid file type
|
||||
- [ ] Toast notification for upload network errors
|
||||
- [ ] Clear feedback when upload succeeds
|
||||
- [ ] Graceful handling of missing/deleted files
|
||||
|
||||
### Out of Scope
|
||||
|
||||
- **React-based track list dialog** - Keep native file dialogs (established pattern)
|
||||
- **Audio processing logic** - All audio handled by native C++ client
|
||||
- **New media types** - Focus only on existing three features
|
||||
- **Refactoring unrelated code** - Minimize changes outside media features
|
||||
- **Backend changes** - Use existing MusicNotation model, S3 storage, and API endpoints
|
||||
- **File attachment from chat window** - Only from session toolbar attach button
|
||||
- **Comment/annotation on attachments** - Just display filename with uploader name
|
||||
- **File icons/thumbnails** - Display text-based attachment messages only
|
||||
- **Claimed recordings attachment** - Only computer files for now
|
||||
- **Music notation attachment** - Defer to future work
|
||||
- **File preview** - Browser handles view/download, no custom preview UI
|
||||
- **Attachment deletion** - Not in scope for v1.2
|
||||
- **Attachment editing/versioning** - Not in scope for v1.2
|
||||
|
||||
## Key Decisions
|
||||
|
||||
| Decision | Rationale | Outcome |
|
||||
|----------|-----------|---------|
|
||||
| Keep native file dialogs | Already working, platform-native UX, no need to rebuild | Confirmed |
|
||||
| Start with Backing Track | Most straightforward, establishes patterns for JamTrack/Metronome | In Progress |
|
||||
| Use local state for playback monitoring | High-frequency transient data doesn't need global Redux visibility | Pending |
|
||||
| 500ms polling interval | Matches legacy pattern, balances responsiveness vs. performance | Pending |
|
||||
| Milliseconds for seek values | Direct mapping to jamClient API, no conversion overhead | Pending |
|
||||
| Keep native file dialogs | Already working, platform-native UX, no need to rebuild | Validated (v1.0) |
|
||||
| Use Redux for chat state | Global visibility needed for badge, history, WebSocket sync | Validated (v1.1) |
|
||||
| Reuse existing backend | MusicNotation model already has S3, API, attachment_type | Confirmed (v1.2) |
|
||||
| Only toolbar upload | Simplifies UX, avoids dual upload paths, matches common patterns | Confirmed (v1.2) |
|
||||
| 10 MB file size limit | Matches legacy app limit, reasonable for notation/audio files | Confirmed (v1.2) |
|
||||
| Browser handles view/download | No custom preview UI, leverages native browser capabilities | Confirmed (v1.2) |
|
||||
| Display in chat window | Natural integration, attachments are part of session communication | Confirmed (v1.2) |
|
||||
| File types from legacy | .pdf, .xml, .mxl, .txt (notation), .png/.jpg/.jpeg/.gif (images), .mp3/.wav (audio) | Confirmed (v1.2) |
|
||||
|
||||
## Constraints
|
||||
|
||||
|
|
@ -112,21 +142,24 @@ All three features are accessible via the "Open" menu in the session screen top
|
|||
|
||||
## Critical Files
|
||||
|
||||
**Backing Track Implementation:**
|
||||
- `/Users/nuwan/Code/jam-cloud/jam-ui/src/components/client/JKSessionBackingTrackPlayer.js` - Main work (lines 1-100 reviewed)
|
||||
- `/Users/nuwan/Code/jam-cloud/jam-ui/src/components/client/JKSessionOpenMenu.js` - Entry point
|
||||
- `/Users/nuwan/Code/jam-cloud/jam-ui/src/components/client/JKSessionBackingTrack.js` - Track display
|
||||
**v1.2 Session Attachments (Current Focus):**
|
||||
- `jam-ui/src/components/client/JKSessionScreen.js` - Session toolbar, attach button entry point
|
||||
- `jam-ui/src/components/client/chat/JKChatWindow.js` - Chat window for attachment display
|
||||
- `jam-ui/src/components/client/chat/JKChatMessageList.js` - Message list to render attachments
|
||||
- `jam-ui/src/store/features/sessionChatSlice.js` - Redux state for chat/attachments
|
||||
- `jam-ui/src/helpers/rest.js` - API calls to backend
|
||||
|
||||
**Backend (Existing Infrastructure):**
|
||||
- `ruby/lib/jam_ruby/models/music_notation.rb` - MusicNotation model with S3 upload
|
||||
- `web/app/controllers/api/music_notations_controller.rb` - REST API for attachments
|
||||
- `web/db/migrations/*_create_music_notations.rb` - Database schema
|
||||
|
||||
**Legacy Reference:**
|
||||
- `/Users/nuwan/Code/jam-cloud/web/app/assets/javascripts/dialog/openBackingTrackDialog.js` - Pattern reference
|
||||
- `/Users/nuwan/Code/jam-cloud/web/app/assets/javascripts/playbackControls.js` - Polling/formatting reference
|
||||
- `web/app/assets/javascripts/react-components/stores/AttachmentStore.js.coffee` - Legacy upload pattern
|
||||
- `web/app/views/clients/_sessionSettings.html.haml` - File type restrictions
|
||||
|
||||
**Redux State:**
|
||||
- `/Users/nuwan/Code/jam-cloud/jam-ui/src/store/features/activeSessionSlice.js` - backingTrackData
|
||||
- `/Users/nuwan/Code/jam-cloud/jam-ui/src/store/features/mediaSlice.js` - openBackingTrack thunk
|
||||
|
||||
**Native Bridge:**
|
||||
- `/Users/nuwan/Code/jam-cloud/jam-ui/src/services/jamClientProxy.js` - API reference
|
||||
**WebSocket:**
|
||||
- `websocket-gateway/` - Real-time attachment broadcast (existing infrastructure)
|
||||
|
||||
---
|
||||
*Last updated: 2026-01-13 after initialization*
|
||||
*Last updated: 2026-02-02 for v1.2 Session Attachments milestone*
|
||||
|
|
|
|||
|
|
@ -0,0 +1,505 @@
|
|||
# Requirements: v1.2 Session Attachments
|
||||
|
||||
**Milestone Goal:** Add file attachment capability to music sessions, allowing users to upload files from their computer and view them in the chat window with real-time synchronization across all session participants.
|
||||
|
||||
**Last Updated:** 2026-02-02
|
||||
|
||||
---
|
||||
|
||||
## 1. File Upload & Validation
|
||||
|
||||
### REQ-1.1: Attach Button in Session Toolbar
|
||||
**Priority:** P0 (Critical)
|
||||
**Description:** Add "Attach" button to session toolbar (top navigation) that opens native OS file dialog when clicked.
|
||||
**Acceptance Criteria:**
|
||||
- Button appears in session toolbar alongside existing controls
|
||||
- Clicking button triggers native OS file picker dialog
|
||||
- Only visible when user is in an active session
|
||||
- Button state indicates if upload is in progress
|
||||
|
||||
**Implementation Notes:**
|
||||
- Similar pattern to Backing Track "Open" button
|
||||
- May use native file dialog or HTML5 file input styled as button
|
||||
- Consider icon + text label for clarity
|
||||
|
||||
---
|
||||
|
||||
### REQ-1.2: File Type Validation
|
||||
**Priority:** P0 (Critical)
|
||||
**Description:** Restrict file uploads to approved file types only.
|
||||
**Acceptance Criteria:**
|
||||
- **Notation files:** .pdf, .xml, .mxl, .txt
|
||||
- **Image files:** .png, .jpg, .jpeg, .gif
|
||||
- **Audio files:** .mp3, .wav
|
||||
- File dialog shows only these extensions (when possible)
|
||||
- Server-side validation rejects disallowed file types
|
||||
- Clear error message if user selects invalid type
|
||||
|
||||
**Implementation Notes:**
|
||||
- File type list matches legacy app: `web/app/views/clients/_sessionSettings.html.haml`
|
||||
- Use `accept` attribute on file input: `accept=".pdf,.xml,.mxl,.txt,.png,.jpg,.jpeg,.gif,.mp3,.wav"`
|
||||
- Backend validates via file extension and/or MIME type
|
||||
|
||||
---
|
||||
|
||||
### REQ-1.3: File Size Limit
|
||||
**Priority:** P0 (Critical)
|
||||
**Description:** Enforce 10 MB maximum file size for uploads.
|
||||
**Acceptance Criteria:**
|
||||
- Files larger than 10 MB (10 * 1024 * 1024 bytes) are rejected
|
||||
- Client-side validation shows immediate error before upload starts
|
||||
- Server-side validation enforces limit as fallback
|
||||
- Error message clearly states: "File size exceeds 10 MB limit"
|
||||
|
||||
**Implementation Notes:**
|
||||
- Limit matches legacy app: `web/app/assets/javascripts/react-components/stores/AttachmentStore.js.coffee`
|
||||
- Check `file.size` property before initiating upload
|
||||
- Backend MusicNotation model already validates size
|
||||
|
||||
---
|
||||
|
||||
### REQ-1.4: Upload Progress Indicator
|
||||
**Priority:** P1 (High)
|
||||
**Description:** Display upload progress in chat window while file is uploading.
|
||||
**Acceptance Criteria:**
|
||||
- Progress indicator appears in chat window immediately when upload starts
|
||||
- Shows percentage complete or indeterminate spinner
|
||||
- Indicator updates in real-time as upload progresses
|
||||
- Indicator disappears when upload completes or fails
|
||||
- User can continue using app while upload is in progress
|
||||
|
||||
**Implementation Notes:**
|
||||
- Use XMLHttpRequest or fetch with progress events
|
||||
- Display progress as temporary message in chat or as overlay
|
||||
- Consider showing filename being uploaded
|
||||
|
||||
---
|
||||
|
||||
## 2. Chat Integration & Display
|
||||
|
||||
### REQ-2.1: Attachment Message Format
|
||||
**Priority:** P0 (Critical)
|
||||
**Description:** Display file attachments as messages in chat window with consistent format.
|
||||
**Acceptance Criteria:**
|
||||
- Message format: `"[UserName] attached [FileName]"`
|
||||
- Example: `"John attached Song.pdf"`
|
||||
- Attachment messages appear in chronological order with regular chat messages
|
||||
- Display upload timestamp like regular messages
|
||||
- Visually distinguish attachments from text messages (icon, styling)
|
||||
|
||||
**Implementation Notes:**
|
||||
- Store attachment info in same messages array as chat messages
|
||||
- Message type field indicates attachment vs. text
|
||||
- Reuse existing chat message component with conditional rendering for attachments
|
||||
|
||||
---
|
||||
|
||||
### REQ-2.2: Attachment Metadata Display
|
||||
**Priority:** P1 (High)
|
||||
**Description:** Show relevant metadata about attached files.
|
||||
**Acceptance Criteria:**
|
||||
- Display filename (full name with extension)
|
||||
- Display file size in human-readable format (KB/MB)
|
||||
- Display uploader name
|
||||
- Display upload timestamp
|
||||
- No comment/annotation field needed
|
||||
|
||||
**Implementation Notes:**
|
||||
- Format file size: `formatFileSize(bytes)` utility function
|
||||
- Metadata comes from MusicNotation model: `file_name`, `size`, `user`, `created_at`
|
||||
|
||||
---
|
||||
|
||||
### REQ-2.3: Attachment Icon/Indicator
|
||||
**Priority:** P2 (Medium)
|
||||
**Description:** Visual indicator that distinguishes attachment messages from text messages.
|
||||
**Acceptance Criteria:**
|
||||
- Attachment messages have distinct visual treatment
|
||||
- Could be paperclip icon, document icon, or styled differently
|
||||
- Icon type optional for v1.2 (text-only acceptable)
|
||||
|
||||
**Implementation Notes:**
|
||||
- Defer custom file-type icons to future work
|
||||
- Simple paperclip or attachment icon sufficient
|
||||
- Use existing icon library in jam-ui
|
||||
|
||||
---
|
||||
|
||||
### REQ-2.4: Clickable Attachment Links
|
||||
**Priority:** P0 (Critical)
|
||||
**Description:** Users can click attachment to view/download file.
|
||||
**Acceptance Criteria:**
|
||||
- Filename is clickable link or button
|
||||
- Click opens file in new browser tab
|
||||
- Browser handles view vs. download based on file type
|
||||
- Link uses attachment `file_url` from MusicNotation model
|
||||
- Works for all supported file types
|
||||
|
||||
**Implementation Notes:**
|
||||
- Use `<a href={fileUrl} target="_blank" rel="noopener noreferrer">`
|
||||
- `fileUrl` is S3 URL from `MusicNotation.file_url`
|
||||
- Browser auto-displays .pdf, .png, .jpg; auto-downloads .xml, .mxl, .mp3, .wav
|
||||
|
||||
---
|
||||
|
||||
### REQ-2.5: Chat History Includes Attachments
|
||||
**Priority:** P0 (Critical)
|
||||
**Description:** Attachment messages persist in chat history across page refreshes and when joining session.
|
||||
**Acceptance Criteria:**
|
||||
- Attachments stored in database like regular messages
|
||||
- Chat history API returns attachments along with text messages
|
||||
- User joining session sees all previous attachments
|
||||
- Attachments visible after page refresh
|
||||
- Attachment order preserved chronologically
|
||||
|
||||
**Implementation Notes:**
|
||||
- Backend stores attachments linked to music_session_id
|
||||
- Chat history API includes attachments in response
|
||||
- Frontend merges attachments with chat messages by timestamp
|
||||
|
||||
---
|
||||
|
||||
## 3. Real-time Communication
|
||||
|
||||
### REQ-3.1: WebSocket Attachment Broadcast
|
||||
**Priority:** P0 (Critical)
|
||||
**Description:** New attachments broadcast to all session participants in real-time via WebSocket.
|
||||
**Acceptance Criteria:**
|
||||
- When user uploads file, WebSocket message sent to all participants
|
||||
- Attachment appears in all users' chat windows immediately
|
||||
- No manual refresh needed
|
||||
- Works for 2+ users in same session
|
||||
|
||||
**Implementation Notes:**
|
||||
- Use existing WebSocket gateway infrastructure
|
||||
- Define new message type: `ATTACHMENT_ADDED` or reuse `CHAT_MESSAGE` with attachment flag
|
||||
- Payload includes: `music_session_id`, `file_name`, `file_url`, `user_name`, `size`, `timestamp`
|
||||
- Similar pattern to existing `CHAT_MESSAGE` handler in `JKSessionScreen.js`
|
||||
|
||||
---
|
||||
|
||||
### REQ-3.2: Attachment Deduplication
|
||||
**Priority:** P1 (High)
|
||||
**Description:** Prevent duplicate attachment messages when receiving via WebSocket.
|
||||
**Acceptance Criteria:**
|
||||
- Optimistic update when uploader sends file
|
||||
- WebSocket broadcast received by all users including uploader
|
||||
- Uploader doesn't see duplicate message
|
||||
- Each attachment appears exactly once in chat
|
||||
|
||||
**Implementation Notes:**
|
||||
- Assign temporary `optimisticId` to local upload
|
||||
- When WebSocket message received, match against optimistic ID
|
||||
- Replace optimistic message with server message
|
||||
- Reuse deduplication logic from chat messages in `sessionChatSlice.js`
|
||||
|
||||
---
|
||||
|
||||
## 4. File Viewing & Download
|
||||
|
||||
### REQ-4.1: Open in New Browser Tab
|
||||
**Priority:** P0 (Critical)
|
||||
**Description:** Clicking attachment opens file in new browser tab for viewing/downloading.
|
||||
**Acceptance Criteria:**
|
||||
- Click opens in new tab (not same tab, not download dialog)
|
||||
- Uses `target="_blank"` to preserve session page
|
||||
- Security: Uses `rel="noopener noreferrer"`
|
||||
- Works for all supported file types
|
||||
|
||||
**Implementation Notes:**
|
||||
- Simple `<a>` tag with correct attributes
|
||||
- S3 URLs are public or signed (check existing MusicNotation implementation)
|
||||
|
||||
---
|
||||
|
||||
### REQ-4.2: Browser-Native Handling
|
||||
**Priority:** P0 (Critical)
|
||||
**Description:** Leverage browser's built-in view/download capabilities for different file types.
|
||||
**Acceptance Criteria:**
|
||||
- PDFs: Open in browser's PDF viewer
|
||||
- Images (.png, .jpg, .jpeg, .gif): Display inline in browser
|
||||
- Audio (.mp3, .wav): Browser audio player
|
||||
- XML/MXL/TXT: Browser may display as text or prompt download
|
||||
- No custom preview/player UI needed in jam-ui
|
||||
|
||||
**Implementation Notes:**
|
||||
- Browser handles Content-Type headers from S3
|
||||
- Ensure S3 serves correct MIME types for each file extension
|
||||
- Check if S3 URLs need `Content-Disposition` header
|
||||
|
||||
---
|
||||
|
||||
## 5. Error Handling & User Feedback
|
||||
|
||||
### REQ-5.1: File Size Exceeded Error
|
||||
**Priority:** P0 (Critical)
|
||||
**Description:** Show clear error when user selects file larger than 10 MB.
|
||||
**Acceptance Criteria:**
|
||||
- Error appears immediately after file selection (before upload)
|
||||
- Toast notification with message: "File size exceeds 10 MB limit"
|
||||
- Upload does not start
|
||||
- User can select different file
|
||||
|
||||
**Implementation Notes:**
|
||||
- Check `file.size` in file input `onChange` handler
|
||||
- Use existing toast system (likely `react-toastify` or similar)
|
||||
- Don't call backend API if client-side validation fails
|
||||
|
||||
---
|
||||
|
||||
### REQ-5.2: Invalid File Type Error
|
||||
**Priority:** P0 (Critical)
|
||||
**Description:** Show clear error when user selects unsupported file type.
|
||||
**Acceptance Criteria:**
|
||||
- Error appears immediately after file selection (before upload)
|
||||
- Toast notification with message: "File type not supported. Allowed: .pdf, .xml, .mxl, .txt, .png, .jpg, .jpeg, .gif, .mp3, .wav"
|
||||
- Upload does not start
|
||||
- User can select different file
|
||||
|
||||
**Implementation Notes:**
|
||||
- Check file extension against whitelist
|
||||
- Use `file.name.toLowerCase().endsWith('.ext')` or regex
|
||||
- Backend validates as fallback
|
||||
|
||||
---
|
||||
|
||||
### REQ-5.3: Upload Network Error
|
||||
**Priority:** P0 (Critical)
|
||||
**Description:** Handle network failures during file upload.
|
||||
**Acceptance Criteria:**
|
||||
- If upload fails due to network error, show toast: "Upload failed. Please try again."
|
||||
- Progress indicator disappears
|
||||
- Optimistic message removed from chat (if shown)
|
||||
- User can retry upload
|
||||
- No partial/corrupted data in chat
|
||||
|
||||
**Implementation Notes:**
|
||||
- Catch fetch/XHR errors
|
||||
- Remove optimistic update on error
|
||||
- Consider retry button in error toast
|
||||
|
||||
---
|
||||
|
||||
### REQ-5.4: Upload Success Feedback
|
||||
**Priority:** P1 (High)
|
||||
**Description:** Confirm successful upload to user.
|
||||
**Acceptance Criteria:**
|
||||
- Success toast: "File uploaded successfully"
|
||||
- Attachment appears in chat window
|
||||
- Progress indicator disappears
|
||||
- Toast auto-dismisses after 3-5 seconds
|
||||
|
||||
**Implementation Notes:**
|
||||
- Show success toast briefly, then auto-dismiss
|
||||
- Attachment message in chat is primary confirmation
|
||||
|
||||
---
|
||||
|
||||
### REQ-5.5: Missing/Deleted File Handling
|
||||
**Priority:** P2 (Medium)
|
||||
**Description:** Gracefully handle case where attachment file no longer exists on S3.
|
||||
**Acceptance Criteria:**
|
||||
- If file deleted from S3, clicking link shows browser error (404)
|
||||
- No app crash or unhandled error
|
||||
- Consider showing toast: "File no longer available"
|
||||
|
||||
**Implementation Notes:**
|
||||
- S3 returns 404 if file missing
|
||||
- Browser handles error page
|
||||
- Could add error handler to detect 404 and show toast (future enhancement)
|
||||
|
||||
---
|
||||
|
||||
## 6. Backend Integration
|
||||
|
||||
### REQ-6.1: Use Existing MusicNotation API
|
||||
**Priority:** P0 (Critical)
|
||||
**Description:** Use existing backend infrastructure for file uploads.
|
||||
**Acceptance Criteria:**
|
||||
- POST to existing API endpoint for creating music notations
|
||||
- Use existing MusicNotation model with S3 upload
|
||||
- No backend code changes required (verify in phase planning)
|
||||
- API returns attachment metadata after upload
|
||||
|
||||
**Implementation Notes:**
|
||||
- Backend endpoint: `POST /api/music_sessions/:id/music_notations` (verify exact route)
|
||||
- Payload: `file` (multipart form data), `attachment_type` (notation or audio)
|
||||
- Response: `{ id, file_name, file_url, size, attachment_type, user_id, created_at }`
|
||||
- Check `ruby/lib/jam_ruby/models/music_notation.rb` for model interface
|
||||
|
||||
---
|
||||
|
||||
### REQ-6.2: Attachment Type Classification
|
||||
**Priority:** P1 (High)
|
||||
**Description:** Set correct `attachment_type` field when creating MusicNotation record.
|
||||
**Acceptance Criteria:**
|
||||
- Notation files (.pdf, .xml, .mxl, .txt): `attachment_type = 'notation'`
|
||||
- Audio files (.mp3, .wav): `attachment_type = 'audio'`
|
||||
- Images (.png, .jpg, .jpeg, .gif): `attachment_type = 'notation'` (or new type if needed)
|
||||
|
||||
**Implementation Notes:**
|
||||
- MusicNotation model has `TYPE_NOTATION = 'notation'` and `TYPE_AUDIO = 'audio'`
|
||||
- Client determines type based on file extension
|
||||
- Send `attachment_type` in POST payload
|
||||
|
||||
---
|
||||
|
||||
### REQ-6.3: Session Association
|
||||
**Priority:** P0 (Critical)
|
||||
**Description:** Associate attachment with correct music session.
|
||||
**Acceptance Criteria:**
|
||||
- Each attachment linked to `music_session_id`
|
||||
- Only session participants can see attachments for that session
|
||||
- Attachments do not appear in other sessions
|
||||
|
||||
**Implementation Notes:**
|
||||
- Include `music_session_id` in API request
|
||||
- Backend validates user is participant in session
|
||||
- Query attachments by session: `MusicNotation.where(music_session_id: session_id)`
|
||||
|
||||
---
|
||||
|
||||
## 7. Performance & UX
|
||||
|
||||
### REQ-7.1: Non-blocking Upload
|
||||
**Priority:** P1 (High)
|
||||
**Description:** File upload happens in background without blocking UI.
|
||||
**Acceptance Criteria:**
|
||||
- User can continue chatting while file uploads
|
||||
- User can browse other UI elements during upload
|
||||
- Upload progress visible but not intrusive
|
||||
- Multiple uploads can be queued (nice-to-have)
|
||||
|
||||
**Implementation Notes:**
|
||||
- Use async fetch with progress events
|
||||
- Don't disable UI during upload
|
||||
- Consider upload queue for multiple files (future enhancement)
|
||||
|
||||
---
|
||||
|
||||
### REQ-7.2: Chat Auto-scroll with Attachments
|
||||
**Priority:** P1 (High)
|
||||
**Description:** Chat window auto-scrolls when new attachment appears.
|
||||
**Acceptance Criteria:**
|
||||
- When attachment uploaded, chat scrolls to show new attachment message
|
||||
- Reuses existing auto-scroll logic from chat messages
|
||||
- Scroll behavior same as regular chat messages
|
||||
|
||||
**Implementation Notes:**
|
||||
- Attachment messages are treated like regular messages
|
||||
- Existing auto-scroll logic in `JKChatMessageList.js` should handle this
|
||||
- No special case needed if attachments are in same message array
|
||||
|
||||
---
|
||||
|
||||
### REQ-7.3: Responsive Layout
|
||||
**Priority:** P2 (Medium)
|
||||
**Description:** Attachment messages display correctly at different window sizes.
|
||||
**Acceptance Criteria:**
|
||||
- Filename truncates if too long (show ellipsis)
|
||||
- Layout doesn't break with long filenames
|
||||
- Works on typical desktop window sizes (1280x720+)
|
||||
|
||||
**Implementation Notes:**
|
||||
- CSS `text-overflow: ellipsis` for long filenames
|
||||
- Consider showing full filename in tooltip on hover
|
||||
- Test with very long filenames (255 chars)
|
||||
|
||||
---
|
||||
|
||||
## Out of Scope (v1.2)
|
||||
|
||||
The following are explicitly **NOT** requirements for v1.2:
|
||||
|
||||
- ❌ Attachment from within chat window (only toolbar)
|
||||
- ❌ Comments/annotations on attachments
|
||||
- ❌ File icons/thumbnails (text-only display acceptable)
|
||||
- ❌ Custom file preview UI
|
||||
- ❌ Attachment deletion
|
||||
- ❌ Attachment editing/versioning
|
||||
- ❌ Drag-and-drop file upload
|
||||
- ❌ Multiple file selection
|
||||
- ❌ Claimed recordings attachment (only computer files)
|
||||
- ❌ Music notation-specific rendering
|
||||
- ❌ Backend API changes (use existing MusicNotation endpoints)
|
||||
|
||||
---
|
||||
|
||||
## Success Criteria
|
||||
|
||||
**Milestone v1.2 is complete when:**
|
||||
|
||||
1. ✅ User can click Attach button in session toolbar
|
||||
2. ✅ User can select file from OS dialog (approved types only)
|
||||
3. ✅ File uploads to S3 via existing backend API
|
||||
4. ✅ Attachment appears in chat window as "[Name] attached [File]"
|
||||
5. ✅ All session participants see attachment in real-time via WebSocket
|
||||
6. ✅ User can click attachment to view/download in new tab
|
||||
7. ✅ Chat history shows attachments after page refresh
|
||||
8. ✅ File size and type validation work correctly
|
||||
9. ✅ Upload progress indicator displays during upload
|
||||
10. ✅ Error handling covers all failure cases (size, type, network)
|
||||
11. ✅ No backend code changes required
|
||||
12. ✅ Comprehensive UAT confirms all requirements met
|
||||
|
||||
---
|
||||
|
||||
## Technical Constraints
|
||||
|
||||
- **No backend changes:** Use existing MusicNotation model, S3 storage, and API endpoints
|
||||
- **File size limit:** 10 MB (matches legacy app)
|
||||
- **File types:** .pdf, .xml, .mxl, .txt, .png, .jpg, .jpeg, .gif, .mp3, .wav
|
||||
- **React version:** 16.13.1 (cannot use React 18 features)
|
||||
- **Redux Toolkit:** 1.6.1 (existing chat state management patterns)
|
||||
- **WebSocket:** Use existing gateway and Protocol Buffer infrastructure
|
||||
- **Browser compatibility:** Modern evergreen browsers (Chrome, Firefox, Safari, Edge)
|
||||
|
||||
---
|
||||
|
||||
## Dependencies
|
||||
|
||||
- ✅ Chat window (v1.1) - Exists, will display attachments
|
||||
- ✅ WebSocket integration (v1.1) - Exists, will broadcast attachments
|
||||
- ✅ Redux state management (v1.1) - Exists, will manage attachment state
|
||||
- ✅ MusicNotation backend (legacy) - Exists, no changes needed
|
||||
- ✅ S3 storage (legacy) - Exists, configured for file uploads
|
||||
- ✅ Toast notification system - Exists in jam-ui for error messages
|
||||
|
||||
---
|
||||
|
||||
## Traceability
|
||||
|
||||
| Requirement | Phase | Status |
|
||||
|-------------|-------|--------|
|
||||
| REQ-1.1 | Phase 13 | Pending |
|
||||
| REQ-1.2 | Phase 13 | Pending |
|
||||
| REQ-1.3 | Phase 13 | Pending |
|
||||
| REQ-1.4 | Phase 13 | Pending |
|
||||
| REQ-2.1 | Phase 14 | Pending |
|
||||
| REQ-2.2 | Phase 14 | Pending |
|
||||
| REQ-2.3 | Phase 14 | Pending |
|
||||
| REQ-2.4 | Phase 14 | Pending |
|
||||
| REQ-2.5 | Phase 14 | Pending |
|
||||
| REQ-3.1 | Phase 15 | Pending |
|
||||
| REQ-3.2 | Phase 15 | Pending |
|
||||
| REQ-4.1 | Phase 14 | Pending |
|
||||
| REQ-4.2 | Phase 14 | Pending |
|
||||
| REQ-5.1 | Phase 16 | Pending |
|
||||
| REQ-5.2 | Phase 16 | Pending |
|
||||
| REQ-5.3 | Phase 16 | Pending |
|
||||
| REQ-5.4 | Phase 16 | Pending |
|
||||
| REQ-5.5 | Phase 16 | Pending |
|
||||
| REQ-6.1 | Phase 13 | Pending |
|
||||
| REQ-6.2 | Phase 13 | Pending |
|
||||
| REQ-6.3 | Phase 13 | Pending |
|
||||
| REQ-7.1 | Phase 13 | Pending |
|
||||
| REQ-7.2 | Phase 14 | Pending |
|
||||
| REQ-7.3 | Phase 14 | Pending |
|
||||
|
||||
**Coverage:** 24/24 requirements mapped (100%)
|
||||
|
||||
**Note:** Phase 12 is a research phase with no direct requirement mapping.
|
||||
|
||||
---
|
||||
|
||||
*END OF REQUIREMENTS v1.2*
|
||||
|
|
@ -2,7 +2,7 @@
|
|||
|
||||
## Overview
|
||||
|
||||
Transform the media opening workflow (Backing Track, JamTrack, Session Chat) from legacy jQuery/CoffeeScript/Rails patterns into modern React patterns in jam-ui. Starting with completing the partially-implemented Backing Track player, we'll establish patterns that carry forward to JamTrack and Session Chat implementations. Each feature involves research phases to understand legacy CoffeeScript patterns, followed by React implementation phases.
|
||||
Transform the media opening workflow (Backing Track, JamTrack, Session Chat, Session Attachments) from legacy jQuery/CoffeeScript/Rails patterns into modern React patterns in jam-ui. Starting with completing the partially-implemented Backing Track player, we'll establish patterns that carry forward to JamTrack, Session Chat, and Session Attachments implementations. Each feature involves research phases to understand legacy CoffeeScript patterns, followed by React implementation phases.
|
||||
|
||||
## Domain Expertise
|
||||
|
||||
|
|
@ -11,7 +11,8 @@ None
|
|||
## Milestones
|
||||
|
||||
- ✅ **v1.0 Media Players** - Phases 1-5 (shipped 2026-01-14)
|
||||
- 🚧 **v1.1 Music Session Chat** - Phases 6-11 (in progress)
|
||||
- ✅ **v1.1 Music Session Chat** - Phases 6-11 (shipped 2026-01-31)
|
||||
- 🚧 **v1.2 Session Attachments** - Phases 12-16 (in progress)
|
||||
|
||||
## Phases
|
||||
|
||||
|
|
@ -34,16 +35,31 @@ Decimal phases appear between their surrounding integers in numeric order.
|
|||
|
||||
</details>
|
||||
|
||||
### 🚧 v1.1 Music Session Chat (Phases 6-11) - IN PROGRESS
|
||||
### ✅ v1.1 Music Session Chat (Phases 6-11) - SHIPPED 2026-01-31
|
||||
|
||||
<details>
|
||||
<summary>Show completed phases</summary>
|
||||
|
||||
**Milestone Goal:** Add real-time chat functionality to music sessions with modeless window, message history, read/unread tracking, and file attachment display.
|
||||
|
||||
- [x] **Phase 6: Session Chat Research & Design** - Explore legacy chat implementation, design React patterns
|
||||
- [x] **Phase 7: Chat Infrastructure & State Management** - Redux state, WebSocket handlers, API integration
|
||||
- [x] **Phase 8: Chat Window UI & Message Display** - Modeless dialog, message list with user info
|
||||
- [x] **Phase 9: Message Composition & Sending** - Text input, send functionality, real-time delivery (2/2 plans complete)
|
||||
- [x] **Phase 10: Read/Unread Status Management** - Unread tracking, indicator badge, mark-as-read logic (1/1 plans complete)
|
||||
- [ ] **Phase 11: Chat Finalization** - Error handling, edge cases, performance optimization, UAT (1/2 plans complete)
|
||||
- [x] **Phase 9: Message Composition & Sending** - Text input, send functionality, real-time delivery
|
||||
- [x] **Phase 10: Read/Unread Status Management** - Unread tracking, indicator badge, mark-as-read logic
|
||||
- [x] **Phase 11: Chat Finalization** - Error handling, edge cases, performance optimization, UAT
|
||||
|
||||
</details>
|
||||
|
||||
### 🚧 v1.2 Session Attachments (Phases 12-16) - IN PROGRESS
|
||||
|
||||
**Milestone Goal:** Add file attachment capability to music sessions, allowing users to upload files from their computer and view them in the chat window with real-time synchronization across all session participants.
|
||||
|
||||
- [ ] **Phase 12: Attachment Research & Backend Validation** - Explore legacy attachment implementation, validate existing backend infrastructure
|
||||
- [ ] **Phase 13: File Upload Infrastructure** - Attach button, file dialog, validation, S3 upload with progress
|
||||
- [ ] **Phase 14: Chat Integration & Display** - Display attachments as messages in chat window
|
||||
- [ ] **Phase 15: Real-time Synchronization** - WebSocket broadcast and attachment history
|
||||
- [ ] **Phase 16: Attachment Finalization** - Error handling, edge cases, UAT
|
||||
|
||||
## Phase Details
|
||||
|
||||
|
|
@ -107,7 +123,10 @@ Plans:
|
|||
|
||||
</details>
|
||||
|
||||
### 🚧 v1.1 Music Session Chat (In Progress)
|
||||
### ✅ v1.1 Music Session Chat (Phases 6-11) - SHIPPED 2026-01-31
|
||||
|
||||
<details>
|
||||
<summary>Show completed phase details</summary>
|
||||
|
||||
**Milestone Goal:** Add real-time chat functionality to music sessions with modeless window, message history, read/unread tracking, and file attachment display.
|
||||
|
||||
|
|
@ -171,12 +190,120 @@ Plans:
|
|||
|
||||
Plans:
|
||||
- [x] 11-01: Error Handling, Accessibility & Polish (3 tasks) - COMPLETE 2026-01-27
|
||||
- [ ] 11-02: UAT & Final Integration Testing
|
||||
- [x] 11-02: UAT & Final Integration Testing - COMPLETE 2026-01-31
|
||||
|
||||
</details>
|
||||
|
||||
### 🚧 v1.2 Session Attachments (Phases 12-16) - IN PROGRESS
|
||||
|
||||
**Milestone Goal:** Add file attachment capability to music sessions, allowing users to upload files from their computer and view them in the chat window with real-time synchronization across all session participants.
|
||||
|
||||
#### Phase 12: Attachment Research & Backend Validation
|
||||
**Goal**: Validate existing backend infrastructure and understand legacy attachment patterns
|
||||
**Depends on**: Phase 11 (previous milestone complete)
|
||||
**Research**: Likely (exploring legacy attachment implementation and backend API)
|
||||
**Research topics**: Legacy AttachmentStore patterns, MusicNotation model and API, S3 upload flow, file type/size validation, attachment-chat integration
|
||||
**Requirements**: None (research phase)
|
||||
**Plans**: 2 plans
|
||||
|
||||
**Success Criteria:**
|
||||
1. Backend API contract documented (endpoints, payloads, responses)
|
||||
2. MusicNotation model capabilities validated (no code changes needed)
|
||||
3. S3 upload flow understood (signed URLs, multipart form data)
|
||||
4. Legacy file validation patterns documented (type whitelist, 10 MB limit)
|
||||
5. Integration points identified (chat window, WebSocket, Redux)
|
||||
|
||||
Plans:
|
||||
- [ ] 12-01: Document legacy attachment implementation and backend API surface
|
||||
- [ ] 12-02: Validate backend infrastructure and design React integration strategy
|
||||
|
||||
#### Phase 13: File Upload Infrastructure
|
||||
**Goal**: Users can select files from OS dialog and upload to S3 with validation and progress feedback
|
||||
**Depends on**: Phase 12
|
||||
**Research**: Unlikely (following established patterns from research phase)
|
||||
**Requirements**: REQ-1.1, REQ-1.2, REQ-1.3, REQ-1.4, REQ-6.1, REQ-6.2, REQ-6.3, REQ-7.1
|
||||
**Plans**: 3 plans
|
||||
|
||||
**Success Criteria:**
|
||||
1. User clicks Attach button in session toolbar → OS file dialog opens
|
||||
2. File selection validates type (.pdf, .xml, .mxl, .txt, .png, .jpg, .jpeg, .gif, .mp3, .wav) and size (≤ 10 MB)
|
||||
3. Invalid files show immediate error toast (type or size) without starting upload
|
||||
4. Valid files upload to S3 via MusicNotation API with multipart form data
|
||||
5. Upload progress indicator displays in chat window (percentage or spinner)
|
||||
6. Upload completes → API returns attachment metadata (id, file_name, file_url, size)
|
||||
7. Correct attachment_type set (notation/audio) based on file extension
|
||||
8. Attachment associated with correct music_session_id
|
||||
9. User can continue using app while upload is in progress (non-blocking)
|
||||
|
||||
Plans:
|
||||
- [ ] 13-01: Attach button, file dialog, and client-side validation (type, size)
|
||||
- [ ] 13-02: S3 upload integration with progress tracking
|
||||
- [ ] 13-03: Error handling and success feedback
|
||||
|
||||
#### Phase 14: Chat Integration & Display
|
||||
**Goal**: Attachments display as messages in chat window with metadata and clickable links
|
||||
**Depends on**: Phase 13
|
||||
**Research**: Unlikely (extending existing chat message display)
|
||||
**Requirements**: REQ-2.1, REQ-2.2, REQ-2.3, REQ-2.4, REQ-2.5, REQ-4.1, REQ-4.2, REQ-7.2, REQ-7.3
|
||||
**Plans**: 2 plans
|
||||
|
||||
**Success Criteria:**
|
||||
1. Attachment appears in chat as message: "[UserName] attached [FileName]"
|
||||
2. Attachment message includes metadata: filename, file size (KB/MB), uploader, timestamp
|
||||
3. Attachment has visual indicator (icon, styling) to distinguish from text messages
|
||||
4. Filename is clickable link that opens file in new browser tab (target="_blank")
|
||||
5. Browser handles view/download based on file type (PDF viewer, image display, audio player, XML download)
|
||||
6. Attachment messages sort chronologically with regular chat messages
|
||||
7. Chat auto-scrolls when new attachment appears (reuses existing logic)
|
||||
8. Chat history includes attachments (persist across page refresh, visible when joining session)
|
||||
9. Attachment messages display correctly at different window sizes (responsive layout, long filename truncation)
|
||||
|
||||
Plans:
|
||||
- [ ] 14-01: Attachment message display with metadata and styling
|
||||
- [ ] 14-02: Clickable links, chat history integration, responsive layout
|
||||
|
||||
#### Phase 15: Real-time Synchronization
|
||||
**Goal**: New attachments broadcast to all session participants in real-time via WebSocket
|
||||
**Depends on**: Phase 14
|
||||
**Research**: Unlikely (extending existing WebSocket handlers)
|
||||
**Requirements**: REQ-3.1, REQ-3.2
|
||||
**Plans**: 1 plan
|
||||
|
||||
**Success Criteria:**
|
||||
1. User uploads file → WebSocket message broadcasts to all session participants
|
||||
2. Attachment appears immediately in all users' chat windows (no manual refresh)
|
||||
3. WebSocket message includes: music_session_id, file_name, file_url, user_name, size, timestamp
|
||||
4. Optimistic update prevents duplicate messages for uploader (deduplication by msg_id)
|
||||
5. Multiple users in same session all see attachment in real-time
|
||||
6. User joining session after upload sees attachment in chat history
|
||||
|
||||
Plans:
|
||||
- [ ] 15-01: WebSocket broadcast and attachment deduplication
|
||||
|
||||
#### Phase 16: Attachment Finalization
|
||||
**Goal**: Complete attachment feature with comprehensive error handling, edge cases, and UAT validation
|
||||
**Depends on**: Phase 15
|
||||
**Research**: Unlikely (error handling and validation of established code)
|
||||
**Requirements**: REQ-5.1, REQ-5.2, REQ-5.3, REQ-5.4, REQ-5.5
|
||||
**Plans**: 2 plans
|
||||
|
||||
**Success Criteria:**
|
||||
1. File size exceeded (>10 MB) → toast "File size exceeds 10 MB limit", upload blocked
|
||||
2. Invalid file type → toast with allowed types list, upload blocked
|
||||
3. Network error during upload → toast "Upload failed. Please try again.", optimistic message removed, retry possible
|
||||
4. Upload success → toast "File uploaded successfully" (auto-dismiss), attachment in chat
|
||||
5. Missing/deleted file on S3 → browser 404 page (no app crash)
|
||||
6. All edge cases handled: rapid clicks, disconnection, empty states, long filenames
|
||||
7. Comprehensive UAT checklist validates all 26 requirements
|
||||
|
||||
Plans:
|
||||
- [ ] 16-01: Error handling and edge case validation
|
||||
- [ ] 16-02: UAT and final integration testing
|
||||
|
||||
## Progress
|
||||
|
||||
**Execution Order:**
|
||||
Phases execute in numeric order: 1 → 2 → 3 → 4 → 5 → 6 → 7 → 8 → 9 → 10 → 11
|
||||
Phases execute in numeric order: 1 → 2 → 3 → 4 → 5 → 6 → 7 → 8 → 9 → 10 → 11 → 12 → 13 → 14 → 15 → 16
|
||||
|
||||
| Phase | Milestone | Plans Complete | Status | Completed |
|
||||
|-------|-----------|----------------|--------|-----------|
|
||||
|
|
@ -190,4 +317,9 @@ Phases execute in numeric order: 1 → 2 → 3 → 4 → 5 → 6 → 7 → 8 →
|
|||
| 8. Chat Window UI & Message Display | v1.1 | 3/3 | Complete | 2026-01-27 |
|
||||
| 9. Message Composition & Sending | v1.1 | 2/2 | Complete | 2026-01-27 |
|
||||
| 10. Read/Unread Status Management | v1.1 | 1/1 | Complete | 2026-01-27 |
|
||||
| 11. Chat Finalization | v1.1 | 1/2 | In progress | 2026-01-27 |
|
||||
| 11. Chat Finalization | v1.1 | 2/2 | Complete | 2026-01-31 |
|
||||
| 12. Attachment Research & Backend Validation | v1.2 | 0/2 | Not started | - |
|
||||
| 13. File Upload Infrastructure | v1.2 | 0/3 | Not started | - |
|
||||
| 14. Chat Integration & Display | v1.2 | 0/2 | Not started | - |
|
||||
| 15. Real-time Synchronization | v1.2 | 0/1 | Not started | - |
|
||||
| 16. Attachment Finalization | v1.2 | 0/2 | Not started | - |
|
||||
|
|
|
|||
|
|
@ -2,19 +2,19 @@
|
|||
|
||||
## Project Reference
|
||||
|
||||
See: .planning/PROJECT.md (updated 2026-01-13)
|
||||
See: .planning/PROJECT.md (updated 2026-02-02)
|
||||
|
||||
**Core value:** Modernize session features (Backing Track, JamTrack, Session Chat) from legacy jQuery/Rails to React patterns in jam-ui
|
||||
**Current focus:** Milestone v1.1 — Music Session Chat
|
||||
**Core value:** Modernize session features (Backing Track, JamTrack, Session Chat, Session Attachments) from legacy jQuery/Rails to React patterns in jam-ui
|
||||
**Current focus:** Milestone v1.2 — Session Attachments
|
||||
|
||||
## Current Position
|
||||
|
||||
Phase: 11 of 11 (Chat Finalization)
|
||||
Plan: 11-02 complete
|
||||
Status: PHASE COMPLETE - All plans done (2/2)
|
||||
Last activity: 2026-01-31 — Completed 11-02-PLAN.md (UAT & Final Integration Testing)
|
||||
Phase: 12 of 16 (Attachment Research & Backend Validation)
|
||||
Plan: Not started
|
||||
Status: NEW MILESTONE - Ready to begin Phase 12
|
||||
Last activity: 2026-02-02 — Created v1.2 phase structure (5 phases, 10 plans estimated)
|
||||
|
||||
Progress: ████████████ 100% (v1.1 MILESTONE COMPLETE)
|
||||
Progress: ░░░░░░░░░░░░ 0% (v1.2 MILESTONE STARTED)
|
||||
|
||||
## Performance Metrics
|
||||
|
||||
|
|
@ -35,14 +35,21 @@ Progress: ████████████ 100% (v1.1 MILESTONE COMPLETE)
|
|||
| 5 | 5 | 54 min | 10.8 min |
|
||||
|
||||
**v1.1 Music Session Chat (COMPLETE):**
|
||||
- Total plans completed: 11 (Phase 6: 2, Phase 7: 3, Phase 8: 3, Phase 9: 2, Phase 10: 1, Phase 11: 2)
|
||||
- Total plans completed: 11
|
||||
- Total phases: 6 (phases 6-11)
|
||||
- Progress: 100% (ALL PHASES COMPLETE)
|
||||
- Completion date: 2026-01-31
|
||||
|
||||
**v1.2 Session Attachments (IN PROGRESS):**
|
||||
- Total plans estimated: 10 (Phase 12: 2, Phase 13: 3, Phase 14: 2, Phase 15: 1, Phase 16: 2)
|
||||
- Total phases: 5 (phases 12-16)
|
||||
- Progress: 0% (PHASE 12 STARTING)
|
||||
- Started: 2026-02-02
|
||||
|
||||
**Recent Trend:**
|
||||
- Last milestone: v1.0 completed 2026-01-14 with excellent velocity
|
||||
- Current milestone: v1.1 started 2026-01-26
|
||||
- v1.0 completed 2026-01-14 with excellent velocity
|
||||
- v1.1 completed 2026-01-31 with consistent execution
|
||||
- v1.2 started 2026-02-02 building on established patterns
|
||||
|
||||
## Accumulated Context
|
||||
|
||||
|
|
@ -179,7 +186,6 @@ Recent decisions affecting current work:
|
|||
- Testing strategy: 80%+ unit test coverage, 7 integration test files, E2E complete workflow, 40+ UAT test cases across 9 categories
|
||||
- Critical decisions: Message virtualization deferred, optimistic UI updates enabled, localStorage for unread persistence, multi-tab sync deferred, auto-scroll tracks scroll position
|
||||
- Deferred features: Server-side read/unread tracking, file attachments, message search/filtering, editing/deletion, typing indicators, emoji picker, multi-channel tabs, notification sounds, desktop notifications
|
||||
- 3 design documents created: CHAT_COMPONENT_DESIGN.md (954 lines), CHAT_REDUX_DESIGN.md (1132 lines), IMPLEMENTATION_ROADMAP.md (1138 lines)
|
||||
|
||||
**From Phase 7 Plan 1 (07-chat-infrastructure):**
|
||||
- Created sessionChatSlice.js with complete initial state structure matching CHAT_REDUX_DESIGN.md
|
||||
|
|
@ -330,7 +336,8 @@ Recent decisions affecting current work:
|
|||
### Roadmap Evolution
|
||||
|
||||
- **v1.0 Media Players** (Phases 1-5): Completed 2026-01-14 - Backing Track and JamTrack modernization
|
||||
- **v1.1 Music Session Chat** (Phases 6-11): Created 2026-01-26 - Real-time chat with read/unread tracking
|
||||
- **v1.1 Music Session Chat** (Phases 6-11): Completed 2026-01-31 - Real-time chat with read/unread tracking
|
||||
- **v1.2 Session Attachments** (Phases 12-16): Started 2026-02-02 - File attachment capability for sessions
|
||||
|
||||
### Blockers/Concerns
|
||||
|
||||
|
|
@ -338,13 +345,14 @@ None yet.
|
|||
|
||||
## Session Continuity
|
||||
|
||||
Last session: 2026-01-31
|
||||
Stopped at: Phase 11 Plan 2 complete (UAT & Final Integration Testing)
|
||||
Last session: 2026-02-02
|
||||
Stopped at: Phase 12 not started (v1.2 milestone created)
|
||||
Resume file: None
|
||||
|
||||
**Status:** v1.1 Music Session Chat milestone COMPLETE
|
||||
**Status:** v1.2 Session Attachments milestone CREATED
|
||||
**Next steps:**
|
||||
1. Complete manual UAT using 11-02-UAT-CHECKLIST.md (50+ test cases)
|
||||
2. Deploy to production environment
|
||||
3. Monitor chat functionality for 24-48 hours
|
||||
4. Plan next milestone (v1.2 Metronome or Session Chat Enhancements)
|
||||
1. Start Phase 12 Plan 1: Document legacy attachment implementation and backend API surface
|
||||
2. Research legacy AttachmentStore patterns in web/app/assets/javascripts/react-components/stores/
|
||||
3. Document MusicNotation model API contract and S3 upload flow
|
||||
4. Identify integration points with existing chat window (Phase 8-11 components)
|
||||
5. Complete Phase 12 research before moving to Phase 13 implementation
|
||||
|
|
|
|||
Loading…
Reference in New Issue