📡 SmartCampus API 文档

概述

本文档定义 SmartCampus 应用使用的所有 API 接口。所有 API 接口的实现均位于 src/services/api.js。

API 配置

基础配置

// src/services/api.js
const baseUrl = 'https://api.example.com';
const timeout = 5000;

认证方式

所有请求应在 Header 中包含认证信息：

headers: {
  'Authorization': `Bearer ${token}`,
  'Content-Type': 'application/json'
}

用户 API

获取用户信息

userApi.getUserInfo()

请求方式： GET

端点： /user/info

参数： 无

响应示例：

{
  "code": 0,
  "message": "success",
  "data": {
    "id": "123",
    "name": "张三",
    "email": "zhangsan@example.com",
    "role": "admin",
    "avatar": "https://example.com/avatar.jpg",
    "department": "校园管理部"
  }
}

使用示例：

import { userApi } from '/src/services/api';

Page({
  onLoad() {
    userApi.getUserInfo()
      .then(data => {
        this.setData({ userInfo: data });
      })
      .catch(err => console.error(err));
  }
});

告警 API

获取告警列表

alarmApi.getAlarmList(options)

请求方式： GET

端点： /alarm/list

参数：

参数名	类型	必需	默认值	说明
`page`	Number	否	1	页码
`pageSize`	Number	否	20	每页数量
`status`	String	否	-	告警状态（all/active/resolved）
`type`	String	否	-	告警类型

响应示例：

{
  "code": 0,
  "message": "success",
  "data": {
    "total": 100,
    "page": 1,
    "pageSize": 20,
    "list": [
      {
        "id": "alarm_001",
        "title": "能源系统异常",
        "type": "energy",
        "status": "active",
        "level": "high",
        "description": "南校区电力供应异常",
        "location": "南校区主楼",
        "createTime": "2026-02-05T10:00:00Z",
        "updateTime": "2026-02-05T11:00:00Z"
      }
    ]
  }
}

获取告警详情

alarmApi.getAlarmDetail(alarmId)

请求方式： GET

端点： /alarm/{id}

参数：

参数名	类型	说明
`id`	String	告警 ID

响应示例：

{
  "code": 0,
  "message": "success",
  "data": {
    "id": "alarm_001",
    "title": "能源系统异常",
    "type": "energy",
    "status": "active",
    "level": "high",
    "description": "南校区电力供应异常",
    "location": "南校区主楼",
    "rootCause": "变压器故障",
    "solution": "已发送维修人员，预计2小时内修复",
    "attachments": [
      {
        "id": "att_001",
        "name": "故障现场照片.jpg",
        "url": "https://example.com/attachments/photo_001.jpg"
      }
    ],
    "createTime": "2026-02-05T10:00:00Z",
    "updateTime": "2026-02-05T11:00:00Z"
  }
}

更新告警状态

alarmApi.updateAlarmStatus(alarmId, status)

请求方式： PUT

端点： /alarm/{id}/status

参数：

参数名	类型	说明
`id`	String	告警 ID
`status`	String	新状态（resolved/ignored）

响应示例：

{
  "code": 0,
  "message": "success",
  "data": {
    "id": "alarm_001",
    "status": "resolved",
    "updateTime": "2026-02-05T12:00:00Z"
  }
}

图表 API

获取图表列表

chartApi.getChartList(page = 1)

请求方式： GET

端点： /chart/list

参数：

参数名	类型	说明
`page`	Number	页码

响应示例：

{
  "code": 0,
  "message": "success",
  "data": {
    "total": 10,
    "list": [
      {
        "id": "chart_001",
        "title": "校园日能耗",
        "type": "line",
        "category": "energy",
        "description": "显示校园每日能耗趋势",
        "thumbnail": "https://example.com/preview/chart_001.png"
      }
    ]
  }
}

获取图表数据

chartApi.getChartData(chartId, timeRange)

请求方式： GET

端点： /chart/{id}/data

参数：

