feat(physical): 新增广告位管理功能

- 新增广告位实体类 PhysicalAdBanner 及相关 VO、BO 类
- 实现广告位的增删改查接口及分页查询功能
- 添加广告位控制器 PhysicalAdBannerController 提供 RESTful API
- 配置 MyBatis Mapper 及 XML 文件实现数据库操作
- 支持广告位数据导出为 Excel 功能
- 使用 MapStruct 进行 BO 与实体类之间的转换
- 添加基础校验和权限控制注解确保数据安全

ruoyi-modules/ruoyi-system/src/main/java/org/dromara/physical/controller/PhysicalAdBannerController.java

@@ -0,0 +1,105 @@
+package org.dromara.physical.controller;
+
+import java.util.List;
+
+import lombok.RequiredArgsConstructor;
+import jakarta.servlet.http.HttpServletResponse;
+import jakarta.validation.constraints.*;
+import cn.dev33.satoken.annotation.SaCheckPermission;
+import org.dromara.physical.domain.bo.PhysicalAdBannerBo;
+import org.dromara.physical.domain.vo.PhysicalAdBannerVo;
+import org.dromara.physical.service.IPhysicalAdBannerService;
+import org.springframework.web.bind.annotation.*;
+import org.springframework.validation.annotation.Validated;
+import org.dromara.common.idempotent.annotation.RepeatSubmit;
+import org.dromara.common.log.annotation.Log;
+import org.dromara.common.web.core.BaseController;
+import org.dromara.common.mybatis.core.page.PageQuery;
+import org.dromara.common.core.domain.R;
+import org.dromara.common.core.validate.AddGroup;
+import org.dromara.common.core.validate.EditGroup;
+import org.dromara.common.log.enums.BusinessType;
+import org.dromara.common.excel.utils.ExcelUtil;
+import org.dromara.common.mybatis.core.page.TableDataInfo;
+
+/**
+ * 广告位
+ *
+ * @author Lion Li
+ * @date 2025-12-03
+ */
+@Validated
+@RequiredArgsConstructor
+@RestController
+@RequestMapping("/physical/adBanner")
+public class PhysicalAdBannerController extends BaseController {
+
+    private final IPhysicalAdBannerService physicalAdBannerService;
+
+    /**
+     * 查询广告位列表
+     */
+    @SaCheckPermission("physical:adBanner:list")
+    @GetMapping("/list")
+    public TableDataInfo<PhysicalAdBannerVo> list(PhysicalAdBannerBo bo, PageQuery pageQuery) {
+        return physicalAdBannerService.queryPageList(bo, pageQuery);
+    }
+
+    /**
+     * 导出广告位列表
+     */
+    @SaCheckPermission("physical:adBanner:export")
+    @Log(title = "广告位", businessType = BusinessType.EXPORT)
+    @PostMapping("/export")
+    public void export(PhysicalAdBannerBo bo, HttpServletResponse response) {
+        List<PhysicalAdBannerVo> list = physicalAdBannerService.queryList(bo);
+        ExcelUtil.exportExcel(list, "广告位", PhysicalAdBannerVo.class, response);
+    }
+
+    /**
+     * 获取广告位详细信息
+     *
+     * @param id 主键
+     */
+    @SaCheckPermission("physical:adBanner:query")
+    @GetMapping("/{id}")
+    public R<PhysicalAdBannerVo> getInfo(@NotNull(message = "主键不能为空")
+                                     @PathVariable Long id) {
+        return R.ok(physicalAdBannerService.queryById(id));
+    }
+
+    /**
+     * 新增广告位
+     */
+    @SaCheckPermission("physical:adBanner:add")
+    @Log(title = "广告位", businessType = BusinessType.INSERT)
+    @RepeatSubmit()
+    @PostMapping()
+    public R<Void> add(@Validated(AddGroup.class) @RequestBody PhysicalAdBannerBo bo) {
+        return toAjax(physicalAdBannerService.insertByBo(bo));
+    }
+
+    /**
+     * 修改广告位
+     */
+    @SaCheckPermission("physical:adBanner:edit")
+    @Log(title = "广告位", businessType = BusinessType.UPDATE)
+    @RepeatSubmit()
+    @PutMapping()
+    public R<Void> edit(@Validated(EditGroup.class) @RequestBody PhysicalAdBannerBo bo) {
+        return toAjax(physicalAdBannerService.updateByBo(bo));
+    }
+
+    /**
+     * 删除广告位
+     *
+     * @param ids 主键串
+     */
+    @SaCheckPermission("physical:adBanner:remove")
+    @Log(title = "广告位", businessType = BusinessType.DELETE)
+    @DeleteMapping("/{ids}")
+    public R<Void> remove(@NotEmpty(message = "主键不能为空")
+                          @PathVariable Long[] ids) {
+        return toAjax(physicalAdBannerService.deleteWithValidByIds(List.of(ids), true));
+    }
+}

