# 外部系统滚动通知接口集成指南

## 📋 概述

本文档介绍如何集成使用 PJCloud 系统的滚动通知接口，该接口提供安全的 API 访问，供外部系统获取滚动通知信息。

## 🔐 认证方式

接口采用 **AppId + AppSecret** 的认证方式，通过 HTTP 请求头进行身份验证。

### 认证参数

| 参数名 | 位置 | 必填 | 说明 |
|--------|------|------|------|
| X-App-Id | 请求头 | 是 | 应用ID，由系统管理员分配 |
| X-App-Secret | 请求头 | 是 | 应用密钥，由系统管理员分配 |

## 🌐 接口信息

### 滚动通知接口

- **接口地址**: `GET /notice/external/scroll`
- **请求方式**: GET
- **认证方式**: 请求头认证
- **数据格式**: JSON

### 请求参数

#### 查询参数
| 参数名 | 必填 | 默认值 | 说明 |
|--------|------|--------|------|
| limit | 否 | 20 | 返回条数，最大50条 |

#### 请求头示例
```http
X-App-Id: 202501270001
X-App-Secret: 550e8400-e29b-41d4-a716-446655440001
```

## 📡 响应格式

### 成功响应
```json
{
  "code": 0,
  "msg": "操作成功",
  "data": [
    {
      "id": 1,
      "title": "系统维护通知",
      "createTime": "2025-01-27 10:00:00",
      "description": "系统将于今晚进行维护升级"
    },
    {
      "id": 2,
      "title": "新功能上线",
      "createTime": "2025-01-26 15:30:00",
      "description": "新增用户管理功能模块"
    }
  ]
}
```

### 错误响应
```json
{
  "code": 500,
  "msg": "无效的应用ID或密钥",
  "data": null
}
```

## ⏰ 过期时间功能

系统支持为公告设置过期时间，到期后公告将自动下架不再显示：

- **过期时间字段**: `expireTime`
- **自动处理**: 每天凌晨2点自动检查并处理过期公告
- **处理逻辑**: 过期公告状态自动更新为"已下架"
- **查询过滤**: 所有查询接口自动过滤已过期公告
- **灵活设置**: 支持设置具体过期时间，也支持永不过期（不设置过期时间）

## 💻 集成示例

### JavaScript 调用示例

#### 基础调用
```javascript
// 获取滚动通知
async function getScrollNotices(limit = 20) {
  try {
    const response = await fetch('/notice/external/scroll?limit=' + limit, {
      method: 'GET',
      headers: {
        'X-App-Id': '202501270001',
        'X-App-Secret': '550e8400-e29b-41d4-a716-446655440001',
        'Content-Type': 'application/json'
      }
    });
    
    const result = await response.json();
    
    if (result.code === 0) {
      return result.data;
    } else {
      throw new Error(result.msg);
    }
  } catch (error) {
    console.error('获取通知失败:', error);
    throw error;
  }
}

// 使用示例
getScrollNotices(15)
  .then(notices => {
    console.log('获取到通知:', notices);
    // 处理通知数据
    displayNotices(notices);
  })
  .catch(error => {
    console.error('错误:', error.message);
  });
```

#### 滚动展示组件
```javascript
// 滚动通知展示组件
class ScrollNoticeDisplay {
  constructor(containerId, appId, appSecret) {
    this.container = document.getElementById(containerId);
    this.appId = appId;
    this.appSecret = appSecret;
    this.notices = [];
    this.currentIndex = 0;
    this.interval = null;
  }
  
  // 获取通知数据
  async fetchNotices() {
    try {
      const response = await fetch('/notice/external/scroll?limit=10', {
        headers: {
          'X-App-Id': this.appId,
          'X-App-Secret': this.appSecret
        }
      });
      
      const result = await response.json();
      if (result.code === 0) {
        this.notices = result.data;
        this.startScroll();
      }
    } catch (error) {
      console.error('获取通知失败:', error);
    }
  }
  
  // 开始滚动
  startScroll() {
    if (this.notices.length === 0) return;
    
    this.interval = setInterval(() => {
      this.showNextNotice();
    }, 3000); // 每3秒切换一次
    
    this.showNextNotice(); // 立即显示第一条
  }
  
  // 显示下一条通知
  showNextNotice() {
    if (this.notices.length === 0) return;
    
    const notice = this.notices[this.currentIndex];
    this.container.innerHTML = `
      <div class="notice-item">
        <span class="notice-title">${notice.title}</span>
        <span class="notice-time">${notice.createTime}</span>
      </div>
    `;
    
    this.currentIndex = (this.currentIndex + 1) % this.notices.length;
  }
  
  // 停止滚动
  stopScroll() {
    if (this.interval) {
      clearInterval(this.interval);
      this.interval = null;
    }
  }
}

// 使用示例
const noticeDisplay = new ScrollNoticeDisplay(
  'notice-container', 
  '202501270001', 
  '550e8400-e29b-41d4-a716-446655440001'
);

noticeDisplay.fetchNotices();
```

### cURL 调用示例

