# 积分服务开发文档

## 一、Entity 实体类

### UserPoints.java

```java
package com.openclaw.entity;

import com.baomidou.mybatisplus.annotation.*;
import lombok.Data;
import java.time.LocalDate;
import java.time.LocalDateTime;

@Data
@TableName("user_points")
public class UserPoints {
    @TableId(type = IdType.AUTO)
    private Long id;
    private Long userId;
    private Integer availablePoints;
    private Integer frozenPoints;
    private Integer totalEarned;
    private Integer totalConsumed;
    private LocalDate lastSignInDate;
    private Integer signInStreak;
    private LocalDateTime updatedAt;
}
```

### PointsRecord.java

```java
package com.openclaw.entity;

import com.baomidou.mybatisplus.annotation.*;
import lombok.Data;
import java.time.LocalDateTime;

@Data
@TableName("points_records")
public class PointsRecord {
    @TableId(type = IdType.AUTO)
    private Long id;
    private Long userId;
    private String pointsType;   // earn / consume / freeze / unfreeze
    private String source;       // register/sign_in/invite/...
    private Integer amount;
    private Integer balance;
    private String description;
    private Long relatedId;
    private String relatedType;
    private LocalDateTime createdAt;
}
```

### PointsRule.java

```java
package com.openclaw.entity;

import com.baomidou.mybatisplus.annotation.*;
import lombok.Data;
import java.time.LocalDateTime;

@Data
@TableName("points_rules")
public class PointsRule {
    @TableId(type = IdType.AUTO)
    private Integer id;
    private String ruleName;
    private String source;
    private Integer pointsAmount;
    private Integer frequencyLimit;
    private String frequencyPeriod; // daily/weekly/monthly/unlimited
    private Boolean enabled;
    private LocalDateTime createdAt;
    private LocalDateTime updatedAt;
}
```

## 二、VO

### PointsBalanceVO.java

```java
package com.openclaw.vo;

import lombok.Data;
import java.time.LocalDate;

@Data
public class PointsBalanceVO {
    private Integer availablePoints;
    private Integer frozenPoints;
    private Integer totalEarned;
    private Integer totalConsumed;
    private LocalDate lastSignInDate;
    private Integer signInStreak;
    private Boolean signedInToday;   // 今日是否已签到
}
```

### PointsRecordVO.java

```java
package com.openclaw.vo;

import lombok.Data;
import java.time.LocalDateTime;

@Data
public class PointsRecordVO {
    private Long id;
    private String pointsType;
    private String source;
    private String sourceLabel;   // 中文描述
    private Integer amount;
    private Integer balance;
    private String description;
    private LocalDateTime createdAt;
}
```

## 三、Service 接口

### PointsService.java

```java
package com.openclaw.service;

import com.baomidou.mybatisplus.core.metadata.IPage;
import com.openclaw.vo.*;

public interface PointsService {
    /** 初始化用户积分账户（注册时调用） */
    void initUserPoints(Long userId);

    /** 获取积分余额 */
    PointsBalanceVO getBalance(Long userId);

    /** 获取积分流水（分页） */
    IPage<PointsRecordVO> getRecords(Long userId, int pageNum, int pageSize);

    /** 每日签到 */
    int signIn(Long userId);

    /** 按规则发放积分（注册/邀请/加群/评价等） */
    void earnPoints(Long userId, String source, Long relatedId, String relatedType);

    /** 消耗积分（购买Skill） */
    void consumePoints(Long userId, int amount, Long relatedId, String relatedType);

    /** 冻结积分（下单时） */
    void freezePoints(Long userId, int amount, Long orderId);

    /** 解冻积分（取消订单时） */
    void unfreezePoints(Long userId, int amount, Long orderId);

    /** 检查积分是否充足 */
    boolean hasEnoughPoints(Long userId, int required);
}
```

## 四、Service 实现

### PointsServiceImpl.java

