顶层设计与技术架构

系统全景

 ┌─────────────┐   HTTPS 事件/心跳    ┌──────────────────────────────┐
 │  ESP32 Hub  │ ───────────────────▶ │            服务器             │
 │ 磁吸/压力/按钮│ ◀──── BLE 配网 ──── │  Nginx                       │
 └─────────────┘                      │   ├─ /fanglian        → 后端 API │
        ▲                             │   └─ /fanglian-admin  → Web 管理台│
        │ 蓝牙下发 Wi-Fi               │                              │
        │                             │  后端 API（PM2 fanglian-backend）│
 ┌─────────────┐   REST / JWT         │   ├─ TDengine（时序事件库）      │
 │  微信小程序  │ ───────────────────▶ │   └─ metadata.json（业务元数据） │
 └─────────────┘                      └─────────────┬────────────────┘
        ▲ 微信服务通知（订阅消息）                     │
        └────────────────────────────────────────────┘

一次典型事件链路：传感器触发 → Hub 立即 HTTPS 上报 → 后端写入 TDengine 并按订阅偏好推送微信服务通知 → 小程序时间线与 Web 管理台实时可查。Hub 每 60 秒一次心跳，用于判断在线/离线。

四端清单

数据库：TDengine

时序事件全部存入 TDengine，初始化脚本为 database/01_init.sql（taos -f 执行）：

CREATE DATABASE IF NOT EXISTS elder_guard KEEP 365 DURATION 1;
USE elder_guard;

CREATE STABLE IF NOT EXISTS sensor_events (
  ts TIMESTAMP, `event_type` VARCHAR(64), `value` DOUBLE
) TAGS (hub_id VARCHAR(64), sensor_id VARCHAR(64), sensor_type VARCHAR(64));

设计要点：

• elder_guard 库保留 365 天数据，按天切分存储文件，贴合 IoT 时序负载。
• 所有事件共用一张超级表 sensor_events，子表以 ${hub_id}_${sensor_id} 命名、首次写入时自动创建，无需预建。
• event_type、value 是 TDengine 保留字，SQL 中必须用反引号包裹。
• 后端通过 REST 接口（默认 http://localhost:6041）读写，事件查询一律 ORDER BY ts DESC，最新在前。

业务元数据持久化

设备、用户、绑定、激活码、亲友卡等业务元数据不放在 TDengine，而是持久化在服务器目录 /var/www/fanglian/data/：

后端运行时有内存缓存：直接改文件必须 pm2 restart fanglian-backend 才生效；通过 API 操作会自动刷新缓存并落盘。该目录务必避免被部署流程清空。

服务器与部署拓扑

生产环境单机部署，Nginx 统一入口 https://yeezytb.com：

部署纪律（都是踩过的坑）：

• Web 端必须在服务器上构建：本地构建会把 NEXT_PUBLIC_API_BASE_URL 固化成 localhost，线上请求全部失败。
• rsync 同步必须排除环境文件：Web 端排除 .env.local，后端排除 .env、.env.local，否则 --delete 会删掉生产配置。
• 服务器上构建用 nohup npm run build & 后台执行，再 pm2 restart，避免 SSH 长连接被断。
• 完整步骤见 dev-logs/web-deploy-guide.md 与 scripts/deploy-web.sh。

命名与标识规范

自定义名（用户称呼、家庭组名、设备名）不超过 6 个字符；Web 端优先显示自定义名，系统 ID 以灰色小字随行展示。

鉴权体系

后端 .env 设 SUBSCRIPTION_REQUIRED=false 可关闭全部订阅校验（开源自部署模式）：事件照常写入，查询接口恒返回会员有效，小程序不显示续费引导。

API 一览

baseURL：https://yeezytb.com/fanglian

设备侧

用户侧（小程序）

管理侧（Web）