======= CTWing 设备数据工作流 — 冷启动文件 =======

> 版本: 1.1 ｜ 日期: 2026-08-16 ｜ 用途: CTWing 设备数据系统的冷启动/重建/排障手册
> 服务器: 腾讯云轻量 lhins-1dai07vu ｜ 公网IP: 82.156.85.124 ｜ 域名: dev.mandolinwu.site（ICP备案中）
> 所属体系: 曼陀林平台（完整平台文档见《曼陀林工作冷启动文件》）

---

====== 1. 系统链路 ======

<code>
设备(4G双头阀/NB球阀/土壤墒情站) → AEP平台(iot.ctwing.cn)
   → 北向订阅(定源,设备级) → HTTP推送 → Flask接收端(:13543)
   → SQLite(ctwing.db) → 每日09:00日报 → MySQL(huifei_daily) → 微信推送
   → H5查询工具(/ctwing/h5: 设备台账管理 + 图表 + 分析报告)
备用通道: RabbitMQ(:5672, vhost=ctwing, 队列ctwing.data) ← MQ消费端(mq_consumer)
</code>

**访问地址：**
| 服务 | 地址 |
|------|------|
| H5设备查询工具 | http://82.156.85.124/ctwing/h5（备案后 https://dev.mandolinwu.site/ctwing/h5）|
| 接收端健康检查 | http://82.156.85.124:13543/ctwing/health |
| RabbitMQ管理台 | http://82.156.85.124:15672 |

====== 2. 核心组件 ======

| 组件 | 位置 | 说明 |
|------|------|------|
| Flask接收端 | ~/projects/ctwing-2/receiver_server.py | 接收AEP推送+解析入库+H5 API+游戏 |
| systemd服务 | ctwing-receiver | 端口13543，开机自启 |
| MQ消费端 | ~/projects/ctwing-2/mq_consumer.py | RabbitMQ订阅消费(备用通道) |
| systemd服务 | mq_consumer | 开机自启 |
| AEP SDK | ~/projects/ctwing-2/aep_sdk/ | 官方Python SDK（用户提供313302_sdk包）|
| AEP API客户端 | ~/projects/ctwing-2/aep_api.py | 订阅管理(增删设备定源) |
| SQLite | ~/projects/ctwing-2/data/ctwing.db | device_data + monitored_devices台账 |
| 日报脚本 | db_writer.py + ~/.hermes/scripts/ctwing_daily.sh | 09:00聚合写MySQL+微信推送 |
| cron | b3b717e6550f 每天09:00 | 设备日报（no_agent）|

====== 3. AEP 开放平台接入（关键） ======

===== 3.1 凭证（存 ~/.hermes/.env，权限600） =====
| 产品 | 产品ID | MasterKey变量 | 协议 |
|------|--------|--------------|------|
| 4G智慧球阀 | 17080670 | AEP_VALVE_MASTER_KEY | MQTT |
| NB智慧球阀 | 17070058 | AEP_NB_MASTER_KEY | LWM2M |
| 土壤墒情气象站 | 17197695 | AEP_MASTER_KEY | 其他 |
- 应用凭证(共用): AEP_APP_KEY=IQsPnFznnO7, AEP_APP_SECRET=dbwgP7q7IM
- 租户ID: 2000455438（=API域名前缀）

===== 3.2 API 接入 =====
- 域名: `https://2000455438.api.ctwing.cn`（租户ID.api.ctwing.cn，open.ctwing.cn 无DNS）
- **签名算法（血泪教训，不是MD5！）**:
<code>
  code = "application:{AppKey}\ntimestamp:{毫秒时间戳}\n" + 参数行"名:值\n"(按key排序,空值参数也要!) + body + "\n"
  signature = Base64(HMAC-SHA1(key=AppSecret, msg=code))
</code>
- 时间校准: GET /echo 的 x-ag-timestamp 头
- 订阅管理API（aep_subscribe_north）:
  - CreateSubscription: POST /subscription version=20181031202018
  - DeleteSubscription: DELETE /subscription version=20181031202023
  - GetSubscriptionsList: GET /subscribes version=20220624163719
