pj_service_cloud/pjcloud-integrated/pjcloud-integrated-biz/API-INTEGRATION-GUIDE.md

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

📋 概述

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

🔐 认证方式

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

认证参数

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

🌐 接口信息

滚动通知接口

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

请求参数

查询参数

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

请求头示例

X-App-Id: 202501270001
X-App-Secret: 550e8400-e29b-41d4-a716-446655440001

📡 响应格式

成功响应

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

错误响应

{
  "code": 500,
  "msg": "无效的应用ID或密钥",
  "data": null
}

💻 集成示例

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);
  });

滚动展示组件

// 滚动通知展示组件
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 调用示例

基础调用

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"

获取最大条数

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 调用示例

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 样式示例

/* 滚动通知容器 */
.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