ruoyi-modules/ruoyi-system/src/main/java/org/dromara/physical/domain/PhysicalAdBanner.java

@@ -0,0 +1,73 @@
+package org.dromara.physical.domain;
+
+import org.dromara.common.mybatis.core.domain.BaseEntity;
+import com.baomidou.mybatisplus.annotation.*;
+import lombok.Data;
+import lombok.EqualsAndHashCode;
+import java.util.Date;
+import com.fasterxml.jackson.annotation.JsonFormat;
+
+import java.io.Serial;
+
+/**
+ * 广告位对象 physical_ad_banner
+ *
+ * @author Lion Li
+ * @date 2025-12-03
+ */
+@Data
+@EqualsAndHashCode(callSuper = true)
+@TableName("physical_ad_banner")
+public class PhysicalAdBanner extends BaseEntity {
+
+    @Serial
+    private static final long serialVersionUID = 1L;
+
+    /**
+     *
+     */
+    @TableId(value = "id")
+    private Long id;
+
+    /**
+     * 广告位位置，如 HOME_MAIN
+     */
+    private String position;
+
+    /**
+     * 图片地址（HTTPS）
+     */
+    private String imageUrl;
+
+    /**
+     * 点击跳转链接
+     */
+    private String linkUrl;
+
+    /**
+     * 排序序号，越小越靠前
+     */
+    private Long sortOrder;
+
+    /**
+     * 状态：ENABLE / DISABLE
+     */
+    private String status;
+
+    /**
+     *
+     */
+    private Date createdAt;
+
+    /**
+     *
+     */
+    private Date updatedAt;
+
+    /**
+     * 软删除时间
+     */
+    private Date deletedAt;
+
+
+}

ruoyi-modules/ruoyi-system/src/main/java/org/dromara/physical/domain/bo/PhysicalAdBannerBo.java

@@ -0,0 +1,74 @@
+package org.dromara.physical.domain.bo;
+
+import org.dromara.common.mybatis.core.domain.BaseEntity;
+import org.dromara.common.core.validate.AddGroup;
+import org.dromara.common.core.validate.EditGroup;
+import io.github.linpeilie.annotations.AutoMapper;
+import lombok.Data;
+import lombok.EqualsAndHashCode;
+import jakarta.validation.constraints.*;
+import org.dromara.physical.domain.PhysicalAdBanner;
+
+import java.util.Date;
+
+/**
+ * 广告位业务对象 physical_ad_banner
+ *
+ * @author Lion Li
+ * @date 2025-12-03
+ */
+@Data
+@EqualsAndHashCode(callSuper = true)
+@AutoMapper(target = PhysicalAdBanner.class, reverseConvertGenerate = false)
+public class PhysicalAdBannerBo extends BaseEntity {
+
+    /**
+     *
+     */
+    @NotNull(message = "不能为空", groups = { EditGroup.class })
+    private Long id;
+
+    /**
+     * 广告位位置，如 HOME_MAIN
+     */
+    //@NotBlank(message = "广告位位置，如 HOME_MAIN不能为空", groups = { AddGroup.class, EditGroup.class })
+    private String position;
+
+    /**
+     * 图片地址（HTTPS）
+     */
+    @NotBlank(message = "图片地址不能为空", groups = { AddGroup.class, EditGroup.class })
+    private String imageUrl;
+
+    /**
+     * 点击跳转链接
+     */
+    private String linkUrl;
+
+    /**
+     * 排序序号，越小越靠前
+     */
+    private Long sortOrder;
+
+    /**
+     * 状态：ENABLE / DISABLE
+     */
+    private String status;
+
+    /**
+     *
+     */
+    private Date createdAt;
+
+    /**
+     *
+     */
+    private Date updatedAt;
+
+    /**
+     * 软删除时间
+     */
+    private Date deletedAt;
+
+
+}

