新用户上手指南

本篇按真实体验顺序，走完「拿到设备 → 看到第一条报平安」的全过程。涉及两类角色：管理员（发码、录设备、看后台）与用户（老人家属，只用微信小程序）。

全流程一览

步骤 0：设备出厂录入白名单（管理员）

每台设备出厂时都有一个唯一的 Hub ID（如 fl_reed_a3m8n1），必须先进入后端白名单 device_inventory，设备才能被激活。在服务器上执行：

npx tsx scripts/seed-device-inventory.ts fl_reed_001..fl_reed_010

白名单没有 Web 端新增入口，只能跑脚本录入；录入后可在 Web「设备白名单」页查看。

步骤 1：领取激活码（管理员发放）

1. 管理员打开 Web 管理台的「激活码管理」页（/fanglian-admin/admin/subscriptions）。
2. 点右上角「生成月卡」（30 天）或「生成年卡」（365 天）。
3. 弹窗中展示明文激活码（形如 fl_sub_xxxx），这是它唯一一次完整出现，点复制后随硬件包裹等形式交付给用户。
4. 之后后台列表中只能看到掩码（前 8 位 + * + 后 4 位）、状态（未使用 / 已激活 / 已撤销）与使用人。

步骤 2：小程序登录与开通会员（用户）

1. 用户在微信中打开「芳莲守护助手」小程序，系统自动完成微信登录（wx.login 换取 JWT），无需注册。
2. 进入「我的 → 会员」页（pages/subscription），在「我的会员」卡片中输入激活码，点「开通/续费」。
3. 开通成功后，会员在账户级生效：名下所有家庭组的设备事件都会正常云端上报并推送微信通知。

如果用户先绑定了设备再开会员，绑定成功后会自动弹出「开通会员」输入框，同样可以输入激活码完成开通。未开通会员时，设备事件上报会被云端暂停（固件收到 403 后自动停发业务事件）。

步骤 3：蓝牙配网（用户 + 设备）

新设备（或长按机身上 BOOT 键 5 秒后的设备）会进入配网模式：蓝灯闪烁，对外广播蓝牙信号，名为 FLAN-XXXX（MAC 地址后两位）。

1. 用户打开小程序「绑定设备」页（pages/bind）的蓝牙配网向导。
2. 小程序扫描并列出 FLAN- 前缀的设备，选中要配网的那一台。
3. 向导会预填手机当前连接的 Wi-Fi 名称，用户只需输入 Wi-Fi 密码并确认。
4. 小程序通过蓝牙把 Wi-Fi 信息发给设备，设备联网成功后回复 ok:<ip> 并自动重启。

仅支持 2.4G Wi-Fi；配网超时约 55 秒，失败可重新发起。

步骤 4：设备自激活（自动完成）

设备重启后自动完成激活，无需人工干预：

1. 固件用烧录时写入的 HOUSEHOLD_ID 与 HUB_ID 请求后端 POST /api/v1/devices/activate。
2. 后端校验白名单后签发 hub_token（存入设备 NVS，后续上报凭据），并生成 8 位数字配对码。
3. 设备白名单中的状态随之变为「已激活」。

步骤 5：查看配对码（管理员）

未绑定设备的 8 位配对码会显示在 Web 管理台两处：

• 「设备白名单」页（/admin/whitelist）表格的「配对码」列，绿底显示；
• 「关系图谱」页（/admin/graph）点击 Hub 节点弹出的详情抽屉中。

管理员把配对码告知用户即可。设备被绑定后配对码立即失效（显示「已绑定」徽标）。

步骤 6：配对码绑定与命名（用户）

1. 用户在小程序「绑定设备」页输入 8 位配对码。
2. 小程序先预览该设备所在家庭组的构成；如果组内有多台设备，会询问「一起绑定 / 仅本设备」。单设备家庭组自动升级为家庭组绑定。
3. 绑定成功后进入命名引导：先给家庭组起名（如「张府」），再逐台给设备起名（如「药盒」「水杯」「平安按钮」，不超过 6 个字符）。
4. 之后用户可在「设备」Tab 查看所有已绑设备（在线状态、最后活跃、传感器数），首页展示守护状态，「时间线」Tab 可回看任意一天的事件。

配对码单次有效。用户在设备页解绑后，后端会为无人绑定的 Hub 重新生成配对码，设备可再次绑定给其他人。

步骤 7：订阅微信通知（用户）

1. 进入小程序「设置」页（pages/settings）。
2. 打开想接收的通知开关，微信会弹出订阅授权（用药提醒 = 磁吸、饮水提醒 = 压力、平安提醒 = 按钮三类模板）。
3. 授权成功后，对应 Hub 的传感器触发时，微信服务通知即刻送达；多台设备可按 Hub 分别订阅。

步骤 8：亲友卡（可选，主卡 → 亲友）

亲友卡让亲友不用自己买激活码也能看到主卡家庭组的设备，并享受会员权益：

1. 主卡用户在「会员」页的亲友卡区块点「+ 添加亲友卡」，再点「分享邀请」，把微信卡片发给亲友。
2. 亲友点开分享卡片（或手动粘贴 fl_gc_xxxx 邀请码），预览「谁邀请了你」，点「接受邀请」。
3. 亲友的会员状态变为「有效 · 亲友共享」。主卡可随时在会员页撤回邀请或移除亲友；主卡到期后亲友权益随之失效。

常见问题

• 设备一直蓝灯闪烁连不上 Wi-Fi？ 确认是 2.4G 网络、密码正确；重新进入小程序配网向导再试一次。
• 配对码输错提示无效？ 配对码可能已被使用（绑定即失效），到 Web「设备白名单」页确认设备是否已绑定。
• 事件有上报但微信收不到通知？ 检查小程序「设置」页对应 Hub 的订阅开关与微信授权状态。
• 想停用订阅校验做自部署？ 后端 .env 设置 SUBSCRIPTION_REQUIRED=false，详见顶层设计与技术架构。