# 系统公告功能使用说明

## 功能概述

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

---

## 已实现的功能

### 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调用：

```typescript
// 导入模拟数据函数
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. **启动开发服务器**

```bash
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. **构建部署**

```bash
npm run build
```

---

## 自定义配置

### 修改关闭时间

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

```typescript
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. **在代码中手动调用**

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

```typescript
import { useAnnouncementStore } from '@/stores'

const announcementStore = useAnnouncementStore()

// 打开弹窗
announcementStore.openDialog()
```

### 重置关闭状态

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

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

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

### 查看当前状态

```typescript
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
- 项目文档
- 技术支持团队

---

**祝使用愉快！**