ruoyi-modules/ruoyi-system/src/main/java/org/dromara/physical/domain/vo/PhysicalAdBannerVo.java

@@ -0,0 +1,87 @@
+package org.dromara.physical.domain.vo;
+
+import java.util.Date;
+import cn.idev.excel.annotation.ExcelIgnoreUnannotated;
+import cn.idev.excel.annotation.ExcelProperty;
+import org.dromara.common.excel.annotation.ExcelDictFormat;
+import org.dromara.common.excel.convert.ExcelDictConvert;
+import io.github.linpeilie.annotations.AutoMapper;
+import lombok.Data;
+import org.dromara.physical.domain.PhysicalAdBanner;
+
+import java.io.Serial;
+import java.io.Serializable;
+
+
+
+/**
+ * 广告位视图对象 physical_ad_banner
+ *
+ * @author Lion Li
+ * @date 2025-12-03
+ */
+@Data
+@ExcelIgnoreUnannotated
+@AutoMapper(target = PhysicalAdBanner.class)
+public class PhysicalAdBannerVo implements Serializable {
+
+    @Serial
+    private static final long serialVersionUID = 1L;
+
+    /**
+     *
+     */
+    @ExcelProperty(value = "")
+    private Long id;
+
+    /**
+     * 广告位位置，如 HOME_MAIN
+     */
+    @ExcelProperty(value = "广告位位置，如 HOME_MAIN")
+    private String position;
+
+    /**
+     * 图片地址（HTTPS）
+     */
+    @ExcelProperty(value = "图片地址", converter = ExcelDictConvert.class)
+    @ExcelDictFormat(readConverterExp = "H=TTPS")
+    private String imageUrl;
+
+    /**
+     * 点击跳转链接
+     */
+    @ExcelProperty(value = "点击跳转链接")
+    private String linkUrl;
+
+    /**
+     * 排序序号，越小越靠前
+     */
+    @ExcelProperty(value = "排序序号，越小越靠前")
+    private Long sortOrder;
+
+    /**
+     * 状态：ENABLE / DISABLE
+     */
+    @ExcelProperty(value = "状态：ENABLE / DISABLE")
+    private String status;
+
+    /**
+     *
+     */
+    @ExcelProperty(value = "")
+    private Date createdAt;
+
+    /**
+     *
+     */
+    @ExcelProperty(value = "")
+    private Date updatedAt;
+
+    /**
+     * 软删除时间
+     */
+    @ExcelProperty(value = "软删除时间")
+    private Date deletedAt;
+
+
+}

ruoyi-modules/ruoyi-system/src/main/java/org/dromara/physical/mapper/PhysicalAdBannerMapper.java

