From 4dc08f87c52b713eb3382bea8695d16107d5cdff Mon Sep 17 00:00:00 2001 From: Samir Boulahtit Date: Sun, 21 Dec 2025 14:11:27 +0100 Subject: [PATCH] docs: add messaging system implementation documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add comprehensive messaging-system.md documentation - Document database models, services, API endpoints - Document admin, vendor, and shop interfaces - Document future enhancements (email notifications, WebSocket) - Add to mkdocs.yml navigation 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- docs/implementation/messaging-system.md | 243 ++++++++++++++++++++++++ mkdocs.yml | 2 + 2 files changed, 245 insertions(+) create mode 100644 docs/implementation/messaging-system.md diff --git a/docs/implementation/messaging-system.md b/docs/implementation/messaging-system.md new file mode 100644 index 00000000..6185632e --- /dev/null +++ b/docs/implementation/messaging-system.md @@ -0,0 +1,243 @@ +# Messaging System Implementation + +This document describes the messaging system that enables threaded conversations between different platform participants. + +## Overview + +The messaging system supports three communication channels: + +1. **Admin <-> Vendor**: Platform administrators communicate with vendor users +2. **Vendor <-> Customer**: Vendors communicate with their customers +3. **Admin <-> Customer**: Platform administrators communicate with customers + +## Architecture + +### Database Models + +Located in `models/database/message.py`: + +| Model | Description | +|-------|-------------| +| `Conversation` | Threaded conversation container with subject, type, and status | +| `ConversationParticipant` | Links participants to conversations with unread tracking | +| `Message` | Individual messages within a conversation | +| `MessageAttachment` | File attachments for messages | + +### Enums + +| Enum | Values | Description | +|------|--------|-------------| +| `ConversationType` | `admin_vendor`, `vendor_customer`, `admin_customer` | Defines conversation channel | +| `ParticipantType` | `admin`, `vendor`, `customer` | Type of participant | + +### Polymorphic Participants + +The system uses polymorphic relationships via `participant_type` + `participant_id`: +- `admin` and `vendor` types reference `users.id` +- `customer` type references `customers.id` + +### Multi-Tenant Isolation + +Conversations involving customers include a `vendor_id` to ensure proper data isolation. Vendor users can only see conversations within their vendor context. + +## Services + +### MessagingService (`app/services/messaging_service.py`) + +Core business logic for conversations and messages: + +| Method | Description | +|--------|-------------| +| `create_conversation()` | Create a new conversation with participants | +| `get_conversation()` | Get conversation with access validation | +| `list_conversations()` | Paginated list with filters | +| `send_message()` | Send message with automatic unread updates | +| `mark_conversation_read()` | Mark all messages read for participant | +| `get_unread_count()` | Get total unread count for header badge | +| `close_conversation()` | Close a conversation thread | +| `reopen_conversation()` | Reopen a closed conversation | + +### MessageAttachmentService (`app/services/message_attachment_service.py`) + +File upload handling: + +| Method | Description | +|--------|-------------| +| `validate_and_store()` | Validate file type/size and store to disk | +| `get_max_file_size_bytes()` | Get limit from platform settings | +| `delete_attachment()` | Remove files from storage | + +**Allowed file types:** +- Images: JPEG, PNG, GIF, WebP +- Documents: PDF, Office documents +- Archives: ZIP +- Text: Plain text, CSV + +**Storage path pattern:** `uploads/messages/YYYY/MM/conversation_id/uuid.ext` + +## API Endpoints + +### Admin API (`/api/v1/admin/messages`) + +| Endpoint | Method | Description | +|----------|--------|-------------| +| `/messages` | GET | List conversations | +| `/messages` | POST | Create conversation | +| `/messages/unread-count` | GET | Get unread badge count | +| `/messages/recipients` | GET | Get available recipients | +| `/messages/{id}` | GET | Get conversation detail | +| `/messages/{id}/messages` | POST | Send message (with attachments) | +| `/messages/{id}/close` | POST | Close conversation | +| `/messages/{id}/reopen` | POST | Reopen conversation | +| `/messages/{id}/read` | PUT | Mark as read | +| `/messages/{id}/preferences` | PUT | Update notification preferences | + +### Vendor API (`/api/v1/vendor/messages`) + +Same structure as admin, but with vendor context filtering. Vendors can only: +- See their own vendor_customer and admin_vendor conversations +- Create vendor_customer conversations with their customers +- Not initiate admin_vendor conversations (admins initiate those) + +## Frontend + +### Admin Interface + +- **Template:** `app/templates/admin/messages.html` +- **JavaScript:** `static/admin/js/messages.js` + +Features: +- Split-panel conversation list + message thread +- Filters by type (vendors/customers) and status (open/closed) +- Compose modal for new conversations +- File attachment support +- 30-second polling for new messages +- Header badge with unread count + +### Vendor Interface + +- **Template:** `app/templates/vendor/messages.html` +- **JavaScript:** `static/vendor/js/messages.js` + +Similar to admin but with vendor-specific: +- Only vendor_customer and admin_vendor channels +- Compose modal for customer conversations only + +## Pydantic Schemas + +Located in `models/schema/message.py`: + +- `ConversationCreate` - Create request +- `ConversationSummary` - List item with unread count +- `ConversationDetailResponse` - Full thread with messages +- `ConversationListResponse` - Paginated list +- `MessageResponse` - Single message with attachments +- `AttachmentResponse` - File metadata with download URL +- `UnreadCountResponse` - For header badge + +## Configuration + +### Platform Setting + +The attachment size limit is configurable via platform settings: + +- **Key:** `message_attachment_max_size_mb` +- **Default:** 10 +- **Category:** messaging + +## Shop (Customer) Interface + +### API Endpoints (`/api/v1/shop/messages`) + +| Endpoint | Method | Description | +|----------|--------|-------------| +| `/messages` | GET | List customer's conversations | +| `/messages/unread-count` | GET | Get unread badge count | +| `/messages/{id}` | GET | Get conversation detail | +| `/messages/{id}/messages` | POST | Send reply message | +| `/messages/{id}/read` | PUT | Mark as read | +| `/messages/{id}/attachments/{att_id}` | GET | Download attachment | + +### Frontend + +- **Template:** `app/templates/shop/account/messages.html` +- **Page Route:** `/shop/account/messages` and `/shop/account/messages/{conversation_id}` + +Features: +- Conversation list with unread badges +- Filter by status (open/closed) +- Thread view with message history +- Reply form with file attachments +- 30-second polling for new messages +- Link from account dashboard with unread count + +### Limitations + +Customers can only: +- View their `vendor_customer` conversations +- Reply to existing conversations (cannot initiate) +- Cannot close conversations + +--- + +## Future Enhancements + +### Email Notifications (Requires Email Infrastructure) + +The messaging system is designed to support email notifications, but requires email infrastructure to be implemented first: + +**Prerequisites:** +- SMTP configuration in settings (host, port, username, password) +- Email service (`app/services/email_service.py`) +- Email templates (`app/templates/emails/`) +- Background task queue for async sending + +**Planned Implementation:** +1. **MessageNotificationService** (`app/services/message_notification_service.py`) + - `notify_new_message()` - Send email to participants on new message + - Respect per-conversation `email_notifications` preference + - Include message preview and reply link + +2. **Email Template** (`app/templates/emails/new_message.html`) + - Subject: "New message: {conversation_subject}" + - Body: Sender name, message preview, link to reply + +3. **Integration Points:** + - Call `notify_new_message()` from `messaging_service.send_message()` + - Skip notification for sender (only notify other participants) + - Rate limit to prevent spam on rapid message exchanges + +**Database Support:** +The `email_notifications` field on `ConversationParticipant` is already in place to store per-conversation preferences. + +### WebSocket Support (Optional) + +Real-time message delivery instead of 30-second polling: +- Would require WebSocket infrastructure (e.g., FastAPI WebSocket, Redis pub/sub) +- Significant infrastructure changes + +## Migration + +The messaging tables are created by migration `e3f4a5b6c7d8_add_messaging_tables.py`: + +```bash +# Apply migration +alembic upgrade head + +# Rollback +alembic downgrade -1 +``` + +## Navigation + +### Admin Sidebar +Messages is available under "Platform Administration" section. + +### Vendor Sidebar +Messages is available under "Sales" section. + +### Shop Account Dashboard +Messages card is available on the customer account dashboard with unread count badge. + +### Header Badge +Both admin and vendor headers show an unread message count badge next to the messages icon. diff --git a/mkdocs.yml b/mkdocs.yml index a31b6d1a..29202247 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -136,8 +136,10 @@ nav: - Vendor Operations Expansion: development/migration/vendor-operations-expansion.md - Implementation Plans: - Admin Inventory Management: implementation/inventory-admin-migration.md + - Admin Notification System: implementation/admin-notification-system.md - Letzshop Order Import: implementation/letzshop-order-import-improvements.md - Letzshop Jobs & Tables: implementation/letzshop-jobs-improvements.md + - Messaging System: implementation/messaging-system.md - Order Item Exceptions: implementation/order-item-exceptions.md - Product Suppliers Table: implementation/product-suppliers-table.md - Unified Order View: implementation/unified-order-view.md