feat(user-invites): 新增用户邀请关系管理后台功能

feat(user-invite-codes): 新增用户邀请码管理功能
- 新增邀请码实体、Mapper、Service及Controller全套接口 - 支持邀请码分页查询、保存及详情展示 - 新增USER_INVITE_CODES_NOT_EXISTS错误码 - 租户模块补充上级返点比例字段 upstreamRebateRatio
2025-12-29 14:25:04 +08:00 · 2025-12-29 14:15:04 +08:00
23 changed files with 1127 additions and 1 deletions
--- a/keyboard-server/src/main/java/com/yolo/keyboard/controller/admin/userinvitecodes/KeyboardUserInviteCodesController.java
+++ b/keyboard-server/src/main/java/com/yolo/keyboard/controller/admin/userinvitecodes/KeyboardUserInviteCodesController.java
@@ -0,0 +1,104 @@
+package com.yolo.keyboard.controller.admin.userinvitecodes;
+
+import org.springframework.web.bind.annotation.*;
+import jakarta.annotation.Resource;
+import org.springframework.validation.annotation.Validated;
+import org.springframework.security.access.prepost.PreAuthorize;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.Operation;
+
+import jakarta.validation.constraints.*;
+import jakarta.validation.*;
+import jakarta.servlet.http.*;
+import java.util.*;
+import java.io.IOException;
+
+import com.yolo.keyboard.framework.common.pojo.PageParam;
+import com.yolo.keyboard.framework.common.pojo.PageResult;
+import com.yolo.keyboard.framework.common.pojo.CommonResult;
+import com.yolo.keyboard.framework.common.util.object.BeanUtils;
+import static com.yolo.keyboard.framework.common.pojo.CommonResult.success;
+
+import com.yolo.keyboard.framework.excel.core.util.ExcelUtils;
+
+import com.yolo.keyboard.framework.apilog.core.annotation.ApiAccessLog;
+import static com.yolo.keyboard.framework.apilog.core.enums.OperateTypeEnum.*;
+
+import com.yolo.keyboard.controller.admin.userinvitecodes.vo.*;
+import com.yolo.keyboard.dal.dataobject.userinvitecodes.KeyboardUserInviteCodesDO;
+import com.yolo.keyboard.service.userinvitecodes.KeyboardUserInviteCodesService;
+
+@Tag(name = "管理后台 - 用户生成的邀请码表，用于邀请新用户注册/安装并建立邀请关系")
+@RestController
+@RequestMapping("/keyboard/user-invite-codes")
+@Validated
+public class KeyboardUserInviteCodesController {
+
+    @Resource
+    private KeyboardUserInviteCodesService userInviteCodesService;
+
+    @PostMapping("/create")
+    @Operation(summary = "创建用户生成的邀请码表，用于邀请新用户注册/安装并建立邀请关系")
+    @PreAuthorize("@ss.hasPermission('keyboard:user-invite-codes:create')")
+    public CommonResult<Long> createUserInviteCodes(@Valid @RequestBody KeyboardUserInviteCodesSaveReqVO createReqVO) {
+        return success(userInviteCodesService.createUserInviteCodes(createReqVO));
+    }
+
+    @PutMapping("/update")
+    @Operation(summary = "更新用户生成的邀请码表，用于邀请新用户注册/安装并建立邀请关系")
+    @PreAuthorize("@ss.hasPermission('keyboard:user-invite-codes:update')")
+    public CommonResult<Boolean> updateUserInviteCodes(@Valid @RequestBody KeyboardUserInviteCodesSaveReqVO updateReqVO) {
+        userInviteCodesService.updateUserInviteCodes(updateReqVO);
+        return success(true);
+    }
+
+    @DeleteMapping("/delete")
+    @Operation(summary = "删除用户生成的邀请码表，用于邀请新用户注册/安装并建立邀请关系")
+    @Parameter(name = "id", description = "编号", required = true)
+    @PreAuthorize("@ss.hasPermission('keyboard:user-invite-codes:delete')")
+    public CommonResult<Boolean> deleteUserInviteCodes(@RequestParam("id") Long id) {
+        userInviteCodesService.deleteUserInviteCodes(id);
+        return success(true);
+    }
+
+    @DeleteMapping("/delete-list")
+    @Parameter(name = "ids", description = "编号", required = true)
+    @Operation(summary = "批量删除用户生成的邀请码表，用于邀请新用户注册/安装并建立邀请关系")
+                @PreAuthorize("@ss.hasPermission('keyboard:user-invite-codes:delete')")
+    public CommonResult<Boolean> deleteUserInviteCodesList(@RequestParam("ids") List<Long> ids) {
+        userInviteCodesService.deleteUserInviteCodesListByIds(ids);
+        return success(true);
+    }
+
+    @GetMapping("/get")
+    @Operation(summary = "获得用户生成的邀请码表，用于邀请新用户注册/安装并建立邀请关系")
+    @Parameter(name = "id", description = "编号", required = true, example = "1024")
+    @PreAuthorize("@ss.hasPermission('keyboard:user-invite-codes:query')")
+    public CommonResult<KeyboardUserInviteCodesRespVO> getUserInviteCodes(@RequestParam("id") Long id) {
+        KeyboardUserInviteCodesDO userInviteCodes = userInviteCodesService.getUserInviteCodes(id);
+        return success(BeanUtils.toBean(userInviteCodes, KeyboardUserInviteCodesRespVO.class));
+    }
+
+    @GetMapping("/page")
+    @Operation(summary = "获得用户生成的邀请码表，用于邀请新用户注册/安装并建立邀请关系分页")
+    @PreAuthorize("@ss.hasPermission('keyboard:user-invite-codes:query')")
+    public CommonResult<PageResult<KeyboardUserInviteCodesRespVO>> getUserInviteCodesPage(@Valid KeyboardUserInviteCodesPageReqVO pageReqVO) {
+        PageResult<KeyboardUserInviteCodesDO> pageResult = userInviteCodesService.getUserInviteCodesPage(pageReqVO);
+        return success(BeanUtils.toBean(pageResult, KeyboardUserInviteCodesRespVO.class));
+    }
+
+    @GetMapping("/export-excel")
+    @Operation(summary = "导出用户生成的邀请码表，用于邀请新用户注册/安装并建立邀请关系 Excel")
+    @PreAuthorize("@ss.hasPermission('keyboard:user-invite-codes:export')")
+    @ApiAccessLog(operateType = EXPORT)
+    public void exportUserInviteCodesExcel(@Valid KeyboardUserInviteCodesPageReqVO pageReqVO,
+              HttpServletResponse response) throws IOException {
+        pageReqVO.setPageSize(PageParam.PAGE_SIZE_NONE);
+        List<KeyboardUserInviteCodesDO> list = userInviteCodesService.getUserInviteCodesPage(pageReqVO).getList();
+        // 导出 Excel
+        ExcelUtils.write(response, "用户生成的邀请码表，用于邀请新用户注册/安装并建立邀请关系.xls", "数据", KeyboardUserInviteCodesRespVO.class,
+                        BeanUtils.toBean(list, KeyboardUserInviteCodesRespVO.class));
+    }
+
+}
--- a/keyboard-server/src/main/java/com/yolo/keyboard/controller/admin/userinvitecodes/vo/KeyboardUserInviteCodesPageReqVO.java
+++ b/keyboard-server/src/main/java/com/yolo/keyboard/controller/admin/userinvitecodes/vo/KeyboardUserInviteCodesPageReqVO.java
@@ -0,0 +1,49 @@
+package com.yolo.keyboard.controller.admin.userinvitecodes.vo;
+
+import lombok.*;
+import java.util.*;
+import io.swagger.v3.oas.annotations.media.Schema;
+import com.yolo.keyboard.framework.common.pojo.PageParam;
+import org.springframework.format.annotation.DateTimeFormat;
+import java.time.LocalDateTime;
+
+import static com.yolo.keyboard.framework.common.util.date.DateUtils.FORMAT_YEAR_MONTH_DAY_HOUR_MINUTE_SECOND;
+
+@Schema(description = "管理后台 - 用户生成的邀请码表，用于邀请新用户注册/安装并建立邀请关系分页 Request VO")
+@Data
+public class KeyboardUserInviteCodesPageReqVO extends PageParam {
+
+    @Schema(description = "邀请码字符串，对外展示，唯一")
+    private String code;
+
+    @Schema(description = "邀请码所属用户ID（邀请人）", example = "14170")
+    private Long ownerUserId;
+
+    @Schema(description = "邀请码状态：1=启用，0=停用", example = "2")
+    private Short status;
+
+    @Schema(description = "邀请码创建时间")
+    private LocalDateTime createdAt;
+
+    @Schema(description = "邀请码过期时间，NULL表示永久有效")
+    private LocalDateTime expiresAt;
+
+    @Schema(description = "邀请码最大可使用次数，NULL表示不限次数")
+    private Integer maxUses;
+
+    @Schema(description = "邀请码已使用次数", example = "25037")
+    private Integer usedCount;
+
+    @Schema(description = "邀请码所属系统用户ID（邀请人）", example = "20047")
+    private Long systemUserId;
+
+    @Schema(description = "邀请码所属租户", example = "17355")
+    private Long ownerTenantId;
+
+    @Schema(description = "邀请码所属系统用户", example = "772")
+    private Long owenrSystemUserId;
+
+    @Schema(description = "邀请码类型", example = "1")
+    private String inviteType;
+
+}
--- a/keyboard-server/src/main/java/com/yolo/keyboard/controller/admin/userinvitecodes/vo/KeyboardUserInviteCodesRespVO.java
+++ b/keyboard-server/src/main/java/com/yolo/keyboard/controller/admin/userinvitecodes/vo/KeyboardUserInviteCodesRespVO.java
@@ -0,0 +1,63 @@
+package com.yolo.keyboard.controller.admin.userinvitecodes.vo;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+import lombok.*;
+import java.util.*;
+import org.springframework.format.annotation.DateTimeFormat;
+import java.time.LocalDateTime;
+import cn.idev.excel.annotation.*;
+
+@Schema(description = "管理后台 - 用户生成的邀请码表，用于邀请新用户注册/安装并建立邀请关系 Response VO")
+@Data
+@ExcelIgnoreUnannotated
+public class KeyboardUserInviteCodesRespVO {
+
+    @Schema(description = "邀请码主键ID", requiredMode = Schema.RequiredMode.REQUIRED, example = "3053")
+    @ExcelProperty("邀请码主键ID")
+    private Long id;
+
+    @Schema(description = "邀请码字符串，对外展示，唯一", requiredMode = Schema.RequiredMode.REQUIRED)
+    @ExcelProperty("邀请码字符串，对外展示，唯一")
+    private String code;
+
+    @Schema(description = "邀请码所属用户ID（邀请人）", requiredMode = Schema.RequiredMode.REQUIRED, example = "14170")
+    @ExcelProperty("邀请码所属用户ID（邀请人）")
+    private Long ownerUserId;
+
+    @Schema(description = "邀请码状态：1=启用，0=停用", requiredMode = Schema.RequiredMode.REQUIRED, example = "2")
+    @ExcelProperty("邀请码状态：1=启用，0=停用")
+    private Short status;
+
+    @Schema(description = "邀请码创建时间", requiredMode = Schema.RequiredMode.REQUIRED)
+    @ExcelProperty("邀请码创建时间")
+    private LocalDateTime createdAt;
+
+    @Schema(description = "邀请码过期时间，NULL表示永久有效")
+    @ExcelProperty("邀请码过期时间，NULL表示永久有效")
+    private LocalDateTime expiresAt;
+
+    @Schema(description = "邀请码最大可使用次数，NULL表示不限次数")
+    @ExcelProperty("邀请码最大可使用次数，NULL表示不限次数")
+    private Integer maxUses;
+
+    @Schema(description = "邀请码已使用次数", requiredMode = Schema.RequiredMode.REQUIRED, example = "25037")
+    @ExcelProperty("邀请码已使用次数")
+    private Integer usedCount;
+
+    @Schema(description = "邀请码所属系统用户ID（邀请人）", example = "20047")
+    @ExcelProperty("邀请码所属系统用户ID（邀请人）")
+    private Long systemUserId;
+
+    @Schema(description = "邀请码所属租户", example = "17355")
+    @ExcelProperty("邀请码所属租户")
+    private Long ownerTenantId;
+
+    @Schema(description = "邀请码所属系统用户", example = "772")
+    @ExcelProperty("邀请码所属系统用户")
+    private Long owenrSystemUserId;
+
+    @Schema(description = "邀请码类型", requiredMode = Schema.RequiredMode.REQUIRED, example = "1")
+    @ExcelProperty("邀请码类型")
+    private String inviteType;
+
+}
--- a/keyboard-server/src/main/java/com/yolo/keyboard/controller/admin/userinvitecodes/vo/KeyboardUserInviteCodesSaveReqVO.java
+++ b/keyboard-server/src/main/java/com/yolo/keyboard/controller/admin/userinvitecodes/vo/KeyboardUserInviteCodesSaveReqVO.java
@@ -0,0 +1,56 @@
+package com.yolo.keyboard.controller.admin.userinvitecodes.vo;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+import lombok.*;
+import java.util.*;
+import jakarta.validation.constraints.*;
+import org.springframework.format.annotation.DateTimeFormat;
+import java.time.LocalDateTime;
+
+@Schema(description = "管理后台 - 用户生成的邀请码表，用于邀请新用户注册/安装并建立邀请关系新增/修改 Request VO")
+@Data
+public class KeyboardUserInviteCodesSaveReqVO {
+
+    @Schema(description = "邀请码主键ID", requiredMode = Schema.RequiredMode.REQUIRED, example = "3053")
+    private Long id;
+
+    @Schema(description = "邀请码字符串，对外展示，唯一", requiredMode = Schema.RequiredMode.REQUIRED)
+    @NotEmpty(message = "邀请码字符串，对外展示，唯一不能为空")
+    private String code;
+
+    @Schema(description = "邀请码所属用户ID（邀请人）", requiredMode = Schema.RequiredMode.REQUIRED, example = "14170")
+    @NotNull(message = "邀请码所属用户ID（邀请人）不能为空")
+    private Long ownerUserId;
+
+    @Schema(description = "邀请码状态：1=启用，0=停用", requiredMode = Schema.RequiredMode.REQUIRED, example = "2")
+    @NotNull(message = "邀请码状态：1=启用，0=停用不能为空")
+    private Short status;
+
+    @Schema(description = "邀请码创建时间", requiredMode = Schema.RequiredMode.REQUIRED)
+    @NotNull(message = "邀请码创建时间不能为空")
+    private LocalDateTime createdAt;
+
+    @Schema(description = "邀请码过期时间，NULL表示永久有效")
+    private LocalDateTime expiresAt;
+
+    @Schema(description = "邀请码最大可使用次数，NULL表示不限次数")
+    private Integer maxUses;
+
+    @Schema(description = "邀请码已使用次数", requiredMode = Schema.RequiredMode.REQUIRED, example = "25037")
+    @NotNull(message = "邀请码已使用次数不能为空")
+    private Integer usedCount;
+
+    @Schema(description = "邀请码所属系统用户ID（邀请人）", example = "20047")
+    private Long systemUserId;
+
+    @Schema(description = "邀请码所属租户", example = "17355")
+    private Long ownerTenantId;
+
+    @Schema(description = "邀请码所属系统用户", example = "772")
+    private Long owenrSystemUserId;
+
+    @Schema(description = "邀请码类型", requiredMode = Schema.RequiredMode.REQUIRED, example = "1")
+    @NotEmpty(message = "邀请码类型不能为空")
+    private String inviteType;
+
+}
--- a/keyboard-server/src/main/java/com/yolo/keyboard/controller/admin/userinvites/KeyboardUserInvitesController.java
+++ b/keyboard-server/src/main/java/com/yolo/keyboard/controller/admin/userinvites/KeyboardUserInvitesController.java
@@ -0,0 +1,104 @@
+package com.yolo.keyboard.controller.admin.userinvites;
+
+import org.springframework.web.bind.annotation.*;
+import jakarta.annotation.Resource;
+import org.springframework.validation.annotation.Validated;
+import org.springframework.security.access.prepost.PreAuthorize;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.Operation;
+
+import jakarta.validation.constraints.*;
+import jakarta.validation.*;
+import jakarta.servlet.http.*;
+import java.util.*;
+import java.io.IOException;
+
+import com.yolo.keyboard.framework.common.pojo.PageParam;
+import com.yolo.keyboard.framework.common.pojo.PageResult;
+import com.yolo.keyboard.framework.common.pojo.CommonResult;
+import com.yolo.keyboard.framework.common.util.object.BeanUtils;
+import static com.yolo.keyboard.framework.common.pojo.CommonResult.success;
+
+import com.yolo.keyboard.framework.excel.core.util.ExcelUtils;
+
+import com.yolo.keyboard.framework.apilog.core.annotation.ApiAccessLog;
+import static com.yolo.keyboard.framework.apilog.core.enums.OperateTypeEnum.*;
+
+import com.yolo.keyboard.controller.admin.userinvites.vo.*;
+import com.yolo.keyboard.dal.dataobject.userinvites.KeyboardUserInvitesDO;
+import com.yolo.keyboard.service.userinvites.KeyboardUserInvitesService;
+
+@Tag(name = "管理后台 - 用户邀请关系绑定台账表，记录新用户最终归属的邀请人")
+@RestController
+@RequestMapping("/keyboard/user-invites")
+@Validated
+public class KeyboardUserInvitesController {
+
+    @Resource
+    private KeyboardUserInvitesService userInvitesService;
+
+    @PostMapping("/create")
+    @Operation(summary = "创建用户邀请关系绑定台账表，记录新用户最终归属的邀请人")
+    @PreAuthorize("@ss.hasPermission('keyboard:user-invites:create')")
+    public CommonResult<Long> createUserInvites(@Valid @RequestBody KeyboardUserInvitesSaveReqVO createReqVO) {
+        return success(userInvitesService.createUserInvites(createReqVO));
+    }
+
+    @PutMapping("/update")
+    @Operation(summary = "更新用户邀请关系绑定台账表，记录新用户最终归属的邀请人")
+    @PreAuthorize("@ss.hasPermission('keyboard:user-invites:update')")
+    public CommonResult<Boolean> updateUserInvites(@Valid @RequestBody KeyboardUserInvitesSaveReqVO updateReqVO) {
+        userInvitesService.updateUserInvites(updateReqVO);
+        return success(true);
+    }
+
+    @DeleteMapping("/delete")
+    @Operation(summary = "删除用户邀请关系绑定台账表，记录新用户最终归属的邀请人")
+    @Parameter(name = "id", description = "编号", required = true)
+    @PreAuthorize("@ss.hasPermission('keyboard:user-invites:delete')")
+    public CommonResult<Boolean> deleteUserInvites(@RequestParam("id") Long id) {
+        userInvitesService.deleteUserInvites(id);
+        return success(true);
+    }
+
+    @DeleteMapping("/delete-list")
+    @Parameter(name = "ids", description = "编号", required = true)
+    @Operation(summary = "批量删除用户邀请关系绑定台账表，记录新用户最终归属的邀请人")
+                @PreAuthorize("@ss.hasPermission('keyboard:user-invites:delete')")
+    public CommonResult<Boolean> deleteUserInvitesList(@RequestParam("ids") List<Long> ids) {
+        userInvitesService.deleteUserInvitesListByIds(ids);
+        return success(true);
+    }
+
+    @GetMapping("/get")
+    @Operation(summary = "获得用户邀请关系绑定台账表，记录新用户最终归属的邀请人")
+    @Parameter(name = "id", description = "编号", required = true, example = "1024")
+    @PreAuthorize("@ss.hasPermission('keyboard:user-invites:query')")
+    public CommonResult<KeyboardUserInvitesRespVO> getUserInvites(@RequestParam("id") Long id) {
+        KeyboardUserInvitesDO userInvites = userInvitesService.getUserInvites(id);
+        return success(BeanUtils.toBean(userInvites, KeyboardUserInvitesRespVO.class));
+    }
+
+    @GetMapping("/page")
+    @Operation(summary = "获得用户邀请关系绑定台账表，记录新用户最终归属的邀请人分页")
+    @PreAuthorize("@ss.hasPermission('keyboard:user-invites:query')")
+    public CommonResult<PageResult<KeyboardUserInvitesRespVO>> getUserInvitesPage(@Valid KeyboardUserInvitesPageReqVO pageReqVO) {
+        PageResult<KeyboardUserInvitesDO> pageResult = userInvitesService.getUserInvitesPage(pageReqVO);
+        return success(BeanUtils.toBean(pageResult, KeyboardUserInvitesRespVO.class));
+    }
+
+    @GetMapping("/export-excel")
+    @Operation(summary = "导出用户邀请关系绑定台账表，记录新用户最终归属的邀请人 Excel")
+    @PreAuthorize("@ss.hasPermission('keyboard:user-invites:export')")
+    @ApiAccessLog(operateType = EXPORT)
+    public void exportUserInvitesExcel(@Valid KeyboardUserInvitesPageReqVO pageReqVO,
+              HttpServletResponse response) throws IOException {
+        pageReqVO.setPageSize(PageParam.PAGE_SIZE_NONE);
+        List<KeyboardUserInvitesDO> list = userInvitesService.getUserInvitesPage(pageReqVO).getList();
+        // 导出 Excel
+        ExcelUtils.write(response, "用户邀请关系绑定台账表，记录新用户最终归属的邀请人.xls", "数据", KeyboardUserInvitesRespVO.class,
+                        BeanUtils.toBean(list, KeyboardUserInvitesRespVO.class));
+    }
+
+}
--- a/keyboard-server/src/main/java/com/yolo/keyboard/controller/admin/userinvites/vo/KeyboardUserInvitesPageReqVO.java
+++ b/keyboard-server/src/main/java/com/yolo/keyboard/controller/admin/userinvites/vo/KeyboardUserInvitesPageReqVO.java
@@ -0,0 +1,55 @@
+package com.yolo.keyboard.controller.admin.userinvites.vo;
+
+import lombok.*;
+import java.util.*;
+import io.swagger.v3.oas.annotations.media.Schema;
+import com.yolo.keyboard.framework.common.pojo.PageParam;
+import org.springframework.format.annotation.DateTimeFormat;
+import java.time.LocalDateTime;
+
+import static com.yolo.keyboard.framework.common.util.date.DateUtils.FORMAT_YEAR_MONTH_DAY_HOUR_MINUTE_SECOND;
+
+@Schema(description = "管理后台 - 用户邀请关系绑定台账表，记录新用户最终归属的邀请人分页 Request VO")
+@Data
+public class KeyboardUserInvitesPageReqVO extends PageParam {
+
+    @Schema(description = "邀请人用户ID", example = "11992")
+    private Long inviterUserId;
+
+    @Schema(description = "被邀请人用户ID（新注册用户）", example = "28499")
+    private Long inviteeUserId;
+
+    @Schema(description = "使用的邀请码ID", example = "30340")
+    private Long inviteCodeId;
+
+    @Schema(description = "绑定时关联的点击Token（通过邀请链接自动绑定时使用）")
+    private String clickToken;
+
+    @Schema(description = "绑定方式：1=手动填写邀请码，2=邀请链接自动绑定，3=其他方式", example = "2")
+    private Short bindType;
+
+    @Schema(description = "邀请关系绑定完成时间")
+    private LocalDateTime boundAt;
+
+    @Schema(description = "绑定 iP")
+    private String bindIp;
+
+    @Schema(description = "userAgent")
+    private String bindUserAgent;
+
+    @Schema(description = "邀请码类型快照：USER=普通用户邀请，AGENT=代理邀请", example = "2")
+    private String inviteType;
+
+    @Schema(description = "收益结算归属租户ID（代理结算用，绑定时固化）", example = "25223")
+    private Long profitTenantId;
+
+    @Schema(description = "收益归因员工ID（用于区分租户员工/渠道，绑定时固化）", example = "31236")
+    private Long profitEmployeeId;
+
+    @Schema(description = "邀请人所属租户ID快照（便于审计/对账，可选）", example = "17028")
+    private Long inviterTenantId;
+
+    @Schema(description = "邀请码字符串快照（便于排查，可选）")
+    private String inviteCode;
+
+}
--- a/keyboard-server/src/main/java/com/yolo/keyboard/controller/admin/userinvites/vo/KeyboardUserInvitesRespVO.java
+++ b/keyboard-server/src/main/java/com/yolo/keyboard/controller/admin/userinvites/vo/KeyboardUserInvitesRespVO.java
@@ -0,0 +1,71 @@
+package com.yolo.keyboard.controller.admin.userinvites.vo;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+import lombok.*;
+import java.util.*;
+import org.springframework.format.annotation.DateTimeFormat;
+import java.time.LocalDateTime;
+import cn.idev.excel.annotation.*;
+
+@Schema(description = "管理后台 - 用户邀请关系绑定台账表，记录新用户最终归属的邀请人 Response VO")
+@Data
+@ExcelIgnoreUnannotated
+public class KeyboardUserInvitesRespVO {
+
+    @Schema(description = "邀请绑定记录主键ID", requiredMode = Schema.RequiredMode.REQUIRED, example = "7254")
+    @ExcelProperty("邀请绑定记录主键ID")
+    private Long id;
+
+    @Schema(description = "邀请人用户ID", requiredMode = Schema.RequiredMode.REQUIRED, example = "11992")
+    @ExcelProperty("邀请人用户ID")
+    private Long inviterUserId;
+
+    @Schema(description = "被邀请人用户ID（新注册用户）", requiredMode = Schema.RequiredMode.REQUIRED, example = "28499")
+    @ExcelProperty("被邀请人用户ID（新注册用户）")
+    private Long inviteeUserId;
+
+    @Schema(description = "使用的邀请码ID", requiredMode = Schema.RequiredMode.REQUIRED, example = "30340")
+    @ExcelProperty("使用的邀请码ID")
+    private Long inviteCodeId;
+
+    @Schema(description = "绑定时关联的点击Token（通过邀请链接自动绑定时使用）")
+    @ExcelProperty("绑定时关联的点击Token（通过邀请链接自动绑定时使用）")
+    private String clickToken;
+
+    @Schema(description = "绑定方式：1=手动填写邀请码，2=邀请链接自动绑定，3=其他方式", requiredMode = Schema.RequiredMode.REQUIRED, example = "2")
+    @ExcelProperty("绑定方式：1=手动填写邀请码，2=邀请链接自动绑定，3=其他方式")
+    private Short bindType;
+
+    @Schema(description = "邀请关系绑定完成时间", requiredMode = Schema.RequiredMode.REQUIRED)
+    @ExcelProperty("邀请关系绑定完成时间")
+    private LocalDateTime boundAt;
+
+    @Schema(description = "绑定 iP")
+    @ExcelProperty("绑定 iP")
+    private String bindIp;
+
+    @Schema(description = "userAgent")
+    @ExcelProperty("userAgent")
+    private String bindUserAgent;
+
+    @Schema(description = "邀请码类型快照：USER=普通用户邀请，AGENT=代理邀请", requiredMode = Schema.RequiredMode.REQUIRED, example = "2")
+    @ExcelProperty("邀请码类型快照：USER=普通用户邀请，AGENT=代理邀请")
+    private String inviteType;
+
+    @Schema(description = "收益结算归属租户ID（代理结算用，绑定时固化）", example = "25223")
+    @ExcelProperty("收益结算归属租户ID（代理结算用，绑定时固化）")
+    private Long profitTenantId;
+
+    @Schema(description = "收益归因员工ID（用于区分租户员工/渠道，绑定时固化）", example = "31236")
+    @ExcelProperty("收益归因员工ID（用于区分租户员工/渠道，绑定时固化）")
+    private Long profitEmployeeId;
+
+    @Schema(description = "邀请人所属租户ID快照（便于审计/对账，可选）", example = "17028")
+    @ExcelProperty("邀请人所属租户ID快照（便于审计/对账，可选）")
+    private Long inviterTenantId;
+
+    @Schema(description = "邀请码字符串快照（便于排查，可选）")
+    @ExcelProperty("邀请码字符串快照（便于排查，可选）")
+    private String inviteCode;
+
+}
--- a/keyboard-server/src/main/java/com/yolo/keyboard/controller/admin/userinvites/vo/KeyboardUserInvitesSaveReqVO.java
+++ b/keyboard-server/src/main/java/com/yolo/keyboard/controller/admin/userinvites/vo/KeyboardUserInvitesSaveReqVO.java
@@ -0,0 +1,62 @@
+package com.yolo.keyboard.controller.admin.userinvites.vo;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+import lombok.*;
+import java.util.*;
+import jakarta.validation.constraints.*;
+import org.springframework.format.annotation.DateTimeFormat;
+import java.time.LocalDateTime;
+
+@Schema(description = "管理后台 - 用户邀请关系绑定台账表，记录新用户最终归属的邀请人新增/修改 Request VO")
+@Data
+public class KeyboardUserInvitesSaveReqVO {
+
+    @Schema(description = "邀请绑定记录主键ID", requiredMode = Schema.RequiredMode.REQUIRED, example = "7254")
+    private Long id;
+
+    @Schema(description = "邀请人用户ID", requiredMode = Schema.RequiredMode.REQUIRED, example = "11992")
+    @NotNull(message = "邀请人用户ID不能为空")
+    private Long inviterUserId;
+
+    @Schema(description = "被邀请人用户ID（新注册用户）", requiredMode = Schema.RequiredMode.REQUIRED, example = "28499")
+    @NotNull(message = "被邀请人用户ID（新注册用户）不能为空")
+    private Long inviteeUserId;
+
+    @Schema(description = "使用的邀请码ID", requiredMode = Schema.RequiredMode.REQUIRED, example = "30340")
+    @NotNull(message = "使用的邀请码ID不能为空")
+    private Long inviteCodeId;
+
+    @Schema(description = "绑定时关联的点击Token（通过邀请链接自动绑定时使用）")
+    private String clickToken;
+
+    @Schema(description = "绑定方式：1=手动填写邀请码，2=邀请链接自动绑定，3=其他方式", requiredMode = Schema.RequiredMode.REQUIRED, example = "2")
+    @NotNull(message = "绑定方式：1=手动填写邀请码，2=邀请链接自动绑定，3=其他方式不能为空")
+    private Short bindType;
+
+    @Schema(description = "邀请关系绑定完成时间", requiredMode = Schema.RequiredMode.REQUIRED)
+    @NotNull(message = "邀请关系绑定完成时间不能为空")
+    private LocalDateTime boundAt;
+
+    @Schema(description = "绑定 iP")
+    private String bindIp;
+
+    @Schema(description = "userAgent")
+    private String bindUserAgent;
+
+    @Schema(description = "邀请码类型快照：USER=普通用户邀请，AGENT=代理邀请", requiredMode = Schema.RequiredMode.REQUIRED, example = "2")
+    @NotEmpty(message = "邀请码类型快照：USER=普通用户邀请，AGENT=代理邀请不能为空")
+    private String inviteType;
+
+    @Schema(description = "收益结算归属租户ID（代理结算用，绑定时固化）", example = "25223")
+    private Long profitTenantId;
+
+    @Schema(description = "收益归因员工ID（用于区分租户员工/渠道，绑定时固化）", example = "31236")
+    private Long profitEmployeeId;
+
+    @Schema(description = "邀请人所属租户ID快照（便于审计/对账，可选）", example = "17028")
+    private Long inviterTenantId;
+
+    @Schema(description = "邀请码字符串快照（便于排查，可选）")
+    private String inviteCode;
+
+}
--- a/keyboard-server/src/main/java/com/yolo/keyboard/dal/dataobject/userinvitecodes/KeyboardUserInviteCodesDO.java
+++ b/keyboard-server/src/main/java/com/yolo/keyboard/dal/dataobject/userinvitecodes/KeyboardUserInviteCodesDO.java
@@ -0,0 +1,77 @@
+package com.yolo.keyboard.dal.dataobject.userinvitecodes;
+
+import com.yolo.keyboard.framework.tenant.core.aop.TenantIgnore;
+import lombok.*;
+import java.util.*;
+import java.time.LocalDateTime;
+import java.time.LocalDateTime;
+import com.baomidou.mybatisplus.annotation.*;
+import com.yolo.keyboard.framework.mybatis.core.dataobject.BaseDO;
+
+/**
+ * 用户生成的邀请码表，用于邀请新用户注册/安装并建立邀请关系 DO
+ *
+ * @author ziin
+ */
+@TableName("keyboard_user_invite_codes")
+@KeySequence("keyboard_user_invite_codes_seq") // 用于 Oracle、PostgreSQL、Kingbase、DB2、H2 数据库的主键自增。如果是 MySQL 等数据库，可不写。
+@Data
+@ToString(callSuper = true)
+@Builder
+@NoArgsConstructor
+@AllArgsConstructor
+@TenantIgnore
+public class KeyboardUserInviteCodesDO {
+
+    /**
+     * 邀请码主键ID
+     */
+    @TableId
+    private Long id;
+    /**
+     * 邀请码字符串，对外展示，唯一
+     */
+    private String code;
+    /**
+     * 邀请码所属用户ID（邀请人）
+     */
+    private Long ownerUserId;
+    /**
+     * 邀请码状态：1=启用，0=停用
+     */
+    private Short status;
+    /**
+     * 邀请码创建时间
+     */
+    private LocalDateTime createdAt;
+    /**
+     * 邀请码过期时间，NULL表示永久有效
+     */
+    private LocalDateTime expiresAt;
+    /**
+     * 邀请码最大可使用次数，NULL表示不限次数
+     */
+    private Integer maxUses;
+    /**
+     * 邀请码已使用次数
+     */
+    private Integer usedCount;
+    /**
+     * 邀请码所属系统用户ID（邀请人）
+     */
+    private Long systemUserId;
+    /**
+     * 邀请码所属租户
+     */
+    private Long ownerTenantId;
+    /**
+     * 邀请码所属系统用户
+     */
+    private Long owenrSystemUserId;
+    /**
+     * 邀请码类型
+     */
+    private String inviteType;
+
+
+}
--- a/keyboard-server/src/main/java/com/yolo/keyboard/dal/dataobject/userinvites/KeyboardUserInvitesDO.java
+++ b/keyboard-server/src/main/java/com/yolo/keyboard/dal/dataobject/userinvites/KeyboardUserInvitesDO.java
@@ -0,0 +1,84 @@
+package com.yolo.keyboard.dal.dataobject.userinvites;
+
+import com.yolo.keyboard.framework.tenant.core.aop.TenantIgnore;
+import lombok.*;
+import java.util.*;
+import java.time.LocalDateTime;
+import com.baomidou.mybatisplus.annotation.*;
+import com.yolo.keyboard.framework.mybatis.core.dataobject.BaseDO;
+
+/**
+ * 用户邀请关系绑定台账表，记录新用户最终归属的邀请人 DO
+ *
+ * @author ziin
+ */
+@TableName("keyboard_user_invites")
+@KeySequence("keyboard_user_invites_seq") // 用于 Oracle、PostgreSQL、Kingbase、DB2、H2 数据库的主键自增。如果是 MySQL 等数据库，可不写。
+@Data
+@ToString(callSuper = true)
+@Builder
+@NoArgsConstructor
+@AllArgsConstructor
+@TenantIgnore
+public class KeyboardUserInvitesDO {
+
+    /**
+     * 邀请绑定记录主键ID
+     */
+    @TableId
+    private Long id;
+    /**
+     * 邀请人用户ID
+     */
+    private Long inviterUserId;
+    /**
+     * 被邀请人用户ID（新注册用户）
+     */
+    private Long inviteeUserId;
+    /**
+     * 使用的邀请码ID
+     */
+    private Long inviteCodeId;
+    /**
+     * 绑定时关联的点击Token（通过邀请链接自动绑定时使用）
+     */
+    private String clickToken;
+    /**
+     * 绑定方式：1=手动填写邀请码，2=邀请链接自动绑定，3=其他方式
+     */
+    private Short bindType;
+    /**
+     * 邀请关系绑定完成时间
+     */
+    private LocalDateTime boundAt;
+    /**
+     * 绑定 iP
+     */
+    private String bindIp;
+    /**
+     * userAgent
+     */
+    private String bindUserAgent;
+    /**
+     * 邀请码类型快照：USER=普通用户邀请，AGENT=代理邀请
+     */
+    private String inviteType;
+    /**
+     * 收益结算归属租户ID（代理结算用，绑定时固化）
+     */
+    private Long profitTenantId;
+    /**
+     * 收益归因员工ID（用于区分租户员工/渠道，绑定时固化）
+     */
+    private Long profitEmployeeId;
+    /**
+     * 邀请人所属租户ID快照（便于审计/对账，可选）
+     */
+    private Long inviterTenantId;
+    /**
+     * 邀请码字符串快照（便于排查，可选）
+     */
+    private String inviteCode;
+
+
+}
--- a/keyboard-server/src/main/java/com/yolo/keyboard/dal/mysql/userinvitecodes/KeyboardUserInviteCodesMapper.java
+++ b/keyboard-server/src/main/java/com/yolo/keyboard/dal/mysql/userinvitecodes/KeyboardUserInviteCodesMapper.java
@@ -0,0 +1,36 @@
+package com.yolo.keyboard.dal.mysql.userinvitecodes;
+
+import java.util.*;
+
+import com.yolo.keyboard.framework.common.pojo.PageResult;
+import com.yolo.keyboard.framework.mybatis.core.query.LambdaQueryWrapperX;
+import com.yolo.keyboard.framework.mybatis.core.mapper.BaseMapperX;
+import com.yolo.keyboard.dal.dataobject.userinvitecodes.KeyboardUserInviteCodesDO;
+import org.apache.ibatis.annotations.Mapper;
+import com.yolo.keyboard.controller.admin.userinvitecodes.vo.*;
+
+/**
+ * 用户生成的邀请码表，用于邀请新用户注册/安装并建立邀请关系 Mapper
+ *
+ * @author ziin
+ */
+@Mapper
+public interface KeyboardUserInviteCodesMapper extends BaseMapperX<KeyboardUserInviteCodesDO> {
+
+    default PageResult<KeyboardUserInviteCodesDO> selectPage(KeyboardUserInviteCodesPageReqVO reqVO) {
+        return selectPage(reqVO, new LambdaQueryWrapperX<KeyboardUserInviteCodesDO>()
+                .eqIfPresent(KeyboardUserInviteCodesDO::getCode, reqVO.getCode())
+                .eqIfPresent(KeyboardUserInviteCodesDO::getOwnerUserId, reqVO.getOwnerUserId())
+                .eqIfPresent(KeyboardUserInviteCodesDO::getStatus, reqVO.getStatus())
+                .eqIfPresent(KeyboardUserInviteCodesDO::getCreatedAt, reqVO.getCreatedAt())
+                .eqIfPresent(KeyboardUserInviteCodesDO::getExpiresAt, reqVO.getExpiresAt())
+                .eqIfPresent(KeyboardUserInviteCodesDO::getMaxUses, reqVO.getMaxUses())
+                .eqIfPresent(KeyboardUserInviteCodesDO::getUsedCount, reqVO.getUsedCount())
+                .eqIfPresent(KeyboardUserInviteCodesDO::getSystemUserId, reqVO.getSystemUserId())
+                .eqIfPresent(KeyboardUserInviteCodesDO::getOwnerTenantId, reqVO.getOwnerTenantId())
+                .eqIfPresent(KeyboardUserInviteCodesDO::getOwenrSystemUserId, reqVO.getOwenrSystemUserId())
+                .eqIfPresent(KeyboardUserInviteCodesDO::getInviteType, reqVO.getInviteType())
+                .orderByDesc(KeyboardUserInviteCodesDO::getId));
+    }
+
+}
--- a/keyboard-server/src/main/java/com/yolo/keyboard/dal/mysql/userinvites/KeyboardUserInvitesMapper.java
+++ b/keyboard-server/src/main/java/com/yolo/keyboard/dal/mysql/userinvites/KeyboardUserInvitesMapper.java
@@ -0,0 +1,38 @@
+package com.yolo.keyboard.dal.mysql.userinvites;
+
+import java.util.*;
+
+import com.yolo.keyboard.framework.common.pojo.PageResult;
+import com.yolo.keyboard.framework.mybatis.core.query.LambdaQueryWrapperX;
+import com.yolo.keyboard.framework.mybatis.core.mapper.BaseMapperX;
+import com.yolo.keyboard.dal.dataobject.userinvites.KeyboardUserInvitesDO;
+import org.apache.ibatis.annotations.Mapper;
+import com.yolo.keyboard.controller.admin.userinvites.vo.*;
+
+/**
+ * 用户邀请关系绑定台账表，记录新用户最终归属的邀请人 Mapper
+ *
+ * @author ziin
+ */
+@Mapper
+public interface KeyboardUserInvitesMapper extends BaseMapperX<KeyboardUserInvitesDO> {
+
+    default PageResult<KeyboardUserInvitesDO> selectPage(KeyboardUserInvitesPageReqVO reqVO) {
+        return selectPage(reqVO, new LambdaQueryWrapperX<KeyboardUserInvitesDO>()
+                .eqIfPresent(KeyboardUserInvitesDO::getInviterUserId, reqVO.getInviterUserId())
+                .eqIfPresent(KeyboardUserInvitesDO::getInviteeUserId, reqVO.getInviteeUserId())
+                .eqIfPresent(KeyboardUserInvitesDO::getInviteCodeId, reqVO.getInviteCodeId())
+                .eqIfPresent(KeyboardUserInvitesDO::getClickToken, reqVO.getClickToken())
+                .eqIfPresent(KeyboardUserInvitesDO::getBindType, reqVO.getBindType())
+                .eqIfPresent(KeyboardUserInvitesDO::getBoundAt, reqVO.getBoundAt())
+                .eqIfPresent(KeyboardUserInvitesDO::getBindIp, reqVO.getBindIp())
+                .eqIfPresent(KeyboardUserInvitesDO::getBindUserAgent, reqVO.getBindUserAgent())
+                .eqIfPresent(KeyboardUserInvitesDO::getInviteType, reqVO.getInviteType())
+                .eqIfPresent(KeyboardUserInvitesDO::getProfitTenantId, reqVO.getProfitTenantId())
+                .eqIfPresent(KeyboardUserInvitesDO::getProfitEmployeeId, reqVO.getProfitEmployeeId())
+                .eqIfPresent(KeyboardUserInvitesDO::getInviterTenantId, reqVO.getInviterTenantId())
+                .eqIfPresent(KeyboardUserInvitesDO::getInviteCode, reqVO.getInviteCode())
+                .orderByDesc(KeyboardUserInvitesDO::getId));
+    }
+
+}
--- a/keyboard-server/src/main/java/com/yolo/keyboard/service/userinvitecodes/KeyboardUserInviteCodesService.java
+++ b/keyboard-server/src/main/java/com/yolo/keyboard/service/userinvitecodes/KeyboardUserInviteCodesService.java
@@ -0,0 +1,62 @@
+package com.yolo.keyboard.service.userinvitecodes;
+
+import java.util.*;
+import jakarta.validation.*;
+import com.yolo.keyboard.controller.admin.userinvitecodes.vo.*;
+import com.yolo.keyboard.dal.dataobject.userinvitecodes.KeyboardUserInviteCodesDO;
+import com.yolo.keyboard.framework.common.pojo.PageResult;
+import com.yolo.keyboard.framework.common.pojo.PageParam;
+
+/**
+ * 用户生成的邀请码表，用于邀请新用户注册/安装并建立邀请关系 Service 接口
+ *
+ * @author ziin
+ */
+public interface KeyboardUserInviteCodesService {
+
+    /**
+     * 创建用户生成的邀请码表，用于邀请新用户注册/安装并建立邀请关系
+     *
+     * @param createReqVO 创建信息
+     * @return 编号
+     */
+    Long createUserInviteCodes(@Valid KeyboardUserInviteCodesSaveReqVO createReqVO);
+
+    /**
+     * 更新用户生成的邀请码表，用于邀请新用户注册/安装并建立邀请关系
+     *
+     * @param updateReqVO 更新信息
+     */
+    void updateUserInviteCodes(@Valid KeyboardUserInviteCodesSaveReqVO updateReqVO);
+
+    /**
+     * 删除用户生成的邀请码表，用于邀请新用户注册/安装并建立邀请关系
+     *
+     * @param id 编号
+     */
+    void deleteUserInviteCodes(Long id);
+
+    /**
+    * 批量删除用户生成的邀请码表，用于邀请新用户注册/安装并建立邀请关系
+    *
+    * @param ids 编号
+    */
+    void deleteUserInviteCodesListByIds(List<Long> ids);
+
+    /**
+     * 获得用户生成的邀请码表，用于邀请新用户注册/安装并建立邀请关系
+     *
+     * @param id 编号
+     * @return 用户生成的邀请码表，用于邀请新用户注册/安装并建立邀请关系
+     */
+    KeyboardUserInviteCodesDO getUserInviteCodes(Long id);
+
+    /**
+     * 获得用户生成的邀请码表，用于邀请新用户注册/安装并建立邀请关系分页
+     *
+     * @param pageReqVO 分页查询
+     * @return 用户生成的邀请码表，用于邀请新用户注册/安装并建立邀请关系分页
+     */
+    PageResult<KeyboardUserInviteCodesDO> getUserInviteCodesPage(KeyboardUserInviteCodesPageReqVO pageReqVO);
+
+}
--- a/keyboard-server/src/main/java/com/yolo/keyboard/service/userinvitecodes/KeyboardUserInviteCodesServiceImpl.java
+++ b/keyboard-server/src/main/java/com/yolo/keyboard/service/userinvitecodes/KeyboardUserInviteCodesServiceImpl.java
@@ -0,0 +1,85 @@
+package com.yolo.keyboard.service.userinvitecodes;
+
+import cn.hutool.core.collection.CollUtil;
+import org.springframework.stereotype.Service;
+import jakarta.annotation.Resource;
+import org.springframework.validation.annotation.Validated;
+import org.springframework.transaction.annotation.Transactional;
+
+import java.util.*;
+import com.yolo.keyboard.controller.admin.userinvitecodes.vo.*;
+import com.yolo.keyboard.dal.dataobject.userinvitecodes.KeyboardUserInviteCodesDO;
+import com.yolo.keyboard.framework.common.pojo.PageResult;
+import com.yolo.keyboard.framework.common.pojo.PageParam;
+import com.yolo.keyboard.framework.common.util.object.BeanUtils;
+
+import com.yolo.keyboard.dal.mysql.userinvitecodes.KeyboardUserInviteCodesMapper;
+
+import static com.yolo.keyboard.framework.common.exception.util.ServiceExceptionUtil.exception;
+import static com.yolo.keyboard.framework.common.util.collection.CollectionUtils.convertList;
+import static com.yolo.keyboard.framework.common.util.collection.CollectionUtils.diffList;
+import static com.yolo.keyboard.module.infra.enums.ErrorCodeConstants.USER_INVITE_CODES_NOT_EXISTS;
+
+/**
+ * 用户生成的邀请码表，用于邀请新用户注册/安装并建立邀请关系 Service 实现类
+ *
+ * @author ziin
+ */
+@Service
+@Validated
+public class KeyboardUserInviteCodesServiceImpl implements KeyboardUserInviteCodesService {
+
+    @Resource
+    private KeyboardUserInviteCodesMapper userInviteCodesMapper;
+
+    @Override
+    public Long createUserInviteCodes(KeyboardUserInviteCodesSaveReqVO createReqVO) {
+        // 插入
+        KeyboardUserInviteCodesDO userInviteCodes = BeanUtils.toBean(createReqVO, KeyboardUserInviteCodesDO.class);
+        userInviteCodesMapper.insert(userInviteCodes);
+
+        // 返回
+        return userInviteCodes.getId();
+    }
+
+    @Override
+    public void updateUserInviteCodes(KeyboardUserInviteCodesSaveReqVO updateReqVO) {
+        // 校验存在
+        validateUserInviteCodesExists(updateReqVO.getId());
+        // 更新
+        KeyboardUserInviteCodesDO updateObj = BeanUtils.toBean(updateReqVO, KeyboardUserInviteCodesDO.class);
+        userInviteCodesMapper.updateById(updateObj);
+    }
+
+    @Override
+    public void deleteUserInviteCodes(Long id) {
+        // 校验存在
+        validateUserInviteCodesExists(id);
+        // 删除
+        userInviteCodesMapper.deleteById(id);
+    }
+
+    @Override
+        public void deleteUserInviteCodesListByIds(List<Long> ids) {
+        // 删除
+        userInviteCodesMapper.deleteByIds(ids);
+        }
+
+
+    private void validateUserInviteCodesExists(Long id) {
+        if (userInviteCodesMapper.selectById(id) == null) {
+            throw exception(USER_INVITE_CODES_NOT_EXISTS);
+        }
+    }
+
+    @Override
+    public KeyboardUserInviteCodesDO getUserInviteCodes(Long id) {
+        return userInviteCodesMapper.selectById(id);
+    }
+
+    @Override
+    public PageResult<KeyboardUserInviteCodesDO> getUserInviteCodesPage(KeyboardUserInviteCodesPageReqVO pageReqVO) {
+        return userInviteCodesMapper.selectPage(pageReqVO);
+    }
+
+}
--- a/keyboard-server/src/main/java/com/yolo/keyboard/service/userinvites/KeyboardUserInvitesService.java
+++ b/keyboard-server/src/main/java/com/yolo/keyboard/service/userinvites/KeyboardUserInvitesService.java
@@ -0,0 +1,62 @@
+package com.yolo.keyboard.service.userinvites;
+
+import java.util.*;
+import jakarta.validation.*;
+import com.yolo.keyboard.controller.admin.userinvites.vo.*;
+import com.yolo.keyboard.dal.dataobject.userinvites.KeyboardUserInvitesDO;
+import com.yolo.keyboard.framework.common.pojo.PageResult;
+import com.yolo.keyboard.framework.common.pojo.PageParam;
+
+/**
+ * 用户邀请关系绑定台账表，记录新用户最终归属的邀请人 Service 接口
+ *
+ * @author ziin
+ */
+public interface KeyboardUserInvitesService {
+
+    /**
+     * 创建用户邀请关系绑定台账表，记录新用户最终归属的邀请人
+     *
+     * @param createReqVO 创建信息
+     * @return 编号
+     */
+    Long createUserInvites(@Valid KeyboardUserInvitesSaveReqVO createReqVO);
+
+    /**
+     * 更新用户邀请关系绑定台账表，记录新用户最终归属的邀请人
+     *
+     * @param updateReqVO 更新信息
+     */
+    void updateUserInvites(@Valid KeyboardUserInvitesSaveReqVO updateReqVO);
+
+    /**
+     * 删除用户邀请关系绑定台账表，记录新用户最终归属的邀请人
+     *
+     * @param id 编号
+     */
+    void deleteUserInvites(Long id);
+
+    /**
+    * 批量删除用户邀请关系绑定台账表，记录新用户最终归属的邀请人
+    *
+    * @param ids 编号
+    */
+    void deleteUserInvitesListByIds(List<Long> ids);
+
+    /**
+     * 获得用户邀请关系绑定台账表，记录新用户最终归属的邀请人
+     *
+     * @param id 编号
+     * @return 用户邀请关系绑定台账表，记录新用户最终归属的邀请人
+     */
+    KeyboardUserInvitesDO getUserInvites(Long id);
+
+    /**
+     * 获得用户邀请关系绑定台账表，记录新用户最终归属的邀请人分页
+     *
+     * @param pageReqVO 分页查询
+     * @return 用户邀请关系绑定台账表，记录新用户最终归属的邀请人分页
+     */
+    PageResult<KeyboardUserInvitesDO> getUserInvitesPage(KeyboardUserInvitesPageReqVO pageReqVO);
+
+}
--- a/keyboard-server/src/main/java/com/yolo/keyboard/service/userinvites/KeyboardUserInvitesServiceImpl.java
+++ b/keyboard-server/src/main/java/com/yolo/keyboard/service/userinvites/KeyboardUserInvitesServiceImpl.java
@@ -0,0 +1,80 @@
+package com.yolo.keyboard.service.userinvites;
+
+import com.yolo.keyboard.controller.admin.userinvites.vo.KeyboardUserInvitesPageReqVO;
+import com.yolo.keyboard.controller.admin.userinvites.vo.KeyboardUserInvitesSaveReqVO;
+import com.yolo.keyboard.dal.dataobject.userinvites.KeyboardUserInvitesDO;
+import com.yolo.keyboard.dal.mysql.userinvites.KeyboardUserInvitesMapper;
+import com.yolo.keyboard.framework.common.pojo.PageResult;
+import com.yolo.keyboard.framework.common.util.object.BeanUtils;
+import jakarta.annotation.Resource;
+import org.springframework.stereotype.Service;
+import org.springframework.validation.annotation.Validated;
+
+import java.util.List;
+
+import static com.yolo.keyboard.framework.common.exception.util.ServiceExceptionUtil.exception;
+import static com.yolo.keyboard.module.infra.enums.ErrorCodeConstants.USER_INVITES_NOT_EXISTS;
+
+/**
+ * 用户邀请关系绑定台账表，记录新用户最终归属的邀请人 Service 实现类
+ *
+ * @author ziin
+ */
+@Service
+@Validated
+public class KeyboardUserInvitesServiceImpl implements KeyboardUserInvitesService {
+
+    @Resource
+    private KeyboardUserInvitesMapper userInvitesMapper;
+
+    @Override
+    public Long createUserInvites(KeyboardUserInvitesSaveReqVO createReqVO) {
+        // 插入
+        KeyboardUserInvitesDO userInvites = BeanUtils.toBean(createReqVO, KeyboardUserInvitesDO.class);
+        userInvitesMapper.insert(userInvites);
+
+        // 返回
+        return userInvites.getId();
+    }
+
+    @Override
+    public void updateUserInvites(KeyboardUserInvitesSaveReqVO updateReqVO) {
+        // 校验存在
+        validateUserInvitesExists(updateReqVO.getId());
+        // 更新
+        KeyboardUserInvitesDO updateObj = BeanUtils.toBean(updateReqVO, KeyboardUserInvitesDO.class);
+        userInvitesMapper.updateById(updateObj);
+    }
+
+    @Override
+    public void deleteUserInvites(Long id) {
+        // 校验存在
+        validateUserInvitesExists(id);
+        // 删除
+        userInvitesMapper.deleteById(id);
+    }
+
+    @Override
+        public void deleteUserInvitesListByIds(List<Long> ids) {
+        // 删除
+        userInvitesMapper.deleteByIds(ids);
+        }
+
+
+    private void validateUserInvitesExists(Long id) {
+        if (userInvitesMapper.selectById(id) == null) {
+            throw exception(USER_INVITES_NOT_EXISTS);
+        }
+    }
+
+    @Override
+    public KeyboardUserInvitesDO getUserInvites(Long id) {
+        return userInvitesMapper.selectById(id);
+    }
+
+    @Override
+    public PageResult<KeyboardUserInvitesDO> getUserInvitesPage(KeyboardUserInvitesPageReqVO pageReqVO) {
+        return userInvitesMapper.selectPage(pageReqVO);
+    }
+
+}
--- a/keyboard-server/src/main/resources/mapper/userinvitecodes/KeyboardUserInviteCodesMapper.xml
+++ b/keyboard-server/src/main/resources/mapper/userinvitecodes/KeyboardUserInviteCodesMapper.xml
@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE mapper PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN" "http://mybatis.org/dtd/mybatis-3-mapper.dtd">
+<mapper namespace="com.yolo.keyboard.dal.mysql.userinvitecodes.KeyboardUserInviteCodesMapper">
+
+    <!--
+        一般情况下，尽可能使用 Mapper 进行 CRUD 增删改查即可。
+        无法满足的场景，例如说多表关联查询，才使用 XML 编写 SQL。
+        代码生成器暂时只生成 Mapper XML 文件本身，更多推荐 MybatisX 快速开发插件来生成查询。
+        文档可见：https://www.iocoder.cn/MyBatis/x-plugins/
+     -->
+
+</mapper>
--- a/keyboard-server/src/main/resources/mapper/userinvites/KeyboardUserInvitesMapper.xml
+++ b/keyboard-server/src/main/resources/mapper/userinvites/KeyboardUserInvitesMapper.xml
@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE mapper PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN" "http://mybatis.org/dtd/mybatis-3-mapper.dtd">
+<mapper namespace="com.yolo.keyboard.module.keyboard.dal.mysql.userinvites.KeyboardUserInvitesMapper">
+
+    <!--
+        一般情况下，尽可能使用 Mapper 进行 CRUD 增删改查即可。
+        无法满足的场景，例如说多表关联查询，才使用 XML 编写 SQL。
+        代码生成器暂时只生成 Mapper XML 文件本身，更多推荐 MybatisX 快速开发插件来生成查询。
+        文档可见：https://www.iocoder.cn/MyBatis/x-plugins/
+     -->
+
+</mapper>
--- a/yolo-module-infra/src/main/java/com/yolo/keyboard/module/infra/enums/ErrorCodeConstants.java
+++ b/yolo-module-infra/src/main/java/com/yolo/keyboard/module/infra/enums/ErrorCodeConstants.java
@@ -91,6 +91,7 @@ public interface ErrorCodeConstants {
    ErrorCode TENANT_BALANCE_WITHDRAW_INSUFFICIENT = new ErrorCode(1_001_202_017, "余额不足，无法提现");
    ErrorCode TENANT_BALANCE_WITHDRAW_CONFIG_NOT_EXISTS = new ErrorCode(1_001_202_018, "提现配置不存在");
    ErrorCode TENANT_WITHDRAW_ORDER_NOT_EXISTS = new ErrorCode(1_001_202_019, "租户提现订单表（申请-审核-打款-完成/失败）不存在");
-
+    ErrorCode USER_INVITE_CODES_NOT_EXISTS = new ErrorCode(1_001_202_020, "用户生成的邀请码表，用于邀请新用户注册/安装并建立邀请关系不存在");
+    ErrorCode USER_INVITES_NOT_EXISTS = new ErrorCode(1_001_202_021, "用户邀请关系绑定台账表，记录新用户最终归属的邀请人不存在");

 }
