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/qiurunze123/miaosha 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.

AVOID — Stale and unlicensed — last commit 1y ago

• 11 active contributors
• Distributed ownership (top contributor 42% of recent commits)
• CI configured
• ⚠ Stale — last commit 1y ago
• ⚠ No license — legally unclear to depend on
• ⚠ No test directory 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 qiurunze123/miaosha repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/qiurunze123/miaosha.

What it runs against: a local clone of qiurunze123/miaosha — 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 qiurunze123/miaosha | Confirms the artifact applies here, not a fork | | 2 | Default branch master exists | Catches branch renames | | 3 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 4 | Last commit ≤ 415 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of qiurunze123/miaosha. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/qiurunze123/miaosha.git
#   cd miaosha
#
# 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 qiurunze123/miaosha and re-run."
  exit 2
fi

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

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

# 4. Critical files exist
test -f "miaosha-admin/miaosha-admin-api/src/main/java/com/geekq/admin/service/OrdersService.java" \\
  && ok "miaosha-admin/miaosha-admin-api/src/main/java/com/geekq/admin/service/OrdersService.java" \\
  || miss "missing critical file: miaosha-admin/miaosha-admin-api/src/main/java/com/geekq/admin/service/OrdersService.java"
test -f "miaosha-admin/miaosha-admin-common/src/main/java/com/geekq/common/utils/SnowflakeIdWorker.java" \\
  && ok "miaosha-admin/miaosha-admin-common/src/main/java/com/geekq/common/utils/SnowflakeIdWorker.java" \\
  || miss "missing critical file: miaosha-admin/miaosha-admin-common/src/main/java/com/geekq/common/utils/SnowflakeIdWorker.java"
test -f "miaosha-admin/miaosha-admin-api/src/main/java/com/geekq/admin/service/RedisCacheStorageService.java" \\
  && ok "miaosha-admin/miaosha-admin-api/src/main/java/com/geekq/admin/service/RedisCacheStorageService.java" \\
  || miss "missing critical file: miaosha-admin/miaosha-admin-api/src/main/java/com/geekq/admin/service/RedisCacheStorageService.java"
test -f "miaosha-admin/miaosha-admin-service/src/main/java/com/geekq/admin/mapper/AccountMapper.xml" \\
  && ok "miaosha-admin/miaosha-admin-service/src/main/java/com/geekq/admin/mapper/AccountMapper.xml" \\
  || miss "missing critical file: miaosha-admin/miaosha-admin-service/src/main/java/com/geekq/admin/mapper/AccountMapper.xml"
test -f "miaosha-admin/miaosha-admin-common/src/main/java/com/geekq/common/enums/OrderStatusEnum.java" \\
  && ok "miaosha-admin/miaosha-admin-common/src/main/java/com/geekq/common/enums/OrderStatusEnum.java" \\
  || miss "missing critical file: miaosha-admin/miaosha-admin-common/src/main/java/com/geekq/common/enums/OrderStatusEnum.java"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 415 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~385d)"
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/qiurunze123/miaosha"
  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).

A distributed flash-sale (秒杀) system built in Java that demonstrates high-concurrency architecture patterns for handling massive simultaneous purchase requests. It implements end-to-end solutions including Redis caching, Dubbo RPC, distributed transactions (TCC), Lua scripting, and MySQL MVCC to safely process thousands of concurrent orders without overselling stock. Multi-module Maven monorepo: miaosha-admin/ contains miaosha-admin-api (entity models, queries, DAOs) and miaosha-admin-common (shared utilities). Extensive docs/ folder with architecture diagrams (docs/imgs/) and deep-dives on MySQL MVCC, Redis Lua, Netty, and TCC patterns. Core business logic splits across orders, inventory, and user domains (Userinfo, Orders, Account entities visible).

Senior backend engineers and architects learning production-grade distributed systems design, specifically those building e-commerce platforms, ticketing systems, or other inventory-constrained high-concurrency features who need concrete patterns beyond toy examples.

