diff --git a/pjcloud-integrated/pjcloud-integrated-biz/NOTICE-EXPIRATION-GUIDE.md b/pjcloud-integrated/pjcloud-integrated-biz/NOTICE-EXPIRATION-GUIDE.md new file mode 100644 index 000000000..955c37aeb --- /dev/null +++ b/pjcloud-integrated/pjcloud-integrated-biz/NOTICE-EXPIRATION-GUIDE.md @@ -0,0 +1,217 @@ +# 通知公告过期时间功能使用指南 + +## 📋 功能概述 + +通知公告系统新增过期时间功能,支持为公告设置具体的过期时间。到期后,公告将自动下架,不再在前端显示,无需手动操作。 + +## ✨ 主要特性 + +- **自动过期**: 支持设置具体过期时间,到期自动下架 +- **灵活配置**: 可选择设置过期时间或永不过期 +- **自动处理**: 系统定时任务自动处理过期公告 +- **智能过滤**: 所有查询接口自动过滤已过期公告 +- **性能优化**: 添加数据库索引,提高查询效率 + +## 🗄️ 数据库变更 + +### 新增字段 +```sql +ALTER TABLE notice ADD COLUMN expire_time DATETIME COMMENT '过期时间,到期后公告自动下架'; +``` + +### 新增索引 +```sql +-- 过期时间索引 +CREATE INDEX idx_notice_expire_time ON notice(expire_time); + +-- 状态+过期时间复合索引 +CREATE INDEX idx_notice_status_expire ON notice(status, expire_time); +``` + +## 🔧 配置说明 + +### 1. 启用定时任务 +在启动类或配置类上添加注解: +```java +@EnableScheduling +``` + +### 2. 定时任务配置 +系统默认每天凌晨2点执行过期处理: +```java +@Scheduled(cron = "0 0 2 * * ?") +``` + +如需调整执行时间,可修改 `NoticeExpirationTask` 中的 cron 表达式。 + +## 💻 使用方法 + +### 1. 创建公告时设置过期时间 + +#### 前端表单示例 +```html +
+ + + + 不设置表示永不过期,设置后到期自动下架 + +
+``` + +#### 后端实体字段 +```java +@Schema(description="过期时间,到期后公告自动下架") +private LocalDateTime expireTime; +``` + +### 2. 过期时间设置建议 + +#### 短期公告(1-7天) +- 活动通知 +- 临时维护公告 +- 节日祝福 + +#### 中期公告(1-30天) +- 功能更新通知 +- 政策变更公告 +- 培训通知 + +#### 长期公告(30天以上) +- 规章制度 +- 长期政策 +- 重要通知 + +#### 永不过期 +- 系统说明文档 +- 基础操作指南 +- 重要规章制度 + +## 🔍 查询逻辑 + +### 自动过滤规则 +所有查询接口都会自动过滤已过期公告: + +```java +// 过滤已过期的公告 +wrapper.and(w -> w.isNull(NoticeEntity::getExpireTime) + .or() + .gt(NoticeEntity::getExpireTime, LocalDateTime.now())); +``` + +### 查询逻辑说明 +- `expireTime IS NULL`: 永不过期的公告 +- `expireTime > NOW()`: 未过期的公告 +- `expireTime <= NOW()`: 已过期的公告(自动过滤) + +## ⏰ 定时任务详情 + +### 执行时间 +- **频率**: 每天执行一次 +- **时间**: 凌晨2点(可配置) +- **时区**: 系统默认时区 + +### 处理逻辑 +1. 查询已过期但状态仍为"已发布"的公告 +2. 批量更新状态为"已下架" +3. 记录处理日志 +4. 异常处理和错误日志 + +### 日志示例 +``` +2025-01-27 02:00:00 INFO - 开始执行通知公告过期处理任务 +2025-01-27 02:00:01 INFO - 发现 3 条过期公告,开始处理 +2025-01-27 02:00:01 INFO - 公告 [系统维护通知] 已过期,状态已更新为已下架 +2025-01-27 02:00:01 INFO - 通知公告过期处理任务执行完成,共处理 3 条过期公告 +``` + +## 🚀 性能优化 + +### 数据库索引 +- 过期时间字段索引,提高过期查询性能 +- 状态+过期时间复合索引,优化常用查询 + +### 查询优化 +- 使用 MyBatis-Plus 的 Lambda 查询 +- 批量更新过期公告状态 +- 避免 N+1 查询问题 + +## 📊 监控和维护 + +### 1. 日志监控 +- 定时任务执行日志 +- 过期公告处理数量 +- 异常错误日志 + +### 2. 数据统计 +```sql +-- 统计过期公告数量 +SELECT COUNT(*) FROM notice +WHERE expire_time IS NOT NULL +AND expire_time <= NOW() +AND status = '0'; + +-- 统计即将过期的公告 +SELECT COUNT(*) FROM notice +WHERE expire_time IS NOT NULL +AND expire_time BETWEEN NOW() AND DATE_ADD(NOW(), INTERVAL 7 DAY) +AND status = '0'; +``` + +### 3. 定期维护 +- 清理过期的过期时间记录 +- 监控定时任务执行情况 +- 优化数据库查询性能 + +## ⚠️ 注意事项 + +### 1. 时区问题 +- 确保系统时区设置正确 +- 过期时间以系统时区为准 +- 考虑跨时区部署的情况 + +### 2. 性能考虑 +- 大量公告时,定时任务执行时间可能较长 +- 建议在业务低峰期执行 +- 监控数据库性能影响 + +### 3. 数据一致性 +- 定时任务执行期间,公告状态可能短暂不一致 +- 查询接口始终过滤过期公告,保证显示一致性 +- 建议在定时任务执行期间避免重要操作 + +## 🔧 故障排除 + +### 1. 定时任务未执行 +**检查项**: +- 是否启用 `@EnableScheduling` +- 定时任务类是否被 Spring 管理 +- cron 表达式是否正确 +- 系统时间是否正确 + +### 2. 过期公告仍显示 +**检查项**: +- 过期时间字段是否正确设置 +- 数据库索引是否创建 +- 查询逻辑是否正确 +- 定时任务是否正常执行 + +### 3. 性能问题 +**优化建议**: +- 检查数据库索引使用情况 +- 优化查询语句 +- 调整定时任务执行时间 +- 考虑分页处理大量数据 + +## 📞 技术支持 + +如遇到问题,请联系技术支持并提供以下信息: +- 错误日志 +- 数据库表结构 +- 定时任务配置 +- 系统环境信息 + +--- + +*最后更新时间: 2025-01-27* +*版本: v1.0* \ No newline at end of file diff --git a/pjcloud-integrated/pjcloud-integrated-biz/src/main/java/com/bsd/pjcloud/integrated/config/SchedulingConfig.java b/pjcloud-integrated/pjcloud-integrated-biz/src/main/java/com/bsd/pjcloud/integrated/config/SchedulingConfig.java new file mode 100644 index 000000000..bc4ba7981 --- /dev/null +++ b/pjcloud-integrated/pjcloud-integrated-biz/src/main/java/com/bsd/pjcloud/integrated/config/SchedulingConfig.java @@ -0,0 +1,16 @@ +package com.bsd.pjcloud.integrated.config; + +import org.springframework.context.annotation.Configuration; +import org.springframework.scheduling.annotation.EnableScheduling; + +/** + * 定时任务配置 + * 启用定时任务功能,支持通知公告自动过期处理 + * + * @author zjf + * @date 2025-01-27 + */ +@Configuration +@EnableScheduling +public class SchedulingConfig { +} \ No newline at end of file diff --git a/pjcloud-integrated/pjcloud-integrated-biz/src/main/java/com/bsd/pjcloud/integrated/task/NoticeExpirationTask.java b/pjcloud-integrated/pjcloud-integrated-biz/src/main/java/com/bsd/pjcloud/integrated/task/NoticeExpirationTask.java new file mode 100644 index 000000000..a666bd56e --- /dev/null +++ b/pjcloud-integrated/pjcloud-integrated-biz/src/main/java/com/bsd/pjcloud/integrated/task/NoticeExpirationTask.java @@ -0,0 +1,65 @@ +package com.bsd.pjcloud.integrated.task; + +import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper; +import com.baomidou.mybatisplus.core.toolkit.Wrappers; +import com.bsd.pjcloud.integrated.entity.NoticeEntity; +import com.bsd.pjcloud.integrated.service.NoticeService; +import lombok.RequiredArgsConstructor; +import lombok.extern.slf4j.Slf4j; +import org.springframework.scheduling.annotation.Scheduled; +import org.springframework.stereotype.Component; + +import java.time.LocalDateTime; +import java.util.List; + +/** + * 通知公告过期处理定时任务 + * 自动将过期的公告状态设置为已下架 + * + * @author zjf + * @date 2025-01-27 + */ +@Slf4j +@Component +@RequiredArgsConstructor +public class NoticeExpirationTask { + + private final NoticeService noticeService; + + /** + * 每天凌晨2点执行,处理过期的公告 + */ + @Scheduled(cron = "0 0 2 * * ?") + public void handleExpiredNotices() { + log.info("开始执行通知公告过期处理任务"); + + try { + // 查询已过期但状态仍为已发布的公告 + LambdaQueryWrapper wrapper = Wrappers.lambdaQuery(); + wrapper.eq(NoticeEntity::getStatus, "0") // 状态为已发布 + .lt(NoticeEntity::getExpireTime, LocalDateTime.now()) // 过期时间小于当前时间 + .isNotNull(NoticeEntity::getExpireTime); // 过期时间不为空 + + List expiredNotices = noticeService.list(wrapper); + + if (expiredNotices.isEmpty()) { + log.info("没有发现过期的公告"); + return; + } + + log.info("发现 {} 条过期公告,开始处理", expiredNotices.size()); + + // 批量更新过期公告状态为已下架 + for (NoticeEntity notice : expiredNotices) { + notice.setStatus("1"); // 设置为已下架 + noticeService.updateById(notice); + log.info("公告 [{}] 已过期,状态已更新为已下架", notice.getTitle()); + } + + log.info("通知公告过期处理任务执行完成,共处理 {} 条过期公告", expiredNotices.size()); + + } catch (Exception e) { + log.error("执行通知公告过期处理任务时发生错误", e); + } + } +} \ No newline at end of file diff --git a/pjcloud-integrated/pjcloud-integrated-biz/src/main/resources/db/migration/V1.0.1__add_expire_time_to_notice.sql b/pjcloud-integrated/pjcloud-integrated-biz/src/main/resources/db/migration/V1.0.1__add_expire_time_to_notice.sql new file mode 100644 index 000000000..8ae398c69 --- /dev/null +++ b/pjcloud-integrated/pjcloud-integrated-biz/src/main/resources/db/migration/V1.0.1__add_expire_time_to_notice.sql @@ -0,0 +1,12 @@ +-- 为通知公告表添加过期时间字段 +-- 版本: V1.0.1 +-- 描述: 添加过期时间字段,支持公告自动过期功能 + +ALTER TABLE notice ADD COLUMN expire_time DATETIME COMMENT '过期时间,到期后公告自动下架'; + +-- 添加索引以提高查询性能 +CREATE INDEX idx_notice_expire_time ON notice(expire_time); +CREATE INDEX idx_notice_status_expire ON notice(status, expire_time); + +-- 更新现有公告的过期时间为空(表示永不过期) +UPDATE notice SET expire_time = NULL WHERE expire_time IS NULL; \ No newline at end of file