Sindbad~EG File Manager

# Chat & Messaging System

## Overview
Comprehensive chat and messaging system with public chat widget, admin management panel, and member portal integration.

## Installation

1. **Run the installer:**
   ```
   https://yoursite.com/install_chat_messaging.php
   ```
   (Requires superuser login)

2. The installer will:
   - Create 4 database tables (`chat_conversations`, `chat_messages`, `message_groups`, `message_group_members`)
   - Register "Messaging" module in sidebar
   - Set up all required schema with foreign keys

## Features

### 1. Public Chat Widget (Landing Page)
- **Location:** Bottom-right floating button on `index.php` and all public pages
- **Works for:**
  - Guests (via session token)
  - Logged-in members (via `member_id`)
- **Features:**
  - Auto-creates conversation on first message
  - Polls for new messages every 4 seconds
  - Shows admin replies in real-time
  - All chats archived in database

### 2. Admin Messaging Panel
**Location:** `modules/messaging/`

#### Live Chats (`index.php`)
- Lists all open public and member-admin conversations
- Shows:
  - Last message preview
  - Unread message count (red badge)
  - Timestamp
  - Guest token or member name
- Stats cards:
  - Total conversations
  - Unread messages
  - Active chats

#### Chat View (`chat.php`)
- Open individual conversations
- Send/receive messages in real-time
- Auto-marks messages as read
- Polling every 3 seconds
- Works with same API endpoints as public widget

#### Broadcasts (`broadcasts.php`)
- Send messages to:
  - **All members**
  - **By Area** (select dropdown)
  - **By District** (select dropdown)
  - **By Assembly** (select dropdown)
  - **By Group** (from `message_groups` table)
  - **Individual member** (live search)
- Creates or reuses `member_admin` conversations
- Shows success message with recipient count

### 3. Member Portal Integration
**Location:** `members/index.php` - New "Messages" tab

- Lists member's conversations with admins
- Shows unread count badge on tab
- Displays:
  - Last message preview
  - Timestamp
  - Unread indicator
- Click to open chat (reuses public chat widget)
- Empty state when no messages yet

### 4. Database Schema

#### `chat_conversations`
- `id` - Primary key
- `type` - ENUM('public', 'member_admin', 'group')
- `guest_token` - For guest chats (nullable)
- `member_id` - For member chats (nullable, FK to members)
- `group_id` - For group chats (nullable, FK to message_groups)
- `created_by_user_id` - Admin who created (nullable)
- `is_closed` - 0/1
- `created_at`, `updated_at`

#### `chat_messages`
- `id` - Primary key
- `conversation_id` - FK to chat_conversations
- `sender_type` - ENUM('guest', 'member', 'admin')
- `sender_member_id` - FK to members (nullable)
- `sender_user_id` - FK to users (nullable)
- `message_text` - TEXT
- `is_read` - 0/1
- `created_at`

#### `message_groups`
- `id` - Primary key
- `name` - Group name
- `scope` - ENUM('global', 'area', 'district', 'assembly')
- `area_id`, `district_id`, `assembly_id` - FKs (nullable)
- `created_by_user_id` - FK to users
- `created_at`, `updated_at`

#### `message_group_members`
- `group_id` - FK to message_groups
- `member_id` - FK to members
- `role` - ENUM('member', 'admin')
- `joined_at`
- Primary key: (group_id, member_id)

### 5. API Endpoints

All under `api/`:

#### `chat_start.php`
- **Method:** GET
- **Purpose:** Initialize or resume conversation
- **Returns:** `{success, conversation_id, guest_token, is_member}`
- **Logic:**
  - If member logged in: uses `member_id`
  - If guest: uses/creates `guest_token` in session
  - Finds existing open conversation or creates new one

#### `chat_send.php`
- **Method:** POST
- **Params:** `conversation_id`, `message`
- **Purpose:** Send a message
- **Sender detection:**
  - Admin: `isLoggedIn()` → `sender_type='admin'`, `sender_user_id`
  - Member: `MemberAuth::isMemberLoggedIn()` → `sender_type='member'`, `sender_member_id`
  - Guest: default → `sender_type='guest'`