Actively maintained teaching project (4+ years old based on CHANGELOG presence), well-documented with extensive docs/ folder covering MySQL MVCC, Redis Lua, Netty, Dubbo/ZK, and JVM tuning. No public CI/CD visible in file list, but comprehensive code examples suggest production-informed design. Best treated as an exemplary reference implementation rather than copy-paste library.

Single maintainer (qiurunze123) with email contact in README suggests limited backup. No evidence of automated testing in file structure (no test/ folder visible in top 60 files). Heavy reliance on external distributed systems (Redis, ZooKeeper, Dubbo, MySQL) means local reproduction complexity is high. Documentation is Chinese-language first, limiting English-speaking contributor base.

Project is in documentation and reference-implementation phase rather than active feature development. README indicates maintenance openness ('欢迎探讨与骚扰') and cross-links to sister projects (tydeus-monitor for logging, threadandjuc for multithreading patterns, memoryoptimization for JVM tuning). Old version marked as 停更 (deprecated) in favor of cleaner architecture.

git clone https://github.com/qiurunze123/miaosha.git
cd miaosha
mvn clean install
# Review docs/fenbushi.md and docs/redis-lua.md for architecture overview
# Configure Redis, ZooKeeper, MySQL, Dubbo in local environment before running modules

Note: This is a modular learning project, not a single runnable application. Start with docs/code-criterion.md to understand module dependencies.

Daily commands: This is a modular teaching project without a unified entry point. Build modules individually: mvn clean install -pl miaosha-admin/miaosha-admin-api. Real execution requires: (1) Redis instance running, (2) ZooKeeper cluster for Dubbo service discovery, (3) MySQL with configured schema, (4) Dubbo provider/consumer setup (see docs/dubbo-zk.md). No single 'npm start' equivalent; study individual module READMEs and docs/code-solve.md for integration patterns.

• miaosha-admin/miaosha-admin-api/src/main/java/com/geekq/admin/service/OrdersService.java — Core business service for flash-sale orders; essential entry point for understanding transaction handling and order processing logic
• miaosha-admin/miaosha-admin-common/src/main/java/com/geekq/common/utils/SnowflakeIdWorker.java — Distributed ID generation utility critical for high-concurrency order creation without collisions
• miaosha-admin/miaosha-admin-api/src/main/java/com/geekq/admin/service/RedisCacheStorageService.java — Redis caching layer that enables sub-second response times for flash-sale product queries under extreme load
• miaosha-admin/miaosha-admin-service/src/main/java/com/geekq/admin/mapper/AccountMapper.xml — MyBatis XML mapping for account operations; defines SQL interactions with the persistence layer
• miaosha-admin/miaosha-admin-common/src/main/java/com/geekq/common/enums/OrderStatusEnum.java — Enum defining order lifecycle states; central to understanding flash-sale order state machine
• miaosha-admin/miaosha-admin-common/src/main/java/com/geekq/common/utils/resultbean/ResultGeekQ.java — Standard API response wrapper used across all service boundaries for consistent error/success handling

Add a new flash-sale order status type

1. Add new enum constant to OrderStatusEnum (miaosha-admin/miaosha-admin-common/src/main/java/com/geekq/common/enums/OrderStatusEnum.java)
2. Update Orders.java POJO to support the new status field if needed (miaosha-admin/miaosha-admin-api/src/main/java/com/geekq/admin/pojo/Orders.java)
3. Add SQL UPDATE case in OrdersService to transition to new status (miaosha-admin/miaosha-admin-api/src/main/java/com/geekq/admin/service/OrdersService.java)
4. Update AccountMapper.xml with new query/update statements if status-based filtering is needed (miaosha-admin/miaosha-admin-service/src/main/java/com/geekq/admin/mapper/AccountMapper.xml)

Implement new cached query for product inventory