```java
package com.openclaw.service.impl;

import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
import com.baomidou.mybatisplus.core.metadata.IPage;
import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
import com.openclaw.constant.ErrorCode;
import com.openclaw.entity.*;
import com.openclaw.exception.BusinessException;
import com.openclaw.repository.*;
import com.openclaw.service.PointsService;
import com.openclaw.vo.*;
import lombok.RequiredArgsConstructor;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;

import java.time.LocalDate;

@Service
@RequiredArgsConstructor
public class PointsServiceImpl implements PointsService {

    private final UserPointsRepository userPointsRepo;
    private final PointsRecordRepository recordRepo;
    private final PointsRuleRepository ruleRepo;

    @Override
    @Transactional
    public void initUserPoints(Long userId) {
        UserPoints up = new UserPoints();
        up.setUserId(userId);
        up.setAvailablePoints(0);
        up.setFrozenPoints(0);
        up.setTotalEarned(0);
        up.setTotalConsumed(0);
        up.setSignInStreak(0);
        userPointsRepo.insert(up);
    }

    @Override
    public PointsBalanceVO getBalance(Long userId) {
        UserPoints up = userPointsRepo.findByUserId(userId);
        PointsBalanceVO vo = new PointsBalanceVO();
        if (up == null) return vo;
        vo.setAvailablePoints(up.getAvailablePoints());
        vo.setFrozenPoints(up.getFrozenPoints());
        vo.setTotalEarned(up.getTotalEarned());
        vo.setTotalConsumed(up.getTotalConsumed());
        vo.setLastSignInDate(up.getLastSignInDate());
        vo.setSignInStreak(up.getSignInStreak());
        vo.setSignedInToday(LocalDate.now().equals(up.getLastSignInDate()));
        return vo;
    }

    @Override
    public IPage<PointsRecordVO> getRecords(Long userId, int pageNum, int pageSize) {
        Page<PointsRecord> page = new Page<>(pageNum, pageSize);
        IPage<PointsRecord> result = recordRepo.selectPage(page,
            new LambdaQueryWrapper<PointsRecord>()
                .eq(PointsRecord::getUserId, userId)
                .orderByDesc(PointsRecord::getCreatedAt));
        return result.convert(this::toRecordVO);
    }

    @Override
    @Transactional
    public int signIn(Long userId) {
        UserPoints up = userPointsRepo.findByUserId(userId);
        LocalDate today = LocalDate.now();

        // 今日已签到
        if (today.equals(up.getLastSignInDate())) {
            throw new BusinessException(ErrorCode.ALREADY_SIGNED_IN);
        }

        // 计算连续签到天数
        boolean consecutive = up.getLastSignInDate() != null &&
            today.minusDays(1).equals(up.getLastSignInDate());
        int streak = consecutive ? up.getSignInStreak() + 1 : 1;

        // 签到积分：连续签到递增，最高20分
        int points = Math.min(5 + (streak - 1) * 1, 20);

        up.setLastSignInDate(today);
        up.setSignInStreak(streak);
        userPointsRepo.updateById(up);

        addPoints(userId, "earn", "sign_in", points, points, "每日签到", null, null);
        return points;
    }

    @Override
    @Transactional
    public void earnPoints(Long userId, String source, Long relatedId, String relatedType) {
        PointsRule rule = ruleRepo.findBySource(source);
        if (rule == null || !rule.getEnabled()) return;

        UserPoints up = userPointsRepo.findByUserId(userId);
        int newBalance = up.getAvailablePoints() + rule.getPointsAmount();
        addPoints(userId, "earn", source, rule.getPointsAmount(), newBalance,
            rule.getRuleName(), relatedId, relatedType);
    }

    @Override
    @Transactional
    public void consumePoints(Long userId, int amount, Long relatedId, String relatedType) {
        UserPoints up = userPointsRepo.findByUserId(userId);
        if (up.getAvailablePoints() < amount) throw new BusinessException(ErrorCode.POINTS_NOT_ENOUGH);
        int newBalance = up.getAvailablePoints() - amount;
        addPoints(userId, "consume", "skill_purchase", -amount, newBalance,
            "兑换Skill", relatedId, relatedType);
    }

    @Override
    @Transactional
    public void freezePoints(Long userId, int amount, Long orderId) {
        userPointsRepo.freezePoints(userId, amount);
        addPoints(userId, "freeze", "skill_purchase", -amount,
            userPointsRepo.findByUserId(userId).getAvailablePoints(),
            "积分冻结-订单" + orderId, orderId, "order");
    }

    @Override
    @Transactional
    public void unfreezePoints(Long userId, int amount, Long orderId) {
        userPointsRepo.unfreezePoints(userId, amount);
        addPoints(userId, "unfreeze", "skill_purchase", amount,
            userPointsRepo.findByUserId(userId).getAvailablePoints(),
            "积分解冻-订单取消" + orderId, orderId, "order");
    }

    @Override
    public boolean hasEnoughPoints(Long userId, int required) {
        UserPoints up = userPointsRepo.findByUserId(userId);
        return up != null && up.getAvailablePoints() >= required;
    }

    private void addPoints(Long userId, String type, String source, int amount,
                           int balance, String desc, Long relatedId, String relatedType) {
        // 更新账户
        if ("earn".equals(type)) {
            userPointsRepo.addAvailablePoints(userId, amount);
        } else if ("consume".equals(type)) {
            userPointsRepo.addAvailablePoints(userId, amount); // amount为负数
            userPointsRepo.addTotalConsumed(userId, -amount);
        }
        userPointsRepo.addTotalEarned(userId, "earn".equals(type) ? amount : 0);

        // 记录流水
        PointsRecord r = new PointsRecord();
        r.setUserId(userId);
        r.setPointsType(type);
        r.setSource(source);
        r.setAmount(amount);
        r.setBalance(balance);
        r.setDescription(desc);
        r.setRelatedId(relatedId);
        r.setRelatedType(relatedType);
        recordRepo.insert(r);
    }

    private PointsRecordVO toRecordVO(PointsRecord r) {
        PointsRecordVO vo = new PointsRecordVO();
        vo.setId(r.getId());
        vo.setPointsType(r.getPointsType());
        vo.setSource(r.getSource());
        vo.setSourceLabel(getSourceLabel(r.getSource()));
        vo.setAmount(r.getAmount());
        vo.setBalance(r.getBalance());
        vo.setDescription(r.getDescription());
        vo.setCreatedAt(r.getCreatedAt());
        return vo;
    }

    @Override
    @Transactional
    public void addPointsDirectly(Long userId, int amount, String source,
                                  Long relatedId, String desc) {
        UserPoints up = userPointsRepo.findByUserId(userId);
        if (up == null) throw new BusinessException(ErrorCode.USER_NOT_FOUND);
        int newBalance = up.getAvailablePoints() + amount;
        if (newBalance < 0) throw new BusinessException(ErrorCode.POINTS_NOT_ENOUGH);
        String type = amount >= 0 ? "earn" : "consume";
        addPoints(userId, type, source, amount, newBalance, desc, relatedId, null);
    }

    @Override
    public void ensureNotNegative(Long userId) {
        UserPoints up = userPointsRepo.findByUserId(userId);
        if (up != null && up.getAvailablePoints() < 0) {
            // 强制归零，记录一条修正流水
            int diff = -up.getAvailablePoints();
            addPoints(userId, "admin_correct", "admin_adjust", diff, 0,
                "积分余额修正（防负）", null, null);
        }
    }

    private String getSourceLabel(String source) {
        return switch (source) {
            case "register"       -> "新用户注册";
            case "sign_in"        -> "每日签到";
            case "invite"         -> "邀请好友";
            case "join_community" -> "加入社群";
            case "recharge"       -> "充值赠送";
            case "skill_purchase" -> "兑换Skill";
            case "review"         -> "发表评价";
            case "activity"       -> "活动奖励";
            case "admin_adjust"   -> "管理员调整";
            default               -> source;
        };
    }
}
```

