Add comprehensive Copilot instructions for Part-DB

Co-authored-by: jbtronics <[email protected]>

Author: Copilot

.github/copilot-instructions.md

@@ -0,0 +1,188 @@
+# Copilot Instructions for Part-DB
+
+Part-DB is an Open-Source inventory management system for electronic components built with Symfony 6 and modern web technologies.
+
+## Technology Stack
+
+- **Backend**: PHP 8.2+, Symfony 7.4, Doctrine ORM
+- **Frontend**: Bootstrap 5, Hotwire Stimulus/Turbo, TypeScript, Webpack Encore
+- **Database**: MySQL 5.7+/MariaDB 10.4+/PostgreSQL 10+/SQLite
+- **Testing**: PHPUnit with DAMA Doctrine Test Bundle
+- **Code Quality**: Easy Coding Standard (ECS), PHPStan (level 5)
+
+## Project Structure
+
+- `src/`: PHP application code organized by purpose (Controller, Entity, Service, Form, etc.)
+- `assets/`: Frontend TypeScript/JavaScript and CSS files
+- `templates/`: Twig templates for views
+- `tests/`: PHPUnit tests mirroring the `src/` structure
+- `config/`: Symfony configuration files
+- `public/`: Web-accessible files
+- `translations/`: Translation files for multi-language support
+
+## Coding Standards
+
+### PHP Code
+
+- Follow [PSR-12](https://www.php-fig.org/psr/psr-12/) and [Symfony coding standards](https://symfony.com/doc/current/contributing/code/standards.html)
+- Use type hints for all parameters and return types
+- Always declare strict types: `declare(strict_types=1);` at the top of PHP files
+- Use PHPDoc blocks for complex logic or when type information is needed
+- Check code style with: `vendor/bin/ecs check src/` or `vendor/bin/ecs check tests/`
+- Fix violations with: `vendor/bin/ecs check src/ --fix`
+
+### TypeScript/JavaScript
+
+- Use TypeScript for new frontend code
+- Follow existing Stimulus controller patterns in `assets/controllers/`
+- Use Bootstrap 5 components and utilities
+- Leverage Hotwire Turbo for dynamic page updates
+
+### Naming Conventions
+
+- Entities: Use descriptive names that reflect database models (e.g., `Part`, `StorageLocation`)
+- Controllers: Suffix with `Controller` (e.g., `PartController`)
+- Services: Descriptive names reflecting their purpose (e.g., `PartService`, `LabelGenerator`)
+- Tests: Match the class being tested with `Test` suffix (e.g., `PartTest`, `PartControllerTest`)
+
+## Development Workflow
+
+### Dependencies
+
+- Install PHP dependencies: `composer install`
+- Install JS dependencies: `yarn install`
+- Build frontend assets: `yarn build` (production) or `yarn watch` (development)
+
+### Database
+
+- Create database: `php bin/console doctrine:database:create --env=dev`
+- Run migrations: `php bin/console doctrine:migrations:migrate --env=dev`
+- Load fixtures: `php bin/console partdb:fixtures:load --env=dev`
+
+Or use Makefile shortcuts:
+- `make dev-setup`: Complete development environment setup
+- `make dev-reset`: Reset development environment (cache clear + migrate)
+
+### Testing
+
+- Set up test environment: `make test-setup`
+- Run all tests: `php bin/phpunit`
+- Run specific test: `php bin/phpunit tests/Path/To/SpecificTest.php`
+- Run tests with coverage: `php bin/phpunit --coverage-html var/coverage`
+- Test environment uses SQLite by default for speed
+
+### Static Analysis
+
+- Run PHPStan: `composer phpstan` or `COMPOSER_MEMORY_LIMIT=-1 php -d memory_limit=1G vendor/bin/phpstan analyse src --level 5`
+- PHPStan configuration is in `phpstan.dist.neon`
+
+### Running the Application
+
+- Development server: `symfony serve` (requires Symfony CLI)
+- Or configure Apache/nginx to serve from `public/` directory
+- Set `APP_ENV=dev` in `.env.local` for development mode
+
+## Best Practices
+
+### Security
+
+- Always sanitize user input
+- Use Symfony's security component for authentication/authorization
+- Check permissions using the permission system before allowing actions
+- Never expose sensitive data in logs or error messages
+- Use parameterized queries (Doctrine handles this automatically)
+
+### Performance
+
+- Use Doctrine query builder for complex queries instead of DQL when possible
+- Lazy load relationships to avoid N+1 queries
+- Cache results when appropriate using Symfony's cache component
+- Use pagination for large result sets (DataTables integration available)
+
+### Database
+
+- Always create migrations for schema changes: `php bin/console make:migration`
+- Review migration files before running them
+- Use Doctrine annotations or attributes for entity mapping
+- Follow existing entity patterns for relationships and lifecycle callbacks
+
+### Frontend
+
+- Use Stimulus controllers for interactive components
+- Leverage Turbo for dynamic page updates without full page reloads
+- Use Bootstrap 5 classes for styling
+- Keep JavaScript modular and organized in controllers
+- Use the translation system for user-facing strings
+
+### Translations
+
+- Use translation keys, not hardcoded strings: `{{ 'part.info.title'|trans }}`
+- Add new translation keys to `translations/` files
+- Primary language is English (en)
+- Translations are managed via Crowdin, but can be edited locally if needed
+
+### Testing
+
+- Write unit tests for services and helpers
+- Write functional tests for controllers
+- Use fixtures for test data
+- Tests should be isolated and not depend on execution order
+- Mock external dependencies when appropriate
+- Follow existing test patterns in the repository
+
+## Common Patterns
+
+### Creating an Entity
+
+1. Create entity class in `src/Entity/` with Doctrine attributes
+2. Generate migration: `php bin/console make:migration`
+3. Review and run migration: `php bin/console doctrine:migrations:migrate`
+4. Create repository if needed in `src/Repository/`
+5. Add fixtures in `src/DataFixtures/` for testing
+
+### Adding a Form
+
+1. Create form type in `src/Form/`
+2. Extend `AbstractType` and implement `buildForm()` and `configureOptions()`
+3. Use in controller and render in Twig template
+4. Follow existing form patterns for consistency
+
+### Creating a Controller Action
+
+1. Add method to appropriate controller in `src/Controller/`
+2. Use route attributes for routing
+3. Check permissions using security voters
+4. Return Response or render Twig template
+5. Add corresponding template in `templates/`
+
+### Adding a Service
+
+1. Create service class in `src/Services/`
+2. Use dependency injection via constructor
+3. Tag service in `config/services.yaml` if needed
+4. Services are autowired by default
+
+## Important Notes
+
+- Part-DB uses fine-grained permissions - always check user permissions before actions
+- Multi-language support is critical - use translation keys everywhere
+- The application supports multiple database backends - write portable code
+- Responsive design is important - test on mobile/tablet viewports
+- Event system is used for logging changes - emit events when appropriate
+- API Platform is integrated for REST API endpoints
+
+## Multi-tenancy Considerations
+
+- Part-DB is designed as a single-tenant application with multiple users
+- User groups have different permission levels
+- Always scope queries to respect user permissions
+- Use the security context to get current user information
+
+## Resources
+
+- [Documentation](https://docs.part-db.de/)
+- [Contributing Guide](CONTRIBUTING.md)
+- [Symfony Documentation](https://symfony.com/doc/current/index.html)
+- [Doctrine Documentation](https://www.doctrine-project.org/projects/doctrine-orm/en/current/)
+- [Bootstrap 5 Documentation](https://getbootstrap.com/docs/5.1/)
+- [Hotwire Documentation](https://hotwired.dev/)