If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/fuzhengwei/itstack-demo-design shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Stale — last commit 2y ago

• 7 active contributors
• Apache-2.0 licensed
• Tests present
• ⚠ Stale — last commit 2y ago
• ⚠ Single-maintainer risk — top contributor 88% of recent commits
• ⚠ No CI workflows detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live fuzhengwei/itstack-demo-design repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/fuzhengwei/itstack-demo-design.

What it runs against: a local clone of fuzhengwei/itstack-demo-design — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in fuzhengwei/itstack-demo-design | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | Last commit ≤ 758 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of fuzhengwei/itstack-demo-design. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/fuzhengwei/itstack-demo-design.git
#   cd itstack-demo-design
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of fuzhengwei/itstack-demo-design and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "fuzhengwei/itstack-demo-design(\\.git)?\\b" \\
  && ok "origin remote is fuzhengwei/itstack-demo-design" \\
  || miss "origin remote is not fuzhengwei/itstack-demo-design (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 758 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~728d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/fuzhengwei/itstack-demo-design"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

itstack-demo-design is a practical learning repository teaching 22 real-world design patterns (Factory, Singleton, Strategy, etc.) through actual e-commerce and trading scenarios (coupons, goods delivery, card services, prize systems). It bridges the gap between textbook design patterns and production code by demonstrating each pattern through concrete modules like itstack-demo-design-1-00 (multi-service coupling), itstack-demo-design-1-01 (prize distribution), and itstack-demo-design-1-02 (store factory pattern). Multi-module Maven monorepo: each design pattern gets its own numbered module (itstack-demo-design-1-00, 1-01, 1-02, etc.) with standard Maven structure (src/main/java/org/itstack/demo/design/ containing pattern implementations, src/test/ for examples). Modules are intentionally independent to isolate each pattern without cross-contamination.

Java backend engineers and junior developers learning to recognize and apply design patterns in real systems; also suitable for tech leads reviewing canonical implementations. Primary audience: developers studying for technical interviews or leveling up from copy-paste coding to architected solutions.

Actively maintained educational project with 244KB of core Java code organized into ~22 modular examples. No visible CI/CD pipeline or automated testing infrastructure in the file list; maturity appears teaching-focused rather than production-hardened. Backed by author's professional experience (小傅哥) with published book and blog documentation at bugstack.cn.

Low risk for learning purposes but not production-ready: minimal test coverage visible (only ApiTest.java in design-1-01), no apparent CI pipeline, and single-maintainer stewardship. Module dependencies are explicit and isolated (each itstack-demo-design-*-* is independent), but no dependency version management shown in snippet beyond parent POM. No indication of how frequently modules are updated post-book publication.

Repository serves as living documentation for the published book '重学Java设计模式' (Relearning Java Design Patterns). No PR, issue, or commit data visible in provided artifact list, suggesting stable maintenance mode focused on preserving canonical examples rather than active feature development.

git clone https://github.com/fuzhengwei/itstack-demo-design.git
cd itstack-demo-design
mvn clean install
cd itstack-demo-design-1-01
mvn test -Dtest=ApiTest

Daily commands: Per module: mvn clean test in the module directory (e.g., cd itstack-demo-design-1-01 && mvn test). ApiTest.java appears to be the primary test runner. No Maven Shade, no fat-JAR, no Docker—these are libraries/examples, not executables.

• itstack-demo-design-1-02/src/main/java/org/itstack/demo/design/StoreFactory.java: Core Factory Pattern implementation—teaches how to hide object creation logic and return appropriate commodity handlers.
• itstack-demo-design-1-02/src/main/java/org/itstack/demo/design/store/ICommodity.java: Interface defining the contract for all commodity types (Strategy Pattern); critical to understanding polymorphism in the codebase.
• itstack-demo-design-1-02/src/main/java/org/itstack/demo/design/store/impl/: Three concrete implementations (Card, Coupon, Goods services) demonstrating how Strategy Pattern enables swappable behavior without conditional logic.
• itstack-demo-design-1-01/src/test/java/org/itstack/demo/test/ApiTest.java: Primary entry point for understanding how patterns are tested; shows real usage of PrizeController and request/response objects.
• itstack-demo-design-1-00/src/main/java/org/itstack/demo/design/: First 'zero' module showing anti-pattern (tight coupling: card, coupon, goods services tightly integrated) before refactoring into patterns.

