From eb70ffabf2638c72ac5ed7ce3631677d15511a72 Mon Sep 17 00:00:00 2001
From: root <root@njcn.local>
Date: Thu, 25 Jun 2026 11:02:01 +0800
Subject: [PATCH] docs: add redis stream demo design

---
 .../2026-06-25-redis-stream-demo-design.md    | 116 ++++++++++++++++++
 1 file changed, 116 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-06-25-redis-stream-demo-design.md

diff --git a/docs/superpowers/specs/2026-06-25-redis-stream-demo-design.md b/docs/superpowers/specs/2026-06-25-redis-stream-demo-design.md
new file mode 100644
index 0000000..9e500ec
--- /dev/null
+++ b/docs/superpowers/specs/2026-06-25-redis-stream-demo-design.md
@@ -0,0 +1,116 @@
+# Redis Stream Starter Demo Design
+
+## Goal
+
+Create an independent Spring Boot demo project at `C:\code\hatch\redis-stream-starter-demo` that imports the local `redis-stream-springboot-starter` and verifies Redis Stream message publish and subscribe behavior against the provided Redis service.
+
+## Context
+
+The current repository is a Maven single-module Spring Boot starter:
+
+- Group/artifact/version: `com.njcn:redis-stream-springboot-starter:1.0.0-SNAPSHOT`
+- Spring Boot baseline: `2.3.12.RELEASE`
+- Java baseline: 8
+- Auto-configuration entry: `META-INF/spring.factories`
+- Producer API: `RedisStreamEnhanceTemplate#send(topic, message, compress)`
+- Consumer API: subclass `EnhanceStreamConsumerHandler<T>`
+
+## Demo Project Location
+
+The demo project will be created outside this repository at:
+
+```text
+C:\code\hatch\redis-stream-starter-demo
+```
+
+This keeps the starter repository unchanged except for this design document and allows the demo to behave like a real downstream application.
+
+## Dependency Flow
+
+Before building the demo, install the starter into the local Maven repository:
+
+```bash
+mvn install
+```
+
+The demo `pom.xml` will then depend on:
+
+```xml
+<dependency>
+    <groupId>com.njcn</groupId>
+    <artifactId>redis-stream-springboot-starter</artifactId>
+    <version>1.0.0-SNAPSHOT</version>
+</dependency>
+```
+
+The demo will use Spring Boot `2.3.12.RELEASE` to match the starter's dependency baseline.
+
+## Redis Configuration
+
+The demo will use the provided Redis Stream service:
+
+- Host: configured as `192.168.1.22`
+- Port: configured as `12379`
+- Password: configured in the local demo application config, not copied into this design document
+
+The demo should allow overriding these values with environment variables or JVM system properties so the sample remains reusable.
+
+## Runtime Components
+
+The demo will include:
+
+- `DemoApplication`: Spring Boot entry point.
+- `DemoMessage`: message payload extending `StreamBaseMessage`.
+- `DemoProducer`: injects `RedisStreamEnhanceTemplate` and publishes a message.
+- `DemoConsumer`: extends `EnhanceStreamConsumerHandler<DemoMessage>` and subscribes to the same topic and group.
+- `DemoStartupRunner`: sends one message after the application starts and logs the returned Redis `RecordId`.
+
+The consumer will log received message content and store consumed messages in an in-memory queue for integration test assertions.
+
+## Message Flow
+
+1. Application starts and auto-configuration creates the starter beans.
+2. `DemoStartupRunner` creates a `DemoMessage`.
+3. `DemoProducer` calls `RedisStreamEnhanceTemplate#send("demo-topic", message, false)`.
+4. The starter writes the message to Redis Stream with `XADD`.
+5. The starter listener reads the message through `XREADGROUP`.
+6. `DemoConsumer#handleMessage` receives the deserialized `DemoMessage`.
+7. The starter ACKs the message after successful handling.
+
+## Testing
+
+Add an integration test that:
+
+- Starts the demo Spring context.
+- Uses the real Redis service when reachable.
+- Sends a unique test message.
+- Waits for the consumer to receive it.
+- Asserts that the received message payload and key match the sent message.
+
+If Redis is unreachable, the integration test should be skipped instead of failed. This keeps local builds deterministic while still validating the real publish/subscribe flow when the service is available.
+
+## Error Handling
+
+The demo consumer will return `false` for `isRetry()` so test failures are surfaced through assertions instead of retry loops. Unexpected handler exceptions will be logged by the starter path and ACKed according to the existing handler behavior.
+
+## Verification Commands
+
+From the starter repository:
+
+```bash
+mvn install
+```
+
+From the demo project:
+
+```bash
+mvn test
+mvn spring-boot:run
+```
+
+## Out of Scope
+
+- Publishing the starter to Nexus.
+- Changing starter production code.
+- Adding Docker or Testcontainers.
+- Building a UI or HTTP API for the demo.