- AEP deviceId = 产品ID + SN（如 17080670+863304082793730）
- 返回: {"code":0,"msg":"ok","result":...}；创建成功 result=null → subId 靠 List 反查

===== 3.3 设备管理原则（用户明确要求） =====
- **添加设备 → 创建该设备的设备级订阅（subLevel=2）**
- **删除设备 → 删除该设备的订阅**
- 禁止产品级订阅（会把全产品设备数据都拉过来）
- 幂等: 已有相同订阅(同deviceId+subUrl)不重复创建
- 安全: 删除只允许动 subUrl=http://82.156.85.124:13543/ctwing/receive 的订阅，其他目的地(旧云函数/合作方)绝不删除

====== 4. 数据解析（AEP直推格式） ======

- AEP推送信封: `{"deviceId":"...","payload":{"APPdata":"<base64>"}}`
- APPdata base64解码(latin-1) → 内含SN(18位) + JSON数据体(cmd/bat/csq/mtemp/mcu_press/charge等)
- 设备类型按deviceId前缀: 17080670=valve 17070058=nb_valve 17197695=soil
- 解析函数: receiver_server.py 的 parse_aep_payload()（mq_consumer.py 同款）

====== 5. H5 设备管理工具 ======

- 页面: /ctwing/h5 ｜ API: /ctwing/api/manage(台账) /data(图表数据) /report(分析报告)
- 台账表: monitored_devices(sn, name, device_type, product, aep_subscribed, aep_device_id, sub_id)
- 功能: 添加/删除设备(自动同步AEP定源) + 4图(电压/信号/温度/压力) + 一键分析报告(HTML下载)
- 产品选择: 4G智慧球阀 / NB智慧球阀 / 土壤墒情气象站（凭证按产品区分）
- 纯前端Canvas绘图，零外部依赖

====== 6. 日报流程（每天09:00） ======

1. cron b3b717e6550f 触发 ~/.hermes/scripts/ctwing_daily.sh
2. db_writer.py: SQLite(昨日08:30~今日08:29的meas数据) → MySQL huifei_daily.daily_reports
3. hermes send 微信推送日报+Excel附件
4. 日报窗口: 昨日08:30 ~ 今日08:29

====== 7. 常见运维命令 ======

<code>
sudo systemctl restart ctwing-receiver   # 重启接收端
sudo systemctl restart mq_consumer       # 重启MQ消费端
sudo systemctl restart caddy             # 重启反代
tail -f ~/projects/ctwing-2/data/cron.log  # 日报日志
cd ~/projects/ctwing-2 && ./venv/bin/python -c "import aep_api; print(aep_api.list_subscriptions('4g_valve'))"  # 查AEP订阅
</code>

====== 8. 排障速查 ======

| 症状 | 排查 |
|------|------|
| 数据没流入 | curl http://localhost:13543/ctwing/health；查AEP订阅列表是否还在 |
| 添加设备报"deviceId不属于该productId" | 该SN未在AEP产品里注册，先到AEP控制台注册设备 |
| 添加设备报"已经存在相同订阅" | 设备已有定源（幂等，正常）|
| 日报无数据 | 检查设备是否上报；cron b3b717e6550f 状态；cron.log |
| AEP签名401 | 时间戳偏差>5分钟？用/echo校准；空值参数也要参与签名 |
| 微信打不开链接 | 未备案域名被拦截，用IP+系统浏览器；二维码在 /home/ubuntu/qrcodes/ |

====== 9. 冷启动恢复步骤 ======

1. 装 Docker + 启动 rabbitmq/huifei-mysql 容器
2. 装 python3-venv + pip install flask pika pymysql；恢复 ~/projects/ctwing-2 代码与 data/ctwing.db
3. systemd: ctwing-receiver + mq_consumer 启用
4. Caddy 配置 + 防火墙放行 80/443/13543/5672
5. cron 建 b3b717e6550f（每天09:00）
6. 验证: /ctwing/health → AEP订阅列表 → 等数据入库 → H5页面