@@ -0,0 +1,42 @@
+package org.dromara.physical.mapper;
+
+import com.baomidou.dynamic.datasource.annotation.DS;
+import com.baomidou.mybatisplus.annotation.InterceptorIgnore;
+import com.baomidou.mybatisplus.core.conditions.Wrapper;
+import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
+import org.apache.ibatis.annotations.Param;
+import org.dromara.common.mybatis.core.mapper.BaseMapperPlus;
+import org.dromara.physical.domain.PhysicalAdBanner;
+import org.dromara.physical.domain.vo.PhysicalAdBannerVo;
+import java.util.Collection;
+import java.util.List;
+
+/**
+ * 广告位Mapper接口
+ *
+ * @author Lion Li
+ * @date 2025-12-03
+ */
+@DS("mysql2")
+public interface PhysicalAdBannerMapper extends BaseMapperPlus<PhysicalAdBanner, PhysicalAdBannerVo> {
+
+
+    @InterceptorIgnore(tenantLine = "true")
+    Page<PhysicalAdBannerVo> selectAdBannerPage(@Param("page") Page<PhysicalAdBanner> page, @Param("ew") Wrapper<PhysicalAdBanner> wrapper);
+
+    @InterceptorIgnore(tenantLine = "true")
+    PhysicalAdBannerVo selectAdBannerById(Long id);
+
+    @InterceptorIgnore(tenantLine = "true")
+    int updateAdBannerById(@Param("banner") PhysicalAdBanner update);
+
+    @InterceptorIgnore(tenantLine = "true")
+    int insertAdBanner(@Param("banner") PhysicalAdBanner insert);
+
+    @InterceptorIgnore(tenantLine = "true")
+    int deleteAdBannerlById(@Param("ids") Collection<Long> ids);
+
+    @InterceptorIgnore(tenantLine = "true")
+    List<PhysicalAdBannerVo> selectAdBannerList(@Param("ew") Wrapper<PhysicalAdBanner> wrapper);
+
+}

ruoyi-modules/ruoyi-system/src/main/java/org/dromara/physical/service/IPhysicalAdBannerService.java

@@ -0,0 +1,68 @@
+package org.dromara.physical.service;
+
+import org.dromara.common.mybatis.core.page.TableDataInfo;
+import org.dromara.common.mybatis.core.page.PageQuery;
+import org.dromara.physical.domain.bo.PhysicalAdBannerBo;
+import org.dromara.physical.domain.vo.PhysicalAdBannerVo;
+
+import java.util.Collection;
+import java.util.List;
+
+/**
+ * 广告位Service接口
+ *
+ * @author Lion Li
+ * @date 2025-12-03
+ */
+public interface IPhysicalAdBannerService {
+
+    /**
+     * 查询广告位
+     *
+     * @param id 主键
+     * @return 广告位
+     */
+    PhysicalAdBannerVo queryById(Long id);
+
+    /**
+     * 分页查询广告位列表
+     *
+     * @param bo        查询条件
+     * @param pageQuery 分页参数
+     * @return 广告位分页列表
+     */
+    TableDataInfo<PhysicalAdBannerVo> queryPageList(PhysicalAdBannerBo bo, PageQuery pageQuery);
+
+    /**
+     * 查询符合条件的广告位列表
+     *
+     * @param bo 查询条件
+     * @return 广告位列表
+     */
+    List<PhysicalAdBannerVo> queryList(PhysicalAdBannerBo bo);
+
+    /**
+     * 新增广告位
+     *
+     * @param bo 广告位
+     * @return 是否新增成功
+     */
+    Boolean insertByBo(PhysicalAdBannerBo bo);
+
+    /**
+     * 修改广告位
+     *
+     * @param bo 广告位
+     * @return 是否修改成功
+     */
+    Boolean updateByBo(PhysicalAdBannerBo bo);
+
+    /**
+     * 校验并批量删除广告位信息
+     *
+     * @param ids     待删除的主键集合
+     * @param isValid 是否进行有效性校验
+     * @return 是否删除成功
+     */
+    Boolean deleteWithValidByIds(Collection<Long> ids, Boolean isValid);
+}

ruoyi-modules/ruoyi-system/src/main/java/org/dromara/physical/service/impl/PhysicalAdBannerServiceImpl.java

