Sync broccolini-bot: rename from zammad, docs in docs/, security gitignore, remove zammad deps

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-02-12 02:56:00 -06:00
parent 08a16b4a75
commit 29a13768f7
37 changed files with 1093 additions and 3229 deletions
--- a/docs/PHASE_FEATURES.md
+++ b/docs/PHASE_FEATURES.md
@@ -0,0 +1,531 @@
+# Broccolini Bot - New Features Documentation
+
+This document outlines all the features implemented in the latest update.
+
+---
+
+## Phase 1: Foundation & Core Commands
+
+### 1. Variables System
+A powerful template system for dynamic messages using placeholders.
+
+**Available Variables:**
+- `{ticket.user}` / `{ticket.creator}` - Ticket creator username
+- `{ticket.email}` - Customer email address
+- `{ticket.number}` - Ticket number
+- `{ticket.subject}` - Ticket subject line
+- `{ticket.claimed}` - "Yes" or "No"
+- `{ticket.claimedby}` - Staff member name or "Unclaimed"
+- `{ticket.priority}` - Ticket priority level
+- `{staff.user}` - Staff username
+- `{staff.name}` - Staff display name
+- `{staff.mention}` - Staff mention (@user)
+- `{server.name}` - Discord server name
+- `{server.membercount}` - Server member count
+- `{hours}` - Hours (for auto-messages)
+- `{date}` - Current date
+- `{time}` - Current time
+
+**Usage:** Variables work in tags, welcome messages, and other customizable messages.
+
+---
+
+### 2. Tags/Saved Responses System
+Create, manage, and use saved responses for common questions.
+
+**Commands:**
+- `/response send <name>` - Send a saved response
+- `/response create <name> <content>` - Create new saved response
+- `/response edit <name> <content>` - Edit existing saved response
+- `/response delete <name>` - Delete a saved response
+- `/response list` - List all saved responses
+- `/tag` - Set ticket category (dropdown: Server Down, Billing, Mod Help, etc.); posts categorization message (channel name unchanged)
+
+**Features:**
+- Autocomplete support for response names
+- Usage counter tracking
+- Supports variable substitution
+- Database-backed persistence (MongoDB via Mongoose `Tag` model; see `models.js`)
+
+---
+
+### 3. User Management Commands
+
+#### `/add @user`
+Add a user to the current ticket thread.
+
+**Permissions:** Sets ViewChannel, SendMessages, and ReadMessageHistory for the user.
+
+#### `/remove @user`
+Remove a user from the current ticket thread.
+
+**Behavior:** Deletes the permission overwrite for the user.
+
+---
+
+### 4. `/help` Command
+Displays a comprehensive embed with all available commands, organized by category.
+
+**Categories:**
+- User Management
+- Ticket Management
+- Tags (Saved Responses)
+- Variables
+- Panel System
+- Other
+
+---
+
+## Phase 2: Ticket Management
+
+### 1. `/transfer @staff [reason]`
+Transfer a ticket to another staff member.
+
+**Features:**
+- Validates target has staff role
+- Updates claimed_by in database
+- Logs to logging channel
+- Optional reason parameter
+
+---
+
+### 2. `/move #category`
+Move a ticket to a different category.
+
+**Features:**
+- Preserves permissions (lockPermissions: true)
+- Logs the move
+- Works with any category channel
+
+---
+
+### 3. `/force-close`
+Force close a ticket without confirmation.
+
+**Features:**
+- Generates transcript
+- Updates the external ticket API (if configured)
+- Archives channel after 5 seconds
+- No confirmation required
+
+---
+
+### 4. Close Confirmation System
+When clicking the "Close Ticket" button, users now see a confirmation prompt.
+
+**Flow:**
+1. User clicks "Close Ticket"
+2. Confirmation buttons appear (ephemeral)
+3. User clicks "Confirm Close" or "Cancel"
+4. If confirmed, ticket closes as usual
+
+**Storage:** Close requests are stored in MongoDB. See `models.js` for schema.
+
+---
+
+### 5. `/topic <text>`
+Set the channel topic/description for a ticket.
+
+**Use Cases:**
+- Document ticket status
+- Add important notes
+- Set expectations
+
+---
+
+## Phase 3: UX Enhancements
+
+### 1. Enhanced Claiming System
+
+#### Claim Overwrite
+**Config:** `ALLOW_CLAIM_OVERWRITE=true/false`
+
+When enabled, allows staff to claim tickets already claimed by someone else.
+
+**Behavior:**
+- If disabled: Shows error message when trying to claim someone else's ticket
+- If enabled: Allows claim overwrite, updates claimed_by
+
+#### Auto-Unclaim on Inactivity
+**Config:**
+- `AUTO_UNCLAIM_ENABLED=true/false`
+- `AUTO_UNCLAIM_AFTER_HOURS=24`
+
+Automatically unclaims tickets after specified hours of inactivity.
+
+**Features:**
+- Checks every hour
+- Based on last_activity timestamp
+- Sends notification message in channel
+- Resets claimed_by to NULL
+
+#### Claim Timeout
+**Config:**
+- `CLAIM_TIMEOUT_ENABLED=true/false`
+- `CLAIM_TIMEOUT_HOURS=48`
+
+Set a maximum time for claims (future enhancement placeholder).
+
+---
+
+### 2. Modal Forms for Ticket Creation
+Users can create Discord-side tickets through an interactive modal form.
+
+**Form Fields:**
+- Subject (required, short text, max 100 chars)
+- Description (required, paragraph, max 1000 chars)
+- Priority (optional, low/normal/high)
+
+**Workflow:**
+1. User clicks "Open Ticket" button on panel
+2. Modal appears with form fields
+3. User fills out and submits
+4. Bot creates ticket channel automatically
+
+**Features:**
+- Validates priority input
+- Auto-generates ticket numbers
+- Sets proper permissions
+- Sends welcome message
+- Logs creation
+
+---
+
+### 3. Priority System
+
+#### `/priority <level>`
+Set ticket priority via dropdown: **low**, **normal**, **medium**, or **high** (default: normal).
+
+**Features:**
+- Dropdown choices: 🟢 Low, 🟡 Normal, 🟠 Medium, 🔴 High
+- When priority is set, the channel/thread name is prefixed with the priority emoji
+- Color-coded embeds
+- Database-backed
+- Visible in ticket embeds
+
+**Priority Colors:**
+- High: Red (#FF0000)
+- Normal / Medium: Info color
+- Low: Green (#00FF00)
+
+**Configuration:**
+```env
+PRIORITY_ENABLED=true
+DEFAULT_PRIORITY=normal
+PRIORITY_HIGH_EMOJI=🔴
+PRIORITY_MEDIUM_EMOJI=🟡
+PRIORITY_LOW_EMOJI=🟢
+```
+
+---
+
+## Phase 4: Panel & Category System
+
+### 1. Panel System
+
+#### `/panel #channel [title] [description]`
+Create a ticket panel that users can interact with to open tickets.
+
+**Features:**
+- Customizable title and description
+- "Open Ticket" button
+- Sends modal form on click
+- Creates Discord-only tickets
+
+**Example Panel:**
+```
+Title: Open a Support Ticket
+Description: Click the button below to create a new support ticket. 
+            A staff member will assist you shortly.
+[🎫 Open Ticket]
+```
+
+---
+
+### 2. Discord-Side Tickets
+Tickets created through panels are Discord-only (no email integration).
+
+**Features:**
+- Stored in same tickets table
+- gmail_thread_id uses format: `discord-{timestamp}-{userId}`
+- sender_email contains Discord tag
+- Full feature parity with email tickets
+
+---
+
+### 3. Category System
+The bot now supports multiple categories through the `/move` command.
+
+**Features:**
+- Move tickets between categories
+- Preserves permissions
+- Works with both email and Discord tickets
+
+---
+
+### 4. Thread-Style Tickets
+**Config:**
+- `USE_THREADS=true/false`
+- `THREAD_PARENT_CHANNEL=<channel_id>`
+
+When enabled, creates tickets as threads instead of channels.
+
+**Benefits:**
+- Cleaner server structure
+- No channel limit concerns
+- Better organization
+
+**Note:** Implementation ready for future activation.
+
+---
+
+## Phase 5: Automation (Future Enhancement)
+
+### Automation Rules Engine
+A framework for creating custom automation rules.
+
+**Planned Features:**
+- Trigger-based actions
+- Condition matching
+- Custom workflows
+- Schedule support
+
+**Example Rules:**
+- Auto-assign based on keywords
+- Auto-tag based on content
+- Auto-escalate high priority
+- Auto-move based on game/topic
+
+**Note:** Foundation in place, specific rules to be implemented based on needs.
+
+---
+
+## Database Schema
+
+The project uses MongoDB. Ticket, tag, and close-request data are defined in `models.js`. See that file and `MONGODB_SETUP.md` for schema reference.
+
+---
+
+## Configuration Reference
+
+### New Environment Variables
+
+```env
+# --- CLAIMING OPTIONS ---
+CLAIM_TIMEOUT_ENABLED=false
+CLAIM_TIMEOUT_HOURS=48
+AUTO_UNCLAIM_ENABLED=false
+AUTO_UNCLAIM_AFTER_HOURS=24
+ALLOW_CLAIM_OVERWRITE=false
+
+# --- THREAD-STYLE TICKETS ---
+USE_THREADS=false
+THREAD_PARENT_CHANNEL=
+```
+
+---
+
+## Complete Command Reference
+
+### User Management
+- `/add @user` - Add user to ticket
+- `/remove @user` - Remove user from ticket
+
+### Ticket Management
+- `/transfer @staff [reason]` - Transfer ticket to another staff member
+- `/move #category` - Move ticket to another category
+- `/force-close` - Force close without confirmation
+- `/topic <text>` - Set channel topic
+- `/priority <level>` - Set ticket priority (low/normal/medium/high); renames channel with priority emoji
+- `/escalate [reason] [tier]` - Escalate ticket to tier 2 or 3
+- `/deescalate` - De-escalate ticket
+
+### Tags / Saved Responses
+- `/response send <name>` - Send saved response
+- `/response create <name> <content>` - Create new saved response
+- `/response edit <name> <content>` - Edit existing saved response
+- `/response delete <name>` - Delete saved response
+- `/response list` - List all saved responses
+- `/tag` - Set ticket category (dropdown)
+
+### Panel System
+- `/panel #channel [title] [description]` - Create ticket panel
+
+### Help
+- `/help` - Show all commands
+
+---
+
+## Migration Notes
+
+### From Previous Version
+
+1. **Database**: New Mongoose schema fields used on startup (collections created as needed)
+   - priority, last_activity, reminder_sent on Ticket
+
+2. **New collections**: Created automatically by Mongoose
+   - Tag (saved responses)
+   - CloseRequest
+
+3. **Environment Variables**: Add to `.env` (repo root):
+   ```env
+   CLAIM_TIMEOUT_ENABLED=false
+   AUTO_UNCLAIM_ENABLED=false
+   ALLOW_CLAIM_OVERWRITE=false
+   USE_THREADS=false
+   ```
+
+4. **No Breaking Changes**: All existing functionality preserved
+
+---
+
+## Best Practices
+
+### Tags
+- Use descriptive names (e.g., `welcome`, `closing`, `escalation-info`)
+- Include variables for personalization
+- Keep content concise but helpful
+- Review and update regularly
+
+### Priority System
+- Set priority early in ticket lifecycle
+- Use high priority sparingly
+- Review priority regularly
+- Consider SLA based on priority
+
+### Panels
+- Place in dedicated support channels
+- Use clear, welcoming language
+- Include instructions
+- Monitor for spam/abuse
+
+### Claiming
+- Enable auto-unclaim to prevent stale claims
+- Set reasonable timeout periods
+- Use overwrite cautiously
+- Communicate with team about transfers
+
+---
+
+## Troubleshooting
+
+### Commands Not Appearing
+- Verify `DISCORD_APPLICATION_ID` is set
+- Check bot has application.commands scope
+- Wait up to 1 hour for Discord to sync
+- Restart bot after .env changes
+
+### Modal Not Showing
+- Ensure user has Create Posts permission
+- Check for Discord outages
+- Verify bot has proper permissions
+
+### Saved Responses Not Working
+- Check MongoDB connection and permissions
+- Use `/response list` to confirm saved response exists
+- Check for errors in saved response content
+
+### Priority Not Updating
+- Verify ticket exists in database
+- Check PRIORITY_ENABLED is true
+- Ensure valid priority value (low/normal/high)
+
+---
+
+## Performance Considerations
+
+### Database
+- MongoDB (Mongoose) for all persistent data
+- Regular backups recommended
+- Run from repo root; `.env` in repo root
+
+### Auto-Checks
+- Auto-close: Runs every hour
+- Auto-unclaim: Runs every hour
+- Reminders: Runs every 30 minutes
+- Adjust intervals in code if needed
+
+### Rate Limits
+- Channel creation: 50/day per guild
+- Channel rename: 2 per 10 minutes per channel ([Discord docs](https://discord.com/developers/docs/topics/rate-limits)). When the limit is reached, the bot skips the rename and posts: *Channel renamed too quickly. Try again \<t:unlock:R\>.*
+- Message edits: Be cautious with bulk operations
+
+---
+
+## Future Enhancements
+
+### Planned Features
+1. **Statistics Dashboard**: Track ticket metrics
+2. **Feedback System**: Collect user ratings
+3. **Advanced Automations**: Rule builder UI
+4. **Ticket Templates**: Pre-filled forms
+5. **SLA Tracking**: Response time monitoring
+6. **Multi-language**: Localization support
+7. **Web Dashboard**: View tickets in browser
+8. **API Endpoints**: External integrations
+
+### Community Requests
+- Custom ticket categories per game
+- User blacklist system
+- Scheduled availability hours
+- Ticket assignment rotation
+- Knowledge base integration
+
+---
+
+## Support & Contributing
+
+### Getting Help
+- Check documentation first
+- Review troubleshooting section
+- Check logs for error messages
+- Test with minimal configuration
+
+### Reporting Bugs
+Include:
+- Steps to reproduce
+- Expected behavior
+- Actual behavior
+- Environment details
+- Log excerpts
+
+### Feature Requests
+Consider:
+- Use case description
+- Priority/importance
+- Potential workarounds
+- Similar existing features
+
+---
+
+## Changelog
+
+### v2.0.0 - Major Feature Update
+**Added:**
+- Variables system for dynamic messages
+- Tags/saved responses system
+- User management commands (/add, /remove)
+- Transfer, move, force-close commands
+- Close confirmation flow
+- Enhanced claiming (overwrite, auto-unclaim)
+- Modal forms for ticket creation
+- Priority system
+- Panel system for Discord tickets
+- Thread-style tickets option
+- Comprehensive /help command
+
+**Improved:**
+- Database schema with new fields
+- Permission handling
+- Error messages
+- Logging
+
+**Fixed:**
+- Various edge cases
+- Permission issues
+- Database constraints
+
+---
+
+*Last Updated: 2025*
+*Version: 2.0.0*