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/linlinjava/litemall 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.

GO — Healthy across all four use cases

• Last commit 7mo ago
• 25+ active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Slowing — last commit 7mo ago
• ⚠ Concentrated ownership — top contributor handles 56% of recent commits

_{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 linlinjava/litemall repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/linlinjava/litemall.

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

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

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

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT 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"

# 4. Critical files exist
test -f "litemall-admin-api/pom.xml" \\
  && ok "litemall-admin-api/pom.xml" \\
  || miss "missing critical file: litemall-admin-api/pom.xml"
test -f "README.md" \\
  && ok "README.md" \\
  || miss "missing critical file: README.md"
test -f "CHANGELOG.md" \\
  && ok "CHANGELOG.md" \\
  || miss "missing critical file: CHANGELOG.md"
test -f "doc/api.md" \\
  && ok "doc/api.md" \\
  || miss "missing critical file: doc/api.md"
test -f "doc/database.md" \\
  && ok "doc/database.md" \\
  || miss "missing critical file: doc/database.md"

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

litemall is a complete e-commerce platform built with Spring Boot backend + Vue.js admin frontend + WeChat Mini Program user app + Vue mobile frontend. It provides a functional small shopping mall system with product catalog, shopping cart, orders, user management, and admin dashboard—designed as a learning/reference implementation rather than a production-ready system. Maven monorepo structure: litemall-core (shared utilities), litemall-db (MyBatis models + SQL), litemall-admin-api (Spring Boot REST backend), litemall-admin (Vue admin dashboard in litemall-admin/), litemall-wx (WeChat Mini Program), litemall-vue (Vue mobile SPA), litemall-all (executable JAR). Database schema under litemall-db/sql/ with separate schema/table/data files; deployment scripts in deploy/.

Chinese developers learning full-stack e-commerce development, specifically those targeting WeChat Mini Programs or building admin dashboards. Also useful for developers wanting a Spring Boot + Vue reference architecture for small-to-medium shopping platforms.

Actively developed but explicitly marked as experimental (README warns 'still in development, not suitable for production use'). Has CI/CD pipelines (GitHub Actions in .github/workflows/), comprehensive SQL schema, and organized module structure, but the Vue mobile frontend (litemall-vue) is noted as 'very unstable' and under development. Not recommended for production deployments.

Single maintainer (linlinjava) with moderate commit frequency; the project explicitly disclaims liability in SECURITY.md. Dependencies on dated libraries (swagger-bootstrap-ui 1.9.6, Shiro for auth, Kaptcha for CAPTCHA) that may have unpatched vulnerabilities. The WeChat Mini Program integration requires developer credentials and API setup that can fail silently. Maven build depends on external Maven Central repos with no lock file equivalent.

No visible recent activity data in provided files, but the .workflow/ and .github/workflows/ suggest active CI/CD (BranchPipeline, MasterPipeline, PRPipeline). CHANGELOG.md and doc/ folder suggest ongoing documentation. The litemall-vue module is explicitly flagged as in-progress.

Clone and install:

git clone https://github.com/linlinjava/litemall.git
cd litemall

Setup database (MySQL required):

mysql -u root -p < litemall-db/sql/litemall_schema.sql
mysql -u root -p < litemall-db/sql/litemall_table.sql
mysql -u root -p < litemall-db/sql/litemall_data.sql

Build and run backend:

mvn install && mvn clean package
java -Dfile.encoding=UTF-8 -jar litemall-all/target/litemall-all-0.1.0-exec.jar

Start admin frontend (http://localhost:9527):

cd litemall-admin && npm install --registry=https://registry.npm.taobao.org && npm run dev

Start mobile frontend (http://localhost:6255):

cd litemall-vue && npm install --registry=https://registry.npm.taobao.org && npm run dev

Import WeChat Mini Program (litemall-wx) via WeChat DevTools.

Daily commands: Backend (after DB setup): mvn clean package && java -Dfile.encoding=UTF-8 -jar litemall-all/target/litemall-all-0.1.0-exec.jar (runs on default Spring Boot port 8080). Admin Frontend: cd litemall-admin && npm install && npm run dev (Webpack dev server on :9527). Mobile Frontend: cd litemall-vue && npm install && npm run dev (on :6255). WeChat Mini Program: Import litemall-wx into WeChat DevTools, enable debug mode, click 'Compile'.

• litemall-admin-api/pom.xml — Parent Maven configuration defining all module dependencies and build profiles for the entire monolithic commerce platform
• README.md — Project overview describing the full stack (Spring Boot backend, Vue admin/mobile frontends, WeChat mini-program) and architecture
• CHANGELOG.md — Version history and breaking changes that impact all contributors working across backend, admin, and mobile modules
• doc/api.md — API contract documentation essential for coordinating between backend developers and frontend teams
• doc/database.md — Database schema and ER diagrams defining the data model for users, orders, goods, and admin operations
• docker/docker-compose.yml — Complete local development environment setup combining MySQL, litemall backend, and deployment configuration
• .workflow/MasterPipeline.yml — Production CI/CD pipeline defining build, test, and deployment workflow for master branch releases

Add a new REST API endpoint (Admin API)

1. Create or modify a Spring @RestController in litemall-admin-api/src/main/java/org/linlinjava module following existing Controller naming patterns (litemall-admin-api/src/main/java/org/linlinjava)
2. Define request/response DTOs in the same package, documenting schema in doc/api.md following existing endpoint format (doc/api.md)
3. Inject the corresponding Service from litemall-core module and implement business logic (litemall-admin-api/pom.xml)
4. Update MyBatis mapper XML files if new database queries are required, referencing database schema in doc/database.md (doc/database.md)

Add a new database table and entity

1. Add CREATE TABLE statement to a new SQL migration file in litemall-db/sql/ following existing naming convention (litemall_*.sql) (doc/database.md)
2. Document the table schema with column definitions and relationships in doc/database.md using entity-relationship diagram notation (doc/database.md)
3. Use MyBatis Generator to auto-generate Entity, Mapper, and MapperXML files from the table definition (doc/platform.md)
4. Create a Service interface and implementation in litemall-core for CRUD and business operations on the new entity (litemall-admin-api/pom.xml)

Deploy a new version to production

1. Update version number in root pom.xml and commit with meaningful message, triggering MasterPipeline.yml (.workflow/MasterPipeline.yml)
2. Verify all GitHub Actions / Aliyun DevOps build stages pass: compile, unit tests, Docker image build (.github/workflows/main.yml)
3. Deploy.sh is automatically executed to pull Docker image, restart MySQL containers via docker-compose.yml, and apply database migrations (docker/bin/deploy.sh)
4. Verify deployment by testing API endpoints documented in doc/api.md against production environment (doc/api.md)

Configure environment-specific settings (dev/stage/prod)

1. Create or modify application.yml in deploy/litemall/ and docker/litemall/ with environment variables for database URL, logging, caching (deploy/litemall/application.yml)
2. Update Maven profiles in root pom.xml and reference in .workflow pipelines to filter application.yml during package phase (.workflow/MasterPipeline.yml)
3. Reference deployment documentation in doc/project.md for Spring profile activation and Dockerfile ENV variables (doc/project.md)

• Spring Boot + Spring MVC — Mature, production-ready framework for rapid REST API development with built-in dependency injection, transaction management, and security
• Vue.js (admin + mobile web) — Progressive framework enabling rapid UI development for both desktop admin dashboard and responsive mobile web with component reusability
• WeChat Mini-Program — Taps native WeChat user ecosystem in China; reduces friction vs. native app download while leveraging WeChat Pay integration
• MySQL 5.7+ — Mature ACID-compliant RDBMS suitable for transactional e-commerce data (orders, payments, inventory) with good JSON support
• MyBatis ORM — Lightweight, SQL-first mapping that preserves direct database control while reducing boilerplate compared to full JPA abstraction
• Docker + Docker Compose — Containerization ensures dev/stage/prod environment parity; Compose simplifies multi-container local development (app + MySQL)
• Maven monorepo — Single build system managing multiple interdependent modules (core, admin-api, shared services) with unified dependency versions

• Monolithic architecture (single Spring Boot backend for admin + consumer APIs)

  • Why: Simpler deployment, unified authentication/authorization, shared data model for rapid MVP iteration
  • Consequence: Tightly coupled admin and consumer business logic; harder to scale consumer API independently if traffic diverges; admin API changes risk breaking consumer clients

• MyBatis over JPA/Hibernate

  • Why: Fine-grained SQL control for complex e-commerce queries (joins, aggregations, pagination); smaller runtime overhead
  • Consequence: More boilerplate mapper code; N+1 query risks if not carefully managed; less abstraction over database-specific dialects

• Vue 2 (implied from context) for both admin and mobile web

  • Why: Code reuse between admin/mobile; single frontend skill set; established ecosystem in 2020–2021 timeframe
  • Consequence: Vue 2 is now in maintenance mode; mobile web UX may lag native mobile apps; shared codebase creates deployment coupling

• Docker Compose for local dev, shell scripts for prod deploy

  • Why: Reduces setup friction (docker-compose up); familiar bash scripts for existing ops teams
  • Consequence: Limited orchestration (no Kubernetes); manual scaling; no declarative infrastructure-as-code for staging/production

• Real-time inventory synchronization across multiple warehouses
• Microservices architecture (intentionally monolithic for simplicity)
• GraphQL API (REST-only design)
• Multi-tenant SaaS platform (single-tenant commerce system)
• Offline-first mobile app (WeChat mini-program requires connectivity)
• Cross-border payment/tax compliance automation (CN-focused, supports WeChat Pay / Alipay)
• Advanced recommendation engine (basic category/tag browsing only)

1. MySQL version: Uses reserved keyword 'like' in some queries; may fail on stricter MySQL 8.0+ configurations. 2. File encoding: Explicitly requires UTF-8 via JVM flag (-Dfile.encoding=UTF-8) to avoid garbled Chinese characters. 3. WeChat credentials: Mini Program features (login, payment, messaging) silently fail without valid AppID/AppSecret in application.yml; no error logs. 4. Node version: npm registry hardcoded to Taobao mirror; may fail outside China or with newer npm versions. 5. Shiro config: Token/session secrets are hardcoded in defaults; must be overridden in production. 6. Database init order: SQL files must load in exact sequence (schema → table → data); partial loads cause foreign key constraint failures.

• RBAC (Role-Based Access Control) — litemall uses Shiro's RBAC model for admin permissions; essential to understand roles, permissions, and resources hierarchy when adding new admin features
• MyBatis ORM and Code Generation — litemall-db uses mybatis-generator plugin to auto-generate mappers from schema; understanding how to regenerate and customize mappers is critical for database schema changes
• JWT vs Session Token Auth — litemall switching between session-based (Shiro) and token-based auth in different modules; knowing the trade-offs is essential for modifying login/permission flows
• WeChat Mini Program API Sandboxing — litemall-wx requires WeChat-specific constraints (no cookies, limited API surface, domain whitelist); these are non-obvious compared to web development
• Maven Monorepo Module Dependencies — litemall-admin-api depends on litemall-core and litemall-db via parent POM; understanding inter-module versioning and build order prevents breakage during refactors
• Swagger 2 / OpenAPI Annotations — All backend endpoints use @ApiOperation and @ApiParam for auto-documentation; modifying without updating annotations breaks the API docs that admins rely on
• Vue Router Lazy Loading and Permission Guards — litemall-admin uses dynamic route registration with permission checks; essential pattern for adding new admin pages without hardcoding routes

• tumobi/nideshop-mini-program — Direct predecessor: litemall-db schema and litemall-wx Mini Program are based on/forked from this Node.js + MySQL shop implementation
• PanJiaChen/vue-element-admin — Frontend framework inspiration: litemall-admin dashboard architecture and UI patterns (router, permissions, layout) extend this Vue + Element admin template
• macrozheng/mall-admin-web — Companion e-commerce admin reference: another Vue + Element mall dashboard used for design pattern comparison and feature inspiration
• juicessh/juice-ssh-android — Not directly related, but if looking for other open Chinese e-commerce projects, this ecosystem includes mobile + backend separation patterns similar to litemall
• apache/shiro — Core auth dependency: litemall uses Shiro for RBAC and token management; understanding Shiro's realm/filter chain is essential for modifying permissions

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 API documentation for litemall-admin-api endpoints in doc/api.md

The repo has doc/api.md referenced in README but the file structure shows it exists without clear endpoint documentation. The litemall-admin-api module uses Swagger (springfox-swagger-ui, springfox-swagger2) but lacks detailed markdown documentation mapping all admin API endpoints, authentication requirements, request/response examples, and error codes. This would improve contributor onboarding and API integration.

• [ ] Extract Swagger endpoint definitions from litemall-admin-api source code
• [ ] Document all admin endpoints with HTTP method, path, authentication (Shiro-based), request/response schemas
• [ ] Add curl/postman examples for key endpoints (login, user management, product management, order management)
• [ ] Update doc/api.md with endpoint reference table and authentication flow diagram
• [ ] Link doc/api.md from README.md and CONTRIBUTE.md for discoverability

Add GitHub Actions workflow for Maven build and unit test validation on PR

The repo has .github/workflows/main.yml and .workflow directories (Aliyun workflows) but GitHub Actions CI is not configured for automated Maven builds and test execution on PRs. This prevents catching broken builds, compilation errors, or test failures before merge, which is critical for a multi-module Java project with litemall-core, litemall-db, and litemall-admin-api dependencies.

• [ ] Create .github/workflows/maven-build.yml workflow that triggers on push and pull_request events
• [ ] Configure Maven build step with Java 1.8+ (matching project.build.sourceEncoding UTF-8)
• [ ] Add Maven test execution step (mvn clean test) to validate all modules
• [ ] Configure workflow to fail if any module fails compilation or tests fail
• [ ] Add workflow badge to README.md showing build status

Add integration test setup for database layer (litemall-db) with test containers

The repo has doc/database.md with database design but no visible integration tests for the MyBatis-generated DAOs in litemall-db module. The file structure shows deploy/db with database configuration but no test fixtures. Adding testcontainers-based integration tests would ensure database migrations and ORM mappings work correctly and help contributors validate schema changes without manual setup.

• [ ] Add testcontainers-mysql dependency to litemall-db pom.xml
• [ ] Create src/test/java/org/linlinjava/litemall/db directory structure
• [ ] Write integration tests for core entities (User, Goods, Order from doc/pics/database)
• [ ] Create DatabaseTestBase class that spins up test MySQL container and runs schema migrations
• [ ] Add test data fixtures and document how to run integration tests in CONTRIBUTE.md
• [ ] Integrate tests into GitHub Actions workflow from PR #2

• Add integration tests for litemall-admin-api endpoints (doc/api.md lists 50+ endpoints but no test files visible in provided list); start with login, product list, and order endpoints using MockMvc.
• Document the complete WeChat Mini Program setup flow in doc/mobmall.md (currently vague on AppID registration, domain whitelist, and payment sandbox config); include screenshots and troubleshooting.
• Extract Shiro auth configuration from hardcoded defaults into externalizable deploy/litemall/application.yml with validated examples; add validation warnings if secrets are too simple.

• High · Outdated Swagger UI Dependency — litemall-admin-api/pom.xml - swagger-bootstrap-ui dependency. The project uses swagger-bootstrap-ui version 1.9.6, which is significantly outdated (released around 2019). This version may contain known security vulnerabilities in its dependencies, including potential XSS issues in Swagger UI rendering. Fix: Update to the latest version of swagger-ui or springfox-swagger-ui. Consider using springdoc-openapi-ui (3.0+) as a modern alternative with better security practices.
• High · Potential Missing Input Validation in Kaptcha Integration — litemall-admin-api/pom.xml - kaptcha dependency; missing validation controller code. The project includes kaptcha for CAPTCHA functionality, but without visible validation logic in the provided file structure, there's risk of improper CAPTCHA validation, session fixation, or replay attacks. Fix: Ensure all CAPTCHA implementations validate: 1) Token expiration, 2) Single-use tokens, 3) Session binding, 4) Rate limiting on attempts
• High · Apache Shiro Security Framework Without Visible Configuration — litemall-admin-api/pom.xml - shiro-spring-boot-web-starter dependency. The project uses Apache Shiro (shiro-spring-boot-web-starter) for authentication/authorization, but configuration details are not visible in provided files. Improper Shiro configuration could lead to authentication bypass or privilege escalation. Fix: Review Shiro configuration for: 1) Strong session management, 2) Proper realm configuration, 3) Secure password hashing (bcrypt/argon2), 4) CSRF protection, 5) Session timeout settings
• Medium · Potential SQL Injection via MyBatis Generator — litemall-db module (referenced in dependencies); MyBatis configuration not fully visible. The file structure indicates MyBatis usage with auto-generated code. While MyBatis uses prepared statements by default, improper usage of dynamic SQL or raw SQL queries could introduce SQL injection vulnerabilities. Fix: 1) Audit all MyBatis XML mappers for dynamic SQL, 2) Ensure parameterized queries are used everywhere, 3) Never concatenate user input into SQL, 4) Use MyBatis parameter binding exclusively
• Medium · WeChat Mini-Program Integration Security Concerns — litemall-admin-api/pom.xml - weixin-java-miniapp dependency. The project integrates weixin-java-miniapp for WeChat Mini-Program authentication. Without visible security implementation, there are risks of: token replay attacks, insecure session handling, or improper signature verification. Fix: 1) Implement proper token validation and refresh mechanisms, 2) Verify WeChat signatures on all requests, 3) Use HTTPS only, 4) Implement rate limiting, 5) Validate user sessions server-side
• Medium · Incomplete Dependency Version Management — litemall root pom.xml (parent configuration). The parent POM defines versions for dependencies, but the spring-boot-starter version is not visible in the provided snippet. Missing explicit version pins for transitive dependencies could lead to unexpected vulnerable versions being pulled in. Fix: 1) Use explicit version ranges or exact versions, 2) Run 'mvn dependency:tree' to audit transitive dependencies, 3) Implement dependency-check plugin to scan for known CVEs, 4) Use Maven enforcer plugin
• Medium · Missing Security Headers Configuration — deploy/litemall/application.yml; doc/conf/nginx.conf. No visible configuration for security headers (CSP, X-Frame-Options, X-Content-Type-Options, Strict-Transport-Security) in the provided deployment or application configuration files. Fix: 1) Add Spring Security configuration for HTTP security headers, 2) Configure Nginx with: 'add_header X-Frame-Options DENY;', 'add_header X-Content-Type-Options nosniff;', 'add_header Strict-Transport-Security max-age=31536000;', 3) Implement Content-Security-Policy
• Medium · Docker Configuration Exposed Port Security — undefined. Docker configuration is present but the actual 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.