{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "邛崃回澜酒厂威士忌陈酿库监控系统 - API契约（FastBee原生格式）",
  "version": "2.1.0",
  "lastUpdated": "2026-06-06 19:45",
  "baseUrl": "https://fastbee.huilang.com",
  "authentication": {
    "type": "Bearer Token",
    "header": "Authorization",
    "tokenFormat": "Bearer {token}",
    "loginEndpoint": "/login"
  },
  "endpoints": {
    "getDashboardMetrics": {
      "method": "GET",
      "path": "/iot/cellar/dashboard/metrics",
      "description": "获取核心指标（温度/湿度/酒精浓度）统计",
      "request": {
        "headers": {
          "Authorization": { "type": "string", "required": true }
        },
        "query": {
          "floor": { "type": "integer", "enum": [1, 3], "description": "楼层筛选（可选）" }
        }
      },
      "response": {
        "200": {
          "description": "成功",
          "body": {
            "type": "object",
            "properties": {
              "code": { "type": "integer", "example": 200 },
              "msg": { "type": "string", "example": "操作成功" },
              "data": {
                "type": "object",
                "properties": {
                  "temperature": {
                    "type": "object",
                    "properties": {
                      "avg": { "type": "number", "example": 18.5 },
                      "min": { "type": "number", "example": 17.2 },
                      "max": { "type": "number", "example": 19.8 },
                      "status": { "type": "string", "enum": ["normal", "warning", "danger"], "example": "normal" }
                    }
                  },
                  "humidity": {
                    "type": "object",
                    "properties": {
                      "avg": { "type": "number", "example": 68 },
                      "min": { "type": "number", "example": 65 },
                      "max": { "type": "number", "example": 72 },
                      "status": { "type": "string", "enum": ["normal", "warning"], "example": "normal" }
                    }
                  },
                  "alcohol": {
                    "type": "object",
                    "properties": {
                      "avg": { "type": "number", "example": 65.3 },
                      "min": { "type": "number", "example": 62.1 },
                      "max": { "type": "number", "example": 68.5 },
                      "status": { "type": "string", "enum": ["normal", "warning", "danger"], "example": "normal" }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "getDashboardDeviceStats": {
      "method": "GET",
      "path": "/iot/cellar/dashboard/deviceStats",
      "description": "获取设备统计（空调/温度传感器/酒精探测仪/摄像头）",
      "request": {
        "headers": {
          "Authorization": { "type": "string", "required": true }
        }
      },
      "response": {
        "200": {
          "description": "成功",
          "body": {
            "type": "object",
            "properties": {
              "code": { "type": "integer", "example": 200 },
              "msg": { "type": "string", "example": "操作成功" },
              "data": {
                "type": "object",
                "properties": {
                  "airConditioner": {
                    "type": "object",
                    "properties": {
                      "total": { "type": "integer", "example": 8 },
                      "online": { "type": "integer", "example": 8 },
                      "offline": { "type": "integer", "example": 0 }
                    }
                  },
                  "tempSensor": {
                    "type": "object",
                    "properties": {
                      "total": { "type": "integer", "example": 16 },
                      "online": { "type": "integer", "example": 16 },
                      "offline": { "type": "integer", "example": 0 }
                    }
                  },
                  "alcoholSensor": {
                    "type": "object",
                    "properties": {
                      "total": { "type": "integer", "example": 32 },
                      "online": { "type": "integer", "example": 32 },
                      "offline": { "type": "integer", "example": 0 }
                    }
                  },
                  "camera": {
                    "type": "object",
                    "properties": {
                      "total": { "type": "integer", "example": 36 },
                      "online": { "type": "integer", "example": 36 },
                      "offline": { "type": "integer", "example": 0 }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "listCellarDevice": {
      "method": "GET",
      "path": "/iot/device/cellarList",
      "description": "获取8个陈酿库的监控数据（基于FastBee的listDeviceShort扩展）",
      "request": {
        "headers": {
          "Authorization": { "type": "string", "required": true }
        },
        "query": {
          "floor": { "type": "integer", "enum": [1, 3], "description": "楼层筛选（可选）" },
          "groupId": { "type": "string", "description": "分组ID（可选，对应陈酿库）" }
        }
      },
      "response": {
        "200": {
          "description": "成功",
          "body": {
            "type": "object",
            "properties": {
              "code": { "type": "integer", "example": 200 },
              "msg": { "type": "string", "example": "查询成功" },
              "data": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "cellarId": { "type": "string", "example": "1F-1" },
                    "cellarName": { "type": "string", "example": "1F-1号库" },
                    "floor": { "type": "integer", "example": 1 },
                    "cellarIndex": { "type": "integer", "example": 1 },
                    "alcohol": {
                      "type": "object",
                      "properties": {
                        "value": { "type": "number", "example": 68.5 },
                        "status": { "type": "string", "enum": ["normal", "warning", "danger"], "example": "normal" }
                      }
                    },
                    "temperature": {
                      "type": "object",
                      "properties": {
                        "value": { "type": "number", "example": 19.2 },
                        "status": { "type": "string", "enum": ["normal", "warning", "danger"], "example": "normal" }
                      }
                    },
                    "humidity": {
                      "type": "object",
                      "properties": {
                        "value": { "type": "number", "example": 68 },
                        "status": { "type": "string", "enum": ["normal", "warning"], "example": "normal" }
                      }
                    },
                    "updateTime": { "type": "string", "format": "date-time", "example": "2026-06-06 19:25:00" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "getWeatherCurrent": {
      "method": "GET",
      "path": "/iot/tool/weather/current",
      "description": "获取当前天气（成都）",
      "request": {
        "headers": {
          "Authorization": { "type": "string", "required": true }
        },
        "query": {
          "city": { "type": "string", "default": "成都", "description": "城市名称" }
        }
      },
      "response": {
        "200": {
          "description": "成功",
          "body": {
            "type": "object",
            "properties": {
              "code": { "type": "integer", "example": 200 },
              "msg": { "type": "string", "example": "查询成功" },
              "data": {
                "type": "object",
                "properties": {
                  "city": { "type": "string", "example": "成都" },
                  "weather": { "type": "string", "example": "多云" },
                  "temp": { "type": "number", "example": 22 },
                  "humidity": { "type": "number", "example": 65 },
                  "updateTime": { "type": "string", "format": "date-time", "example": "2026-06-06 19:25:00" }
                }
              }
            }
          }
        }
      }
    },
    "listScene": {
      "method": "GET",
      "path": "/iot/scene/list",
      "description": "查询场景联动列表（包含5个预设模板 + 自定义场景）",
      "request": {
        "headers": {
          "Authorization": { "type": "string", "required": true }
        },
        "query": {
          "sceneName": { "type": "string", "description": "场景名称（模糊查询）" },
          "status": { "type": "integer", "enum": [1, 2], "description": "状态（1=启用，2=停用）" }
        }
      },
      "response": {
        "200": {
          "description": "成功",
          "body": {
            "type": "object",
            "properties": {
              "code": { "type": "integer", "example": 200 },
              "msg": { "type": "string", "example": "查询成功" },
              "rows": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "sceneId": { "type": "integer", "example": 1 },
                    "sceneName": { "type": "string", "example": "过温保护" },
                    "triggers": { "type": "string", "example": "温度 > 20°C", "description": "JSON字符串或简单描述" },
                    "actions": { "type": "string", "example": "空调开机,制冷模式,目标温度18°C", "description": "JSON字符串或逗号分隔" },
                    "status": { "type": "integer", "enum": [1, 2], "example": 2, "description": "1=启用，2=停用" },
                    "createTime": { "type": "string", "format": "date-time" }
                  }
                }
              },
              "total": { "type": "integer", "example": 8 }
            }
          }
        }
      }
    },
    "getScene": {
      "method": "GET",
      "path": "/iot/scene/{sceneId}",
      "description": "查询场景联动详细",
      "request": {
        "headers": {
          "Authorization": { "type": "string", "required": true }
        },
        "path": {
          "sceneId": { "type": "integer", "required": true }
        }
      },
      "response": {
        "200": {
          "description": "成功",
          "body": {
            "type": "object",
            "properties": {
              "code": { "type": "integer", "example": 200 },
              "msg": { "type": "string", "example": "查询成功" },
              "data": {
                "type": "object",
                "properties": {
                  "sceneId": { "type": "integer", "example": 1 },
                  "sceneName": { "type": "string", "example": "过温保护" },
                  "triggers": { "type": "string", "example": "{\"condition\":\"temperature > 20\"}" },
                  "actions": { "type": "string", "example": "[{\"action\":\"turnOn\",\"deviceId\":1}]" },
                  "status": { "type": "integer", "example": 1 }
                }
              }
            }
          }
        }
      }
    },
    "updateSceneStatus": {
      "method": "PUT",
      "path": "/iot/scene/updateStatus",
      "description": "修改场景状态（启用/禁用）",
      "request": {
        "headers": {
          "Authorization": { "type": "string", "required": true }
        },
        "body": {
          "type": "object",
          "properties": {
            "sceneId": { "type": "integer", "required": true, "example": 1 },
            "status": { "type": "integer", "required": true, "enum": [1, 2], "example": 1, "description": "1=启用，2=停用" }
          }
        }
      },
      "response": {
        "200": {
          "description": "成功",
          "body": {
            "type": "object",
            "properties": {
              "code": { "type": "integer", "example": 200 },
              "msg": { "type": "string", "example": "操作成功" }
            }
          }
        }
      }
    },
    "listAlertLog": {
      "method": "GET",
      "path": "/iot/alertLog/list",
      "description": "查询设备告警数据（用于系统动态时间线）",
      "request": {
        "headers": {
          "Authorization": { "type": "string", "required": true }
        },
        "query": {
          "alertLevel": { "type": "integer", "enum": [1, 2, 3], "description": "告警级别（1=提示，2=一般，3=严重）" },
          "status": { "type": "integer", "enum": [1, 2], "description": "状态（1=未处理，2=已处理）" },
          "pageNum": { "type": "integer", "default": 1 },
          "pageSize": { "type": "integer", "default": 10 }
        }
      },
      "response": {
        "200": {
          "description": "成功",
          "body": {
            "type": "object",
            "properties": {
              "code": { "type": "integer", "example": 200 },
              "msg": { "type": "string", "example": "查询成功" },
              "rows": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "alertLogId": { "type": "integer", "example": 1 },
                    "alertLevel": { "type": "integer", "example": 3 },
                    "alertName": { "type": "string", "example": "温度告警" },
                    "alertContent": { "type": "string", "example": "1F-1号库温度超限 21.5°C" },
                    "createTime": { "type": "string", "format": "date-time" },
                    "status": { "type": "integer", "example": 1 }
                  }
                }
              },
              "total": { "type": "integer", "example": 128 }
            }
          }
        }
      }
    },
    "listDeviceLog": {
      "method": "GET",
      "path": "/iot/deviceLog/list",
      "description": "查询设备日志（用于系统动态时间线）",
      "request": {
        "headers": {
          "Authorization": { "type": "string", "required": true }
        },
        "query": {
          "logType": { "type": "integer", "enum": [1, 2, 3], "description": "日志类型（1=上线，2=离线，3=属性上报）" },
          "pageNum": { "type": "integer", "default": 1 },
          "pageSize": { "type": "integer", "default": 10 }
        }
      },
      "response": {
        "200": {
          "description": "成功",
          "body": {
            "type": "object",
            "properties": {
              "code": { "type": "integer", "example": 200 },
              "msg": { "type": "string", "example": "查询成功" },
              "rows": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "logId": { "type": "integer", "example": 1 },
                    "logType": { "type": "integer", "example": 1 },
                    "logValue": { "type": "string", "example": "设备上线" },
                    "createTime": { "type": "string", "format": "date-time" }
                  }
                }
              },
              "total": { "type": "integer", "example": 256 }
            }
          }
        }
      }
    },
    "getUserProfile": {
      "method": "GET",
      "path": "/system/user/profile",
      "description": "获取用户信息",
      "request": {
        "headers": {
          "Authorization": { "type": "string", "required": true }
        }
      },
      "response": {
        "200": {
          "description": "成功",
          "body": {
            "type": "object",
            "properties": {
              "code": { "type": "integer", "example": 200 },
              "msg": { "type": "string", "example": "操作成功" },
              "data": {
                "type": "object",
                "properties": {
                  "userId": { "type": "integer", "example": 1 },
                  "userName": { "type": "string", "example": "范东桥" },
                  "nickName": { "type": "string", "example": "范东桥" },
                  "phonenumber": { "type": "string", "example": "138****1234" },
                  "avatar": { "type": "string", "example": "/profile/avatar/default.png" },
                  "roles": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "roleId": { "type": "integer", "example": 1 },
                        "roleName": { "type": "string", "example": "系统管理员" }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "getUserDataOverview": {
      "method": "GET",
      "path": "/iot/cellar/user/overview",
      "description": "获取用户数据概览（陈酿库/设备/告警）",
      "request": {
        "headers": {
          "Authorization": { "type": "string", "required": true }
        }
      },
      "response": {
        "200": {
          "description": "成功",
          "body": {
            "type": "object",
            "properties": {
              "code": { "type": "integer", "example": 200 },
              "msg": { "type": "string", "example": "查询成功" },
              "data": {
                "type": "object",
                "properties": {
                  "cellarCount": { "type": "integer", "example": 8 },
                  "deviceCount": { "type": "integer", "example": 92 },
                  "alertCount": { "type": "integer", "example": 3 }
                }
              }
            }
          }
        }
      }
    },
    "getNoticeUnreadCount": {
      "method": "GET",
      "path": "/system/notice/unreadCount",
      "description": "获取未读消息通知数量",
      "request": {
        "headers": {
          "Authorization": { "type": "string", "required": true }
        }
      },
      "response": {
        "200": {
          "description": "成功",
          "body": {
            "type": "object",
            "properties": {
              "code": { "type": "integer", "example": 200 },
              "msg": { "type": "string", "example": "查询成功" },
              "data": { "type": "integer", "example": 3 }
            }
          }
        }
      }
    }
  },
  "errorCodes": {
    "200": "操作成功",
    "401": "认证失败，无法访问系统资源",
    "403": "无权限访问",
    "404": "请求资源不存在",
    "450": "新增数据失败，请联系管理员",
    "500": "系统内部错误，请联系管理员"
  },
  "notes": {
    "responseDateFormat": "FastBee后端返回的时间格式为 'yyyy-MM-dd HH:mm:ss'，不是ISO 8601格式",
    "statusField": "场景状态使用 status=1（启用）/ status=2（停用），不是 enabled=true/false",
    "pathPrefix": "所有路径使用 /iot/ 前缀（FastBee原生结构），除了用户相关使用 /system/",
    "pagination": "分页使用 pageNum/pageSize（FastBee原生），返回 rows/total",
    "customEndpoints": [
      "/iot/cellar/dashboard/metrics",
      "/iot/cellar/dashboard/deviceStats",
      "/iot/device/cellarList",
      "/iot/cellar/user/overview"
    ]
  },
  "implementation": {
    "strategy": "零后端开发（方案A）",
    "决策时间": "2026-06-06 20:08 GMT+8",
    "决策人": "范东桥 (Max)",
    "核心原则": [
      "复用 FastBee 原生接口",
      "前端聚合计算",
      "FastBee 后台配置分组",
      "前端直接调用第三方天气 API"
    ]
  },
  "backendTasks": [
    {
      "task": "在 FastBee 管理后台配置 8 个陈酿库分组",
      "groups": [
        {"groupId": "cellar-1f-1", "groupName": "1F-1号库", "floor": 1},
        {"groupId": "cellar-1f-2", "groupName": "1F-2号库", "floor": 1},
        {"groupId": "cellar-1f-3", "groupName": "1F-3号库", "floor": 1},
        {"groupId": "cellar-3f-1", "groupName": "3F-1号库", "floor": 3},
        {"groupId": "cellar-3f-2", "groupName": "3F-2号库", "floor": 3},
        {"groupId": "cellar-3f-3", "groupName": "3F-3号库", "floor": 3},
        {"groupId": "cellar-3f-4", "groupName": "3F-4号库", "floor": 3},
        {"groupId": "cellar-3f-5", "groupName": "3F-5号库", "floor": 3}
      ],
      "deviceAssignment": "根据设备命名规则分配（如 '2F3W5西门空调' → 3F-5号库）",
      "status": "待实施"
    },
    {
      "task": "申请和风天气 API Key",
      "url": "https://dev.qweather.com/",
      "freeQuota": "1000次/天",
      "chengduLocationCode": "101270101",
      "apiEndpoint": "https://devapi.qweather.com/v7/weather/now?location=101270101&key=YOUR_KEY",
      "status": "待实施"
    }
  ],
  "frontendImplementation": [
    {
      "feature": "核心指标统计",
      "approach": "前端聚合计算",
      "baseApi": "GET /iot/device/shortList",
      "logic": "获取所有设备数据后，按设备类型筛选并计算平均值/最小值/最大值/状态"
    },
    {
      "feature": "设备统计",
      "approach": "前端聚合计算",
      "baseApi": "GET /iot/device/shortList",
      "logic": "按设备类型分组统计总数/在线/离线数量"
    },
    {
      "feature": "陈酿库设备列表",
      "approach": "使用 FastBee 分组筛选",
      "baseApi": "GET /iot/device/shortList?groupId={cellar-id}",
      "logic": "通过 groupId 参数获取指定陈酿库的设备列表"
    },
    {
      "feature": "天气查询",
      "approach": "前端直接调用第三方 API",
      "provider": "和风天气",
      "apiEndpoint": "https://devapi.qweather.com/v7/weather/now",
      "logic": "前端直接 fetch 调用，解析响应后展示"
    },
    {
      "feature": "用户数据概览",
      "approach": "前端聚合计算",
      "baseApis": [
        "GET /iot/device/shortList （设备数量）",
        "GET /iot/alertLog/list （告警数量）"
      ],
      "logic": "陈酿库数量固定为 8，设备/告警数量通过现有接口统计"
    }
  ],
  "removedEndpoints": [
    "/iot/cellar/dashboard/metrics （不需要，前端聚合）",
    "/iot/cellar/dashboard/deviceStats （不需要，前端聚合）",
    "/iot/device/cellarList （不需要，使用 groupId 筛选）",
    "/iot/tool/weather/current （不需要，前端调用第三方）",
    "/iot/cellar/user/overview （不需要，前端聚合）"
  ],
  "unknowns": [
    "场景模板（5个预设）是否需要在数据库中预置？还是由前端硬编码？",
    "实时数据刷新是否使用WebSocket推送？还是前端轮询？",
    "告警通知是否使用FastBee原生的通知模板（/notify/template/getAlertWechatMini）？"
  ]
}
