Use attachments from old CollectionFS database structure, when not yet migrated to Meteor-Files/ostrio-files, without needing to migrate database structure.

Thanks to xet7 !

docs/AttachmentBackwardCompatibility.md

@@ -0,0 +1,169 @@
+# Attachment Backward Compatibility
+
+This document describes the backward compatibility implementation for Wekan attachments, allowing the system to read attachments from both the old CollectionFS structure (Wekan v6.09 and earlier) and the new Meteor-Files structure (Wekan v7.x and later).
+
+## Overview
+
+When Wekan migrated from CollectionFS to Meteor-Files (ostrio-files), the database structure for attachments changed significantly. This backward compatibility layer ensures that:
+
+1. Old attachments can still be accessed and downloaded
+2. No database migration is required
+3. Both old and new attachments can coexist
+4. The UI works seamlessly with both structures
+
+## Database Structure Changes
+
+### Old Structure (CollectionFS)
+- **CollectionFS Files**: `cfs_gridfs.attachments.files`
+- **CollectionFS Records**: `cfs.attachments.filerecord`
+- **File Storage**: GridFS with bucket name `cfs_gridfs.attachments`
+
+### New Structure (Meteor-Files)
+- **Files Collection**: `attachments`
+- **File Storage**: Configurable (Filesystem, GridFS, or S3)
+
+## Implementation Details
+
+### Files Added/Modified
+
+1. **`models/lib/attachmentBackwardCompatibility.js`**
+   - Main backward compatibility layer
+   - Handles reading from old CollectionFS structure
+   - Converts old data format to new format
+   - Provides GridFS streaming for downloads
+
+2. **`models/attachments.js`**
+   - Added backward compatibility methods to Attachments collection
+   - Imports compatibility functions
+
+3. **`imports/reactiveCache.js`**
+   - Updated to use backward compatibility layer
+   - Falls back to old structure when new structure has no results
+
+4. **`server/routes/legacyAttachments.js`**
+   - Handles legacy attachment downloads via `/cfs/files/attachments/:id`
+   - Provides proper HTTP headers and streaming
+
+5. **`server/migrations/migrateAttachments.js`**
+   - Migration methods for converting old attachments to new structure
+   - Optional migration tools for users who want to fully migrate
+
+### Key Functions
+
+#### `getAttachmentWithBackwardCompatibility(attachmentId)`
+- Tries new structure first, falls back to old structure
+- Returns attachment data in new format
+- Handles both single attachment lookups
+
+#### `getAttachmentsWithBackwardCompatibility(query)`
+- Queries both old and new structures
+- Combines and deduplicates results
+- Used for card attachment lists
+
+#### `getOldAttachmentData(attachmentId)`
+- Reads from old CollectionFS structure
+- Converts old format to new format
+- Handles file type detection and metadata
+
+#### `getOldAttachmentStream(attachmentId)`
+- Creates GridFS download stream for old attachments
+- Used for file downloads
+
+## Usage
+
+### Automatic Fallback
+The system automatically falls back to the old structure when:
+- An attachment is not found in the new structure
+- Querying attachments for a card returns no results
+
+### Legacy Download URLs
+Old attachment download URLs (`/cfs/files/attachments/:id`) continue to work and are handled by the legacy route.
+
+### Migration (Optional)
+Users can optionally migrate their old attachments to the new structure using the migration methods:
+
+```javascript
+// Migrate a single attachment
+Meteor.call('migrateAttachment', attachmentId);
+
+// Migrate all attachments for a card
+Meteor.call('migrateCardAttachments', cardId);
+
+// Check migration status
+Meteor.call('getAttachmentMigrationStatus', cardId);
+```
+
+## Performance Considerations
+
+1. **Query Optimization**: The system queries the new structure first, only falling back to old structure when necessary
+2. **Caching**: ReactiveCache handles caching for both old and new attachments
+3. **Streaming**: Large files are streamed efficiently using GridFS streams
+
+## Error Handling
+
+- Graceful fallback when old structure is not available
+- Proper error logging for debugging
+- HTTP error codes for download failures
+- Permission checks for both old and new attachments
+
+## Security
+
+- Permission checks are maintained for both old and new attachments
+- Board access rules apply to legacy attachments
+- File type validation is preserved
+
+## Testing
+
+To test the backward compatibility:
+
+1. Ensure you have old Wekan v6.09 data with attachments
+2. Upgrade to Wekan v7.x
+3. Verify that old attachments are visible in the UI
+4. Test downloading old attachments
+5. Verify that new attachments work normally
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Old attachments not showing**
+   - Check that old CollectionFS collections exist in database
+   - Verify GridFS bucket is accessible
+   - Check server logs for errors
+
+2. **Download failures**
+   - Verify GridFS connection
+   - Check file permissions
+   - Ensure legacy route is loaded
+
+3. **Performance issues**
+   - Consider migrating old attachments to new structure
+   - Check database indexes
+   - Monitor query performance
+
+### Debug Mode
+
+Enable debug logging by setting:
+```javascript
+console.log('Legacy attachments route loaded');
+```
+
+This will help identify if the backward compatibility layer is properly loaded.
+
+## Future Considerations
+
+- The backward compatibility layer can be removed in future versions
+- Users should be encouraged to migrate old attachments
+- Consider adding migration tools to the admin interface
+- Monitor usage of old vs new structures
+
+## Migration Path
+
+For users who want to fully migrate to the new structure:
+
+1. Use the migration methods to convert old attachments
+2. Verify all attachments are working
+3. Remove old CollectionFS collections (optional)
+4. Update any hardcoded URLs to use new structure
+
+The backward compatibility layer ensures that migration is optional and can be done gradually.