## 五、Controller

### PointsController.java

```java
package com.openclaw.controller;

import com.baomidou.mybatisplus.core.metadata.IPage;
import com.openclaw.common.Result;
import com.openclaw.service.PointsService;
import com.openclaw.util.UserContext;
import com.openclaw.vo.*;
import lombok.RequiredArgsConstructor;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/api/v1/points")
@RequiredArgsConstructor
public class PointsController {

    private final PointsService pointsService;

    /** 获取积分余额 */
    @GetMapping("/balance")
    public Result<PointsBalanceVO> getBalance() {
        return Result.ok(pointsService.getBalance(UserContext.getUserId()));
    }

    /** 获取积分流水 */
    @GetMapping("/records")
    public Result<IPage<PointsRecordVO>> getRecords(
            @RequestParam(defaultValue = "1") int pageNum,
            @RequestParam(defaultValue = "20") int pageSize) {
        return Result.ok(pointsService.getRecords(UserContext.getUserId(), pageNum, pageSize));
    }

    /** 每日签到 */
    @PostMapping("/sign-in")
    public Result<Integer> signIn() {
        int earned = pointsService.signIn(UserContext.getUserId());
        return Result.ok(earned);
    }
}
```

---

**文档版本**：v1.0
**创建日期**：2026-03-16