仪表盘
用户增长、固件与运维概览
GET /xiantao/api/admin/user-stats → 用户 KPI + 趋势 · GET /xiantao/api/admin/ota-upgrade-stats → total / success / failed / successRate / weekSuccess / weekFailed / byVersion[] / byDevice[] / byUser[] / weekTrend[] · 需 Header tk
注册用户总数
—
较上月 +20.3%
本周新增
—
日均 9.0 人
本月新增
—
+12.5% 环比
在架固件
—条
—
用户增长趋势
近 7 天每日新增注册
新增用户
最近上传固件
用户国家 / 地区分布
Top 5
近期 OTA 升级
目标版本升级统计
by fwTo
设备升级统计
Top 设备
数据口径：用户维度取自 User 表；固件维度取自 Firmware 表；设备维度取自 devices（bleMac 唯一）/ device_cmd_logs / device_ota_upgrade_logs。OTA 统计含成功 / 失败、按版本（fwTo）、按设备聚合；文件字节不入库。
用户管理
查看与管理 App 注册用户
GET /xiantao/api/admin/users?page=1&size=20 → { list[], currentPage, size, total }，按 created_at 倒序；size 上限 100；普通管理员列表不含超级管理员
PUT /xiantao/api/system/users/:id/role { role: 0 | 1 }（仅 System）
DELETE /xiantao/api/system/users/:id（仅 System）
PUT /xiantao/api/system/users/:id/role { role: 0 | 1 }（仅 System）
DELETE /xiantao/api/system/users/:id（仅 System）
| 用户邮箱▼ | 角色▼ | 国家 / 地区▼ | App 版本 | 设备机型 | 注册时间▼ | 最近登录▼ | 操作 |
|---|
—
交互：点击行 → 右侧详情抽屉（含时区 / 语言 / phoneId 等调试字段）；行尾 ⋯ → 调整角色 / 删除账号（禁用态见说明）；表头可排序
固件管理
按「设备型号 + 版本」唯一管理 OTA 固件包，App 端通过 /device/ota/:devType 拉取最新版本
GET /xiantao/api/firmware/list?currentPage&size&devType&version¬e&isTest · POST /xiantao/api/firmware/upload/otafile?devType&version¬e&isTest（multipart uploadFile）
PUT /xiantao/api/firmware/update { reqVo:{ id, authCode, devType, note, version, isTest } } · DELETE /xiantao/api/firmware/del/:id/:authCode
鉴权：Header X-Firmware-Auth 或 Authorization: Firmware <code>；磁盘路径 assets/ota/{devType}/{version}/{文件名}
PUT /xiantao/api/firmware/update { reqVo:{ id, authCode, devType, note, version, isTest } } · DELETE /xiantao/api/firmware/del/:id/:authCode
鉴权：Header X-Firmware-Auth 或 Authorization: Firmware <code>；磁盘路径 assets/ota/{devType}/{version}/{文件名}
| 设备型号▼ | 版本▼ | 固件文件 | 大小 | MD5 | 类型 | 上传时间▼ | 操作 |
|---|
—
设备型号
固件所属设备型号编码
GET /xiantao/api/firmware/types → [{ id, code, firmwareCnt }] · POST /xiantao/api/firmware/types { authCode, code }
DELETE /xiantao/api/firmware/types/:code/:authCode → 当该型号下仍有固件时返回 Cannot delete type: firmware records still exist
DELETE /xiantao/api/firmware/types/:code/:authCode → 当该型号下仍有固件时返回 Cannot delete type: firmware records still exist
服务启动时自动写入 12 个默认型号（SeedFirmwareTypes）。testType 为测试通道专用，正式发布请勿占用。
| 型号编码 | 固件数量 | 状态 | 操作 |
|---|
管理员
后台管理员账号
GET /xiantao/api/admin/me → { id, email, nickName, role } · POST /xiantao/api/system/admins { email, pwd, nickName }（密码 ≥ 6 位）
PUT /xiantao/api/system/users/:id/role → 仅支持 0 / 1；不能修改自己，不能修改系统管理员（917518045@qq.com）
PUT /xiantao/api/system/users/:id/role → 仅支持 0 / 1；不能修改自己，不能修改系统管理员（917518045@qq.com）
角色 2（超级管理员）由配置的保留邮箱自动获得，无法通过后台创建或降级，避免误操作锁死后台。
| 账号 | 角色 | 最近登录 | 创建时间 | 操作 |
|---|
设备管理
BLE 设备登记与日志
GET /xiantao/api/admin/devices?deviceType&sn&advName&bleMac&page&pageSize → { list: Device[], total, page, pageSize } · RoleAdmin+ · Header tk
App 侧写入：POST /device/bind · POST /device/cmd-logs · POST /device/ota-upgrade-logs（OTA 文件内容不入库）
App 侧写入：POST /device/bind · POST /device/cmd-logs · POST /device/ota-upgrade-logs（OTA 文件内容不入库）
| 设备 | 型号 | BLE MAC | SN | 固件 | 最近可见 | 操作 |
|---|
—
交互：点击行 → 设备详情（Status / Info / Inverter·Select / Cmd / OTA）；与 App Admin「Device Logs」对齐。空态展示「暂无登记设备」。
设备详情
对齐 App：Home / Basic Information / Info / Inverter / Select Device；SN 与固件版本单独展示
GET /admin/devices/:id → { device, binds[], latestSnapshot } · GET /admin/devices/:id/status-snapshot · GET /admin/devices/:id/protection-events · cmd-logs / ota-logs
OTA 升级日志
全局 OTA 升级尝试记录
GET /xiantao/api/admin/ota-upgrade-stats → 版本 / 设备 / 用户聚合 · GET /xiantao/api/admin/ota-upgrade-logs?status&deviceType&bleMac&advName&fwTo&userId&page&pageSize → { list, total }
各版本升级数量
| 目标版本 fwTo | 总计 | 成功 | 失败 |
|---|
各设备升级数量
| 设备 | 型号 | 总计 | 成功 | 失败 |
|---|
—
字段：status / fwFrom / fwTo / fileName / fileSize / totalPackets / lastPacketIndex / retryCount / failStep / failCode / failMsg / stepsJson / durationMs · 点击卡片打开步骤时间线
系统设置
界面语言与运行参数。语言设置写入本机缓存；其余项由服务端 config 控制
显示语言
界面语言
未设置时跟随系统语言；设置后保存在本机浏览器
固件仓库
存储目录
assets/ota
路径规则
{devType}/{version}/{fileName}
单包上限
100 MB（security.upload_max_bytes）
文件校验
上传即计算 MD5，随 OTA 下发返回 checkSum
磁盘占用
248.6 MB / 31 个文件
UploadMaxBytes 超限时 multipart 内存阈值自动降为 32MB，避免大包占满内存
下载与签名
下载链接
/xiantao/api/firmware/download/:id?exp=&sig=
签名算法
HMAC-SHA256(id:exp)
有效期
60 分钟（download_url_ttl_minutes）
密钥来源
download_sign_secret，未配置时回退 jwt_secret
固件授权码
••••••••••••
Web 固件管理
未启用
超级管理员启用授权码后，所有管理员可用登录 JWT 管理固件；App 仍使用 X-Firmware-Auth
访问限流
已启用
全局
GlobalRateLimit 作用于整个 /xiantao/api
登录
login_per_ip_minute = 10 次 / IP / 分钟
迁移
migrate_per_ip_minute = 5
上传
upload_per_ip_hour = 20
下载
download_per_ip_minute = 60
验证码
邮箱维度限制，超限返回 429
服务与文档
BasePath
/xiantao/api
鉴权方式
JWT，登录返回 tk 字段，置于请求头
角色模型
0 普通用户 · 1 管理员 · 2 超级管理员
数据库
SQLite · sok_app.db
接口文档
/swagger/index.html
BASIC AUTH
日志
结构化 JSON，控制台 + server.log，含 requestId
请求头会附带 X-Request-ID，便于按 requestId 串联排查
接口一览
后台页面与 Go 服务端路由的对应关系
本页即设计稿与实现的对齐基线：每个模块的读写动作都能在下方找到唯一对应路由
登录与账号 公开 / JWT
POST/user/login登录，返回 tk / role
GET/user/getRandomCode/:verifyType/:userNameverifyType 0=注册 1=重置
POST/user/register注册
POST/user/resetPwd重置密码
POST/user/updateUserInfo · /user/modifyPwd需 tk
GET/user/info/:email用户信息
DEL/user/注销本人账号
仪表盘 Admin / System
GET/admin/user-statsKPI + 三条趋势
GET/system/stats总数统计（仅 System）
用户管理 Admin
GET/admin/users?page&size分页列表
GET/admin/me当前管理员身份
GET/admin/users/:id/device-binds用户历史绑定设备
PUT/system/users/:id/role改角色（仅 System）
DEL/system/users/:id删除用户（仅 System）
设备管理 / 日志 Admin
GET/admin/devices筛选 deviceType / sn / advName / bleMac
GET/admin/devices/:id快照 + binds[]
GET/admin/devices/:id/cmd-logsTX/RX 指令帧
GET/admin/devices/:id/ota-logs单设备 OTA 尝试
GET/admin/devices/:id/status-snapshot最新保护/MOS 快照
GET/admin/devices/:id/protection-events保护/MOS 边沿事件
GET/admin/protection-events全局保护事件
GET/admin/ota-upgrade-logs全局 OTA 升级日志
GET/admin/ota-upgrade-statsOTA 版本/设备/用户统计
固件管理 X-Firmware-Auth
GET/firmware/list筛选 devType / version / note / isTest
POST/firmware/upload/otafilemultipart 上传
PUT/firmware/updatereqVo 内更新
DEL/firmware/del/:id/:authCode删除含磁盘文件
GET/firmware/download/:idexp + sig 签名下载
设备型号 X-Firmware-Auth
GET/firmware/types含 firmwareCnt
POST/firmware/types新增型号
DEL/firmware/types/:code/:authCode有固件时禁止删除
管理员 System
POST/system/admins新建或提升为管理员
设备端上传 App · JWT
GET/device/ota/:devType检查更新
POST/device/bind登记设备 + 绑定用户
POST/device/cmd-logs批量上报 TX/RX（过滤 OTA 帧）
POST/device/status-snapshots保护/MOS 周期快照
POST/device/protection-events保护/MOS 边沿事件
POST/device/ota-upgrade-logsOTA 结束上报（无 bin）