387 lines
8.7 KiB
Markdown
387 lines
8.7 KiB
Markdown
# 外部系统滚动通知接口集成指南
|
|
|
|
## 📋 概述
|
|
|
|
本文档介绍如何集成使用 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": [
|
|
{
|
|
"title": "系统维护通知",
|
|
"createTime": "2025-01-27 10:00:00",
|
|
"description": "系统将于今晚进行维护升级"
|
|
},
|
|
{
|
|
"title": "新功能上线",
|
|
"createTime": "2025-01-26 15:30:00",
|
|
"description": "新增用户管理功能模块"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
### 错误响应
|
|
```json
|
|
{
|
|
"code": 500,
|
|
"msg": "无效的应用ID或密钥",
|
|
"data": null
|
|
}
|
|
```
|
|
|
|
## 💻 集成示例
|
|
|
|
### 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* |