# How the Member Level and Points System Works in the Mall E-Commerce Platform

> Discover how the Mall member level and points system boosts loyalty with automatic upgrades for consumption, sign-ins, and tasks, unlocking shipping discounts and exclusive promotions.

- Repository: [macro/mall](https://github.com/macrozheng/mall)
- Tags: deep-dive
- Published: 2026-02-28

---

**The Mall member level and points system uses a dual-track mechanism of growth value and integration points to drive user loyalty, where consumption, sign-ins, and task completion trigger automatic level upgrades and unlock shipping discounts or exclusive promotions.**

The `macrozheng/mall` project implements a comprehensive membership hierarchy that rewards customer engagement through configurable rules. All core logic resides in the **mall-portal** service layer and **mall-mbg** data models, creating a flexible foundation for e-commerce loyalty programs.

## Core Data Models

The system relies on four primary entities that define member status, level thresholds, and reward calculations.

### UmsMember: The Member Entity

In [`mall-mbg/src/main/java/com/macro/mall/model/UmsMember.java`](https://github.com/macrozheng/mall/blob/main/mall-mbg/src/main/java/com/macro/mall/model/UmsMember.java), the `UmsMember` class stores the runtime state of each user. Critical fields include:

- `memberLevelId`: Foreign key linking to the current membership tier
- `integration`: Available points balance (积分) used for order discounts
- `growth`: Cumulative growth value determining level eligibility

### UmsMemberLevel: Tier Definitions

The `UmsMemberLevel` model defines each membership tier's requirements and privileges. Key fields include `growthPoint` (the minimum growth value required to achieve this level), `defaultStatus` (boolean flag identifying the entry-level tier for new registrations), and privilege flags like `priviledgeFreeFreight` and `priviledgeSignIn` that enable specific benefits.

### UmsMemberRuleSetting: Conversion Rules

This entity stores the business logic for converting actions into rewards. The `type` field distinguishes between **0** (points rules) and **1** (growth rules). Important parameters include `consumePerPoint` (currency amount required to earn one point), `maxPointPerOrder` (earning cap per transaction), `lowOrderAmount` (minimum purchase to qualify), and `continueSignPoint` (daily sign-in reward value).

### UmsMemberTask: Achievement Rewards

Pre-defined accomplishments like first login or daily check-ins are stored in `UmsMemberTask`, which specifies the `growth` and `intergration` (points) awarded upon completion.

## Registration and Default Level Assignment

When a new user registers via `UmsMemberServiceImpl.register`, the system automatically assigns the default membership tier. The implementation queries `UmsMemberLevel` for the record where `defaultStatus = 1` and assigns that ID to the new member's `memberLevelId` field.

```java
// mall-portal/src/main/java/com/macro/mall/portal/service/impl/UmsMemberServiceImpl.java
UmsMemberLevelExample levelExample = new UmsMemberLevelExample();
levelExample.createCriteria().andDefaultStatusEqualTo(1);
List<UmsMemberLevel> memberLevelList = memberLevelMapper.selectByExample(levelExample);
if (!CollectionUtils.isEmpty(memberLevelList)) {
    umsMember.setMemberLevelId(memberLevelList.get(0).getId());
}

```

This ensures every new registrant starts with consistent baseline privileges without manual administrative intervention.

## How Points (Integration) and Growth Value Are Earned

The system maintains two distinct currencies: **integration points** (consumable for discounts) and **growth value** (lifetime cumulative progress toward level upgrades).

### Order Consumption Rewards

The `consumePerPoint` rule in `UmsMemberRuleSetting` defines the conversion rate from spending to points. During order processing in `OmsPortalOrderServiceImpl`, the system handles integration balances through precise lifecycle management.

When creating an order, the service deducts any points the member chooses to apply:

```java
// Deduct used points at order creation
memberService.updateIntegration(currentMember.getId(),
        currentMember.getIntegration() - orderParam.getUseIntegration());

```

If the order times out or cancels, the system refunds the reserved points:

```java
// Refund integration on cancellation
memberService.updateIntegration(order.getMemberId(),
        member.getIntegration() + order.getUseIntegration());

```

Upon order completion, the system calculates earned points as `orderAmount ÷ consumePerPoint`, rounded down, then applies the `maxPointPerOrder` ceiling before crediting the member's balance.

### Daily Sign-In Growth

The `continueSignPoint` field in `UmsMemberRuleSetting` specifies the growth value awarded for daily attendance. When `type = 1` (growth rule), the sign-in service adds this value directly to the member's `growth` field, accelerating their progress toward higher tiers.

### Task Completion Bonuses

The `UmsMemberTask` entity supports one-off achievements like "complete first login" or "finish profile setup." When triggered, the service adds `task.getGrowth()` to the cumulative growth value and `task.getIntergration()` to the spendable points balance, creating immediate gratification for user milestones.

## Level Upgrade Logic

Growth value serves as the sole determinant for tier progression. After any operation modifies a member's `growth` field—whether through purchases, sign-ins, or task completion—the system evaluates upgrade eligibility.

The logic queries all `UmsMemberLevel` records ordered by `growthPoint` ascending, then selects the highest tier where `growthPoint ≤ currentMember.growth`. If this tier differs from the current `memberLevelId`, the system updates the member record, effectively promoting the user and unlocking new privileges immediately.

```java
List<UmsMemberLevel> levels = memberLevelMapper
        .selectByExample(new UmsMemberLevelExample().orderBy("growth_point ASC"));

UmsMemberLevel newLevel = null;
for (UmsMemberLevel lvl : levels) {
    if (member.getGrowth() >= lvl.getGrowthPoint()) {
        newLevel = lvl;
    } else {
        break;
    }
}
if (newLevel != null && !newLevel.getId().equals(member.getMemberLevelId())) {
    member.setMemberLevelId(newLevel.getId());
    memberMapper.updateByPrimaryKeySelective(member);
}

```

## Member Privileges and Benefits

Each `UmsMemberLevel` record contains boolean privilege flags that frontend components and controllers evaluate to conditionally render features. The `priviledgeFreeFreight` flag enables free shipping options, while `priviledgeSignIn` may unlock enhanced daily rewards or exclusive promotional access. These flags decouple business rules from application code, allowing marketers to configure tier benefits through database updates alone.

## Summary

- The Mall member level and points system tracks **growth value** (for tier progression) and **integration points** (for order discounts) in the `UmsMember` entity.
- New registrations automatically receive the `UmsMemberLevel` where `defaultStatus = 1` via `UmsMemberServiceImpl.register`.
- Point earnings follow `consumePerPoint` ratios and `maxPointPerOrder` caps defined in `UmsMemberRuleSetting`, managed through `OmsPortalOrderServiceImpl`.
- Growth accumulates via sign-ins (`continueSignPoint`) and task completion (`UmsMemberTask`), triggering automatic tier upgrades when thresholds defined in `growthPoint` are crossed.
- Tier benefits like free shipping are controlled by privilege flags in `UmsMemberLevel`, enabling flexible loyalty program management.

## Frequently Asked Questions

### What is the difference between integration and growth in the Mall system?

**Integration** represents spendable points used to discount orders during checkout, while **growth** is a cumulative lifetime metric that determines membership tier eligibility. You can spend integration (decreasing your balance), but growth only increases until you reach the maximum tier level.

### How are points calculated when a customer places an order?

According to `UmsMemberRuleSetting`, the system divides the order amount by `consumePerPoint` (e.g., 10 yuan per point), rounds down to the nearest integer, then applies the `maxPointPerOrder` ceiling to prevent excessive earnings on large purchases. This calculation occurs in the order service layer after successful payment confirmation.

### Can a member lose their level status once achieved?

Based on the source code in `macrozheng/mall`, the level upgrade logic only promotes members when growth thresholds are crossed; there is no implemented decay mechanism or periodic review that reduces `growth` value or demotes tiers. Levels function as permanent achievements unless manually overridden in the database.

### How do I configure different point earning rates for different membership tiers?

While the current implementation uses global rules in `UmsMemberRuleSetting`, you can extend the system by adding a `memberLevelId` foreign key to the rule setting entity. This would allow tier-specific multipliers where higher levels earn points faster (lower `consumePerPoint` values) or have higher `maxPointPerOrder` limits, requiring custom logic in `UmsMemberServiceImpl.updateIntegration` to select the appropriate rule based on the member's current level.