Yi.Framework/Yi.Ai.Vue3/系统公告功能使用说明.md

系统公告功能使用说明

功能概述

本次更新为项目添加了完整的系统公告弹窗功能，包括活动展示、公告通知、轮播图等。用户可以通过不同的关闭选项来控制弹窗的显示频率。

---

已实现的功能

1. 系统公告弹窗

• 自动弹出: 用户进入应用时自动检测并显示公告弹窗
• 手动打开: 右上角有公告按钮（铃铛图标），随时可以点击打开公告弹窗
• 未读提示: 公告按钮上显示红色徽章，标识最新公告数量
• Tab切换: 支持"活动"和"公告"两个Tab页面
• 关闭选项: 提供三种关闭方式
  • 今日关闭：24小时内不再自动弹出，但仍可通过按钮手动打开
  • 本周关闭：7天内不再自动弹出，但仍可通过按钮手动打开
  • 关闭公告：永久不再自动弹出（除非清除浏览器缓存），但仍可通过按钮手动打开

2. 活动页面

• 轮播图: 顶部展示活动轮播图，支持自动播放
• 活动列表: 显示所有活动，包含标题、简介、状态标签
• 状态标识:
  • 进行中：绿色标签
  • 已结束：灰色标签
• 查看详情: 点击可跳转到活动详情页面

3. 公告页面

• 最新公告: 顶部显示最新发布的公告，带蓝色边框高亮
• 重要标识: 重要公告显示警告图标
• 历史公告: 使用时间线形式展示历史公告
• 查看详情: 点击可跳转到公告详情页面

4. 详情页面

活动详情页面

• 活动标题和状态
• 浏览次数和参与人数
• 活动封面图
• 活动简介
• 活动时间信息（开始、结束、发布、更新时间）
• 完整的活动内容（支持HTML格式）

公告详情页面

• 公告标题和类型
• 重要公告标识（带动画效果）
• 浏览次数
• 发布时间
• 完整的公告内容（支持HTML格式）
• 创建和更新时间

---

文件结构

Yi.Ai.Vue3/
├── src/
│   ├── api/
│   │   └── announcement/
│   │       ├── index.ts          # API接口定义
│   │       └── types.ts          # TypeScript类型定义
│   ├── components/
│   │   └── SystemAnnouncementDialog/
│   │       └── index.vue         # 系统公告弹窗组件
│   ├── layouts/
│   │   └── components/
│   │       └── Header/
│   │           ├── components/
│   │           │   └── AnnouncementBtn.vue  # 公告按钮组件（新增）
│   │           └── index.vue     # Header组件（已更新）
│   ├── pages/
│   │   ├── activity/
│   │   │   └── detail.vue        # 活动详情页面
│   │   └── announcement/
│   │       └── detail.vue        # 公告详情页面
│   ├── stores/
│   │   └── modules/
│   │       └── announcement.ts   # 公告状态管理
│   ├── data/
│   │   └── mockAnnouncementData.ts  # 模拟数据
│   ├── routers/
│   │   └── modules/
│   │       └── staticRouter.ts   # 路由配置（已更新）
│   ├── utils/
│   │   └── request.ts            # HTTP请求工具（已修复Pinia初始化问题）
│   └── App.vue                   # 主应用文件（已更新）
├── 系统公告API接口文档.md          # API接口文档
└── 系统公告功能使用说明.md          # 本文档

---

如何使用

开发环境测试（使用模拟数据）

1. 导入模拟数据

在 src/App.vue 中临时替换API调用：

// 导入模拟数据函数
import { getMockSystemAnnouncements } from '@/data/mockAnnouncementData'

// 替换 getSystemAnnouncements() 为 getMockSystemAnnouncements()
onMounted(async () => {
  if (announcementStore.shouldShowDialog) {
    try {
      // 使用模拟数据
      const res = await getMockSystemAnnouncements()
      if (res.data) {
        announcementStore.setAnnouncementData(res.data)
        announcementStore.openDialog()
      }
    }
    catch (error) {
      console.error('获取系统公告失败:', error)
    }
  }
})

2. 同样的方式更新详情页面

在 src/pages/activity/detail.vue 和 src/pages/announcement/detail.vue 中也可以使用模拟数据函数进行测试。

3. 启动开发服务器

npm run dev

4. 测试功能

• 打开浏览器访问应用
• 应该会自动弹出系统公告弹窗
• 测试不同的关闭选项
• 点击"查看详情"按钮测试跳转

生产环境部署（使用真实API）

1. 后端实现API接口

