Add development documentation and task tracking
- CLAUDE.md: Comprehensive development guide documenting patterns, conventions, and project structure - TODO.md: Organized task list with completed items, bugs, enhancements, and feature ideas - Both files provide context for future AI-assisted development sessions - Includes testing procedures, coding standards, and architectural decisions 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
megaproxy
parent
c8cb99a4d0
commit
f8ac661cd1
2 changed files with 503 additions and 0 deletions
296
CLAUDE.md
Normal file
296
CLAUDE.md
Normal file
|
|
@ -0,0 +1,296 @@
|
|||
# CLAUDE.md - PetBot Development Guide
|
||||
|
||||
This file documents the development patterns, conventions, and best practices established for the PetBot project during AI-assisted development.
|
||||
|
||||
## Project Overview
|
||||
|
||||
PetBot is a Discord/IRC Pokemon-style pet collecting bot with web interface. The project consists of:
|
||||
- IRC bot with modular command system
|
||||
- Web server with unified navigation and interactive interfaces
|
||||
- SQLite database with comprehensive pet, player, and game state management
|
||||
- Team builder with drag-and-drop functionality and PIN verification
|
||||
|
||||
## Development Workflow
|
||||
|
||||
### 1. Planning and Task Management
|
||||
- Use TodoWrite tool for complex multi-step tasks (3+ steps)
|
||||
- Break down large features into specific, actionable items
|
||||
- Mark todos as `in_progress` before starting work
|
||||
- Complete todos immediately after finishing tasks
|
||||
- Don't batch completions - update status in real-time
|
||||
|
||||
### 2. Code Analysis and Search
|
||||
- Use Task tool for keyword searches and file discovery
|
||||
- Use Grep tool for specific code patterns and function definitions
|
||||
- Use Read tool for examining specific file content
|
||||
- Use Glob tool for finding files by name patterns
|
||||
|
||||
### 3. Testing and Validation
|
||||
- Always run `python3 -c "import webserver; print('✅ syntax check')"` after webserver changes
|
||||
- Test database operations with simple validation scripts
|
||||
- Check IRC bot functionality with `python3 run_bot_debug.py`
|
||||
- Verify web interface functionality through browser testing
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
/home/megaproxy/petbot/
|
||||
├── src/ # Core system components
|
||||
│ ├── database.py # Database operations and schema
|
||||
│ ├── game_engine.py # Game mechanics and weather system
|
||||
│ └── bot.py # IRC bot core functionality
|
||||
├── modules/ # Command modules (modular architecture)
|
||||
│ ├── base_module.py # Abstract base class for all modules
|
||||
│ ├── core_commands.py # Basic bot commands (!start, !help, !stats)
|
||||
│ ├── exploration.py # !explore, !travel, !weather commands
|
||||
│ ├── battle_system.py # !battle, !attack, !moves, !flee commands
|
||||
│ ├── pet_management.py # !pets, !activate, !deactivate commands
|
||||
│ ├── inventory.py # !inventory, !use commands (redirects to web)
|
||||
│ ├── gym_battles.py # !gym commands and gym mechanics
|
||||
│ ├── achievements.py # Achievement tracking and validation
|
||||
│ ├── admin.py # Administrative commands
|
||||
│ └── team_builder.py # Team builder module (web-only)
|
||||
├── webserver.py # Web server with unified templates
|
||||
├── run_bot_debug.py # Bot startup and debug mode
|
||||
├── help.html # Static help documentation
|
||||
├── CHANGELOG.md # Version history and feature tracking
|
||||
└── README.md # Project documentation
|
||||
```
|
||||
|
||||
## Coding Conventions
|
||||
|
||||
### 1. Module Architecture
|
||||
- All command modules inherit from `BaseModule`
|
||||
- Implement `get_commands()` and `handle_command()` methods
|
||||
- Use `self.normalize_input()` for case-insensitive command processing
|
||||
- Use `self.send_message()` for IRC responses
|
||||
- Use `await self.require_player()` for player validation
|
||||
|
||||
### 2. Database Operations
|
||||
- All database methods are async
|
||||
- Use proper error handling with try/catch blocks
|
||||
- Always use parameterized queries to prevent SQL injection
|
||||
- Implement proper transaction handling for complex operations
|
||||
- Use `team_order` column for numbered team slots (1-6)
|
||||
|
||||
### 3. Web Interface Development
|
||||
- Use unified template system with `get_page_template()`
|
||||
- Implement CSS variables for consistent theming
|
||||
- Add proper navigation bar to all pages
|
||||
- Use center alignment: `max-width: 1200px; margin: 0 auto`
|
||||
- Implement drag-and-drop with proper event handlers
|
||||
- Add double-click backup methods for accessibility
|
||||
|
||||
### 4. Security Practices
|
||||
- Use PIN verification for sensitive operations (team changes)
|
||||
- Send PINs via IRC private messages
|
||||
- Implement proper session validation
|
||||
- Never log or expose sensitive data
|
||||
- Use parameterized database queries
|
||||
|
||||
## Key Development Patterns
|
||||
|
||||
### 1. Command Redirection Pattern
|
||||
```python
|
||||
async def cmd_inventory(self, channel, nickname):
|
||||
"""Redirect player to their web profile for inventory management"""
|
||||
player = await self.require_player(channel, nickname)
|
||||
if not player:
|
||||
return
|
||||
|
||||
# Redirect to web interface for better experience
|
||||
self.send_message(channel, f"🎒 {nickname}: View your complete inventory at: http://petz.rdx4.com/player/{nickname}#inventory")
|
||||
```
|
||||
|
||||
### 2. State Management Pattern
|
||||
```python
|
||||
async def cmd_explore(self, channel, nickname):
|
||||
# Check if player has an active encounter that must be resolved first
|
||||
if player["id"] in self.bot.active_encounters:
|
||||
current_encounter = self.bot.active_encounters[player["id"]]
|
||||
self.send_message(channel, f"{nickname}: You must resolve your active encounter first!")
|
||||
return
|
||||
```
|
||||
|
||||
### 3. Drag-and-Drop Implementation Pattern
|
||||
```javascript
|
||||
// Initialize when DOM is ready
|
||||
document.addEventListener('DOMContentLoaded', function() {
|
||||
initializeTeamBuilder();
|
||||
});
|
||||
|
||||
function initializeTeamBuilder() {
|
||||
// Initialize drag and drop
|
||||
initializeDragAndDrop();
|
||||
|
||||
// Initialize double-click backup
|
||||
initializeDoubleClick();
|
||||
|
||||
// Update save button state
|
||||
updateSaveButton();
|
||||
}
|
||||
```
|
||||
|
||||
### 4. PIN Verification Pattern
|
||||
```python
|
||||
async def saveTeam():
|
||||
# Send team data to server
|
||||
response = await fetch('/teambuilder/{nickname}/save', {
|
||||
method: 'POST',
|
||||
headers: { 'Content-Type': 'application/json' },
|
||||
body: JSON.stringify(teamData)
|
||||
});
|
||||
|
||||
# PIN sent via IRC, show verification interface
|
||||
if (result.success) {
|
||||
document.getElementById('pin-section').style.display = 'block';
|
||||
}
|
||||
```
|
||||
|
||||
## Database Schema Conventions
|
||||
|
||||
### 1. Player Management
|
||||
- `players` table with basic player information
|
||||
- `pets` table with `team_order` column for numbered slots (1-6)
|
||||
- `player_items` table for inventory management
|
||||
- `pending_team_changes` table for PIN verification
|
||||
|
||||
### 2. Game State Management
|
||||
- Use `is_active` boolean for team membership
|
||||
- Use `team_order` (1-6) for slot positioning
|
||||
- Store encounter state in bot memory, not database
|
||||
- Use timestamps for PIN expiration
|
||||
|
||||
## Web Interface Conventions
|
||||
|
||||
### 1. Unified Template System
|
||||
```python
|
||||
def get_page_template(self, title, content, active_page):
|
||||
return f"""
|
||||
<!DOCTYPE html>
|
||||
<html>
|
||||
<head>
|
||||
<title>{title}</title>
|
||||
<style>{self.get_unified_css()}</style>
|
||||
</head>
|
||||
<body>
|
||||
{self.get_navigation_bar(active_page)}
|
||||
<div class="main-container">
|
||||
{content}
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
"""
|
||||
```
|
||||
|
||||
### 2. Navigation Integration
|
||||
- All pages include unified navigation bar
|
||||
- Use hover dropdowns for sub-navigation
|
||||
- Highlight active page in navigation
|
||||
- Include jump points for direct section linking (#inventory, #pets)
|
||||
|
||||
### 3. Interactive Elements
|
||||
- Implement proper drag-and-drop with visual feedback
|
||||
- Add loading states and error handling
|
||||
- Use consistent button styling and interactions
|
||||
- Provide alternative interaction methods (double-click)
|
||||
|
||||
## Testing and Debugging
|
||||
|
||||
### 1. Component Testing
|
||||
```bash
|
||||
# Test webserver syntax
|
||||
python3 -c "import webserver; print('✅ webserver.py syntax is correct')"
|
||||
|
||||
# Test database operations
|
||||
python3 -c "from src.database import Database; db = Database(); print('✅ database imports')"
|
||||
|
||||
# Test bot startup
|
||||
python3 run_bot_debug.py
|
||||
```
|
||||
|
||||
### 2. Web Interface Testing
|
||||
- Test drag-and-drop functionality in browser
|
||||
- Verify PIN delivery via IRC
|
||||
- Check responsive design and center alignment
|
||||
- Validate form submissions and error handling
|
||||
|
||||
### 3. Git Workflow
|
||||
- Create descriptive commit messages explaining changes
|
||||
- Group related changes into logical commits
|
||||
- Include "🤖 Generated with [Claude Code]" attribution
|
||||
- Push changes with `git push` after testing
|
||||
|
||||
## Common Issues and Solutions
|
||||
|
||||
### 1. CSS in JavaScript Templates
|
||||
**Problem**: F-string braces conflict with CSS braces
|
||||
**Solution**: Use string concatenation instead of f-strings for CSS content
|
||||
|
||||
### 2. Drag-and-Drop Not Working
|
||||
**Problem**: JavaScript initialization timing issues
|
||||
**Solution**: Use `DOMContentLoaded` event and proper DOM element checking
|
||||
|
||||
### 3. IRC PIN Not Sent
|
||||
**Problem**: Bot instance not accessible from webserver
|
||||
**Solution**: Pass bot instance to webserver constructor and add proper IRC message methods
|
||||
|
||||
### 4. Database Schema Changes
|
||||
**Problem**: Adding new columns to existing tables
|
||||
**Solution**: Use proper migration pattern with ALTER TABLE statements
|
||||
|
||||
## Performance Considerations
|
||||
|
||||
### 1. Database Operations
|
||||
- Use connection pooling for high-traffic scenarios
|
||||
- Implement proper indexing for frequently queried columns
|
||||
- Use transactions for multi-step operations
|
||||
- Cache frequently accessed data when appropriate
|
||||
|
||||
### 2. Web Interface
|
||||
- Minimize CSS and JavaScript for faster loading
|
||||
- Use efficient DOM manipulation techniques
|
||||
- Implement proper error handling and loading states
|
||||
- Optimize images and static assets
|
||||
|
||||
## Future Development Guidelines
|
||||
|
||||
### 1. Adding New Commands
|
||||
1. Create method in appropriate module
|
||||
2. Add command to `get_commands()` list
|
||||
3. Implement proper error handling
|
||||
4. Update help documentation
|
||||
5. Test thoroughly before committing
|
||||
|
||||
### 2. Web Interface Enhancements
|
||||
1. Follow unified template system
|
||||
2. Implement proper responsive design
|
||||
3. Add accessibility features
|
||||
4. Test across different browsers
|
||||
5. Update navigation if adding new pages
|
||||
|
||||
### 3. Database Schema Updates
|
||||
1. Plan migrations carefully
|
||||
2. Test with existing data
|
||||
3. Document schema changes
|
||||
4. Update related code components
|
||||
5. Consider backward compatibility
|
||||
|
||||
## Resources and References
|
||||
|
||||
- **IRC Bot Framework**: Custom implementation based on socket programming
|
||||
- **Web Server**: Python's built-in HTTPServer with custom request handling
|
||||
- **Database**: SQLite with aiosqlite for async operations
|
||||
- **Frontend**: Vanilla JavaScript with modern ES6+ features
|
||||
- **CSS Framework**: Custom CSS with CSS variables for theming
|
||||
|
||||
## Notes for Future Development
|
||||
|
||||
- Maintain modular architecture for easy feature additions
|
||||
- Keep web interface and IRC commands in sync
|
||||
- Document all major changes in CHANGELOG.md
|
||||
- Use consistent error messages and user feedback
|
||||
- Test thoroughly before pushing to production
|
||||
- Consider security implications for all user interactions
|
||||
|
||||
This documentation should be updated as the project evolves to maintain accuracy and usefulness for future development efforts.
|
||||
Loading…
Add table
Add a link
Reference in a new issue