#### 基础调用
```bash
curl -X GET "http://your-domain/notice/external/scroll?limit=15" \
  -H "X-App-Id: 202501270001" \
  -H "X-App-Secret: 550e8400-e29b-41d4-a716-446655440001"
```

#### 获取最大条数
```bash
curl -X GET "http://your-domain/notice/external/scroll?limit=50" \
  -H "X-App-Id: 202501270001" \
  -H "X-App-Secret: 550e8400-e29b-41d4-a716-446655440001"
```

### Java 调用示例

```java
import org.springframework.http.HttpHeaders;
import org.springframework.http.HttpEntity;
import org.springframework.http.HttpMethod;
import org.springframework.http.ResponseEntity;
import org.springframework.web.client.RestTemplate;

public class NoticeApiClient {
    
    private final String baseUrl;
    private final String appId;
    private final String appSecret;
    private final RestTemplate restTemplate;
    
    public NoticeApiClient(String baseUrl, String appId, String appSecret) {
        this.baseUrl = baseUrl;
        this.appId = appId;
        this.appSecret = appSecret;
        this.restTemplate = new RestTemplate();
    }
    
    public List<NoticeScreenVo> getScrollNotices(int limit) {
        HttpHeaders headers = new HttpHeaders();
        headers.set("X-App-Id", appId);
        headers.set("X-App-Secret", appSecret);
        
        HttpEntity<String> entity = new HttpEntity<>(headers);
        
        String url = baseUrl + "/notice/external/scroll?limit=" + limit;
        
        ResponseEntity<ApiResponse> response = restTemplate.exchange(
            url, 
            HttpMethod.GET, 
            entity, 
            ApiResponse.class
        );
        
        if (response.getBody() != null && response.getBody().getCode() == 0) {
            return response.getBody().getData();
        }
        
        throw new RuntimeException("获取通知失败");
    }
}

// 使用示例
NoticeApiClient client = new NoticeApiClient(
    "http://your-domain", 
    "202501270001", 
    "550e8400-e29b-41d4-a716-446655440001"
);

List<NoticeScreenVo> notices = client.getScrollNotices(20);
```

## 🎨 CSS 样式示例

```css
/* 滚动通知容器 */
.notice-container {
  width: 100%;
  height: 40px;
  background: linear-gradient(90deg, #f8f9fa, #e9ecef);
  border: 1px solid #dee2e6;
  border-radius: 4px;
  overflow: hidden;
  position: relative;
}

/* 通知项 */
.notice-item {
  display: flex;
  justify-content: space-between;
  align-items: center;
  padding: 8px 16px;
  height: 100%;
  animation: slideIn 0.5s ease-in-out;
}

/* 通知标题 */
.notice-title {
  font-weight: 500;
  color: #495057;
  flex: 1;
  white-space: nowrap;
  overflow: hidden;
  text-overflow: ellipsis;
}

/* 通知时间 */
.notice-time {
  font-size: 12px;
  color: #6c757d;
  margin-left: 16px;
}

/* 滑动动画 */
@keyframes slideIn {
  from {
    transform: translateX(100%);
    opacity: 0;
  }
  to {
    transform: translateX(0);
    opacity: 1;
  }
}

/* 响应式设计 */
@media (max-width: 768px) {
  .notice-container {
    height: 50px;
  }
  
  .notice-item {
    padding: 12px 16px;
  }
  
  .notice-time {
    display: none; /* 移动端隐藏时间 */
  }
}
```

## ⚠️ 注意事项

### 安全要求
1. **密钥保护**: 请妥善保管 AppSecret，不要泄露给第三方
2. **HTTPS 传输**: 建议使用 HTTPS 协议进行数据传输
3. **访问频率**: 建议控制调用频率，避免频繁请求

### 技术限制
1. **返回条数**: 单次请求最多返回 50 条通知
2. **数据时效**: 只返回已发布的公告信息
3. **排序规则**: 按置顶状态和创建时间倒序排列

### 错误处理
1. **认证失败**: 检查 AppId 和 AppSecret 是否正确
2. **网络异常**: 实现重试机制和超时处理
3. **数据异常**: 对返回数据进行有效性验证

## 🔧 故障排除

### 常见问题

#### 1. 认证失败
**错误信息**: "无效的应用ID或密钥"
**解决方案**: 
- 检查 AppId 和 AppSecret 是否正确
- 确认应用是否已启用
- 联系系统管理员验证配置

#### 2. 网络超时
**错误信息**: 请求超时或无响应
**解决方案**:
- 检查网络连接
- 确认服务器地址是否正确
- 实现请求超时和重试机制

#### 3. 数据为空
**可能原因**:
- 当前没有已发布的公告
- 查询参数设置不当
- 系统维护中

## 📞 技术支持

如果在集成过程中遇到问题，请联系技术支持：

- **技术文档**: 本文档
- **API 地址**: `/notice/external/scroll`
- **认证方式**: AppId + AppSecret
- **数据格式**: JSON

---

*最后更新时间: 2025-01-27*
*版本: v1.0*