Mall — Administrator & Developer Guide

1. Architecture Overview

Mall is a multi-module Spring Boot 2.7.5 e-commerce backend platform structured as a monolithic application with clear module boundaries. It provides REST APIs for both back-office administration and customer-facing shopping operations, backed by MySQL, Redis, MongoDB, Elasticsearch, and RabbitMQ.

The system follows a layered architecture within each module: Controller → Service → DAO/Mapper, with a shared security module providing JWT-based authentication and dynamic URL-level authorization across all deployable modules.

┌─────────────────────────────────────────────────────────────────┐
│                        Client Applications                       │
│              (Admin SPA, Mobile App, Web Storefront)             │
└──────────┬──────────────────┬──────────────────┬────────────────┘
           │                  │                  │
     ┌─────▼─────┐    ┌──────▼──────┐    ┌─────▼─────┐
     │ mall-admin │    │ mall-portal │    │mall-search│
     │  :8080    │    │   :8085     │    │  :8081    │
     └─────┬─────┘    └──────┬──────┘    └─────┬─────┘
           │                  │                  │
     ┌─────▼──────────────────▼──────────────────▼─────┐
     │              mall-security (JWT + RBAC)          │
     └─────────────────────┬───────────────────────────┘
                           │
     ┌─────────────────────▼───────────────────────────┐
     │                   mall-mbg                       │
     │        (MyBatis Generated Mappers/Models)        │
     └─────────────────────┬───────────────────────────┘
                           │
     ┌─────────────────────▼───────────────────────────┐
     │                  mall-common                     │
     │    (Redis, Swagger, Pagination, Error Handling)  │
     └──┬──────────┬──────────┬──────────┬─────────────┘
        │          │          │          │
   ┌────▼───┐ ┌───▼───┐ ┌───▼────┐ ┌───▼─────┐
   │ MySQL  │ │ Redis │ │MongoDB │ │RabbitMQ │
   │  5.7   │ │   7   │ │   4    │ │  3.9    │
   └────────┘ └───────┘ └────────┘ └─────────┘
                                          │
                              ┌────────────▼────────────┐
                              │    Elasticsearch 7.17   │
                              └─────────────────────────┘

Component Inventory

Technology Stack

Note

The project targets Java 8 but includes javax.xml.bind:jaxb-api:2.3.1 for JDK 11+ compatibility. The codebase uses Spring Security's pre-6.0 API style (imperative HttpSecurity chain, not the newer Lambda DSL).

Data Flow: Order Placement

1. Customer calls POST /order/generateOrder with address, coupon, payment type
2. OmsPortalOrderServiceImpl validates cart, calculates promotions, deducts stock
3. Order record inserted into MySQL with status 0 (pending payment)
4. CancelOrderSender sends order ID to RabbitMQ TTL queue (mall.order.cancel.ttl)
5. If paid: POST /order/paySuccess updates status to 1
6. If TTL expires: message routed to dead-letter queue → CancelOrderReceiver cancels order, restores stock

2. System Requirements

Hardware (Minimum for Development)

Software Dependencies

3. Configuration Reference

Configuration Files

Spring Configuration Keys

Database (all modules)

Redis

MongoDB (mall-portal)

RabbitMQ (mall-portal)

Elasticsearch (mall-search)

JWT Security

Important

The jwt.secret value MUST be changed from any default in production. Issue #948 demonstrates that a weak default enables authentication bypass. Use a cryptographically random string of at least 64 characters.

Security Whitelist

Typical whitelist entries:

secure:
  ignored:
    urls:
      - /swagger-ui/**
      - /swagger-resources/**
      - /v2/api-docs
      - /**/admin/login
      - /**/sso/login
      - /**/sso/register
      - /actuator/**

Aliyun OSS (mall-admin)

MinIO (mall-admin)

Alipay (mall-portal)

Caution

Never commit Alipay private keys or OSS secrets to source control. Use environment variables or external secret management in production.

Spring MVC / Swagger Compatibility

4. Deployment & Scaling

Docker Image Build

The project uses the fabric8 Docker Maven plugin configured in the parent POM:

# Build all modules + Docker images
mvn clean package -DskipTests

Image naming convention: mall/{module-name}:1.0-SNAPSHOT

The Docker build base image is openjdk:8 with entrypoint:

java -jar -Dspring.profiles.active=prod /${module}.jar

Remote Docker host is configured at ${docker.host} (default: http://192.168.3.101:2375).

Infrastructure Deployment

Environment services (document/docker/docker-compose-env.yml):

docker compose -f document/docker/docker-compose-env.yml up -d

This deploys: MySQL, Redis, Nginx, RabbitMQ, Elasticsearch, Logstash, Kibana, MongoDB, MinIO.

Application services (document/docker/docker-compose-app.yml):

docker compose -f document/docker/docker-compose-app.yml up -d

This deploys: mall-admin (:8080), mall-search (:8081), mall-portal (:8085).

Port Mapping

Volume Mounts

Tip

All persistent data resides under /mydata/. Back up this directory for full system recovery.

Scaling Considerations

• mall-admin: Stateless — scale horizontally behind a load balancer. Redis handles session/cache.
• mall-portal: Stateless — scale horizontally. Ensure shared Redis for member caching.
• mall-search: Stateless — scale horizontally. All state lives in Elasticsearch.
• MySQL: Vertical scaling or read replicas. The application uses a single datasource.
• Elasticsearch: Add nodes to the cluster and change discovery.type from single-node.

Note

The Docker Compose files use external_links for inter-container communication (a deprecated feature). For production, use Docker networks or Kubernetes service discovery.

5. Operations

Health Checks

Each module exposes Spring Boot Actuator at /actuator/health:

curl http://localhost:8080/actuator/health
curl http://localhost:8085/actuator/health
curl http://localhost:8081/actuator/health

Log Management

Logging is configured via mall-common/src/main/resources/logback-spring.xml with Logstash integration:

• Application logs write to /var/logs/ (mapped to /mydata/app/{module}/logs/ on host)
• Logstash collects from ports 4560-4563 (one per module)
• Kibana provides visualization at port 5601

Database Initialization

mysql -u root -proot < document/sql/mall.sql

The SQL file creates:

• Database mall
• All ~70 tables with schema (prefixed: cms_*, oms_*, pms_*, sms_*, ums_*)
• Seed data (admin user, default categories, demo products)

MyBatis Generator (Code Regeneration)

To regenerate mapper/model classes after schema changes:

1. Update mall-mbg/src/main/resources/generator.properties with DB connection
2. Update mall-mbg/src/main/resources/generatorConfig.xml with target tables
3. Run Generator.java main class in mall-mbg

Warning

Regeneration overwrites all files in mall-mbg/src/main/java/com/macro/mall/mapper/ and mall-mbg/src/main/java/com/macro/mall/model/. Custom DAO classes in mall-admin or mall-portal dao/ packages are safe — they're in separate packages.

Elasticsearch Index Management

Import all products:

curl -X POST http://localhost:8081/esProduct/importAll

The EsProduct document maps product data with nested EsProductAttributeValue objects. The search service supports keyword matching, brand/category filtering, and attribute aggregation.

RabbitMQ Queue Setup

Queues are declared automatically by mall-portal on startup via RabbitMqConfig:

The TTL queue forwards expired messages to the cancel queue using dead-letter exchange configuration.

Tip

Monitor queue depth via RabbitMQ Management UI (http://localhost:15672). A growing mall.order.cancel.ttl queue during peak hours is normal; a growing mall.order.cancel queue indicates the consumer is falling behind.

Scheduled Tasks

mall-portal enables Spring's @EnableScheduling. The OrderTimeOutCancelTask runs on a cron schedule to catch any orders that weren't cancelled via the RabbitMQ mechanism (belt-and-suspenders approach).

6. Performance

Redis Caching Strategy

• Cache TTL: 1 day (configured in BaseRedisConfig)
• Serialization: Jackson2 with type information (enables proper deserialization)
• Cache service: RedisServiceImpl provides get/set/delete/expire operations used by UmsAdminCacheService and UmsMemberCacheService
• Cache failure resilience: RedisCacheAspect wraps all *CacheService methods — if Redis is down, cache operations silently fail unless annotated with @CacheException

Note

The @CacheException annotation marks cache methods that MUST throw on failure (e.g., login verification code validation). All other cache methods degrade gracefully when Redis is unavailable.

Connection Pooling

Druid connection pool is configured per module in application.yml. Key tuning parameters:

• initialSize — initial connections on startup
• minIdle — minimum idle connections
• maxActive — maximum concurrent connections
• maxWait — max wait time for a connection from pool

Pagination

All list operations use PageHelper (MyBatis plugin) or Spring Data pagination:

• CommonPage.restPage(List) — wraps MyBatis PageHelper results
• CommonPage.restPage(Page) — wraps Spring Data Page results (MongoDB, ES)

7. Security

Authentication Architecture

Request → JwtAuthenticationTokenFilter → SecurityFilterChain
  ├── Token present & valid → SecurityContext populated → proceed
  ├── Token missing/invalid → RestAuthenticationEntryPoint (401)
  └── Token valid but insufficient permissions → RestfulAccessDeniedHandler (403)

JWT Implementation (JwtTokenUtil):

• Algorithm: HS512
• Claims: sub (username), created (issue timestamp as millis)
• Expiration: configurable via jwt.expiration (seconds)
• Token refresh: only re-issues if current token is >30 min old (tokenRefreshJustBefore)

Dynamic URL-Based Authorization

When DynamicSecurityService bean is present (e.g., in mall-admin), the system enforces URL-level authorization:

1. DynamicSecurityMetadataSource loads all ums_resource entries on startup
2. For each request, it matches the URL against resource patterns
3. DynamicAccessDecisionManager checks if the user's roles include the required resource
4. This filter runs AFTER JwtAuthenticationTokenFilter and BEFORE FilterSecurityInterceptor

Warning

The mall-portal module does NOT enable dynamic resource authorization (no DynamicSecurityService bean). It relies solely on JWT authentication — any authenticated member can access all portal endpoints. If you need endpoint-level restrictions for members, you must implement it.

Password Security

• Algorithm: BCrypt (BCryptPasswordEncoder)
• Storage: ums_admin.password column stores BCrypt hash
• No password complexity enforcement in code (business logic only)

Security Whitelist

URLs in secure.ignored.urls completely bypass the security filter chain. Default whitelist includes:

• Swagger endpoints
• Login/register endpoints
• Actuator health check
• Static resources

Known Security Issues

Caution

The CORS configuration (addAllowedOriginPattern("*")) is suitable for development only. In production, restrict to your actual frontend domain(s).

Session Management

Sessions are disabled (SessionCreationPolicy.STATELESS). All state is carried in the JWT token. Redis is used for:

• Admin/member data caching (not session storage)
• Temporary verification codes (if implemented)

8. Developer Internals

Repository Structure

mall/
├── pom.xml                          # Parent POM (dependency management)
├── mall-common/                     # Shared library
│   └── src/main/java/.../common/
│       ├── api/                     # CommonResult, CommonPage, ResultCode
│       ├── config/                  # BaseRedisConfig, BaseSwaggerConfig
│       ├── domain/                  # SwaggerProperties, WebLog
│       ├── exception/               # ApiException, GlobalExceptionHandler
│       ├── log/                     # WebLogAspect (request logging)
│       ├── service/                 # RedisService interface + impl
│       └── util/                    # RequestUtil
├── mall-mbg/                        # MyBatis Generator
│   └── src/main/java/.../
│       ├── mapper/                  # 76 mapper interfaces
│       ├── model/                   # 76 model + 76 example classes
│       ├── Generator.java           # Code generation entry
│       └── CommentGenerator.java    # Custom comment generator
├── mall-security/                   # Security library
│   └── src/main/java/.../security/
│       ├── annotation/              # @CacheException
│       ├── aspect/                  # RedisCacheAspect
│       ├── component/               # Filters, handlers, dynamic auth
│       ├── config/                  # SecurityConfig, IgnoreUrlsConfig
│       └── util/                    # JwtTokenUtil, SpringUtil
├── mall-admin/                      # Admin API (deployable)
│   └── src/main/java/.../
│       ├── config/                  # CORS, Security, MyBatis, OSS, Swagger
│       ├── controller/              # 30+ REST controllers
│       ├── dao/                     # Custom DAO interfaces
│       ├── dto/                     # Request/response DTOs
│       ├── bo/                      # Business objects
│       ├── service/                 # Service interfaces
│       ├── service/impl/            # Service implementations
│       └── validator/               # Custom validation (@FlagValidator)
├── mall-portal/                     # Portal API (deployable)
│   └── src/main/java/.../portal/
│       ├── config/                  # Alipay, RabbitMQ, Jackson, CORS, etc.
│       ├── controller/              # 14 REST controllers
│       ├── component/               # CancelOrderSender/Receiver, scheduled task
│       ├── dao/                     # Custom DAO interfaces
│       ├── domain/                  # Domain models (Mongo docs, DTOs)
│       ├── repository/              # MongoDB repositories
│       ├── service/                 # Service interfaces
│       ├── service/impl/            # Service implementations
│       └── util/                    # DateUtil
├── mall-search/                     # Search API (deployable)
│   └── src/main/java/.../search/
│       ├── config/                  # MyBatis, Swagger
│       ├── controller/              # EsProductController
│       ├── dao/                     # EsProductDao (MyBatis)
│       ├── domain/                  # EsProduct, EsProductAttributeValue
│       ├── repository/              # EsProductRepository (Spring Data ES)
│       ├── service/                 # EsProductService
│       └── service/impl/            # EsProductServiceImpl
├── mall-demo/                       # Demo module (not production)
└── document/                        # Deployment & reference docs
    ├── docker/                      # Docker Compose files, nginx.conf
    ├── sh/                          # Deployment shell scripts
    ├── sql/                         # Database schema (mall.sql)
    ├── postman/                     # API collections
    ├── elk/                         # Logstash config
    ├── reference/                   # Developer reference docs
    └── resource/                    # Architecture diagrams, screenshots

Module Dependency Graph

mall-common ← mall-mbg ← mall-security ← mall-admin
                     ↑                  ← mall-portal
                     ↑                  ← mall-search
                     └── mall-demo

• mall-common: no internal dependencies (only Spring starters)
• mall-mbg: depends on mall-common (uses Redis, Swagger base, pagination)
• mall-security: depends on mall-common (uses Redis for caching)
• mall-admin: depends on mall-mbg + mall-security + Aliyun OSS + MinIO
• mall-portal: depends on mall-mbg + mall-security + MongoDB + RabbitMQ + Alipay
• mall-search: depends on mall-mbg + Elasticsearch (excludes Redis from mall-mbg transitively)

Database Schema Overview

The schema uses prefixed table naming to organize by domain:

Total: ~70 tables with full referential integrity.

API Response Patterns

Standard success response:

{"code": 200, "message": "操作成功", "data": {...}}

Standard error responses:

{"code": 401, "message": "暂未登录或token已经过期", "data": null}
{"code": 403, "message": "没有相关权限", "data": null}
{"code": 404, "message": "参数检验失败", "data": null}
{"code": 500, "message": "操作失败", "data": null}

Paginated response:

{
  "code": 200,
  "data": {
    "pageNum": 1,
    "pageSize": 5,
    "totalPage": 10,
    "total": 48,
    "list": [...]
  }
}

Code Patterns and Conventions

Controller pattern:

• Annotated with @Controller (not @RestController) + @ResponseBody per method
• @Api and @Tag for Swagger documentation
• @RequestMapping on class for base path
• Return CommonResult<T> or CommonResult<CommonPage<T>>

Service pattern:

• Interface in service/ package
• Implementation in service/impl/ with @Service
• Business logic lives here; controllers are thin dispatchers

DAO pattern (custom queries):

• Interface in dao/ package (annotated with MyBatis @Mapper via @MapperScan)
• XML mapping in resources/dao/ directory
• Used for complex queries beyond single-table CRUD (which uses MBG mappers)

Validation:

• Custom @FlagValidator annotation validates integer fields against allowed values
• Standard JSR-303 validation via Spring Boot Validation starter

Exception handling:

• GlobalExceptionHandler catches ApiException and validation errors
• Asserts.fail(message) throws ApiException with custom message
• Framework-level: RestAuthenticationEntryPoint (401), RestfulAccessDeniedHandler (403)

Testing

The project has minimal test coverage:

• mall-admin: PmsDaoTests (product DAO integration test)
• mall-portal: PortalProductDaoTests (product DAO test)
• mall-search: MallSearchApplicationTests (context load test)
• mall-demo: MallDemoApplicationTests (context load test)

Tests are skipped by default (<skipTests>true</skipTests> in parent POM).

9. Integration Points

Swagger UI (API Documentation)

Each deployable module auto-generates Swagger documentation:

Security-enabled Swagger configs (admin, portal) include the Authorization header parameter for testing protected endpoints.

Alipay Payment Integration

mall-portal integrates Alipay via the official Java SDK:

Configuration binds to prefix alipay.* via AlipayConfig (@ConfigurationProperties).

External Storage

MinIO (preferred for self-hosted):

• MinioController handles file upload/delete
• Bucket policy set to allow public read of uploaded files
• Configured via minio.* properties

Aliyun OSS (cloud option):

• OssController generates pre-signed upload policies
• Supports browser-direct upload with server callback
• Configured via aliyun.oss.* properties

Logstash Integration

logback-spring.xml in mall-common configures appenders that send structured JSON logs to Logstash:

• Port 4560: Default application logs
• Ports 4561-4563: Available for per-module separation

The WebLogAspect AOP aspect logs all controller method invocations with request/response details into structured WebLog objects.

MongoDB Collections

mall-portal uses MongoDB for:

• MemberReadHistory — product browsing history
• MemberProductCollection — product collections/favorites
• MemberBrandAttention — brand follows

These use Spring Data MongoDB repositories with automatic pagination support.

10. Troubleshooting

Startup Failures

Error: Failed to configure a DataSource

Cause: MySQL not reachable or credentials incorrect.

Solution:

1. Verify MySQL is running: docker ps | grep mysql
2. Test connection: mysql -h localhost -u root -proot
3. Verify application-dev.yml datasource configuration

Error: Connection refused to Redis/MongoDB/RabbitMQ

Cause: Infrastructure service not started.

Solution:

docker compose -f document/docker/docker-compose-env.yml up -d
docker ps  # verify all containers are running

Error: BeanCreationException related to Elasticsearch

Cause: Elasticsearch version mismatch or not running.

Solution: Ensure ES 7.17.x is running. Spring Data ES in Boot 2.7.5 targets ES 7.17. Using ES 8.x will fail.

Runtime Issues

Dynamic security metadata not loading

Cause: ums_resource table empty or DynamicSecurityService bean not registered.

Solution:

1. Check SELECT * FROM ums_resource — should have entries
2. Verify MallSecurityConfig in mall-admin declares dynamicSecurityService() bean

Note

Community issue #884 reports path matching optimization needed for the dynamic security filter — URL patterns with path variables may not match correctly in all edge cases.

Single-product order generation fails

Cause: Known issue with generating orders for individual products (vs. cart-based). (Community issue #469)

Solution: Use the cart-based flow: add product to cart, then generate order from cart contents.

Promotion calculation errors with full-reduction

Cause: Edge case in coupon amount distribution algorithm. (Community issue #492)

Solution: Verify promotion rules don't create conflicting overlapping conditions.

Warning

The coupon apportionment algorithm distributes discount amounts proportionally across order items. Rounding errors of ±1 cent can occur with certain item price/quantity combinations. (Issue #356)

11. Quick Reference

API Endpoint Summary

mall-admin (port 8080)

mall-portal (port 8085)

mall-search (port 8081)

Docker Commands Quick Reference

# Start all infrastructure
docker compose -f document/docker/docker-compose-env.yml up -d

# Start all application services
docker compose -f document/docker/docker-compose-app.yml up -d

# View logs for a specific container
docker logs -f mall-admin

# Restart a single service
docker restart mall-portal

# Check all container status
docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"

Build Commands

# Full build (skip tests)
mvn clean package -DskipTests

# Build single module
mvn clean package -DskipTests -pl mall-admin -am

# Run locally (dev profile)
java -jar mall-admin/target/mall-admin-1.0-SNAPSHOT.jar --spring.profiles.active=dev