#### `chat_fetch.php`
- **Method:** GET
- **Params:** `conversation_id`, `last_message_id` (optional)
- **Purpose:** Fetch new messages
- **Returns:** `{success, messages: [{id, sender_type, message_text, created_at}]}`
- **Used by:** Public widget, member portal, admin panel

#### `search_members.php`
- **Method:** GET
- **Params:** `q` (search query)
- **Purpose:** Search members by name/email for broadcasts
- **Returns:** `{members: [{id, first_name, last_name, email}]}`
- **Limit:** 20 results

## Access Control

### Who Can Use:
- **Public chat widget:** Anyone (guests + logged-in users)
- **Admin messaging panel:** Any logged-in admin user with module access (assembly/district/area/superuser)
- **Member portal messages:** Any logged-in member

### Permissions:
- Module registered with `required_role='assembly'`
- Superusers have full access
- Area/District/Assembly users can access based on sidebar logic

## UI/UX Details

### Styling:
- Uses existing gradient color scheme:
  - Primary: Blue (#1E40AF) → Mauve (#9333EA)
  - Secondary: Orange (#F97316) → Yellow (#FBBF24)
- Consistent with Tailwind utility classes
- Responsive design (mobile-friendly)

### Real-time Behavior:
- **Public widget:** Polls every 4 seconds
- **Admin chat:** Polls every 3 seconds
- **No WebSockets required** (simple PHP/AJAX polling)

### Notifications:
- Unread badge on Messages tab (member portal)
- Red badge on conversation list (unread count)
- Auto-scroll to bottom on new messages

## Usage Workflow

### For Visitors/Members:
1. Open landing page
2. Click chat button (bottom-right)
3. Type message and send
4. Admin replies appear automatically (via polling)
5. Chat history persists across sessions

### For Admins:
1. Go to **Messaging** in sidebar
2. See list of active conversations
3. Click any conversation to open chat
4. Send replies in real-time
5. Or use **Send Broadcast** to message multiple members

### For Members (Portal):
1. Login to member portal
2. Click **Messages** tab
3. See conversations with admins
4. Click to open and reply
5. Receive broadcast messages from admins

## Future Enhancements (Optional)

- Group chat creation UI for admins
- File/image attachments in messages
- Push notifications (browser notifications API)
- Email notifications for offline members
- Message search/filter
- Archive/delete conversations
- Typing indicators
- Read receipts
- WebSocket upgrade for true real-time (optional)

## Files Created/Modified

### New Files:
- `sql/chat_messaging.sql` - Database schema
- `install_chat_messaging.php` - Installer script
- `api/chat_start.php` - Start conversation endpoint
- `api/chat_send.php` - Send message endpoint
- `api/chat_fetch.php` - Fetch messages endpoint
- `api/search_members.php` - Member search for broadcasts
- `modules/messaging/index.php` - Main messaging panel
- `modules/messaging/chat.php` - Individual chat view
- `modules/messaging/broadcasts.php` - Broadcast interface

### Modified Files:
- `index.php` - Added floating chat widget
- `members/index.php` - Added Messages tab

## Testing Checklist

- [ ] Run `install_chat_messaging.php` as superuser
- [ ] Verify "Messaging" appears in admin sidebar
- [ ] Test public chat widget on landing page (as guest)
- [ ] Test admin replying to guest chat
- [ ] Test member portal Messages tab
- [ ] Test broadcast to all members
- [ ] Test broadcast by area/district/assembly
- [ ] Test individual member message
- [ ] Verify unread counts update correctly
- [ ] Test on mobile devices

## Support

For issues or questions, check:
- Database tables exist: `SHOW TABLES LIKE 'chat_%'`
- Module registered: `SELECT * FROM module_management WHERE module_name='Messaging'`
- API endpoints accessible: Test `api/chat_start.php` directly
- Browser console for JavaScript errors

---

**Version:** 1.0  
**Last Updated:** November 2025  
**Requirements:** PHP 7.4+, MySQL 5.7+, Modern browser with JavaScript enabled