参考 系统公告API接口文档.md 实现以下三个接口：

• GET /announcement/system - 获取系统公告数据
• GET /announcement/activity/{id} - 获取活动详情
• GET /announcement/detail/{id} - 获取公告详情

2. 确认API调用

确保 src/App.vue 和详情页面使用的是真实的API函数（默认配置）：

• getSystemAnnouncements()
• getActivityDetail(id)
• getAnnouncementDetail(id)

3. 构建部署

npm run build

---

自定义配置

修改关闭时间

在 src/stores/modules/announcement.ts 中修改时间计算逻辑：

const shouldShowDialog = computed(() => {
  // ... 现有代码

  if (closeType.value === 'today') {
    // 修改为其他时间，如12小时
    return elapsed > 12 * 60 * 60 * 1000
  }

  if (closeType.value === 'week') {
    // 修改为其他时间，如3天
    return elapsed > 3 * 24 * 60 * 60 * 1000
  }

  // ... 现有代码
})

修改弹窗样式

在 src/components/SystemAnnouncementDialog/index.vue 中修改样式：

• 修改弹窗宽度：width="700px" 改为其他值
• 修改轮播图高度：height="250px" 改为其他值
• 修改CSS样式：在 <style> 部分进行调整

添加新的Tab页

1. 在弹窗组件中添加新的 <el-tab-pane>
2. 添加对应的数据类型定义
3. 更新API接口和store

---

管理功能

手动触发弹窗

用户可以通过以下方式打开公告弹窗：

1. 点击右上角公告按钮（推荐）

   • 位于Header右侧的铃铛图标
   • 显示未读公告数量的红色徽章
   • 点击即可打开公告弹窗

2. 在代码中手动调用

在任何组件中可以手动打开公告弹窗：

import { useAnnouncementStore } from '@/stores'

const announcementStore = useAnnouncementStore()

// 打开弹窗
announcementStore.openDialog()

重置关闭状态

如果需要重置用户的关闭状态（例如有重要公告需要强制显示）：

// 重置关闭状态
announcementStore.resetCloseStatus()

// 然后重新打开弹窗
announcementStore.openDialog()

查看当前状态

const announcementStore = useAnnouncementStore()

// 查看是否应该显示弹窗
console.log(announcementStore.shouldShowDialog)

// 查看关闭类型
console.log(announcementStore.closeType)

// 查看关闭时间
console.log(announcementStore.closedAt)

---

注意事项

1. XSS防护: 公告和活动内容使用 v-html 渲染，请确保后端返回的HTML内容是安全的，建议进行内容过滤和转义。

2. 图片资源: 轮播图和封面图需要可访问的URL地址，建议使用CDN。

3. 性能优化:

   • 弹窗数据会在应用启动时加载，确保接口响应快速
   • 考虑添加加载状态和错误处理

4. 响应式设计: 当前设计主要针对PC端，如需移动端适配，需要调整样式和布局。

5. 浏览器兼容: 使用了现代CSS特性，建议在主流现代浏览器中使用。

6. 状态持久化: 关闭状态存储在 localStorage 中，清除浏览器缓存会重置状态。

---

后续优化建议

1. 数据统计: 添加打点统计，记录用户查看公告的行为
2. 推送通知: 对重要公告支持浏览器推送通知
3. 多语言支持: 支持国际化（i18n）
4. 个性化推荐: 根据用户兴趣推荐相关活动
5. 评论功能: 允许用户对活动和公告进行评论
6. 分享功能: 支持将活动和公告分享到社交媒体
7. 搜索功能: 添加公告和活动的搜索功能
8. 管理后台: 开发管理后台用于创建和管理公告活动

---

技术栈

• Vue 3.5.17: 核心框架，使用 Composition API
• TypeScript: 类型安全
• Element Plus: UI组件库
• Pinia: 状态管理，支持持久化
• Vue Router 4: 路由管理
• Vite: 构建工具

---

问题排查

弹窗不显示

1. 检查 announcementStore.shouldShowDialog 的值
2. 检查API是否返回数据
3. 查看浏览器控制台是否有错误
4. 尝试调用 announcementStore.resetCloseStatus() 重置状态

详情页面404

1. 确认路由配置是否正确
2. 检查路由名称是否匹配
3. 确认ID参数是否正确传递

样式显示异常

1. 检查Element Plus是否正确安装
2. 确认 SCSS 预处理器是否配置
3. 清除浏览器缓存重试

---

联系支持

如有问题或建议，请通过以下方式联系：

• GitHub Issues
• 项目文档
• 技术支持团队

---

祝使用愉快！