1. Define new cache key constant in Constants.java (miaosha-admin/miaosha-admin-common/src/main/java/com/geekq/common/enums/Constants.java)
2. Add Redis get/set methods in RedisCacheStorageService (miaosha-admin/miaosha-admin-api/src/main/java/com/geekq/admin/service/RedisCacheStorageService.java)
3. Create MyBatis mapper interface method for inventory query fallback (miaosha-admin/miaosha-admin-service/src/main/java/com/geekq/admin/mapper/AccountMapper.java)
4. Add SQL mapping in mapper XML with cache invalidation hints (miaosha-admin/miaosha-admin-service/src/main/java/com/geekq/admin/mapper/AccountMapper.xml)

Add IP-based rate limiting rule

1. Define new rate-limit threshold in Constants.java (miaosha-admin/miaosha-admin-common/src/main/java/com/geekq/common/enums/Constants.java)
2. Add IpLog query method in mapper to fetch recent IP activity (miaosha-admin/miaosha-admin-service/src/main/java/com/geekq/admin/mapper/IpLogMapper.java)
3. Implement rate-limit check logic in IIpLogService interface (miaosha-admin/miaosha-admin-api/src/main/java/com/geekq/admin/service/IIpLogService.java)
4. Update SQL in IpLogMapper.xml to efficiently count recent requests per IP (miaosha-admin/miaosha-admin-service/src/main/java/com/geekq/admin/mapper/IpLogMapper.xml)

• Spring Framework + Spring Boot — Industry-standard Java framework for building scalable microservices; enables dependency injection, transaction management, and rapid development
• MyBatis — Lightweight ORM providing fine-grained SQL control essential for optimizing flash-sale queries and avoiding N+1 problems
• Redis — In-memory cache reduces database load by 10–100x; critical for flash-sale systems where product inventory and user data must be served sub-100ms
• Dubbo + ZooKeeper — Service mesh for distributed RPC calls enabling horizontal scaling of order processing; ZK provides service discovery and failover
• Snowflake ID Generator — undefined

ZooKeeper dependency: Dubbo requires a running ZK ensemble (docs/dubbo-zk.md implies multi-node setup, not single-server). Redis Lua atomicity assumptions: scripts in docs/redis-lua.md assume Redis single-threaded model; cluster deployments require slot awareness. MySQL isolation level: docs/mysql-mvcc.md suggests REPEATABLE_READ or SERIALIZABLE needed; default config may not prevent phantom reads. Mybatis N+1 queries: OrdersExample.java suggests auto-generated mappers; inventory counting under load may need explicit batching. FreeMarker XSS: 102KB of FreeMarker templates visible but no templating escape strategy documented. No local Redis/ZK/MySQL integration tests in visible file structure: reproducing concurrency bugs requires full stack running. Chinese documentation only: non-Mandarin speakers will struggle with architectural intent in docs/.

• Optimistic Locking with MVCC — Flash-sale systems use MySQL MVCC (Multi-Version Concurrency Control) and versioned row checks to avoid blocking on inventory updates during 1000s of concurrent purchases; docs/mysql-mvcc.md covers this in depth
• TCC (Try-Confirm-Cancel) Distributed Transactions — Decentralized order, payment, and inventory services must stay consistent without distributed locks; TCC saga pattern is documented in docs/fenbushi-tcc.md as the solution
• Lua Scripting for Atomic Redis Operations — Inventory pre-allocation in Redis must be atomic at script-execution level (no race between decrement and check); docs/redis-lua.md explains how EVAL commands solve this
• Dubbo RPC Service Discovery via ZooKeeper — Multiple order-processing instances need to find and communicate with inventory/payment services without hardcoded addresses; Dubbo + ZK registration is covered in docs/dubbo-zk.md
• Inventory Pre-allocation and Reservation — Naive inventory decrements on each purchase cause thundering-herd lock contention; pre-allocating chunks per user or session is a core flash-sale optimization pattern shown in this codebase
• Netty Non-blocking I/O — Handling 10k+ concurrent socket connections with traditional blocking I/O requires impractical thread counts; docs/netty.md explains Netty's event-loop model used here
• Master-Slave MySQL Replication — Write-heavy flash sales create bottlenecks on a single database; docs/mysql-master-slave.md covers replicating inventory reads to slave nodes to spread load