参数名	类型	说明
`id`	String	图表 ID
`startDate`	String	开始日期（YYYY-MM-DD）
`endDate`	String	结束日期（YYYY-MM-DD）

响应示例：

{
  "code": 0,
  "message": "success",
  "data": {
    "chartId": "chart_001",
    "chartType": "line",
    "series": [
      {
        "name": "能耗（度）",
        "data": [100, 105, 102, 108, 110, 115, 120]
      }
    ],
    "xAxis": {
      "data": ["2026-02-01", "2026-02-02", "2026-02-03", "2026-02-04", "2026-02-05", "2026-02-06", "2026-02-07"]
    },
    "yAxis": {
      "name": "能耗（度）",
      "type": "value"
    }
  }
}

获取图表详情

chartApi.getChartDetail(chartId)

请求方式： GET

端点： /chart/{id}

参数：

参数名	类型	说明
`id`	String	图表 ID

响应示例：

{
  "code": 0,
  "message": "success",
  "data": {
    "id": "chart_001",
    "title": "校园日能耗",
    "description": "显示校园每日能耗趋势",
    "type": "line",
    "category": "energy",
    "updateFrequency": "daily",
    "lastUpdateTime": "2026-02-05T23:59:59Z",
    "owner": "能源中心",
    "permissions": ["view", "export"],
    "relatedAlerts": [
      {
        "id": "alarm_001",
        "title": "能耗异常"
      }
    ]
  }
}

工单 API

获取工单列表

ticketApi.getTicketList(options)

请求方式： GET

端点： /ticket/list

参数：

参数名	类型	说明
`page`	Number	页码
`status`	String	工单状态（open/in-progress/closed/all）
`type`	String	工单类型

响应示例：

{
  "code": 0,
  "message": "success",
  "data": {
    "total": 50,
    "page": 1,
    "list": [
      {
        "id": "ticket_001",
        "title": "教室空调故障",
        "status": "open",
        "priority": "high",
        "type": "maintenance",
        "createdBy": "李四",
        "createTime": "2026-02-05T09:00:00Z",
        "location": "教学楼A-101"
      }
    ]
  }
}

获取工单详情

ticketApi.getTicketDetail(ticketId)

请求方式： GET

端点： /ticket/{id}

响应示例：

{
  "code": 0,
  "message": "success",
  "data": {
    "id": "ticket_001",
    "title": "教室空调故障",
    "description": "教室里的空调无法正常工作",
    "status": "open",
    "priority": "high",
    "type": "maintenance",
    "createdBy": "李四",
    "createTime": "2026-02-05T09:00:00Z",
    "location": "教学楼A-101",
    "estimatedTime": "1d",
    "comments": [
      {
        "id": "comment_001",
        "author": "维修员",
        "content": "已上门检查，明天进行维修",
        "createTime": "2026-02-05T10:00:00Z"
      }
    ]
  }
}

创建工单

ticketApi.createTicket(data)

请求方式： POST

端点： /ticket

参数：

参数名	类型	必需	说明
`title`	String	是	工单标题
`description`	String	是	详细描述
`type`	String	是	工单类型
`priority`	String	是	优先级（low/medium/high）
`location`	String	是	位置
`attachments`	Array	否	附件（文件 URL 数组）

请求示例：

const ticketData = {
  title: "宿舍电路故障",
  description: "宿舍603号房间B插座没有电",
  type: "maintenance",
  priority: "high",
  location: "学生宿舍6号楼603"
};

ticketApi.createTicket(ticketData)
  .then(res => console.log('工单创建成功', res))
  .catch(err => console.error('创建失败', err));

响应示例：

{
  "code": 0,
  "message": "success",
  "data": {
    "id": "ticket_002",
    "title": "宿舍电路故障",
    "status": "open",
    "createdBy": "user_123",
    "createTime": "2026-02-05T14:00:00Z"
  }
}

更新工单状态

ticketApi.updateTicketStatus(ticketId, status)

请求方式： PUT