To add a new pattern: (1) create itstack-demo-design-*-NN/ directory with Maven structure, (2) implement the pattern under src/main/java/org/itstack/demo/design/, (3) add test case in src/test/java/org/itstack/demo/test/ApiTest.java or equivalent, (4) update parent pom.xml to include module. Example: look at itstack-demo-design-1-02/src/main/java/org/itstack/demo/design/store/impl/ to see how three implementations (Card, Coupon, Goods) satisfy a single interface (ICommodity).

No hidden environment variables or service dependencies identified in provided file list. Key gotcha: each module is intentionally self-contained and independent—do not expect cross-module imports (modules don't depend on each other). Maven parent POM is assumed to exist at repository root but not shown in snippet. No Java version explicitly specified; infer from package structure (likely Java 8+, no records or sealed classes visible).

• Factory Pattern (Abstract Factory variant) — StoreFactory.java demonstrates how to decouple object creation from usage, critical for testability and runtime polymorphism in the commodity system.
• Strategy Pattern — ICommodity interface with three implementations (Card, Coupon, Goods) shows how to eliminate conditional logic and make behavior swappable at runtime—core pattern in this repo.
• Tight Coupling (Anti-pattern demonstration) — itstack-demo-design-1-00 deliberately shows what NOT to do (multiple if-else chains across CouponService, CardService, GoodsService); later modules refactor these into proper patterns.
• Polymorphism via Interface Segregation — Each commodity service implements a minimal ICommodity contract; teaches Single Responsibility and how to design narrow, focused interfaces.
• Service Locator Pattern — Implicit in StoreFactory—central registry that maps commodity type to implementation; common in older Java systems and useful for understanding when not to use Dependency Injection.
• Request/Response Objects (DTO pattern) — AwardReq, AwardRes, CouponResult, DeliverReq throughout codebase; demonstrates how to encapsulate data transfers between layers and avoid primitive parameter lists.

• iluwatar/java-design-patterns — Comprehensive reference implementation of all 23 Gang of Four patterns in Java with examples; complements this repo's real-world business-case focus.
• refactoringguru/design-patterns-java — Refactoring Guru's official Java translation of design patterns with visual diagrams and explanations; best for understanding the theory behind itstack examples.
• fuzhengwei/CodeGuide — Author's companion repo (mentioned in README); comprehensive Java knowledge base and interview prep material expanding on patterns taught here.
• fuzhengwei/DDD-Practice — Author's domain-driven design project showing how patterns scale in large systems; natural evolution after mastering individual patterns in itstack.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for design pattern modules (itstack-demo-design-1-00 through 1-02)

The repository demonstrates design patterns through practical scenarios (cards, coupons, goods, store factory, commodities), but the visible test files are minimal. Currently only itstack-demo-design-1-02 shows a test structure with ApiTest.java. Adding thorough unit tests for CouponService, GoodsService, IQiYiCardService, StoreFactory, and all ICommodity implementations would improve code reliability and serve as executable documentation for how each pattern works in practice.

• [ ] Create unit tests in itstack-demo-design-1-00/src/test/java for CouponService, GoodsService, and IQiYiCardService
• [ ] Create unit tests in itstack-demo-design-1-02/src/test/java for StoreFactory and all commodity implementations (CardCommodityService, CouponCommodityService, GoodsCommodityService)
• [ ] Add test cases covering both happy paths and edge cases for each service
• [ ] Use JUnit 4/5 or similar framework consistent with existing ApiTest.java patterns

Add missing README documentation for individual pattern modules (itstack-demo-design-1-00 through 1-10)

While the main repository README exists, each numbered subdirectory (itstack-demo-design-1-00, 1-01, 1-02, etc.) represents a distinct design pattern scenario but lacks its own README explaining the pattern, its use case, and how the code demonstrates it. This makes it harder for learners to understand what pattern each module teaches. Adding focused README files for each module would significantly improve the learning experience.

• [ ] Create itstack-demo-design-1-00/README.md documenting the scenario pattern with card/coupon/goods interactions
• [ ] Create itstack-demo-design-1-01/README.md explaining the prize/award distribution pattern demonstrated
• [ ] Create itstack-demo-design-1-02/README.md explaining the Factory pattern through StoreFactory and commodity implementations
• [ ] Continue for remaining numbered modules (1-03 through 1-10+), each describing the specific design pattern and business scenario

Add GitHub Actions CI workflow to validate Java builds and tests across all modules

With 10+ Maven modules (itstack-demo-design-1-00 through itstack-demo-design-10-00 and beyond), there is no visible CI/CD pipeline to ensure code compiles and tests pass. This is critical for an educational repository where contributors might submit changes. Adding a GitHub Actions workflow to build all modules and run tests would catch regressions early and maintain code quality standards.

• [ ] Create .github/workflows/maven-build.yml with Java setup (versions 8, 11, 17)
• [ ] Configure workflow to run 'mvn clean install' from repository root to validate all modules compile
• [ ] Add test execution step: 'mvn test' to ensure unit tests pass across all modules
• [ ] Add optional step to check for code style/formatting (e.g., using Checkstyle plugin already defined in parent pom.xml)
• [ ] Set workflow to trigger on push, pull_request, and schedule (e.g., weekly validation)

• Add comprehensive unit tests for itstack-demo-design-1-00 modules (card, coupon, goods services). Currently only ApiTest visible in 1-01; 1-00 and 1-02 show no test coverage.
• Create a README.md or JavaDoc overview for each design pattern module explaining the pattern, its use case, and the business scenario (e.g., '1-01: Lottery/Prize distribution using Strategy Pattern'). Current documentation exists only at bugstack.cn blog.
• Implement missing structural patterns: add modules for Decorator (customizing coupons), Composite (bundled goods), and Facade (unified order API across card/coupon/goods). Look at how store/impl/ is structured for consistency.

The codebase is an educational design patterns repository with moderate security posture. Primary concerns include lack of explicit dependency version management, absence of security disclosure procedures, and missing build-time security scanning. No critical vulnerabilities were identified in the file structure or configuration snippets provided. However, individual modules (especially those with controller/service components like PrizeController and CouponService) should implement proper input validation, authentication, and authorization controls before any production use. The repository should include security-focused documentation and build-time security checks.

• Medium · Missing Dependency Version Management — itstack-demo-design-1-00/pom.xml and other module pom.xml files. The pom.xml file shows a parent module reference but no explicit dependency versions are declared in the provided snippet. This could lead to version conflicts or use of outdated/vulnerable transitive dependencies if the parent POM doesn't properly manage versions. Fix: Implement explicit dependency version management using <dependencyManagement> in the parent POM. Use dependency check tools like OWASP Dependency-Check or Snyk to identify vulnerable dependencies.
• Low · No Security Policy or SECURITY.md — Repository root. The repository lacks a SECURITY.md file that defines responsible disclosure procedures and security contact information. This makes it difficult for security researchers to report vulnerabilities responsibly. Fix: Create a SECURITY.md file documenting vulnerability disclosure policy, supported versions, and how to report security issues.
• Low · Educational Code Without Security Guardrails — itstack-demo-design-1-00 and itstack-demo-design-1-01 modules. As an educational design patterns repository, the code may contain intentional anti-patterns or simplified implementations for teaching purposes. Production-like code (e.g., PrizeController, CouponService) should include security validations. Fix: Add security disclaimers in code comments. Include input validation, output encoding, and authentication checks in controller/service examples. Add notes about what's omitted for educational purposes.
• Low · No Build Security Scanning — Parent pom.xml. The pom.xml files show no integration with security scanning tools during the build process (e.g., maven-dependency-check-plugin, spotbugs-maven-plugin, or jacoco for code coverage). Fix: Integrate OWASP Dependency-Check, Spotbugs, or similar tools into the Maven build process to automatically scan for known vulnerabilities and code quality issues.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.