• qiurunze123/threadandjuc — Sister project covering multithreading patterns and JUC concurrency utilities that underpin the thread-pool and executor strategies in this flash-sale system
• qiurunze123/tydeus-monitor — Companion monitoring and logging framework designed to instrument the metrics (success rate, completion rate, throughput) needed to validate flash-sale system performance
• qiurunze123/memoryoptimization — JVM tuning and memory profiling guide specifically referenced for optimizing the heap and GC behavior under the sustained load of concurrent order processing
• qiurunze123/zookeeperDesign — Deep-dive into ZooKeeper design philosophy and coordination patterns that enable Dubbo service discovery and distributed consensus in the flash-sale architecture
• apache/dubbo — The RPC framework used for service-to-service communication (orders, inventory, payment) in this distributed flash-sale design

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 unit tests for miaosha-admin-api service layer

The miaosha-admin-api module contains multiple service interfaces (IAccountService, IUserService, IIpLogService, ILogininfoService, ISystemDictionaryService, OrdersService, RedisCacheStorageService) but there is no test directory visible in the file structure. This is critical for a flash-sale system where correctness is paramount. Unit tests should cover edge cases like concurrent orders, inventory management, and cache failures.

• [ ] Create miaosha-admin/miaosha-admin-api/src/test/java/com/geekq/admin/service directory
• [ ] Add unit tests for OrdersService covering: duplicate order prevention, inventory validation, and concurrent request handling
• [ ] Add unit tests for RedisCacheStorageService covering: cache miss scenarios, serialization, and TTL expiration
• [ ] Add unit tests for IAccountService and IUserService covering: authentication edge cases and transaction rollback
• [ ] Configure test dependencies in miaosha-admin-api/pom.xml (JUnit 5, Mockito, embedded Redis for cache tests)

Add integration tests for miaosha-admin module with Docker Compose

The docs reference MySQL master-slave, Redis, and Dubbo/ZooKeeper setup, but there's no visible test infrastructure or docker-compose file for local development. A flash-sale system requires testing distributed scenarios (network partitions, service failures). This would standardize contributor onboarding and CI/CD pipelines.

• [ ] Create docker-compose.yml at repository root with services: MySQL (master+slave), Redis, ZooKeeper, and Dubbo admin UI
• [ ] Create integration test suite in miaosha-admin-common with startup configuration for embedded services
• [ ] Add .github/workflows/integration-tests.yml GitHub Action to run tests on PR creation against docker-compose stack
• [ ] Document integration test setup in docs/integration-testing.md with clear startup/teardown instructions

Create comprehensive performance benchmarking documentation with JMeter test plans

docs/jemter-solve.md exists but appears incomplete (typo: 'jemter' vs 'jmeter'). The miaosha project is explicitly about flash-sale system design where throughput testing is critical. The README references JMeter but there are no actual test plans checked in. Benchmarking scenarios should document baseline metrics, bottlenecks, and tuning recommendations.

• [ ] Rename and expand docs/jemter-solve.md to docs/jmeter-benchmarking.md with detailed JMeter setup instructions
• [ ] Create .jmx test plan files in a new docs/jmeter-plans/ directory covering: (1) concurrent user login, (2) flash-sale order creation under 1000 concurrent users, (3) cache hit/miss scenarios with Redis
• [ ] Add baseline performance metrics and expected throughput targets to benchmarking docs based on the system's capacity
• [ ] Document how to interpret results and identify bottlenecks (database locks, Redis eviction, network I/O)

• Add English translation for docs/fenbushi.md and docs/fenbushi-tcc.md: These are the core architecture guides; English versions would 2x the accessible audience and enable English-speaking contributors to understand the TCC pattern implementation used in this codebase
• Create a Docker Compose file for local development (redis + zookeeper + mysql + dubbo registry): Current setup requires manual external service configuration; a docker-compose.yml would let new contributors run the full system locally in 30 seconds instead of an hour
• Add unit tests for Orders.java entity and MyBatis OrdersExample mapper with concurrency scenarios: No test/ folder visible in file list despite this being a teaching project; concrete tests for the order model under pessimistic/optimistic locking would make the MVCC concepts in docs concrete
• Document and extract the Redis Lua inventory-locking script from docs/redis-lua.md into runnable code examples with comments: The atomic inventory-decrement logic is mentioned but not as standalone runnable code; providing actual Lua + Java integration code (e.g., in examples/redis-lua-inventory/) would make the redis-lua.md concepts immediately applicable