端点： /ticket/{id}/status

响应示例：

{
  "code": 0,
  "message": "success",
  "data": {
    "id": "ticket_001",
    "status": "closed",
    "updateTime": "2026-02-05T15:00:00Z"
  }
}

添加工单评论

ticketApi.addTicketComment(ticketId, comment)

请求方式： POST

端点： /ticket/{id}/comments

参数：

{
  "content": "评论内容",
  "attachments": ["url1", "url2"]
}

错误处理

错误响应格式

所有错误响应均遵循以下格式：

{
  "code": 400,
  "message": "错误描述信息",
  "details": {
    "field": "field_name",
    "issue": "validation_error"
  }
}

常见错误码

错误码	含义	处理方式
200	成功	-
400	请求参数错误	检查请求参数
401	未认证/Token 过期	重新登录
403	没有权限	提示用户权限不足
404	资源不存在	提示资源已删除
500	服务器错误	稍后重试
503	服务不可用	稍后重试

错误处理最佳实践

async function makeRequest() {
  try {
    const response = await api.getData();
    return response;
  } catch (error) {
    if (error.code === 401) {
      // 重新登录
      wx.navigateTo({ url: '/src/pages/login/login' });
    } else if (error.code === 500) {
      // 显示错误提示
      wx.showToast({
        title: '服务错误，请稍后重试',
        icon: 'error'
      });
    }
    throw error;
  }
}

请求示例

示例 1：获取告警列表

import { alarmApi } from '/src/services/api';

Page({
  onLoad() {
    this.loadAlarms();
  },
  
  loadAlarms() {
    alarmApi.getAlarmList({ page: 1 })
      .then(response => {
        this.setData({
          alarms: response.list,
          total: response.total
        });
      })
      .catch(error => {
        wx.showToast({
          title: '加载失败',
          icon: 'error'
        });
        console.error('加载告警失败:', error);
      });
  }
});

示例 2：创建工单

import { ticketApi } from '/src/services/api';

Page({
  data: {
    form: {
      title: '',
      description: '',
      type: 'maintenance',
      priority: 'medium',
      location: ''
    }
  },
  
  submitForm() {
    if (!this.validateForm()) {
      return;
    }
    
    ticketApi.createTicket(this.data.form)
      .then(result => {
        wx.showToast({
          title: '工单创建成功',
          icon: 'success'
        });
        // 返回列表页面
        wx.navigateBack();
      })
      .catch(error => {
        wx.showToast({
          title: '创建失败，请重试',
          icon: 'error'
        });
      });
  },
  
  validateForm() {
    const { title, description, location } = this.data.form;
    if (!title || !description || !location) {
      wx.showToast({
        title: '请填写必填项',
        icon: 'error'
      });
      return false;
    }
    return true;
  }
});

更新日志

2026-02-05 - API 文档初版发布

文档版本： v1.0
最后更新： 2026年2月5日

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

📡 SmartCampus API 文档

概述

目录

API 配置

基础配置

认证方式

用户 API

获取用户信息

告警 API

获取告警列表

获取告警详情

更新告警状态

图表 API

获取图表列表

获取图表数据

获取图表详情

工单 API

获取工单列表

获取工单详情

创建工单

更新工单状态

添加工单评论

错误处理

错误响应格式

常见错误码

错误处理最佳实践

请求示例

示例 1：获取告警列表

示例 2：创建工单

更新日志

FilesExpand file tree

API.md

Latest commit

History

API.md

File metadata and controls

📡 SmartCampus API 文档

概述

目录

API 配置

基础配置

认证方式

用户 API

获取用户信息

告警 API

获取告警列表

获取告警详情

更新告警状态

图表 API

获取图表列表

获取图表数据

获取图表详情

工单 API

获取工单列表

获取工单详情

创建工单

更新工单状态

添加工单评论

错误处理

错误响应格式

常见错误码

错误处理最佳实践

请求示例

示例 1：获取告警列表

示例 2：创建工单

更新日志