@@ -0,0 +1,141 @@
+package org.dromara.physical.service.impl;
+
+import org.dromara.common.core.utils.MapstructUtils;
+import org.dromara.common.core.utils.StringUtils;
+import org.dromara.common.mybatis.core.page.TableDataInfo;
+import org.dromara.common.mybatis.core.page.PageQuery;
+import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
+import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
+import com.baomidou.mybatisplus.core.toolkit.Wrappers;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.dromara.physical.domain.PhysicalAdBanner;
+import org.dromara.physical.domain.bo.PhysicalAdBannerBo;
+import org.dromara.physical.domain.vo.PhysicalAdBannerVo;
+import org.dromara.physical.mapper.PhysicalAdBannerMapper;
+import org.dromara.physical.service.IPhysicalAdBannerService;
+import org.springframework.stereotype.Service;
+
+import java.util.List;
+import java.util.Map;
+import java.util.Collection;
+
+/**
+ * 广告位Service业务层处理
+ *
+ * @author Lion Li
+ * @date 2025-12-03
+ */
+@Slf4j
+@RequiredArgsConstructor
+@Service
+public class PhysicalAdBannerServiceImpl implements IPhysicalAdBannerService {
+
+    private final PhysicalAdBannerMapper baseMapper;
+
+    /**
+     * 查询广告位
+     *
+     * @param id 主键
+     * @return 广告位
+     */
+    @Override
+    public PhysicalAdBannerVo queryById(Long id){
+        return baseMapper.selectAdBannerById(id);
+    }
+
+    /**
+     * 分页查询广告位列表
+     *
+     * @param bo        查询条件
+     * @param pageQuery 分页参数
+     * @return 广告位分页列表
+     */
+    @Override
+    public TableDataInfo<PhysicalAdBannerVo> queryPageList(PhysicalAdBannerBo bo, PageQuery pageQuery) {
+        LambdaQueryWrapper<PhysicalAdBanner> lqw = buildQueryWrapper(bo);
+        Page<PhysicalAdBannerVo> result = baseMapper.selectAdBannerPage(pageQuery.build(), lqw);
+        return TableDataInfo.build(result);
+    }
+
+    /**
+     * 查询符合条件的广告位列表
+     *
+     * @param bo 查询条件
+     * @return 广告位列表
+     */
+    @Override
+    public List<PhysicalAdBannerVo> queryList(PhysicalAdBannerBo bo) {
+        LambdaQueryWrapper<PhysicalAdBanner> lqw = buildQueryWrapper(bo);
+        return baseMapper.selectAdBannerList(lqw);
+    }
+
+    private LambdaQueryWrapper<PhysicalAdBanner> buildQueryWrapper(PhysicalAdBannerBo bo) {
+        Map<String, Object> params = bo.getParams();
+        LambdaQueryWrapper<PhysicalAdBanner> lqw = Wrappers.lambdaQuery();
+        lqw.orderByAsc(PhysicalAdBanner::getId);
+        lqw.eq(StringUtils.isNotBlank(bo.getPosition()), PhysicalAdBanner::getPosition, bo.getPosition());
+        lqw.eq(StringUtils.isNotBlank(bo.getImageUrl()), PhysicalAdBanner::getImageUrl, bo.getImageUrl());
+        lqw.eq(StringUtils.isNotBlank(bo.getLinkUrl()), PhysicalAdBanner::getLinkUrl, bo.getLinkUrl());
+        lqw.eq(bo.getSortOrder() != null, PhysicalAdBanner::getSortOrder, bo.getSortOrder());
+        lqw.eq(StringUtils.isNotBlank(bo.getStatus()), PhysicalAdBanner::getStatus, bo.getStatus());
+        lqw.eq(bo.getCreatedAt() != null, PhysicalAdBanner::getCreatedAt, bo.getCreatedAt());
+        lqw.eq(bo.getUpdatedAt() != null, PhysicalAdBanner::getUpdatedAt, bo.getUpdatedAt());
+        lqw.eq(bo.getDeletedAt() != null, PhysicalAdBanner::getDeletedAt, bo.getDeletedAt());
+        return lqw;
+    }
+
+    /**
+     * 新增广告位
+     *
+     * @param bo 广告位
+     * @return 是否新增成功
+     */
+    @Override
+    public Boolean insertByBo(PhysicalAdBannerBo bo) {
+        PhysicalAdBanner add = MapstructUtils.convert(bo, PhysicalAdBanner.class);
+        validEntityBeforeSave(add);
+        add.setPosition("HOME_MAIN");
+        boolean flag = baseMapper.insertAdBanner(add) > 0;
+        if (flag) {
+            bo.setId(add.getId());
+        }
+        return flag;
+    }
+
+    /**
+     * 修改广告位
+     *
+     * @param bo 广告位
+     * @return 是否修改成功
+     */
+    @Override
+    public Boolean updateByBo(PhysicalAdBannerBo bo) {
+        PhysicalAdBanner update = MapstructUtils.convert(bo, PhysicalAdBanner.class);
+        validEntityBeforeSave(update);
+        return baseMapper.updateAdBannerById(update) > 0;
+    }
+
+    /**
+     * 保存前的数据校验
+     */
+    private void validEntityBeforeSave(PhysicalAdBanner entity){
+        //TODO 做一些数据校验,如唯一约束
+        entity.setStatus("ENABLE");
+    }
+
+    /**
+     * 校验并批量删除广告位信息
+     *
+     * @param ids     待删除的主键集合
+     * @param isValid 是否进行有效性校验
+     * @return 是否删除成功
+     */
+    @Override
+    public Boolean deleteWithValidByIds(Collection<Long> ids, Boolean isValid) {
+        if(isValid){
+            //TODO 做一些业务上的校验,判断是否需要校验
+        }
+        return baseMapper.deleteAdBannerlById(ids) > 0;
+    }
+}