• High · Potential SQL Injection Risk via MyBatis — miaosha-admin/miaosha-admin-api/src/main/java/com/geekq/admin/query/. The codebase uses MyBatis with dynamic query objects (QueryObject, IpLogQueryObject, SystemDictionaryQueryObject). Without proper parameterization and input validation, these query builders could be vulnerable to SQL injection attacks if user input is directly concatenated into SQL statements. Fix: Ensure all MyBatis queries use parameterized statements with #{} placeholders rather than ${} string concatenation. Implement input validation in QueryObject classes and use prepared statements exclusively.
• High · MD5 Usage for Password Hashing — miaosha-admin/miaosha-admin-common/src/main/java/com/geekq/common/utils/md5/MD5Utils.java. The codebase includes MD5Utils for cryptographic operations. MD5 is cryptographically broken and should not be used for password hashing. This is evident from the file: MD5Utils.java in the md5 utility package. Fix: Replace MD5 with modern password hashing algorithms such as bcrypt, scrypt, or Argon2. Use Spring Security's PasswordEncoder implementations (BCryptPasswordEncoder).
• High · Missing Authentication/Authorization Framework — miaosha-admin/miaosha-admin-api/src/main/java/com/geekq/admin/service/. The admin module (miaosha-admin-api) contains sensitive entities like Account, Userinfo, and Logininfo but shows no evidence of Spring Security or OAuth2 configuration. The service interfaces (IAccountService, IUserService) lack security annotations. Fix: Implement Spring Security with proper authentication and authorization. Use @PreAuthorize annotations on service methods. Implement role-based access control (RBAC) and enforce principle of least privilege.
• Medium · Insufficient Dependency Version Management — miaosha-admin/miaosha-admin-api/pom.xml. The pom.xml uses parent version ${revision} without explicit version pinning for transitive dependencies. MyBatis and MyBatis-Spring versions are inherited but not explicitly declared, potentially exposing the application to vulnerabilities in older versions. Fix: Explicitly declare all dependency versions. Use Spring Dependency Management BOM. Regularly audit dependencies with tools like OWASP Dependency-Check or Snyk for known vulnerabilities.
• Medium · Exposed Sensitive Information in Documentation — README.md. The README contains a personal email address (QiuRunZe_key@163.com) and references to internal communication. This could be exploited for social engineering attacks or targeted phishing campaigns. Fix: Use a dedicated organization email or contact form instead of personal email. Remove direct contact information from public repositories or use a business email account.
• Medium · Potential XSS Risk via JsonUtils — miaosha-admin/miaosha-admin-common/src/main/java/com/geekq/common/utils/JsonUtils.java. JsonUtils is present in the codebase for JSON serialization/deserialization. Without proper output encoding when returning JSON responses to web clients, XSS vulnerabilities could occur if user input is reflected in responses. Fix: Implement proper output encoding for JSON responses. Use Content-Type: application/json headers. Implement Content Security Policy (CSP) headers. Validate and sanitize all user inputs before serialization.
• Medium · SnowflakeIdWorker Implementation Review Needed — miaosha-admin/miaosha-admin-common/src/main/java/com/geekq/common/utils/SnowflakeIdWorker.java. Custom ID generation using SnowflakeIdWorker is implemented. If not properly implemented, it could suffer from clock skew issues or collision problems that could impact data integrity in a distributed system. Fix: Review the SnowflakeIdWorker implementation for proper timestamp handling and collision detection. Add comprehensive unit tests. Consider using battle-tested libraries like UidGenerator or Tinyid.
• Low · Incomplete Input Validation Framework — undefined. ValidatorUtil exists but its implementation is not visible. Entities lack visible @NotNull, Fix: undefined

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.