intershop-icm-best-practices

# Intershop ICM Best Practices Comprehensive best practices guide for Intershop Commerce Management (ICM) backend development, maintained by Intershop Engineering. Contains 68 rules across 20 categories, prioritized by impact to guide automated refactoring and code generation. ## When to Apply Reference these guidelines when: - Developing custom ICM cartridges - Creating or modifying REST API endpoints - Implementing B2B features (punchout, customer pricing, organizations, quotes, budgets) - Working with business objects and persistent objects - Writing pipelets and pipelines - Performing database initialization or migration - Implementing batch jobs and event handling - Customizing Solr search - Adding security measures - Writing tests - Deploying to Kubernetes environments ## Rule Categories by Priority | Priority | Category | Impact | Prefix | |----------|----------|--------|--------| | 1 | Customization Patterns | CRITICAL | `custom-` | | 2 | Performance Optimization | CRITICAL | `perf-` | | 3 | State Management & Data Flow | CRITICAL | `state-` | | 4 | B2B Features | CRITICAL | `b2b-` | | 5 | Security | CRITICAL | `security-` | | 6 | REST API Development | HIGH | `rest-` | | 7 | Cartridge Architecture | HIGH | `cartridge-` | | 8 | Testing | HIGH | `test-` | | 9 | Search | HIGH | `search-` | | 10 | Internationalization | HIGH | `i18n-` | | 11 | Monitoring & Observability | HIGH | `monitoring-` | | 12 | Database & Persistence | MEDIUM-HIGH | `db-` | | 13 | Pipeline & Pipelet Development | MEDIUM | `pipeline-` | | 14 | Dependency Injection & Guice | MEDIUM | `guice-` | | 15 | Job & Batch Processing | MEDIUM | `job-` | | 16 | Events & Messaging | MEDIUM | `event-` | | 17 | ImpEx Data Exchange | MEDIUM | `impex-` | | 18 | Logging & Observability | MEDIUM | `logging-` | | 19 | ISML Templates | MEDIUM | `template-` | | 20 | Deployment & DevOps | LOW-MEDIUM | `devops-` | ## Quick Reference ### 1. Customization Patterns (CRITICAL) - `custom-no-direct-modification` - Never modify standard files directly - `custom-use-extensions` - Use business object extensions for custom behavior - `custom-cartridge-naming` - Follow layer-based cartridge naming conventions - `custom-mark-changes` - Mark all customizations with comments - `custom-microservices` - Prefer microservices for complex customizations ### 2. Performance Optimization (CRITICAL) - `perf-caching-pattern` - Use caching for expensive operations - `perf-query-optimization` - Optimize database queries, avoid N+1 - `perf-async-operations` - Use async processing for non-critical ops - `perf-lazy-loading` - Use lazy loading with explicit fetch joins - `perf-batch-processing` - Batch operations with flush/clear pattern - `perf-connection-pooling` - Configure database connection pools properly - `perf-memory-management` - Manage memory efficiently, stream large data - `perf-session-size` - Minimize session size for scalability ### 3. State Management & Data Flow (CRITICAL) - `state-repository-pattern` - Use repositories for BO lifecycle management - `state-bo-po-separation` - Maintain strict BO/PO separation ### 4. B2B Features (CRITICAL) - `b2b-punchout-implementation` - Implement punchout with proper security - `b2b-customer-pricing` - Implement customer-specific pricing correctly - `b2b-organization-hierarchy` - Manage organization hierarchies - `b2b-approval-workflows` - Implement approval workflows with audit - `b2b-budget-management` - Implement budget controls at multiple levels - `b2b-quote-management` - Manage quotes with state machine and versioning - `b2b-user-roles` - Implement flexible RBAC with delegation ### 5. Security (CRITICAL) - `security-input-validation` - Validate all inputs with JSR-303 - `security-sql-injection` - Use parameterized queries - `security-xss-prevention` - Use proper output encoding - `security-sensitive-data` - Handle PII properly - `security-access-control` - Implement RBAC correctly - `security-csrf-protection` - Implement CSRF token validation ### 6. REST API Development (HIGH) - `rest-authentication` - Authenticate REST resources like server actions - `rest-resource-objects` - Use proper resource object patterns - `rest-handlers` - Use handlers for customizable REST resources - `rest-pagination` - Implement proper pagination with metadata - `rest-error-handling` - Use consistent error response format - `rest-versioning` - Version APIs with URL path versioning - `rest-hateoas` - Implement HATEOAS links properly ### 7. Cartridge Architecture (HIGH) - `cartridge-api-separation` - Separate API and implementation cartridges ### 8. Testing (HIGH) - `test-unit-test-services` - Unit test services with mocking - `test-integration-pipelines` - Integration test pipelines - `test-mock-repositories` - Mock repositories correctly - `test-test-data-builders` - Use test data builders - `test-rest-api-testing` - Test REST APIs comprehensively ### 9. Search (HIGH) - `search-solr-customization` - Customize Solr search correctly - `search-query-building` - Build search queries safely ### 10. Database & Persistence (MEDIUM-HIGH) - `db-dbprepare-migration` - Use DBPrepare for initialization and migration - `db-transaction-management` - Manage transactions properly - `db-optimistic-locking` - Use optimistic locking for concurrency - `db-po-lifecycle` - Manage PO lifecycle correctly ### 11. Pipeline & Pipelet Development (MEDIUM) - `pipeline-best-practices` - Follow pipeline design best practices - `pipeline-error-handling` - Handle errors with transitions - `pipeline-transactions` - Manage pipeline transactions correctly ### 12. Dependency Injection & Guice (MEDIUM) - `guice-dependency-injection` - Use Guice dependency injection correctly ### 13. Job & Batch Processing (MEDIUM) - `job-implementation` - Implement jobs with progress tracking - `job-error-handling` - Handle job errors with retry and DLQ ### 14. Events & Messaging (MEDIUM) - `event-publishing` - Publish domain events properly - `event-consuming` - Consume events reliably with idempotency ### 15. ImpEx Data Exchange (MEDIUM) - `impex-import-patterns` - Implement imports with streaming and validation - `impex-export-patterns` - Implement exports with delta support ### 16. Logging & Observability (MEDIUM) - `logging-structured-logging` - Use structured logging - `logging-correlation-ids` - Use correlation IDs - `logging-log-levels` - Use appropriate log levels - `logging-no-sensitive-data` - Never log sensitive data ### 17. ISML Templates (MEDIUM) - `template-isml-best-practices` - Follow ISML coding standards - `template-include-patterns` - Use includes properly - `template-loop-optimization` - Optimize loops - `template-caching` - Use fragment caching ### 18. Deployment & DevOps (LOW-MEDIUM) - `devops-container-deployment` - Follow container deployment best practices ### 19. Internationalization (HIGH) - `i18n-localization` - Implement proper multi-language and multi-locale support ### 20. Monitoring & Observability (HIGH) - `monitoring-apm-integration` - Integrate APM for performance and error tracking ## Core Principles ### The Golden Rule: No Customization is Best Before writing any custom code, always check: 1. Can this be achieved through back office configuration? 2. Is there an existing Intershop feature that meets this need? 3. Is this feature request standard-worthy (contact Intershop)? ### Upgrade Safety All customizations should be designed with upgrades in mind: - Use extension mechanisms over file modifications - Mark all changes with standardized comments - Keep custom cartridges separate from standard ones - Prefer microservices for complex integrations ### Layer Separation Maintain clear boundaries between layers: - **API (capi)** - Public interfaces only - **Internal** - Implementation details - **ORM** - Database persistence - **Pipeline** - Business workflows ## How to Use Read individual rule files for detailed explanations and code examples: ``` rules/custom-use-extensions.md rules/perf-caching-pattern.md rules/b2b-punchout-implementation.md rules/security-input-validation.md rules/test-unit-test-services.md ``` Each rule file contains: - Brief explanation of why it matters - Incorrect code example with explanation - Correct code example with explanation - Additional context and references ## Full Compiled Document For the complete guide with all rules expanded: `AGENTS.md`