feat(aicompanion): 新增AI陪聊角色管理功能

2026-02-08 16:03:06 +08:00
parent a99f05d029
commit afa2c47c89
10 changed files with 660 additions and 1 deletions
--- a/keyboard-server/src/main/java/com/yolo/keyboard/controller/admin/aicompanion/KeyboardAiCompanionController.java
+++ b/keyboard-server/src/main/java/com/yolo/keyboard/controller/admin/aicompanion/KeyboardAiCompanionController.java
@@ -0,0 +1,104 @@
+package com.yolo.keyboard.controller.admin.aicompanion;
+
+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.aicompanion.vo.*;
+import com.yolo.keyboard.dal.dataobject.aicompanion.KeyboardAiCompanionDO;
+import com.yolo.keyboard.service.aicompanion.KeyboardAiCompanionService;
+
+@Tag(name = "管理后台 - AI陪聊角色表，用于定义恋爱/陪伴型虚拟角色的基础信息与人设")
+@RestController
+@RequestMapping("/keyboard/ai-companion")
+@Validated
+public class KeyboardAiCompanionController {
+
+    @Resource
+    private KeyboardAiCompanionService aiCompanionService;
+
+    @PostMapping("/create")
+    @Operation(summary = "创建AI陪聊角色表，用于定义恋爱/陪伴型虚拟角色的基础信息与人设")
+    @PreAuthorize("@ss.hasPermission('keyboard:ai-companion:create')")
+    public CommonResult<Long> createAiCompanion(@Valid @RequestBody KeyboardAiCompanionSaveReqVO createReqVO) {
+        return success(aiCompanionService.createAiCompanion(createReqVO));
+    }
+
+    @PutMapping("/update")
+    @Operation(summary = "更新AI陪聊角色表，用于定义恋爱/陪伴型虚拟角色的基础信息与人设")
+    @PreAuthorize("@ss.hasPermission('keyboard:ai-companion:update')")
+    public CommonResult<Boolean> updateAiCompanion(@Valid @RequestBody KeyboardAiCompanionSaveReqVO updateReqVO) {
+        aiCompanionService.updateAiCompanion(updateReqVO);
+        return success(true);
+    }
+
+    @DeleteMapping("/delete")
+    @Operation(summary = "删除AI陪聊角色表，用于定义恋爱/陪伴型虚拟角色的基础信息与人设")
+    @Parameter(name = "id", description = "编号", required = true)
+    @PreAuthorize("@ss.hasPermission('keyboard:ai-companion:delete')")
+    public CommonResult<Boolean> deleteAiCompanion(@RequestParam("id") Long id) {
+        aiCompanionService.deleteAiCompanion(id);
+        return success(true);
+    }
+
+    @DeleteMapping("/delete-list")
+    @Parameter(name = "ids", description = "编号", required = true)
+    @Operation(summary = "批量删除AI陪聊角色表，用于定义恋爱/陪伴型虚拟角色的基础信息与人设")
+                @PreAuthorize("@ss.hasPermission('keyboard:ai-companion:delete')")
+    public CommonResult<Boolean> deleteAiCompanionList(@RequestParam("ids") List<Long> ids) {
+        aiCompanionService.deleteAiCompanionListByIds(ids);
+        return success(true);
+    }
+
+    @GetMapping("/get")
+    @Operation(summary = "获得AI陪聊角色表，用于定义恋爱/陪伴型虚拟角色的基础信息与人设")
+    @Parameter(name = "id", description = "编号", required = true, example = "1024")
+    @PreAuthorize("@ss.hasPermission('keyboard:ai-companion:query')")
+    public CommonResult<KeyboardAiCompanionRespVO> getAiCompanion(@RequestParam("id") Long id) {
+        KeyboardAiCompanionDO aiCompanion = aiCompanionService.getAiCompanion(id);
+        return success(BeanUtils.toBean(aiCompanion, KeyboardAiCompanionRespVO.class));
+    }
+
+    @GetMapping("/page")
+    @Operation(summary = "获得AI陪聊角色表，用于定义恋爱/陪伴型虚拟角色的基础信息与人设分页")
+    @PreAuthorize("@ss.hasPermission('keyboard:ai-companion:query')")
+    public CommonResult<PageResult<KeyboardAiCompanionRespVO>> getAiCompanionPage(@Valid KeyboardAiCompanionPageReqVO pageReqVO) {
+        PageResult<KeyboardAiCompanionDO> pageResult = aiCompanionService.getAiCompanionPage(pageReqVO);
+        return success(BeanUtils.toBean(pageResult, KeyboardAiCompanionRespVO.class));
+    }
+
+    @GetMapping("/export-excel")
+    @Operation(summary = "导出AI陪聊角色表，用于定义恋爱/陪伴型虚拟角色的基础信息与人设 Excel")
+    @PreAuthorize("@ss.hasPermission('keyboard:ai-companion:export')")
+    @ApiAccessLog(operateType = EXPORT)
+    public void exportAiCompanionExcel(@Valid KeyboardAiCompanionPageReqVO pageReqVO,
+              HttpServletResponse response) throws IOException {
+        pageReqVO.setPageSize(PageParam.PAGE_SIZE_NONE);
+        List<KeyboardAiCompanionDO> list = aiCompanionService.getAiCompanionPage(pageReqVO).getList();
+        // 导出 Excel
+        ExcelUtils.write(response, "AI陪聊角色表，用于定义恋爱/陪伴型虚拟角色的基础信息与人设.xls", "数据", KeyboardAiCompanionRespVO.class,
+                        BeanUtils.toBean(list, KeyboardAiCompanionRespVO.class));
+    }
+
+}
--- a/keyboard-server/src/main/java/com/yolo/keyboard/controller/admin/aicompanion/vo/KeyboardAiCompanionPageReqVO.java
+++ b/keyboard-server/src/main/java/com/yolo/keyboard/controller/admin/aicompanion/vo/KeyboardAiCompanionPageReqVO.java
@@ -0,0 +1,73 @@
+package com.yolo.keyboard.controller.admin.aicompanion.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 = "管理后台 - AI陪聊角色表，用于定义恋爱/陪伴型虚拟角色的基础信息与人设分页 Request VO")
+@Data
+public class KeyboardAiCompanionPageReqVO extends PageParam {
+
+    @Schema(description = "角色名称（展示用，如：Katie Leona）", example = "张三")
+    private String name;
+
+    @Schema(description = "角色头像URL，用于列表页和聊天页", example = "https://www.iocoder.cn")
+    private String avatarUrl;
+
+    @Schema(description = "角色封面图URL，用于角色详情页", example = "https://www.iocoder.cn")
+    private String coverImageUrl;
+
+    @Schema(description = "角色性别（male / female / other）")
+    private String gender;
+
+    @Schema(description = "角色年龄段描述（如：20s、25-30）")
+    private String ageRange;
+
+    @Schema(description = "一句话人设描述，用于卡片或列表展示")
+    private String shortDesc;
+
+    @Schema(description = "角色详细介绍文案，用于角色详情页")
+    private String introText;
+
+    @Schema(description = "角色性格标签数组（如：温柔、黏人、治愈）")
+    private Object personalityTags;
+
+    @Schema(description = "角色说话风格（如：撒娇型、理性型、活泼型）")
+    private String speakingStyle;
+
+    @Schema(description = "AI系统Prompt，定义角色核心人设，仅供模型使用")
+    private String systemPrompt;
+
+    @Schema(description = "角色状态：1=上线，0=下线", example = "2")
+    private Short status;
+
+    @Schema(description = "角色可见性：1=公开，2=内测，3=隐藏")
+    private Short visibility;
+
+    @Schema(description = "排序权重，数值越大排序越靠前")
+    private Integer sortOrder;
+
+    @Schema(description = "角色热度评分，用于推荐排序")
+    private Integer popularityScore;
+
+    @Schema(description = "创建时间")
+    private LocalDateTime createdAt;
+
+    @Schema(description = "更新时间")
+    private LocalDateTime updatedAt;
+
+    @Schema(description = "开场白")
+    private String prologue;
+
+    @Schema(description = "开场白音频")
+    private String prologueAudio;
+
+    @Schema(description = "音频Id", example = "31328")
+    private String voiceId;
+
+}
--- a/keyboard-server/src/main/java/com/yolo/keyboard/controller/admin/aicompanion/vo/KeyboardAiCompanionRespVO.java
+++ b/keyboard-server/src/main/java/com/yolo/keyboard/controller/admin/aicompanion/vo/KeyboardAiCompanionRespVO.java
@@ -0,0 +1,95 @@
+package com.yolo.keyboard.controller.admin.aicompanion.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 = "管理后台 - AI陪聊角色表，用于定义恋爱/陪伴型虚拟角色的基础信息与人设 Response VO")
+@Data
+@ExcelIgnoreUnannotated
+public class KeyboardAiCompanionRespVO {
+
+    @Schema(description = "陪聊角色唯一ID", requiredMode = Schema.RequiredMode.REQUIRED, example = "7816")
+    @ExcelProperty("陪聊角色唯一ID")
+    private Long id;
+
+    @Schema(description = "角色名称（展示用，如：Katie Leona）", requiredMode = Schema.RequiredMode.REQUIRED, example = "张三")
+    @ExcelProperty("角色名称（展示用，如：Katie Leona）")
+    private String name;
+
+    @Schema(description = "角色头像URL，用于列表页和聊天页", example = "https://www.iocoder.cn")
+    @ExcelProperty("角色头像URL，用于列表页和聊天页")
+    private String avatarUrl;
+
+    @Schema(description = "角色封面图URL，用于角色详情页", example = "https://www.iocoder.cn")
+    @ExcelProperty("角色封面图URL，用于角色详情页")
+    private String coverImageUrl;
+
+    @Schema(description = "角色性别（male / female / other）")
+    @ExcelProperty("角色性别（male / female / other）")
+    private String gender;
+
+    @Schema(description = "角色年龄段描述（如：20s、25-30）")
+    @ExcelProperty("角色年龄段描述（如：20s、25-30）")
+    private String ageRange;
+
+    @Schema(description = "一句话人设描述，用于卡片或列表展示")
+    @ExcelProperty("一句话人设描述，用于卡片或列表展示")
+    private String shortDesc;
+
+    @Schema(description = "角色详细介绍文案，用于角色详情页")
+    @ExcelProperty("角色详细介绍文案，用于角色详情页")
+    private String introText;
+
+    @Schema(description = "角色性格标签数组（如：温柔、黏人、治愈）")
+    @ExcelProperty("角色性格标签数组（如：温柔、黏人、治愈）")
+    private Object personalityTags;
+
+    @Schema(description = "角色说话风格（如：撒娇型、理性型、活泼型）")
+    @ExcelProperty("角色说话风格（如：撒娇型、理性型、活泼型）")
+    private String speakingStyle;
+
+    @Schema(description = "AI系统Prompt，定义角色核心人设，仅供模型使用", requiredMode = Schema.RequiredMode.REQUIRED)
+    @ExcelProperty("AI系统Prompt，定义角色核心人设，仅供模型使用")
+    private String systemPrompt;
+
+    @Schema(description = "角色状态：1=上线，0=下线", requiredMode = Schema.RequiredMode.REQUIRED, example = "2")
+    @ExcelProperty("角色状态：1=上线，0=下线")
+    private Short status;
+
+    @Schema(description = "角色可见性：1=公开，2=内测，3=隐藏", requiredMode = Schema.RequiredMode.REQUIRED)
+    @ExcelProperty("角色可见性：1=公开，2=内测，3=隐藏")
+    private Short visibility;
+
+    @Schema(description = "排序权重，数值越大排序越靠前")
+    @ExcelProperty("排序权重，数值越大排序越靠前")
+    private Integer sortOrder;
+
+    @Schema(description = "角色热度评分，用于推荐排序")
+    @ExcelProperty("角色热度评分，用于推荐排序")
+    private Integer popularityScore;
+
+    @Schema(description = "创建时间", requiredMode = Schema.RequiredMode.REQUIRED)
+    @ExcelProperty("创建时间")
+    private LocalDateTime createdAt;
+
+    @Schema(description = "更新时间", requiredMode = Schema.RequiredMode.REQUIRED)
+    @ExcelProperty("更新时间")
+    private LocalDateTime updatedAt;
+
+    @Schema(description = "开场白")
+    @ExcelProperty("开场白")
+    private String prologue;
+
+    @Schema(description = "开场白音频")
+    @ExcelProperty("开场白音频")
+    private String prologueAudio;
+
+    @Schema(description = "音频Id", example = "31328")
+    @ExcelProperty("音频Id")
+    private String voiceId;
+
+}
--- a/keyboard-server/src/main/java/com/yolo/keyboard/controller/admin/aicompanion/vo/KeyboardAiCompanionSaveReqVO.java
+++ b/keyboard-server/src/main/java/com/yolo/keyboard/controller/admin/aicompanion/vo/KeyboardAiCompanionSaveReqVO.java
@@ -0,0 +1,80 @@
+package com.yolo.keyboard.controller.admin.aicompanion.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 = "管理后台 - AI陪聊角色表，用于定义恋爱/陪伴型虚拟角色的基础信息与人设新增/修改 Request VO")
+@Data
+public class KeyboardAiCompanionSaveReqVO {
+
+    @Schema(description = "陪聊角色唯一ID", requiredMode = Schema.RequiredMode.REQUIRED, example = "7816")
+    private Long id;
+
+    @Schema(description = "角色名称（展示用，如：Katie Leona）", requiredMode = Schema.RequiredMode.REQUIRED, example = "张三")
+    @NotEmpty(message = "角色名称（展示用，如：Katie Leona）不能为空")
+    private String name;
+
+    @Schema(description = "角色头像URL，用于列表页和聊天页", example = "https://www.iocoder.cn")
+    private String avatarUrl;
+
+    @Schema(description = "角色封面图URL，用于角色详情页", example = "https://www.iocoder.cn")
+    private String coverImageUrl;
+
+    @Schema(description = "角色性别（male / female / other）")
+    private String gender;
+
+    @Schema(description = "角色年龄段描述（如：20s、25-30）")
+    private String ageRange;
+
+    @Schema(description = "一句话人设描述，用于卡片或列表展示")
+    private String shortDesc;
+
+    @Schema(description = "角色详细介绍文案，用于角色详情页")
+    private String introText;
+
+    @Schema(description = "角色性格标签数组（如：温柔、黏人、治愈）")
+    private Object personalityTags;
+
+    @Schema(description = "角色说话风格（如：撒娇型、理性型、活泼型）")
+    private String speakingStyle;
+
+    @Schema(description = "AI系统Prompt，定义角色核心人设，仅供模型使用", requiredMode = Schema.RequiredMode.REQUIRED)
+    @NotEmpty(message = "AI系统Prompt，定义角色核心人设，仅供模型使用不能为空")
+    private String systemPrompt;
+
+    @Schema(description = "角色状态：1=上线，0=下线", requiredMode = Schema.RequiredMode.REQUIRED, example = "2")
+    @NotNull(message = "角色状态：1=上线，0=下线不能为空")
+    private Short status;
+
+    @Schema(description = "角色可见性：1=公开，2=内测，3=隐藏", requiredMode = Schema.RequiredMode.REQUIRED)
+    @NotNull(message = "角色可见性：1=公开，2=内测，3=隐藏不能为空")
+    private Short visibility;
+
+    @Schema(description = "排序权重，数值越大排序越靠前")
+    private Integer sortOrder;
+
+    @Schema(description = "角色热度评分，用于推荐排序")
+    private Integer popularityScore;
+
+    @Schema(description = "创建时间", requiredMode = Schema.RequiredMode.REQUIRED)
+    @NotNull(message = "创建时间不能为空")
+    private LocalDateTime createdAt;
+
+    @Schema(description = "更新时间", requiredMode = Schema.RequiredMode.REQUIRED)
+    @NotNull(message = "更新时间不能为空")
+    private LocalDateTime updatedAt;
+
+    @Schema(description = "开场白")
+    private String prologue;
+
+    @Schema(description = "开场白音频")
+    private String prologueAudio;
+
+    @Schema(description = "音频Id", example = "31328")
+    private String voiceId;
+
+}
--- a/keyboard-server/src/main/java/com/yolo/keyboard/dal/dataobject/aicompanion/KeyboardAiCompanionDO.java
+++ b/keyboard-server/src/main/java/com/yolo/keyboard/dal/dataobject/aicompanion/KeyboardAiCompanionDO.java
@@ -0,0 +1,108 @@
+package com.yolo.keyboard.dal.dataobject.aicompanion;
+
+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;
+
+/**
+ * AI陪聊角色表，用于定义恋爱/陪伴型虚拟角色的基础信息与人设 DO
+ *
+ * @author ziin
+ */
+@TableName("keyboard_ai_companion")
+@KeySequence("keyboard_ai_companion_seq") // 用于 Oracle、PostgreSQL、Kingbase、DB2、H2 数据库的主键自增。如果是 MySQL 等数据库，可不写。
+@Data
+@ToString(callSuper = true)
+@Builder
+@NoArgsConstructor
+@AllArgsConstructor
+@TenantIgnore
+public class KeyboardAiCompanionDO {
+
+    /**
+     * 陪聊角色唯一ID
+     */
+    @TableId
+    private Long id;
+    /**
+     * 角色名称（展示用，如：Katie Leona）
+     */
+    private String name;
+    /**
+     * 角色头像URL，用于列表页和聊天页
+     */
+    private String avatarUrl;
+    /**
+     * 角色封面图URL，用于角色详情页
+     */
+    private String coverImageUrl;
+    /**
+     * 角色性别（male / female / other）
+     */
+    private String gender;
+    /**
+     * 角色年龄段描述（如：20s、25-30）
+     */
+    private String ageRange;
+    /**
+     * 一句话人设描述，用于卡片或列表展示
+     */
+    private String shortDesc;
+    /**
+     * 角色详细介绍文案，用于角色详情页
+     */
+    private String introText;
+    /**
+     * 角色性格标签数组（如：温柔、黏人、治愈）
+     */
+    private Object personalityTags;
+    /**
+     * 角色说话风格（如：撒娇型、理性型、活泼型）
+     */
+    private String speakingStyle;
+    /**
+     * AI系统Prompt，定义角色核心人设，仅供模型使用
+     */
+    private String systemPrompt;
+    /**
+     * 角色状态：1=上线，0=下线
+     */
+    private Short status;
+    /**
+     * 角色可见性：1=公开，2=内测，3=隐藏
+     */
+    private Short visibility;
+    /**
+     * 排序权重，数值越大排序越靠前
+     */
+    private Integer sortOrder;
+    /**
+     * 角色热度评分，用于推荐排序
+     */
+    private Integer popularityScore;
+    /**
+     * 创建时间
+     */
+    private LocalDateTime createdAt;
+    /**
+     * 更新时间
+     */
+    private LocalDateTime updatedAt;
+    /**
+     * 开场白
+     */
+    private String prologue;
+    /**
+     * 开场白音频
+     */
+    private String prologueAudio;
+    /**
+     * 音频Id
+     */
+    private String voiceId;
+
+
+}
--- a/keyboard-server/src/main/java/com/yolo/keyboard/dal/mysql/aicompanion/KeyboardAiCompanionMapper.java
+++ b/keyboard-server/src/main/java/com/yolo/keyboard/dal/mysql/aicompanion/KeyboardAiCompanionMapper.java
@@ -0,0 +1,44 @@
+package com.yolo.keyboard.dal.mysql.aicompanion;
+
+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.aicompanion.KeyboardAiCompanionDO;
+import org.apache.ibatis.annotations.Mapper;
+import com.yolo.keyboard.controller.admin.aicompanion.vo.*;
+
+/**
+ * AI陪聊角色表，用于定义恋爱/陪伴型虚拟角色的基础信息与人设 Mapper
+ *
+ * @author ziin
+ */
+@Mapper
+public interface KeyboardAiCompanionMapper extends BaseMapperX<KeyboardAiCompanionDO> {
+
+    default PageResult<KeyboardAiCompanionDO> selectPage(KeyboardAiCompanionPageReqVO reqVO) {
+        return selectPage(reqVO, new LambdaQueryWrapperX<KeyboardAiCompanionDO>()
+                .likeIfPresent(KeyboardAiCompanionDO::getName, reqVO.getName())
+                .eqIfPresent(KeyboardAiCompanionDO::getAvatarUrl, reqVO.getAvatarUrl())
+                .eqIfPresent(KeyboardAiCompanionDO::getCoverImageUrl, reqVO.getCoverImageUrl())
+                .eqIfPresent(KeyboardAiCompanionDO::getGender, reqVO.getGender())
+                .eqIfPresent(KeyboardAiCompanionDO::getAgeRange, reqVO.getAgeRange())
+                .eqIfPresent(KeyboardAiCompanionDO::getShortDesc, reqVO.getShortDesc())
+                .eqIfPresent(KeyboardAiCompanionDO::getIntroText, reqVO.getIntroText())
+                .eqIfPresent(KeyboardAiCompanionDO::getPersonalityTags, reqVO.getPersonalityTags())
+                .eqIfPresent(KeyboardAiCompanionDO::getSpeakingStyle, reqVO.getSpeakingStyle())
+                .eqIfPresent(KeyboardAiCompanionDO::getSystemPrompt, reqVO.getSystemPrompt())
+                .eqIfPresent(KeyboardAiCompanionDO::getStatus, reqVO.getStatus())
+                .eqIfPresent(KeyboardAiCompanionDO::getVisibility, reqVO.getVisibility())
+                .eqIfPresent(KeyboardAiCompanionDO::getSortOrder, reqVO.getSortOrder())
+                .eqIfPresent(KeyboardAiCompanionDO::getPopularityScore, reqVO.getPopularityScore())
+                .eqIfPresent(KeyboardAiCompanionDO::getCreatedAt, reqVO.getCreatedAt())
+                .eqIfPresent(KeyboardAiCompanionDO::getUpdatedAt, reqVO.getUpdatedAt())
+                .eqIfPresent(KeyboardAiCompanionDO::getPrologue, reqVO.getPrologue())
+                .eqIfPresent(KeyboardAiCompanionDO::getPrologueAudio, reqVO.getPrologueAudio())
+                .eqIfPresent(KeyboardAiCompanionDO::getVoiceId, reqVO.getVoiceId())
+                .orderByDesc(KeyboardAiCompanionDO::getId));
+    }
+
+}
--- a/keyboard-server/src/main/java/com/yolo/keyboard/service/aicompanion/KeyboardAiCompanionService.java
+++ b/keyboard-server/src/main/java/com/yolo/keyboard/service/aicompanion/KeyboardAiCompanionService.java
@@ -0,0 +1,63 @@
+package com.yolo.keyboard.service.aicompanion;
+
+import com.yolo.keyboard.controller.admin.aicompanion.vo.KeyboardAiCompanionPageReqVO;
+import com.yolo.keyboard.controller.admin.aicompanion.vo.KeyboardAiCompanionSaveReqVO;
+import com.yolo.keyboard.dal.dataobject.aicompanion.KeyboardAiCompanionDO;
+import com.yolo.keyboard.framework.common.pojo.PageResult;
+import jakarta.validation.Valid;
+
+import java.util.List;
+
+/**
+ * AI陪聊角色表，用于定义恋爱/陪伴型虚拟角色的基础信息与人设 Service 接口
+ *
+ * @author ziin
+ */
+public interface KeyboardAiCompanionService {
+
+    /**
+     * 创建AI陪聊角色表，用于定义恋爱/陪伴型虚拟角色的基础信息与人设
+     *
+     * @param createReqVO 创建信息
+     * @return 编号
+     */
+    Long createAiCompanion(@Valid KeyboardAiCompanionSaveReqVO createReqVO);
+
+    /**
+     * 更新AI陪聊角色表，用于定义恋爱/陪伴型虚拟角色的基础信息与人设
+     *
+     * @param updateReqVO 更新信息
+     */
+    void updateAiCompanion(@Valid KeyboardAiCompanionSaveReqVO updateReqVO);
+
+    /**
+     * 删除AI陪聊角色表，用于定义恋爱/陪伴型虚拟角色的基础信息与人设
+     *
+     * @param id 编号
+     */
+    void deleteAiCompanion(Long id);
+
+    /**
+    * 批量删除AI陪聊角色表，用于定义恋爱/陪伴型虚拟角色的基础信息与人设
+    *
+    * @param ids 编号
+    */
+    void deleteAiCompanionListByIds(List<Long> ids);
+
+    /**
+     * 获得AI陪聊角色表，用于定义恋爱/陪伴型虚拟角色的基础信息与人设
+     *
+     * @param id 编号
+     * @return AI陪聊角色表，用于定义恋爱/陪伴型虚拟角色的基础信息与人设
+     */
+    KeyboardAiCompanionDO getAiCompanion(Long id);
+
+    /**
+     * 获得AI陪聊角色表，用于定义恋爱/陪伴型虚拟角色的基础信息与人设分页
+     *
+     * @param pageReqVO 分页查询
+     * @return AI陪聊角色表，用于定义恋爱/陪伴型虚拟角色的基础信息与人设分页
+     */
+    PageResult<KeyboardAiCompanionDO> getAiCompanionPage(KeyboardAiCompanionPageReqVO pageReqVO);
+
+}
--- a/keyboard-server/src/main/java/com/yolo/keyboard/service/aicompanion/KeyboardAiCompanionServiceImpl.java
+++ b/keyboard-server/src/main/java/com/yolo/keyboard/service/aicompanion/KeyboardAiCompanionServiceImpl.java
@@ -0,0 +1,80 @@
+package com.yolo.keyboard.service.aicompanion;
+
+import com.yolo.keyboard.controller.admin.aicompanion.vo.KeyboardAiCompanionPageReqVO;
+import com.yolo.keyboard.controller.admin.aicompanion.vo.KeyboardAiCompanionSaveReqVO;
+import com.yolo.keyboard.dal.dataobject.aicompanion.KeyboardAiCompanionDO;
+import com.yolo.keyboard.dal.mysql.aicompanion.KeyboardAiCompanionMapper;
+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.AI_COMPANION_NOT_EXISTS;
+
+/**
+ * AI陪聊角色表，用于定义恋爱/陪伴型虚拟角色的基础信息与人设 Service 实现类
+ *
+ * @author ziin
+ */
+@Service
+@Validated
+public class KeyboardAiCompanionServiceImpl implements KeyboardAiCompanionService {
+
+    @Resource
+    private KeyboardAiCompanionMapper aiCompanionMapper;
+
+    @Override
+    public Long createAiCompanion(KeyboardAiCompanionSaveReqVO createReqVO) {
+        // 插入
+        KeyboardAiCompanionDO aiCompanion = BeanUtils.toBean(createReqVO, KeyboardAiCompanionDO.class);
+        aiCompanionMapper.insert(aiCompanion);
+
+        // 返回
+        return aiCompanion.getId();
+    }
+
+    @Override
+    public void updateAiCompanion(KeyboardAiCompanionSaveReqVO updateReqVO) {
+        // 校验存在
+        validateAiCompanionExists(updateReqVO.getId());
+        // 更新
+        KeyboardAiCompanionDO updateObj = BeanUtils.toBean(updateReqVO, KeyboardAiCompanionDO.class);
+        aiCompanionMapper.updateById(updateObj);
+    }
+
+    @Override
+    public void deleteAiCompanion(Long id) {
+        // 校验存在
+        validateAiCompanionExists(id);
+        // 删除
+        aiCompanionMapper.deleteById(id);
+    }
+
+    @Override
+        public void deleteAiCompanionListByIds(List<Long> ids) {
+        // 删除
+        aiCompanionMapper.deleteByIds(ids);
+        }
+
+
+    private void validateAiCompanionExists(Long id) {
+        if (aiCompanionMapper.selectById(id) == null) {
+            throw exception(AI_COMPANION_NOT_EXISTS);
+        }
+    }
+
+    @Override
+    public KeyboardAiCompanionDO getAiCompanion(Long id) {
+        return aiCompanionMapper.selectById(id);
+    }
+
+    @Override
+    public PageResult<KeyboardAiCompanionDO> getAiCompanionPage(KeyboardAiCompanionPageReqVO pageReqVO) {
+        return aiCompanionMapper.selectPage(pageReqVO);
+    }
+
+}
--- a/keyboard-server/src/main/resources/mapper/aicompanion/KeyboardAiCompanionMapper.xml
+++ b/keyboard-server/src/main/resources/mapper/aicompanion/KeyboardAiCompanionMapper.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.aicompanion.KeyboardAiCompanionMapper">
+
+    <!--
+        一般情况下，尽可能使用 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
@@ -94,6 +94,6 @@ public interface ErrorCodeConstants {
    ErrorCode USER_INVITE_CODES_NOT_EXISTS = new ErrorCode(1_001_202_020, "用户生成的邀请码表，用于邀请新用户注册/安装并建立邀请关系不存在");
    ErrorCode USER_INVITES_NOT_EXISTS = new ErrorCode(1_001_202_021, "用户邀请关系绑定台账表，记录新用户最终归属的邀请人不存在");
    ErrorCode TENANT_COMMISSION_NOT_EXISTS = new ErrorCode(1_001_202_022, "租户内购分成记录不存在");
-
+    ErrorCode AI_COMPANION_NOT_EXISTS = new ErrorCode(1_001_202_023, "AI陪聊角色表，用于定义恋爱/陪伴型虚拟角色的基础信息与人设不存在");

 }