--- a/yolo-module-system/src/main/java/com/yolo/keyboard/module/system/controller/admin/tenant/vo/tenant/TenantPageReqVO.java
+++ b/yolo-module-system/src/main/java/com/yolo/keyboard/module/system/controller/admin/tenant/vo/tenant/TenantPageReqVO.java
@@ -65,4 +65,7 @@ public class TenantPageReqVO extends PageParam {
     */
    @Schema(description = "分润比例")
    private BigDecimal profitShareRatio;
+
+    @Schema(description = "上级返点比例")
+    private BigDecimal upstreamRebateRatio;
 }
--- a/yolo-module-system/src/main/java/com/yolo/keyboard/module/system/controller/admin/tenant/vo/tenant/TenantRespVO.java
+++ b/yolo-module-system/src/main/java/com/yolo/keyboard/module/system/controller/admin/tenant/vo/tenant/TenantRespVO.java
@@ -82,4 +82,8 @@ public class TenantRespVO {

    @Schema(description = "分润比例")
    private BigDecimal profitShareRatio;
+
+
+    @Schema(description = "上级返点比例")
+    private BigDecimal upstreamRebateRatio;
 }
--- a/yolo-module-system/src/main/java/com/yolo/keyboard/module/system/controller/admin/tenant/vo/tenant/TenantSaveReqVO.java
+++ b/yolo-module-system/src/main/java/com/yolo/keyboard/module/system/controller/admin/tenant/vo/tenant/TenantSaveReqVO.java
@@ -97,4 +97,8 @@ public class TenantSaveReqVO {

    @Schema(description = "分润比例")
    private BigDecimal profitShareRatio;
+
+
+    @Schema(description = "上级返点比例")
+    private BigDecimal upstreamRebateRatio;
 }
--- a/yolo-module-system/src/main/java/com/yolo/keyboard/module/system/dal/dataobject/tenant/TenantDO.java
+++ b/yolo-module-system/src/main/java/com/yolo/keyboard/module/system/dal/dataobject/tenant/TenantDO.java
@@ -111,4 +111,6 @@ public class TenantDO extends BaseDO {
    private Integer tenantLevel;

    private BigDecimal profitShareRatio;
+
+    private BigDecimal upstreamRebateRatio;
 }