ruoyi-modules/ruoyi-system/src/main/resources/mapper/physical/PhysicalAdBannerMapper.xml

@@ -0,0 +1,109 @@
+<?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="org.dromara.physical.mapper.PhysicalAdBannerMapper">
+
+
+
+    <select id="selectAdBannerPage" resultType="org.dromara.physical.domain.vo.PhysicalAdBannerVo">
+        SELECT
+            id,
+            position,
+            image_url,
+            link_url,
+            sort_order,
+            status,
+            created_at,
+            updated_at
+        FROM physical_ad_banner ${ew.customSqlSegment}
+    </select>
+
+
+
+    <select id="selectAdBannerList" resultType="org.dromara.physical.domain.vo.PhysicalAdBannerVo">
+        SELECT
+            id,
+            position,
+            image_url,
+            link_url,
+            sort_order,
+            status,
+            created_at,
+            updated_at
+        FROM physical_ad_banner ${ew.customSqlSegment}
+    </select>
+
+    <select id="selectAdBannerById" resultType="org.dromara.physical.domain.vo.PhysicalAdBannerVo">
+        SELECT
+            id,
+            position,
+            image_url,
+            link_url,
+            sort_order,
+            status,
+            created_at,
+            updated_at
+        FROM physical_ad_banner  where id = #{id}
+    </select>
+
+    <!-- 插入：校验非空字段（position, image_url 必填） -->
+    <insert id="insertAdBanner" useGeneratedKeys="true" keyProperty="id">
+        INSERT INTO physical_ad_banner (
+            position,
+            image_url,
+            link_url,
+            sort_order,
+            status,
+            created_at,
+            updated_at
+        ) VALUES (
+                     #{banner.position},
+                     #{banner.imageUrl},
+                     #{banner.linkUrl},
+                     #{banner.sortOrder},
+                     #{banner.status},
+                     NOW(),
+                     NOW()
+                 )
+    </insert>
+
+    <!-- 更新：仅更新非空字段，且校验必要字段不为空 -->
+    <update id="updateAdBannerById">
+        UPDATE physical_ad_banner
+        <set>
+            <if test="banner.position != null and banner.position != ''">
+                position = #{banner.position},
+            </if>
+            <if test="banner.imageUrl != null and banner.imageUrl != ''">
+                image_url = #{banner.imageUrl},
+            </if>
+            <if test="banner.linkUrl != null">
+                link_url = #{banner.linkUrl},
+            </if>
+            <if test="banner.sortOrder != null">
+                sort_order = #{banner.sortOrder},
+            </if>
+            <if test="banner.status != null and banner.status != ''">
+                status = #{banner.status},
+            </if>
+            updated_at = NOW()
+        </set>
+        WHERE id = #{banner.id}
+        AND deleted_at IS NULL
+    </update>
+
+
+    <delete id="deleteAdBannerlById">
+        DELETE FROM physical_ad_banner
+        <where>
+            id IN
+            <foreach item="id" collection="ids" open="(" separator="," close=")">
+                <if test="id > 0">
+                    #{id}
+                </if>
+            </foreach>
+        </where>
+    </delete>
+
+</mapper>