# icutool-esp-backend

**Repository Path**: plusboy/icutool-esp-backend

## Basic Information

- **Project Name**: icutool-esp-backend
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-06
- **Last Updated**: 2026-05-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

## 编译步骤
``` shell                                                                    
$env:GOOS="linux"    
$env:GOARCH="amd64"
$env:CGO_ENABLED="0"
go build -o icutoolEspServer .\cmd\server\main.go
APP_ENV=prod ./icutoolEspServer
```

说明：项目已切换为 pure Go 的 SQLite 驱动，Windows 下交叉编译 Linux 时请保持 `CGO_ENABLED=0`，这样生成的二进制可以直接在 Linux 运行，不需要额外安装 CGO 相关依赖。
## 项目介绍
这是一个管理嵌入式设备的web项目后端,使用Go语言进行开发,主要的作用是提供 websocket 长链地址，用于设备与 web 端进行数据交互,
设备上线之后,立马向设备发送最新的数据,同时也可以在后台配置一些定时任务的发送频率,比如天气数据,新闻数据。同时也支持 Windows 客户端通过新的 `/ws/pcTunnel` 长链，把 CPU、内存使用率等 JSON 消息透传给同一用户下的 ESP 设备。
## 项目依赖
数据库使用sqlite,方便部署
http开发框架请使用gin
## 项目规范
1. 开发请符合企业级开发规范,方便后续维护升级
project/
├── cmd/                    # 可执行程序入口
│   └── server/
│       └── main.go
├── internal/              # 私有代码，不可对外暴露
│   ├── handler/          # 处理器层（HTTP handlers）
│   ├── service/          # 业务逻辑层
│   ├── repository/       # 数据访问层
│   ├── model/            # 数据模型
│   └── middleware/       # 中间件
│   └── router/           # 接口分组路由层
├── pkg/                   # 公共代码，可被外部引用
├── configs/              # 配置文件
├── docs/                 # 文档
├── go.mod
├── go.sum
└── Makefile

2. 日志输出不允许使用print,请使用Logger日志框架打印
3. 方法和代码需要有足够的中文注释和相关日志输出,我是一个新手,需要通过日志和注释来加深学习

4. 常用到的一些变量,需要写入到配置文件dev.yaml prod.yaml中,比如外部接口api地址,请求头信息

## 外部api接口
用户获取天气以及新闻数据的api接口文档
1. 天气接口
数据获取接口：
- `GET https://api.icutool.cn/backend/util/qweather`
- Header: `hfToken: weatherPlusboyKeyXt1234`
- Query 参数：
  - `location`，
  - `city`，

接口返回：
``` json
{
    "code": 200,
    "msg": "查询和风天气成功",
    "data": {
        "tempCur": "当前温度",
        "tempHigh": "当日最高温度",
        "tempLow": "当时最低温度",
        "description": "天气情况",
        "city": "地区",
        "base64Ico": "天气图标"
    }
}
```

2. 新闻接口
数据获取接口：
- `GET https://api.icutool.cn/backend/util/newsHot`
- Header: `hfToken: weatherPlusboyKeyXt1234`
- Query 参数：
  - `top`，新闻数量

接口返回

```json
{
    "code": 200,
    "msg": "查询新闻热搜成功",
    "data": {
        "category": "微博",
        "headline": "热搜榜",
        "source": "tophub_weibo",
        "timeStr": "更新于12:45:38",
        "updated_at": "2026-05-06T12:45:38+08:00",
        "items": [
            {
                "rank": 1,
                "title": "山姆回应多名顾客拿袋子装免费酱料",
                "heat": "122万",
                "url": "https://s.weibo.com/weibo?q=%E5%B1%B1%E5%A7%86%E5%9B%9E%E5%BA%94%E5%A4%9A%E5%90%8D%E9%A1%BE%E5%AE%A2%E6%8B%BF%E8%A2%8B%E5%AD%90%E8%A3%85%E5%85%8D%E8%B4%B9%E9%85%B1%E6%96%99"
            },
            {
                "rank": 2,
                "title": "汉坦病毒疫情",
                "heat": "87万",
                "url": "https://s.weibo.com/weibo?q=%E6%B1%89%E5%9D%A6%E7%97%85%E6%AF%92%E7%96%AB%E6%83%85"
            },
            {
                "rank": 3,
                "title": "以旧换新加力扩围掀起消费新热潮",
                "heat": "83万",
                "url": "https://s.weibo.com/weibo?q=%E4%BB%A5%E6%97%A7%E6%8D%A2%E6%96%B0%E5%8A%A0%E5%8A%9B%E6%89%A9%E5%9B%B4%E6%8E%80%E8%B5%B7%E6%B6%88%E8%B4%B9%E6%96%B0%E7%83%AD%E6%BD%AE"
            }
        ]
    }
}
```

## 接口逻辑
除了注册接口登录接口 不需要请求头token外,其他接口都需要请求头token
1. 用户系统
使用sqlite建表保存用户信息
提供登录接口,使用内存缓存存储生成的token即可,token使用uuid(去掉-符号)即可,24小时有效期,后端接口入口需要校验token
注册接口,密码md5加密,注册需要 用户名 密码 邮箱,用户名和邮箱都是唯一不能重复,邮箱目前不需要校验,存储就行了,密码不需要设置规则
2. 任务接口
目前只有两个任务,一个新闻任务,一个天气任务,创建一个任务表,塞入这两个任务信息即可 不需要提供多余的接口
用户可以设置任务的频率,使用cron表达式来配置,需要你输出任务频率查询接口,频率修改接口
重新设置任务频率之后,需要立即生效推送逻辑
3. 配置接口
新闻任务:可以配置推送的新闻数量 字段为 top
天气任务:可以配置需要推送的地区编号和地区,字段为 location city
后续向长链推送数据 需要从配置表查询相关配置信息,因为每个用户设置的不一样

## 长链逻辑
#### 长链逻辑
1. 心跳超过10秒则断开长链
2. 设备连接长链,会有四个参数 ip mac username password 需要校验用户名密码是否正确,不正确拒绝连接 ip mac不需要校验 日志打印即可
3. 设备连接成功之后,立即向设备推送最新的天气数据,新闻数据.
需要查询用户设置的新闻数量,天气编号,天气城市来进行推送
如果未设置, 新闻数量默认值=3  天气编号=101190110 天气城市=建邺
这些默认值需要写入到配置文件里
后续根据用户设置的cron表达式(未设置就默认1分钟一次,需要写入到配置文件),来推送对应的数据
4. Windows 客户端可以使用登录后拿到的 token 连接 `/ws/pcTunnel`, 服务端校验 token 成功后建立长链, 用户后续发来的 JSON 消息需要按 userID 原样转发给 `/ws/device` 在线的单片机客户端

#### 长链消息格式
1. 新闻

```json
{
  "type": "weather",
  "data": {
    "tempCur": 12,
    "tempHigh": 21,
    "tempLow": 9,
    "description": "晴",
    "city": "南京", //用户配置的地区
    "base64Ico": "ZmFrZS1pY29u"
  }
}
```
2. 天气

```json
{
  "type": "news",
  "data": {
    "category": "微博",
    "headline": "热搜榜",
    "news": [
      "张雪机车再夺冠军",
      "日本地震",
      "95后把卡脖子难题变成咱的杀手锏"
    ],
    "timeAgo": "更新于23:29:53"
  }
}
```