docs: Clarify behavior difference between Cacheable and non-Cacheable classes

- Explain automatic binding for Cacheable classes (CommandInterceptor)
- Explain explicit attribute requirement for non-Cacheable classes (RefreshInterceptor)
- Cross-reference related interceptors in documentation
- Address review comment: #167 (comment)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: koriym

src-annotation/Purge.php

@@ -9,17 +9,19 @@
 /**
  * Purges cache for specified URI after command execution
  *
+ * Behavior differs based on class attributes:
+ * - **#[Cacheable] classes**: CommandInterceptor automatically binds to all
+ *   command methods (onPut/onPatch/onDelete) and processes #[Purge] annotations
+ * - **Non-Cacheable classes**: RefreshInterceptor binds only to methods explicitly
+ *   marked with #[Purge] or #[Refresh]
+ *
  * Example:
  * ```php
  * #[Purge(uri: 'app://self/user/profile?user_id={id}')]
  * #[Purge(uri: 'app://self/user/friend?user_id={id}')]
  * public function onDelete(int $id): static
  * ```
  *
- * Interceptors bound:
- * - RefreshInterceptor (when applied to non-Cacheable classes)
- * - CommandInterceptor (when applied to Cacheable classes)
- *
  * @see https://bearsunday.github.io/manuals/1.0/en/cache.html#tag-based-cache-invalidation
  */
 #[Attribute(Attribute::TARGET_METHOD | Attribute::IS_REPEATABLE)]

src-annotation/Refresh.php

@@ -9,16 +9,18 @@
 /**
  * Refreshes cache for specified URI after command execution
  *
+ * Behavior differs based on class attributes:
+ * - **#[Cacheable] classes**: CommandInterceptor automatically binds to all
+ *   command methods (onPut/onPatch/onDelete) and processes #[Refresh] annotations
+ * - **Non-Cacheable classes**: RefreshInterceptor binds only to methods explicitly
+ *   marked with #[Purge] or #[Refresh]
+ *
  * Example:
  * ```php
  * #[Refresh(uri: 'app://self/user/profile?user_id={id}')]
  * public function onPut(int $id, string $name): static
  * ```
  *
- * Interceptors bound:
- * - RefreshInterceptor (when applied to non-Cacheable classes)
- * - CommandInterceptor (when applied to Cacheable classes)
- *
  * @see https://bearsunday.github.io/manuals/1.0/en/cache.html#event-driven-content
  */
 #[Attribute(Attribute::TARGET_METHOD | Attribute::IS_REPEATABLE)]

src/CommandInterceptor.php

@@ -15,8 +15,12 @@
 /**
  * Interceptor for cache invalidation on CQRS commands with #[Purge] or #[Refresh]
  *
- * Bound to command methods (onPut/onPatch/onDelete) of #[Cacheable] classes.
- * Executes cache invalidation after successful write operations.
+ * Automatically bound to all command methods (onPut/onPatch/onDelete) of #[Cacheable] classes.
+ * Processes #[Purge] and #[Refresh] annotations on these methods and executes cache
+ * invalidation after successful write operations.
+ *
+ * For non-Cacheable classes, use RefreshInterceptor instead by explicitly marking methods
+ * with #[Purge] or #[Refresh].
  *
  * @see \BEAR\RepositoryModule\Annotation\Purge
  * @see \BEAR\RepositoryModule\Annotation\Refresh

src/RefreshInterceptor.php

@@ -14,7 +14,10 @@
 /**
  * Interceptor for cache refresh commands with #[Purge] or #[Refresh]
  *
- * Bound to methods marked with #[Purge] or #[Refresh] on non-Cacheable classes.
+ * Bound only to methods explicitly marked with #[Purge] or #[Refresh] on non-Cacheable classes.
+ * Unlike CommandInterceptor (which automatically binds to all command methods of #[Cacheable]
+ * classes), this interceptor requires explicit attribute annotation on each method.
+ *
  * Executes cache invalidation commands after successful method execution.
  *
  * @see \BEAR\RepositoryModule\Annotation\Purge