name: app-common-event-generator description: "Use when generating or extending the app-common event system (outbox/inbox, dispatcher, handlers, retry policy) or adding BC-level event handlers with concurrency and idempotency rules."

App Common Event Generator

Overview

Generates and extends the event integration infrastructure (outbox/inbox, dispatcher, handlers) with stable event-type contracts, idempotency, and retry semantics. REQUIRED: Follow GENERATOR_SKILL_STRUCTURE.md. Variables in VARIABLES.md.

Templates: See references/templates.md.

When to Use

{{basePackage}}.app.common.event.*
Adding event handlers under {{basePackage}}.app.{{bcName}}.event.handler

Don't use when

You need the infra-level Kafka transport — use infra-mq-transport-generator.
You need the adapter-level MQ consumer — use adapter-mq-consumer-generator.
You need a workflow step handler — use app-common-workflow-generator.
You are adding a use-case handler (Command/Query) — use app-usecase-generator.

Inputs Required

eventType (stable string contract)
Consumer name / group semantics (who owns idempotency)
Retry semantics: which exceptions are retryable vs terminal

Outputs

App/common:
- event model / ports / dispatcher changes (if extending core)
- unit tests for dispatch behavior
BC handlers:
- .../app/{{bcName}}/event/handler/<XxxHandler>.java

Naming & Packaging

Event handler names: <EventType>Handler or <BusinessAction>On<EventType>Handler
Keep core framework-free in app/common; wiring in start.

Rules

Stable eventType strings (contract).
Inbox idempotency: tryStart claim, then handle, then mark.
Missing handler: mark inbox DEAD, do not leave stuck rows.
Retry semantics via EventHandlingException (retryable vs non-retryable).
Keep app-common focused on event orchestration contracts; storage and transport details belong to infra.
Event type strings MUST follow the naming convention: <bc>.<aggregate>.<past-tense-verb> (lowercase, dot-separated).
Generate a <BcName>EventTypes constants class in domain/<bcName>/event/ holding all event type strings for the BC.
Do NOT use Java class names (e.g., OrderCreated.class.getName()) as event type contracts.

Reference Implementations

{{appModuleDir}}/src/main/java/{{basePackagePath}}/app/common/event/integration/service/DefaultIntegrationEventDispatcher.java
{{infraModuleDir}}/src/main/java/{{basePackagePath}}/infra/event/inbox/store/MybatisInboxStore.java
{{adapterModuleDir}}/src/main/java/{{basePackagePath}}/adapter/mq/system/consumer/OutboxEventKafkaConsumer.java

Tests

Unit tests for dispatcher behavior, handler selection, exception mapping.
For each business integration handler, add unit tests that assert:
- expected side effects (e.g., compensation command/projection upsert)
- retryability behavior on runtime failure
- one success branch and one failure branch

Common Mistakes

Mistake	Why It Happens	Fix
Creating inbox rows before verifying handler exists	Optimistic insert without validation	Check handler registry before claiming inbox; mark unknown events as `DEAD`
Throwing `Exception` from handler interfaces	Catch-all habit from other layers	Use `EventHandlingException` with explicit retryable/non-retryable semantics
Hardcoding event type strings in handlers	Inline string constants	Define stable `eventType` constants in a shared contract location
Missing DEAD handling for unknown events	Assuming all events have handlers	Explicitly mark inbox as `DEAD` when no handler is found to prevent stuck rows

Integration

Called by: scaffold-router, dev-workflow-ddd-implementation-workflow
Pairs with: app-port-generator (outbox/inbox store ports), infra-mq-transport-generator (Kafka transport), adapter-mq-consumer-generator (consumer wiring), app-usecase-generator (handlers that publish events)

Commit Gate

pass required tests (mvn -q clean test minimum, mvn -q clean verify if DB behavior changed)
run requesting-code-review
resolve Critical/Important findings
keep the commit focused

Name	app-common-event-generator
Description	Generates/extends app-common event system (outbox/inbox, dispatcher, handlers, retry policy) with concurrency and idempotency rules.

app-common-event-generator

SKILL.md