研年艾灸椅APP需求文档_v2.md 93 KB
研年艾灸椅APP需求文档（详细版）
文档版本：v2.0
整理日期：2026-05-25
项目说明：后台和算法已完成，本文档用于指导APP前端开发
技术栈：UniApp框架（非UniAppX），支持iOS/Android/HarmonyOS跨平台
目录
- 1. 项目概述与架构
- 2. 技术框架规范
- 3. 全局交互规范
- 4. 启动与引导模块
- 5. 登录注册模块
- 6. 用户管理模块
- 7. 设备管理模块
- 8. 首页-设备控制模块
- 9. 无艾灸模式（休闲模式）
- 10. 专业模式（一键艾灸）
- 11. 自定义模式
- 12. 艾灸执行过程
- 13. 我的方案管理
- 14. 发现模块
- 15. 健康模块
- 16. 消息中心模块
- 17. 个人中心模块
- 18. 版本升级模块
- 19. 蓝牙通信规范
- 20. 后台接口清单
- 21. 全局错误码与提示文案
- 22. 页面清单与路由表
1. 项目概述与架构
1.1 产品定义
研年艾灸椅APP是一款配合智能艾灸椅硬件使用的移动控制应用。用户通过APP完成设备配对、艾灸方案选择/编辑、艾灸过程控制、设备状态监控等操作。APP通过蓝牙BLE与艾灸椅通信，通过HTTPS与后台服务交互。
1.2 核心业务流程图
+-------------------------------------------------------------+
| 用户打开APP |
| ↓ |
| 首次使用？ → 隐私政策 → 登录/注册 → 补充信息 → 首页 |
| ↓ |
| 已登录？ → 检查蓝牙 → 连接设备 → 选择模式 → 开始艾灸 |
| ↓ |
| 艾灸中 ←→ 暂停/继续/结束 ←→ 查看记录 |
+-------------------------------------------------------------+
1.3 系统架构
+------------------+ BLE蓝牙 +------------------+
| | <--------------> | |
| APP (UniApp) | | 艾灸椅设备 |
| | | (主控端) |
+--------+---------+ +------------------+
| HTTPS RESTful
v
+------------------+ +------------------+
| | <--------------> | 算法服务 |
| 后台服务 | | (穴位计算) |
| (业务API) | +------------------+
| |
| - 用户管理 |
| - 方案管理 |
| - 消息推送 |
| - 版本管理 |
| - 数据记录 |
| - 推荐算法 |
+------------------+
2. 技术框架规范
2.1 框架选型
| 项目 | 规范 |
|---|---|
| 开发框架 | UniApp（Vue3语法，非UniAppX） |
| 支持平台 | iOS / Android / HarmonyOS |
| 蓝牙通信 | uni-app蓝牙API（BLE低功耗蓝牙） |
| 网络请求 | uni.request（HTTPS） |
| 本地存储 | uni.setStorageSync / plus.sqlite |
| 推送服务 | uni-push 或厂商推送通道 |
| 页面路由 | uni.navigateTo / uni.redirectTo |
2.2 蓝牙通信要求
- 蓝牙版本：BLE 4.0及以上
- 通信协议：GATT协议
- 数据帧格式：包头(1B) + 命令字(1B) + 数据长度(2B) + 数据内容(NB) + 校验(1B)
- 坐标精度：毫米单位传输
- 连接距离：有效范围内自动重连
2.3 网络要求
- 协议：HTTPS
- 数据格式：JSON
- 认证方式：Header携带Token（长期有效）
- 超时设置：10秒
- 重试策略：失败时自动重试1次
3. 全局交互规范
3.1 页面加载规范
| 场景 | 交互方式 |
|---|---|
| 页面初始化 | 显示骨架屏，加载完成后展示内容 |
| 数据加载中 | 显示loading动画，禁止重复提交 |
| 数据为空 | 显示空状态插图+提示文字 |
| 网络错误 | 显示错误状态，提供"重新加载"按钮 |
| 请求失败 | Toast提示错误信息 |
3.2 弹窗层级规范
| 类型 | 使用场景 | 交互特性 |
|---|---|---|
| Toast | 轻提示（成功/失败/警告） | 2秒自动消失，不阻塞操作 |
| 确认弹窗 | 需要用户确认的操作 | 阻断操作，必须选择 |
| 底部弹窗 | 选项选择、信息展示 | 点击蒙层可关闭 |
| 全屏弹窗 | 复杂表单填写 | 带返回/关闭按钮 |
3.3 按钮状态规范
| 状态 | 视觉表现 | 交互特性 |
|---|---|---|
| 正常 | 主色调填充 | 可点击 |
| 禁用 | 灰色填充 | 不可点击，点击无响应 |
| 加载中 | 显示loading图标 | 不可点击 |
| 危险操作 | 红色填充 | 二次确认 |
3.4 输入验证规范
| 输入项 | 验证规则 | 错误提示 |
|---|---|---|
| 手机号 | 1开头的11位数字 | "请输入正确的手机号码" |
| 验证码 | 6位数字 | "请输入6位验证码" |
| 用户姓名 | 1-20个字符 | "姓名长度不超过20个字符" |
| 身高 | 50-250的数字 | "请输入50-250之间的数字" |
| 体重 | 10-300的数字 | "请输入10-300之间的数字" |
| 方案名称 | 1-30个字符 | "方案名称不超过30个字符" |
3.5 下拉刷新与上拉加载
| 页面 | 下拉刷新 | 上拉加载 |
|---|---|---|
| 我的设备 | 是（刷新连接状态） | 否 |
| 我的方案 | 是 | 否 |
| 发现首页 | 是 | 否 |
| 专家方案 | 是 | 是 |
| 消息中心 | 是 | 是 |
| 使用记录 | 是 | 是 |
| 健康推荐 | 是 | 是 |
4. 启动与引导模块
4.1 冷启动流程
步骤说明：
步骤1：用户点击APP图标
→ 显示启动页（品牌LOGO，固定2秒）
步骤2：判断是否为首次安装
→ 是：进入隐私政策弹窗
→ 否：进入步骤3
步骤3：判断登录状态
→ 本地存在有效Token：进入首页
→ 本地无Token或Token失效：进入登录页
错误处理： | 异常场景 | 处理方式 | |---------|---------| | 启动时崩溃 | 记录日志，下次启动尝试恢复 | | 启动页加载超时 | 5秒后自动跳过 | | 本地数据损坏 | 清除本地缓存，视为首次启动 |
4.2 隐私政策弹窗
页面元素：
- 弹窗标题："服务协议与隐私政策"
- 内容区域：滚动显示政策摘要
- 关键条款高亮：
- 《用户协议》：协议适用范围、服务内容及形式、软件使用及许可、终端责任安全、用户权利与义务、用户行为规范、知识产权声明、用户信息保护
- 《隐私政策》：我们收集的信息（个人信息、设备信息、日志信息、位置信息）、我们如何使用信息
- 底部按钮组：
- "不同意"按钮（灰色）
- "同意"按钮（主色调）
操作流程：
步骤1：弹窗显示
→ 用户阅读政策内容（可上下滚动）
步骤2：用户点击"不同意"
→ 弹出二次确认："不同意将无法使用APP，是否退出？"
→ 确认退出 → 关闭APP
→ 取消 → 回到隐私政策弹窗
步骤3：用户点击"同意"
→ 记录同意状态（本地持久化）
→ 关闭弹窗，进入登录页
错误提示： | 操作 | 错误提示 | |------|---------| | 未阅读直接点同意 | 无强制要求，但提供可滚动阅读 | | 点击内容中的链接 | 跳转对应的协议详情页面 |
4.3 协议详情页面
页面元素：
- 顶部导航栏：返回按钮 + "隐私政策"/"用户协议"
- 内容区域：完整协议文本
- 支持字体缩放
操作流程：
步骤1：从隐私政策弹窗点击协议链接 或 从设置页进入
→ 打开协议详情页
步骤2：用户阅读（可上下滚动）
步骤3：点击返回按钮
→ 返回上一页
5. 登录注册模块
5.1 登录页面
页面布局：
+----------------------------------+
| 状态栏 |
+----------------------------------+
| |
| HELLO, |
| 欢迎使用研年健康平台 |
| |
| +------------------------------+ |
| | +86 | 请输入手机号 | |
| +------------------------------+ |
| |
| +------------------------------+ |
| | 请输入验证码 | [获取验证码] | |
| +------------------------------+ |
| |
| +------------------------------+ |
| | 登录 | |
| +------------------------------+ |
| |
| ---------- 其他登录方式 --------- |
| |
| [微信图标] [Apple图标] |
| |
| [ ] 登录即代表同意隐私政策 |
+----------------------------------+
操作流程：
【整体流程】
步骤1：进入登录页
→ 手机号输入框自动获得焦点
→ 唤起数字键盘
步骤2：输入手机号
→ 实时校验手机号格式（1开头的11位数字）
→ 格式正确时，"获取验证码"按钮变为可用状态
→ 格式不正确时，按钮保持禁用状态
步骤3：点击"获取验证码"
→ 按钮变为禁用状态，开始60秒倒计时
→ 按钮文字变为"60s"（逐秒递减）
→ 后台调用发送验证码接口
→ 发送成功：Toast提示"验证码已发送"
→ 发送失败：恢复按钮状态，Toast提示错误原因
步骤4：输入验证码
→ 限制输入6位数字
→ 满6位后自动校验格式
步骤5：点击"登录"按钮
→ 按钮进入loading状态
→ 调用登录接口（手机号+验证码）
→ 登录成功：
- 保存Token到本地（持久化存储，永不过期）
- 保存用户信息
- 判断是否为首次登录
- 是：跳转到补充信息页
- 否：跳转到首页
→ 登录失败：
- 恢复按钮状态
- Toast提示错误信息
【第三方登录流程】
步骤1：点击微信/Apple图标
→ 唤起对应第三方登录SDK
→ 用户完成授权
→ 获取第三方授权码
→ 调用后台绑定/登录接口
→ 后续流程同手机号登录
详细错误提示清单：
| 场景 | 错误提示 | 处理方式 |
|---|---|---|
| 手机号为空 | "请输入手机号" | 登录按钮禁用 |
| 手机号格式错误 | "请输入正确的11位手机号" | 实时校验，红色边框提示 |
| 手机号未注册 | 后台自动注册新用户 | 无需提示，直接进入补充信息 |
| 验证码为空 | "请输入验证码" | 登录按钮禁用 |
| 验证码格式错误 | "验证码为6位数字" | 实时校验 |
| 验证码已过期 | "验证码已过期，请重新获取" | 清空验证码框，恢复获取按钮 |
| 验证码错误 | "验证码错误，请重新输入" | 保留手机号，清空验证码框 |
| 发送验证码频繁 | "发送过于频繁，请稍后再试" | 保持倒计时 |
| 网络请求失败 | "网络连接失败，请检查网络" | 提供重试按钮 |
| 服务器异常 | "服务器繁忙，请稍后再试" | 提供重试按钮 |
| 第三方登录取消 | "登录已取消" | Toast提示，留在登录页 |
| 第三方登录失败 | "登录失败，请尝试其他方式" | Toast提示 |
边缘场景处理：
| 场景 | 处理方案 |
|---|---|
| 倒计时期间切换页面 | 保持倒计时，返回后显示剩余时间 |
| 倒计时结束未获取 | 按钮恢复为"获取验证码" |
| 登录过程中杀掉APP | 下次启动重新走登录流程 |
| 同一账号多设备登录 | 允许多设备同时登录，各自独立 |
5.2 补充信息页面（首次登录引导）
页面布局：
+----------------------------------+
| < 完善个人信息 |
+----------------------------------+
| |
| 请完善以下信息，以便我们为您 |
| 提供更精准的艾灸服务 |
| |
| 姓名 |
| +------------------------------+ |
| | 请输入您的姓名 | |
| +------------------------------+ |
| |
| 性别 |
| [ 男 ] [ 女 ] |
| |
| 年龄 |
| +------------------------------+ |
| | 请选择年龄 | |
| +------------------------------+ |
| |
| 身高（cm） |
| +------------------------------+ |
| | 请输入身高 | |
| +------------------------------+ |
| |
| 体重（kg） |
| +------------------------------+ |
| | 请输入体重 | |
| +------------------------------+ |
| |
| +------------------------------+ |
| | 保存并进入 | |
| +------------------------------+ |
+----------------------------------+
操作流程：
步骤1：新用户登录成功后自动跳转
→ 表单所有字段为空
步骤2：填写姓名
→ 输入1-20个字符
→ 超过20字符禁止继续输入
步骤3：选择性别
→ 点击男/女单选按钮
→ 选中项高亮显示
步骤4：选择年龄
→ 点击弹出底部选择器
→ 范围：1-120岁
→ 默认选中25岁
→ 滑动选择后点击确认
步骤5：填写身高
→ 输入50-250的数字
→ 限制只能输入数字
→ 输入范围外数字时红色提示
步骤6：填写体重
→ 输入10-300的数字
→ 限制只能输入数字
步骤7：点击"保存并进入"
→ 校验所有字段是否已填写
→ 未填写项红色提示并滚动到对应位置
→ 校验通过：调用用户信息更新接口
→ 保存成功：进入首页
→ 保存失败：Toast提示错误信息
详细错误提示清单：
| 场景 | 错误提示 |
|---|---|
| 姓名为空 | "请输入姓名" |
| 姓名超过20字符 | "姓名不超过20个字符" |
| 性别未选择 | "请选择性别" |
| 年龄未选择 | "请选择年龄" |
| 身高为空 | "请输入身高" |
| 身高超出范围 | "请输入50-250之间的数字" |
| 体重为空 | "请输入体重" |
| 体重超出范围 | "请输入10-300之间的数字" |
| 网络保存失败 | "保存失败，请检查网络后重试" |
边缘场景：
| 场景 | 处理方案 |
|---|---|
| 用户点击返回 | 弹窗提示"完善信息可获得更精准的服务，是否跳过？"，跳过则以默认参数进入首页 |
| 保存过程中断网 | 提示网络错误，保留表单数据 |
| 后台返回错误 | 保留表单数据，提示具体错误原因 |
6. 用户管理模块
6.1 用户列表管理
入口： 首页 → 设备详情页 → 点击用户切换按钮
页面布局：
+----------------------------------+
| < 用户管理 [+ 新增] |
+----------------------------------+
| 最多可添加10个用户 |
+----------------------------------+
| [========= 用户卡片 =========] |
| 头像 张三 男 28岁 |
| 肩高:135cm 肩宽:42cm |
| [编辑] [删除] |
| [============================] |
| |
| [========= 用户卡片 =========] |
| 头像 李四 女 56岁 |
| 肩高:128cm 肩宽:38cm |
| [编辑] [删除] |
| [============================] |
+----------------------------------+
操作流程 - 查看用户列表：
步骤1：进入用户管理页
→ 调用接口获取用户列表
→ 显示loading动画
→ 加载完成显示用户卡片列表
步骤2：用户切换
→ 点击某个用户卡片
→ 该卡片高亮显示（选中状态）
→ 保存选中用户ID到本地
→ Toast提示"已切换至用户：XXX"
→ 自动返回设备详情页
操作流程 - 新增用户：
步骤1：点击右上角"+ 新增"按钮
→ 进入体形数据录入页
步骤2：填写用户信息
→ 同5.2节补充信息表单
步骤3：点击保存
→ 校验：当前用户数量是否已达到10个
→ 已达10个：Toast提示"最多可添加10个用户，请先删除其他用户"
→ 未满10个：调用新增接口
→ 成功：返回用户列表，显示新用户
→ 失败：提示错误信息
操作流程 - 编辑用户：
步骤1：点击用户卡片的"编辑"按钮
→ 进入编辑页面
→ 表单回显当前用户信息
步骤2：修改信息
→ 同新增流程
步骤3：点击保存
→ 调用编辑接口
→ 成功：返回列表页，刷新显示
操作流程 - 删除用户：
步骤1：点击用户卡片的"删除"按钮
→ 弹出确认弹窗："确定删除用户XXX？删除后将无法恢复"
→ 按钮："取消" / "确定删除"（红色）
步骤2：点击确定
→ 调用删除接口
→ 删除成功：移除该卡片，Toast提示"删除成功"
→ 删除失败：Toast提示错误
详细错误提示清单：
| 场景 | 错误提示 |
|---|---|
| 用户达到上限(10人) | "最多可添加10个用户" |
| 删除最后一个用户 | "至少保留一个用户" |
| 删除失败 | "删除失败，请重试" |
| 编辑时用户不存在 | "用户信息已过期，请刷新" |
| 网络错误 | "网络连接失败，请检查网络" |
6.2 体形数据录入
页面布局：
+----------------------------------+
| < 体形参数 |
+----------------------------------+
| 请录入体形参数，用于精准定位穴位 |
+----------------------------------+
| |
| 肩高（地面到肩膀的高度，cm） |
| +------------------------------+ |
| | 例如：135 | |
| +------------------------------+ |
| [========滑块========] 135cm |
| |
| 肩宽（两肩之间的宽度，cm） |
| +------------------------------+ |
| | 例如：42 | |
| +------------------------------+ |
| [========滑块========] 42cm |
| |
| 体重（kg） |
| +------------------------------+ |
| | 例如：65 | |
| +------------------------------+ |
| |
| +------------------------------+ |
| | 保存 | |
| +------------------------------+ |
+----------------------------------+
操作流程：
步骤1：进入体形参数页
→ 如已有数据则回显
步骤2：填写肩高
→ 输入框输入数字
→ 或拖动滑块调节
→ 范围：50-250cm
步骤3：填写肩宽
→ 输入框输入数字
→ 或拖动滑块调节
→ 范围：20-80cm
步骤4：填写体重
→ 输入框输入数字
→ 范围：10-300kg
步骤5：点击保存
→ 校验所有字段
→ 调用体形数据保存接口
→ 后台触发穴位坐标计算算法
→ 保存成功：返回上一页
→ 保存失败：提示错误
详细错误提示清单：
| 场景 | 错误提示 |
|---|---|
| 肩高为空 | "请输入肩高" |
| 肩高超出范围 | "肩高范围50-250cm" |
| 肩宽为空 | "请输入肩宽" |
| 肩宽超出范围 | "肩宽范围20-80cm" |
| 体重为空 | "请输入体重" |
| 体重超出范围 | "体重范围10-300kg" |
| 保存失败 | "保存失败，请重试" |
6.3 指纹录入绑定
操作流程：
步骤1：在用户管理页选择"指纹录入"
→ 进入指纹录入引导页
步骤2：阅读操作说明
→ 显示图文并茂的操作指引：
"请将手指放在艾灸椅扶手处的指纹采集器上，
听到'滴'声后抬起，重复3次完成录入"
步骤3：点击"开始录入"
→ 通过蓝牙发送指纹采集指令到设备
→ 设备进入指纹录入模式
→ APP显示"等待指纹录入..."
步骤4：用户在设备上录入指纹
→ 设备采集指纹
→ 蓝牙回传指纹ID
步骤5：绑定指纹
→ APP收到指纹ID
→ 调用后台接口绑定用户与指纹ID
→ 显示"指纹录入成功"
→ 返回用户管理页
详细错误提示清单：
| 场景 | 错误提示 | 处理方式 |
|---|---|---|
| 设备未连接 | "请先连接艾灸椅设备" | 引导用户先连接设备 |
| 指纹采集超时 | "指纹采集超时，请重试" | 提供"重新录入"按钮 |
| 指纹质量不佳 | "指纹采集不清晰，请清洁手指后重试" | 重试 |
| 指纹ID回传失败 | "设备通信异常，请检查蓝牙连接" | 重试 |
| 后台绑定失败 | "绑定失败，请稍后再试" | 重试 |
| 该指纹已被绑定 | "该指纹已被其他用户绑定，请更换手指" | 提示更换手指 |
7. 设备管理模块
7.1 我的设备（首页默认页面）
页面布局：
+----------------------------------+
| 我的设备 [+]添加 |
+----------------------------------+
| 已添加的设备 |
+----------------------------------+
| +---------------------------+ |
| | [艾灸椅图片] | |
| | | |
| | 我的艾灸椅 | |
| | ● 已连接 | |
| +---------------------------+ |
| |
| +---------------------------+ |
| | [艾灸椅图片] | |
| | | |
| | 客厅艾灸椅 | |
| | ○ 未连接 | |
| +---------------------------+ |
| |
+----------------------------------+
| [首页] [发现] [健康] [我的] |
+----------------------------------+
操作流程 - 进入页面：
步骤1：点击底部Tab"首页"
→ 检查本地是否有已绑定设备
→ 无设备：显示空状态（"暂无设备，点击添加" + 添加按钮）
→ 有设备：显示设备列表卡片
步骤2：自动刷新设备状态
→ 遍历设备列表尝试蓝牙连接
→ 已连接设备显示"已连接"绿色状态
→ 未连接设备显示"未连接"灰色状态
→ 连接中显示loading动画
错误提示：
| 场景 | 错误提示 |
|---|---|
| 蓝牙未开启 | 提示"蓝牙未开启，部分功能不可用" |
| 刷新状态失败 | "状态刷新失败，下拉重试" |
| 连接超时 | "连接超时，请确保设备在附近且已开机" |
7.2 添加设备流程
完整操作流程：
【步骤1：进入添加页面】
操作：点击"+"按钮
结果：跳转到添加设备页
【步骤2：检查蓝牙状态】
操作：页面自动检查手机蓝牙是否开启
→ 蓝牙已开启：进入步骤3
→ 蓝牙未开启：弹出引导弹窗
弹窗内容："当前手机蓝牙未开启，是否打开以扫描附近蓝牙设备？"
按钮："取消" / "去开启"
点击"取消"：返回上一页
点击"去开启"：跳转系统蓝牙设置
→ 用户开启蓝牙后返回APP
→ 自动进入步骤3
【步骤3：搜索设备】
页面显示：
- 中央：蓝牙信号搜索动画（波纹扩散效果）
- 文字："正在搜索附近设备..."
- 下方："请确保艾灸椅已接通电源并处于待连接状态"
后台行为：
→ 调用 uni.openBluetoothAdapter 初始化蓝牙
→ 调用 uni.startBluetoothDevicesDiscovery 开始搜索
→ 监听 uni.onBluetoothDeviceFound 事件
→ 超时设置：30秒
【步骤4：搜索结果处理】
情况A：搜索到艾灸椅设备
→ 底部弹出设备选择弹窗
→ 弹窗标题："搜索到以下设备"
→ 列表显示发现的设备名称（过滤非艾灸椅设备）
→ 点击设备项选中（高亮）
→ 按钮："取消" / "连接"
点击"连接"后：
→ 显示"正在连接..."
→ 调用 uni.createBLEConnection
→ 连接成功：
→ 停止搜索
→ 发现GATT服务和特征值
→ 显示"连接成功"
→ 1秒后自动跳转到设备详情页
→ 连接失败：
→ 提示"连接失败，请重试"
→ 保留在弹窗，可重新选择
情况B：未搜索到设备（30秒超时）
→ 停止搜索动画
→ 显示"未扫描到设备"
→ 提示文字："请检查：\n1. 手机蓝牙是否已开启\n2. 艾灸椅是否已接通电源\n3. 艾灸椅是否在附近（10米内）"
→ 按钮："重新搜索" / "手动输入"
→ 点击"重新搜索"：回到步骤3
情况C：搜索过程中蓝牙被关闭
→ 停止搜索
→ 提示"蓝牙已关闭，搜索已停止"
→ 提供"开启蓝牙重新搜索"按钮
【步骤5：绑定设备】
操作：首次连接成功后自动绑定
→ 调用后台接口：绑定设备到当前用户
→ 保存设备信息到本地
→ 保存蓝牙MAC地址用于自动重连
→ Toast提示"设备添加成功"
详细错误提示清单：
| 场景 | 错误提示 | 处理方式 |
|---|---|---|
| 蓝牙适配器初始化失败 | "蓝牙初始化失败，请重启手机蓝牙" | 引导重启蓝牙 |
| 搜索被其他应用占用 | "蓝牙搜索被占用，请关闭其他应用后重试" | 提示关闭其他BLE应用 |
| 连接被拒绝 | "连接被拒绝，请确认设备是否处于配对模式" | 引导检查设备 |
| 连接超时 | "连接超时，请确保设备在有效范围内" | 重试 |
| 服务发现失败 | "设备服务异常，请重启设备后重试" | 引导重启设备 |
| 特征值获取失败 | "设备通信异常" | 断开重连 |
| 绑定后台接口失败 | "设备绑定失败，请检查网络" | 本地保存，网络恢复后重试 |
| 已达到最大绑定数 | "每个账号最多绑定5台设备" | 提示解绑旧设备 |
7.3 设备详情页
页面布局：
+----------------------------------+
| < 我的艾灸椅 [≡]菜单 |
+----------------------------------+
| |
| [艾灸椅3D图] |
| ● 大椎穴 |
| |
| 蓝牙已连接 |
| |
+----------------------------------+
| 选择模式 |
| +----------------------------+ |
| | 专业模式 [切换→] | |
| +----------------------------+ |
+----------------------------------+
| 其他功能 |
| [⭐我的方案] [📦艾灸余量] [🔧滤芯状态] |
+----------------------------------+
| |
| +------------------------------+ |
| | [开始按钮] | |
| | ● | |
| | 开始 | |
| +------------------------------+ |
+----------------------------------+
页面布局 - 艾灸执行中状态：
+----------------------------------+
| < 我的艾灸椅 [≡]菜单 |
+----------------------------------+
| [设备] [穴位] |
| [艾灸椅3D图/穴位图] |
| ● 大椎穴 |
| |
| 蓝牙已连接 |
+----------------------------------+
| 选择模式 |
| +----------------------------+ |
| | 自定义模式 [切换→] | |
| +----------------------------+ |
+----------------------------------+
| 其他功能 |
| [📦艾灸余量] [🔧滤芯状态] |
+----------------------------------+
| 正在艾灸 00:10:38 |
| [继续] [暂停] [结束] |
+----------------------------------+
Tab切换 - 设备/穴位：
| Tab | 显示内容 |
|---|---|
| 设备 | 艾灸椅3D模型图，当前施灸穴位红点标记 |
| 穴位 | 人体背部穴位图，白色圆点标记所有穴位，红色标记当前穴位 |
操作流程 - 模式切换：
步骤1：点击"选择模式"卡片
→ 底部弹出模式选择弹窗
步骤2：选择模式
→ 无艾灸模式
→ 专业模式
→ 自定义模式
步骤3：点击确认
→ 关闭弹窗，更新显示的模式名称
→ 同时更新下方功能区域显示
7.4 设备状态监控
操作流程 - 查看耗材状态：
步骤1：点击"艾灸余量"图标
→ 进入耗材管理页面
步骤2：页面显示
→ 尘盒滤芯：进度条 + 百分比（如75%）
→ 艾灸柱：剩余数量（如5个）
步骤3：实时监控
→ 通过蓝牙轮询读取传感器数据（每5秒）
→ 数据变化时更新显示
→ 艾材余量≤3：进度条变红色
→ 废料舱≥80%：进度条变红色
状态阈值与提示：
| 监控项 | 正常 | 预警 | 危险 | 操作限制 |
|---|---|---|---|---|
| 艾材余量 | >3个 | 1-3个 | 0个 | =0时禁止启动艾灸 |
| 废料舱 | <80% | 80-99% | 100% | ≥100%时禁止启动 |
| 滤芯寿命 | <80% | 80-99% | 100% | ≥100%时提醒更换 |
预警提示文案：
| 场景 | 提示方式 | 提示文案 |
|---|---|---|
| 艾材余量=3 | Toast | "艾材余量不足，剩余3个，请及时补充" |
| 艾材余量=1 | 弹窗 | "艾材即将用完，只剩1个，建议补充后再使用" |
| 艾材余量=0 | 弹窗 | "艾材已用完，无法启动艾灸，请补充艾材" |
| 废料舱=80% | Toast | "废料舱即将满仓，请及时清理" |
| 废料舱=100% | 弹窗 | "废料舱已满，无法启动艾灸，请清理废料舱" |
| 滤芯=80% | Toast | "滤芯使用寿命即将到期，建议更换" |
| 滤芯=100% | 弹窗 | "滤芯已到期，请更换滤芯以保证使用效果" |
7.5 座椅角度调节
页面布局：
+----------------------------------+
| < 座椅角度调节 |
+----------------------------------+
| |
| [艾灸椅侧视图] |
| 当前角度：100° |
| |
| 90° [========●===========] 150° |
| 拖动滑块调节角度 |
| |
| 快捷角度： |
| [ 90° ] [ 110° ] [ 130° ] [ 150° ]|
+----------------------------------+
操作流程：
步骤1：进入座椅角度调节页
→ 显示当前角度值
→ 滑块定位到当前角度
步骤2A：拖动滑块调节
→ 实时显示角度值（整数）
→ 松开手指后：通过蓝牙发送目标角度指令
→ 设备执行角度调节
→ 设备反馈到位信号后更新显示
步骤2B：点击快捷角度按钮
→ 直接设置到对应角度
→ 蓝牙发送目标角度指令
步骤3：调节完成
→ 点击返回按钮回到设备详情页
错误提示：
| 场景 | 错误提示 |
|---|---|
| 设备未连接 | "设备未连接，无法调节角度" |
| 调节超时 | "角度调节超时，请检查设备" |
| 调节被中断 | "调节被中断，当前角度：XXX°" |
8. 首页-设备控制模块
8.1 模式选择流程
操作流程：
步骤1：在设备详情页点击"选择模式"区域
→ 底部弹出模式选择面板
步骤2：面板内容
→ 单选列表：
○ 无艾灸模式
副标题："纯休闲模式，享受白噪音和座椅按摩"
○ 专业模式
副标题："选择功效，自动匹配灸方"
○ 自定义模式
副标题："自选穴位，个性化艾灸方案"
→ 底部："模式说明"链接
步骤3：选择一个模式
→ 该选项高亮（单选）
→ 其他选项取消选中
步骤4：点击"确认"或点击蒙层关闭
→ 更新首页显示的模式名称
→ 根据模式切换下方功能区域
模式说明弹窗内容：
- 无艾灸模式：不启动艾灸功能，仅使用座椅角度调节和白噪音播放功能
- 专业模式：选择八大功效之一，系统自动根据您的体形数据计算穴位并匹配灸方
- 自定义模式：手动选择穴位、设置时长和温度，编辑个性化艾灸方案
8.2 开始艾灸流程
操作流程（通用）：
前置检查（点击开始按钮时自动执行）：
1. 检查蓝牙连接 → 未连接：提示"请先连接设备"
2. 检查艾材余量 → =0：提示"艾材不足，请补充"
3. 检查废料舱 → =100%：提示"废料舱已满，请清理"
4. 检查滤芯 → =100%：提示"滤芯已到期，请更换"
步骤1：点击"开始"按钮
→ 按钮变为loading状态
→ 根据当前模式准备艾灸数据
步骤2：进入预热阶段
→ 显示"正在预热 X%"
→ 进度条动态增长
→ 此阶段设备预热艾材
→ 显示倒计时（如30秒预热）
步骤3：预热完成
→ 显示"已完成预热 100%"
→ 弹窗："已完成预热，即将开始艾灸5s"
→ 3秒倒计时自动关闭，或点击"确认"
步骤4：艾灸开始
→ 更新UI为"正在艾灸"状态
→ 显示倒计时
→ 开始播放白噪音（如已选择）
→ 开始接收设备状态上报
步骤5：艾灸过程中
→ 实时更新：当前穴位、剩余时长、当前温度、当前手法
→ 穴位Tab显示当前施灸穴位红色标记
9. 无艾灸模式（休闲模式）
9.1 模式配置页
页面布局：
+----------------------------------+
| < 无艾灸模式 |
+----------------------------------+
| |
| 座椅角度（拖动滑块调整） |
| [====●===========] 100° |
| |
+----------------------------------+
| 选择模式 |
| +----------------------------+ |
| | 无艾灸模式 [切换→] | |
| +----------------------------+ |
+----------------------------------+
| 白噪音 |
| +----------------------------+ |
| | [⏵] 河流 03:21 / --:--| |
| | 夏雨 | |
| | 森林 | |
| | 鸟鸣 | |
| | 漂流 | |
| | 雨滴 | |
| | 炉火 | |
| | 海浪 | |
| +----------------------------+ |
| |
| 音量 |
| [--●----------] |
| [🔔] 一键静音 |
+----------------------------------+
| |
| +------------------------------+ |
| | 开始 | |
| +------------------------------+ |
+----------------------------------+
9.2 音效控制详细操作
操作流程 - 选择音效：
步骤1：在音效列表中点击某一项
→ 该项高亮显示
→ 自动开始播放
→ 播放按钮变为暂停图标
→ 显示播放进度条
步骤2：播放控制
→ 点击暂停：暂停播放，按钮变为播放图标
→ 点击继续：继续播放
→ 进度条可拖动快进/快退
步骤3：切换音效
→ 点击其他音效项
→ 当前音效淡出
→ 新音效淡入播放
→ 更新进度条
步骤4：停止播放
→ 模式切换或退出页面时自动停止
音量调节：
步骤1：拖动音量滑块
→ 实时调节音量（0-100%）
→ 通过蓝牙发送音量控制指令
步骤2：点击静音按钮
→ 一键静音（音量设为0）
→ 静音图标变为带斜杠
→ 保留系统提示音不受静音影响
步骤3：再次点击静音
→ 恢复静音前的音量值
错误提示：
| 场景 | 错误提示 |
|---|---|
| 音效播放失败 | "音效播放失败，请重试" |
| 蓝牙音量控制失败 | "音量调节失败，请检查设备连接" |
10. 专业模式（一键艾灸）
10.1 功效选择页面
页面布局：
+----------------------------------+
| < 选择功效 |
+----------------------------------+
| 请选择您需要的艾灸功效 |
+----------------------------------+
| +------------+ +------------+ |
| | ❄️ | | 💨 | |
| | 驱寒 | | 祛风 | |
| +------------+ +------------+ |
| |
| +------------+ +------------+ |
| | 💧 | | 🩸 | |
| | 祛湿 | | 化瘀 | |
| +------------+ +------------+ |
| |
| +------------+ +------------+ |
| | 🫁 | | ❤️ | |
| | 化痰 | | 活血 | |
| +------------+ +------------+ |
| |
| +------------+ +------------+ |
| | ☀️ | | 🌸 | |
| | 扶阳 | | 养颜 | |
| +------------+ +------------+ |
+----------------------------------+
| +------------------------------+ |
| | 确认选择 | |
| +------------------------------+ |
+----------------------------------+
操作流程：
步骤1：进入功效选择页
→ 显示8种功效网格
→ 无默认选中项
步骤2：选择功效
→ 点击某个功效卡片
→ 卡片高亮（选中状态）
→ 再次点击取消选中
步骤3：确认选择
→ 点击"确认选择"按钮
→ 校验：必须选中至少1个功效
→ 未选中：提示"请至少选择一种功效"
→ 已选中：进入艾灸准备流程
步骤4：一键艾灸准备
→ 显示loading："正在为您计算穴位方案..."
→ APP读取当前选中用户的体形数据
→ 调用后台接口：用户穴位坐标计算
参数：用户ID、体形数据（肩高/肩宽/体重）
返回：各穴位坐标参数
→ 调用后台接口：功效-灸方参数匹配
参数：作用类型、穴位坐标
返回：灸方参数（穴位/温度/手法/时长）
→ 计算完成：显示方案摘要弹窗
步骤5：方案确认弹窗
→ 显示内容：
"为您匹配的艾灸方案："
"施灸穴位：大椎穴、风池穴、肩井穴..."
"总时长：25分钟"
"温度：40℃"
→ 按钮："重新选择" / "开始艾灸"
→ 点击"开始艾灸"：进入预热流程
功效说明：
| 功效 | 适用症状 | 灸方特点 |
|---|---|---|
| 驱寒 | 手脚冰凉、畏寒怕冷 | 温热灸法，重点督脉 |
| 祛风 | 风寒感冒、头痛 | 祛风穴位组合 |
| 祛湿 | 身体困重、水肿 | 健脾祛湿穴位 |
| 化瘀 | 血瘀疼痛、经络不通 | 活血化瘀手法 |
| 化痰 | 咳嗽痰多、胸闷 | 理气化痰穴位 |
| 活血 | 血液循环不畅 | 促进血液循环 |
| 扶阳 | 阳气不足、乏力 | 温补阳气穴位 |
| 养颜 | 面色暗沉、皮肤松弛 | 面部相关穴位 |
详细错误提示清单：
| 场景 | 错误提示 | 处理方式 |
|---|---|---|
| 未选择功效 | "请至少选择一种功效" | 停留在选择页 |
| 用户无体形数据 | "请先完善体形信息" | 跳转到体形录入页 |
| 穴位计算接口失败 | "方案生成失败，请检查网络后重试" | 提供重试按钮 |
| 灸方匹配失败 | "灸方匹配失败，请尝试其他功效" | 返回功效选择 |
| 蓝牙未连接 | "设备未连接，无法开始艾灸" | 引导连接设备 |
| 用户切换后无数据 | "当前用户无体形数据，请先录入" | 跳转体形录入 |
10.2 多功效组合选择（扩展功能）
如需支持多功效同时选择：
操作：点击多个功效卡片（多选）
→ 多个卡片同时高亮
→ 按钮显示"已选X种功效"
限制：最多同时选择3种功效
→ 选第4个时提示"最多同时选择3种功效"
11. 自定义模式
11.1 穴位选择页面
页面布局：
+----------------------------------+
| < 穴位编辑 [设备][穴位] |
+----------------------------------+
| |
| [人体背部穴位图] |
| ○ ○ ○ |
| ○ ● ○ |
| ○ ○ ○ |
| ○ ○ ○ |
| |
| ○ 大椎穴 ○ 风池穴 ○ 肩井穴 |
| （白色=未选 红色=已选 黄色=当前）|
| |
+----------------------------------+
| 已选穴位(0/3)： |
| |
| +------------------------------+ |
| | 开始 | |
| +------------------------------+ |
+----------------------------------+
操作流程 - 穴位选择：
步骤1：进入穴位编辑页
→ 默认显示"穴位"Tab
→ 显示人体背部穴位图
→ 所有可用穴位显示白色圆点
→ 底部显示"已选穴位(0/3)"
步骤2：点击穴位
→ 方式A：点击图上穴位点
→ 该穴位变为红色（选中状态）
→ 显示穴位名称标签
→ 底部"已选穴位"计数+1
→ 弹出时长温度设定面板
→ 方式B：点击下方穴位名称列表
→ 同上效果
步骤3：设置时长和温度（弹出面板）
→ 温度选择：38℃ / 40℃ / 42℃ / 44℃（单选）
→ 时长选择：5分 / 10分 / 15分 / ... / 50分（单选）
→ 按钮："取消" / "确认"
→ 点击确认：保存该穴位参数，面板关闭
步骤4：继续添加穴位（可选）
→ 重复步骤2-3
→ 最多3个穴位
→ 选第4个时：弹窗"单次最多可选择3个穴位"
步骤5：总时长校验
→ 每次添加后校验总时长
→ 总时长 = 所有穴位时长之和
→ 总时长 > 30分钟：弹窗"总时长不超过30分钟，请重新分配"
→ 超出时：要求用户减少某个穴位的时长
步骤6：调整穴位顺序
→ 在已选穴位列表中长按拖拽
→ 调整执行顺序
→ 蓝牙下发时按此顺序
步骤7：二次修改穴位参数
→ 点击已选的穴位
→ 重新弹出时长温度面板
→ 回显已设置的参数
→ 修改后确认
步骤8：删除穴位
→ 在已选穴位列表中左滑
→ 显示"删除"按钮
→ 点击删除，该穴位恢复白色
步骤9：点击"开始"按钮
→ 校验：至少选择1个穴位
→ 未选穴位：提示"请至少选择一个穴位"
→ 已选穴位：进入艾灸预热流程
穴位图交互说明：
| 状态 | 颜色 | 说明 |
|---|---|---|
| 未选中 | 白色 | 可选的穴位 |
| 已选中 | 红色 | 已添加到方案的穴位 |
| 当前施灸 | 黄色闪烁 | 艾灸执行中正在施灸的穴位 |
详细错误提示清单：
| 场景 | 错误提示 | 处理方式 |
|---|---|---|
| 未选穴位点开始 | "请至少选择一个穴位" | 停留页面 |
| 穴位超过3个 | "单次最多可增加3个穴位" | 阻止添加 |
| 总时长超30分钟 | "总时长不超过30分钟，请重新分配" | 弹出时长调整面板 |
| 温度未设置 | "请为每个穴位设置温度" | 引导设置 |
| 时长未设置 | "请为每个穴位设置时长" | 引导设置 |
| 穴位坐标获取失败 | "穴位数据加载失败，请下拉刷新" | 下拉刷新 |
11.2 保存自定义方案
操作流程：
触发条件：自定义模式编辑完成后
步骤1：编辑完成后不直接开始，可选择保存
→ 显示"保存方案"按钮
步骤2：点击"保存方案"
→ 弹出输入框："请输入方案名称"
→ 默认名称："自定义方案 + 当前日期"
→ 最多30个字符
步骤3：输入名称并确认
→ 校验名称是否为空
→ 调用后台接口保存方案
参数：用户ID + 方案名称 + 艾灸工艺数组 + 总时长
→ 保存成功：Toast"方案保存成功"，跳转到我的方案页
→ 保存失败：提示错误
12. 艾灸执行过程
12.1 预热阶段
操作流程：
步骤1：点击开始 → 进入预热
→ 显示"正在预热 0%"
→ 圆形/条形进度条动画
→ 预计预热时间：30秒
步骤2：预热进度更新
→ 蓝牙接收设备预热进度上报
→ 进度条动态增长：0% → 25% → 50% → 75% → 100%
→ 显示预计剩余时间
步骤3：预热完成
→ 进度条达到100%
→ 显示"已完成预热"
→ 弹窗："已完成预热，即将开始艾灸"
→ 3秒倒计时，或点击"确认"立即开始
→ 弹窗关闭，进入艾灸执行阶段
异常情况 - 预热失败：
→ 进度长时间不更新（超时60秒）
→ 弹窗："预热超时，请检查设备后重试"
→ 按钮："重试" / "取消"
异常情况 - 预热中断：
→ 蓝牙断开
→ 提示"连接已断开，预热中断"
→ 重新连接后可重新开始
12.2 艾灸执行阶段
设备Tab显示内容：
+----------------------------------+
| [设备] [穴位] |
| [艾灸椅3D图] |
| ● 大椎穴 |
| （红色标记当前穴位） |
+----------------------------------+
| 正在艾灸 |
| 剩余时间：00:08:25 |
| 当前穴位：大椎穴 |
| 当前温度：40℃ |
| 当前手法：悬定灸 |
+----------------------------------+
| [⏵ 继续] [⏸ 暂停] [⏹ 结束] |
+----------------------------------+
穴位Tab显示内容：
+----------------------------------+
| [设备] [穴位] |
| [人体背部穴位图] |
| ○ ○ ○ |
| ○ 🟡 ○ |
| ○ ○ ○ |
| ○ ○ ○ |
| （🟡黄色=当前施灸穴位） |
+----------------------------------+
操作 - 暂停：
步骤1：点击"暂停"按钮
→ 通过蓝牙发送暂停指令
→ 设备：灸头后退2cm（安全距离）
→ 设备：暂停计时
→ APP状态更新："已暂停"
→ 按钮切换：显示"继续"按钮
步骤2：暂停状态显示
→ 倒计时停止
→ 显示"已暂停 剩余XX:XX"
→ 温度显示逐步降低（自然散热）
操作 - 继续：
步骤1：点击"继续"按钮
→ 通过蓝牙发送继续指令
→ 设备：灸头回到施灸位置
→ 设备：恢复计时
→ APP状态更新："正在艾灸"
→ 按钮切换：显示"暂停"按钮
操作 - 结束：
步骤1：点击"结束"按钮
→ 弹出二次确认弹窗
→ "确定结束本次艾灸？"
→ 按钮："取消" / "确定结束"（红色）
步骤2：确认结束
→ 通过蓝牙发送结束指令
→ 设备：灸头归位，停止加热
→ APP显示"艾灸已完成"
→ 上报使用记录到后台
→ 3秒后自动返回设备详情页（待机状态）
步骤3：取消结束
→ 关闭弹窗，继续艾灸
12.3 温度监控与安全防护
温度监控流程：
实时上报：
→ 设备每2秒上报一次温度数据
→ APP更新温度显示
→ 温度曲线可查看（可选功能）
超温保护：
→ 温度超过安全阈值
→ 设备自动切换为"雀啄灸"手法（快速提插，避免持续高温）
→ APP显示："温度过高，已自动切换手法防止灼伤"
→ 温度回落后恢复正常手法
极端超温：
→ 温度持续超限
→ 设备自动暂停
→ APP显示警告："温度异常，艾灸已自动暂停，请检查"
12.4 艾灸完成
正常完成流程：
步骤1：最后一个穴位施灸完成
→ 设备发送完成信号
→ 蓝牙上报完成状态
步骤2：APP显示
→ "艾灸已完成"
→ 显示本次艾灸摘要：
- 施灸穴位列表
- 总时长
- 平均温度
→ 播放完成提示音
步骤3：数据上报
→ 自动上报使用记录到后台
→ 参数：用户ID/时间/功效/穴位/时长/温度
步骤4：3秒后自动返回设备详情页（待机状态）
12.5 异常中断处理
| 中断原因 | 处理方式 | 用户提示 |
|---|---|---|
| 蓝牙断开 | 自动重连（3次），失败后暂停艾灸 | "蓝牙连接断开，正在尝试重连..." |
| APP被杀掉 | 设备继续执行（独立运行） | 下次打开APP恢复状态 |
| 设备断电 | 艾灸终止 | "设备已断电" |
| 检测到异物 | 设备自动暂停 | "检测到有异物，已暂停艾灸，清理后重试" |
| 艾材用完 | 设备自动暂停 | "艾材已用完，艾灸已暂停" |
| 多手机操控 | 当前操控权被抢占 | "当前设备正在被其他手机操控" |
13. 我的方案管理
13.1 方案列表页面
页面布局：
+----------------------------------+
| < 我的方案 |
+----------------------------------+
| |
| +---------------------------+ |
| | 一套针对颈椎的艾灸方案 | |
| | 王凤娇 | |
| | [使用] | |
| +---------------------------+ |
| |
| +---------------------------+ |
| | 艾灸方案二 | |
| | [使用] | |
| +---------------------------+ |
| |
| +---------------------------+ |
| | 艾灸方案三 | |
| | [使用] | |
| +---------------------------+ |
| |
| [更多方案] |
+----------------------------------+
操作流程 - 查看列表：
步骤1：从设备详情页点击"我的方案"
→ 进入方案列表页
→ 调用接口获取当前用户的方案列表
→ 按创建时间倒序排列
→ 显示loading → 显示列表
步骤2：方案操作
→ 点击方案卡片：进入方案详情
→ 点击"使用"按钮：直接应用该方案开始艾灸
→ 左滑方案卡片：显示"删除"按钮
操作流程 - 删除方案：
步骤1：左滑方案卡片
→ 显示红色"删除"按钮
步骤2：点击删除
→ 弹出确认："确定删除方案XXX？"
→ 取消：关闭弹窗
→ 确认：调用删除接口
→ 成功：移除卡片，Toast"删除成功"
→ 失败：Toast"删除失败"
13.2 方案详情页面
页面布局：
+----------------------------------+
| < 方案详情 |
+----------------------------------+
| |
| 方案名称：一套针对颈椎的艾灸方案 |
| 作者：王凤娇 |
| |
| 艾灸穴位： |
| 1. 大椎穴 - 15分钟 - 40℃ |
| 2. 风池穴 - 10分钟 - 42℃ |
| 3. 肩井穴 - 10分钟 - 40℃ |
| |
| 总时长：35分钟 |
| |
| [编辑方案] [立即使用] |
+----------------------------------+
操作 - 立即使用：
步骤1：点击"立即使用"
→ 弹窗确认"使用该方案开始艾灸？"
→ 确认：进入艾灸预热流程
→ 取消：关闭弹窗
13.3 从发现页添加方案
操作流程：
步骤1：在发现页浏览公用方案
→ 进入方案详情页
→ 显示"添加到我的方案"按钮
步骤2：点击"添加到我的方案"
→ 弹窗："确认添加到我的方案？"
→ 按钮："取消" / "确认"
步骤3：点击确认
→ 调用后台接口：复制方案到个人方案（深拷贝）
→ 成功：Toast"已添加到我的方案"
→ 失败：提示错误
权限控制：
→ 公用方案：所有用户可见，可复制到个人方案
→ 个人方案：仅本人可见
→ 定向方案：仅指定用户可见
13.4 多用户方案同步
操作流程：
步骤1：切换用户
→ 进入用户管理页
→ 选择另一个用户
步骤2：方案自动切换
→ 刷新方案列表
→ 显示当前用户的方案
→ 不同用户的方案完全隔离
步骤3：方案同步到设备
→ 选择方案后点击"同步到设备"
→ 蓝牙发送方案数据包到设备
→ 设备本地存储该方案
→ 后续可通过指纹直接调用
13.5 离线方案使用
网络正常时：
→ 方案列表从服务器获取
→ 同时缓存到本地数据库
网络异常时：
→ 从本地数据库读取方案列表
→ 可查看已保存的方案
→ 已同步到设备的方案可直接通过蓝牙使用
→ 无需网络即可完成艾灸
蓝牙直连模式：
→ 无需网络
→ 直接使用已同步到设备的方案
→ 通过指纹识别调用用户方案
14. 发现模块
14.1 发现首页
页面布局：
+----------------------------------+
| [LOGO] |
+----------------------------------+
| [======== Banner轮播 ========] |
| 源自天然古法精髓 |
| 手工艾灸，延传养生之道 |
+----------------------------------+
| 热灸推荐 |
| +---------------------------+ |
| | [图] 颈腰同治-督脉艾灸方案 | |
| | 缓解颈椎僵硬与腰椎酸痛 | |
| | 45分钟 | |
| +---------------------------+ |
| +---------------------------+ |
| | [图] 通络强背-脊柱养护方案 | |
| | 改善胸背疼痛与脊柱侧弯 | |
| | 60分钟 | |
| +---------------------------+ |
+----------------------------------+
| 灸研室 [更多] |
| +---------+ +---------+ |
| |[图]方案1| |[图]方案2| |
| +---------+ +---------+ |
| +---------+ +---------+ |
| |[图]方案3| |[图]方案4| |
| +---------+ +---------+ |
+----------------------------------+
| [首页] [发现] [健康] [我的] |
+----------------------------------+
操作流程 - 浏览首页：
步骤1：点击底部Tab"发现"
→ 加载发现页数据
→ Banner轮播自动播放（每3秒切换）
→ 显示热灸推荐列表
→ 显示灸研室方案网格
步骤2：Banner操作
→ 左右滑动切换
→ 点击Banner进入对应详情页
步骤3：热灸推荐
→ 上下滑动浏览
→ 点击方案卡片进入方案详情
步骤4：灸研室
→ 点击"更多"进入专家方案列表
→ 点击方案卡片进入方案详情
错误提示：
| 场景 | 错误提示 |
|---|---|
| 数据加载失败 | "内容加载失败，下拉刷新试试" |
| Banner加载失败 | 显示默认占位图 |
| 图片加载失败 | 显示默认占位图 |
14.2 专家方案列表
页面布局：
+----------------------------------+
| < 专家方案 |
+----------------------------------+
| |
| +--------+ +--------+ |
| |[图] | |[图] | |
| |方案一名| |方案二名| |
| |简介... | |简介... | |
| +--------+ +--------+ |
| |
| +--------+ +--------+ |
| |[图] | |[图] | |
| |方案三名| |方案四名| |
| |简介... | |简介... | |
| +--------+ +--------+ |
+----------------------------------+
操作流程：
步骤1：从发现页点击"更多"进入
→ 调用接口获取专家方案列表
→ 2列网格布局展示
步骤2：浏览方案
→ 上下滑动浏览
→ 上拉加载更多（分页加载）
→ 下拉刷新
步骤3：点击方案卡片
→ 进入方案详情页
14.3 方案详情页
页面布局：
+----------------------------------+
| < 分享 |
| [========= 方案大图 =========] |
+----------------------------------+
| 一套针对颈椎的艾灸方案 |
| 王凤娇 |
| [立即体验] |
+----------------------------------+
| 简介 |
| 通过艾灸特定穴位，缓解颈椎病症状...|
| [展开] |
+----------------------------------+
| 艾灸穴位 |
| 1. 风池穴 |
| • 定位：枕骨下方，胸锁乳突肌与 |
| 斜方肌上端之间的凹陷处 |
| • 作用：疏风散寒，缓解头痛、颈痛 |
| 2. 大椎穴 |
| • 定位：第七颈椎棘突下凹陷中 |
| • 作用：通阳解表，缓解颈肩疼痛 |
| ... |
+----------------------------------+
| 适用人群 |
| • 颈椎病患者 |
| • 长期伏案工作者 |
| • 颈部肌肉紧张者 |
+----------------------------------+
| 注意事项 |
| 1. 保暖：艾灸后避免受风受寒 |
| 2. 时间控制：每次艾灸时间不宜过长 |
| 3. 皮肤保护：艾灸前可在皮肤上涂 |
| 少量凡士林，防止灼伤 |
+----------------------------------+
操作流程：
步骤1：浏览方案详情
→ 上下滚动查看完整内容
→ 简介区域默认折叠，点击"展开"查看全部
步骤2：点击"立即体验"
→ 判断登录状态
→ 未登录：跳转登录页
→ 已登录：弹窗"确认添加到我的方案？"
→ 点击"确认"
→ 调用方案复制接口（深拷贝）
→ 成功：Toast"已添加到我的方案"
→ 可跳转"我的方案"或留在当前页
→ 点击"取消"：关闭弹窗
步骤3：点击"分享"
→ 唤起系统分享面板
→ 可分享给微信好友/朋友圈
15. 健康模块
15.1 推荐列表页面
页面布局：
+----------------------------------+
| 推荐 |
+----------------------------------+
| +--------+ +--------+ |
| |[图] | |[图] | |
| |文章标题| |文章标题| |
| |官方 12-21| |官方 12-20| |
| +--------+ +--------+ |
| +--------+ +--------+ |
| |[图] | |[图] | |
| |文章标题| |文章标题| |
| |官方 12-19| |官方 12-18| |
| +--------+ +--------+ |
+----------------------------------+
| [首页] [发现] [健康] [我的] |
+----------------------------------+
操作流程：
步骤1：点击底部Tab"健康"
→ 加载推荐文章列表
→ 2列网格布局
步骤2：浏览文章
→ 上下滑动
→ 下拉刷新
→ 上拉加载更多
步骤3：点击文章卡片
→ 进入文章详情页
15.2 文章详情页
页面布局：
+----------------------------------+
| < 详情 |
+----------------------------------+
| |
| [========= 文章配图 =========] |
| |
| 灸后调养做好这三点，效果会更好！ |
| |
| 2024-12-21 研年健康贴士 |
| |
| -------------------------------- |
| |
| 关注艾灸后调养的三个要素：休息... |
| |
| 1. 灸后休息有保障。 |
| 艾灸后，尤其是重灸后对机体来说是 |
| 一个较强的刺激... |
| |
| 2. 灸后锻炼要适度。 |
| "生命在于运动"，任何疗法也代替不 |
| 了运动。但是... |
| |
| [展开全文] |
+----------------------------------+
操作流程：
步骤1：进入文章详情
→ 加载文章内容（富文本渲染）
→ 图片懒加载
步骤2：阅读文章
→ 上下滚动
→ 长文默认折叠，点击"展开全文"
→ 展开后可继续阅读
步骤3：返回
→ 点击返回按钮
→ 回到推荐列表（保持浏览位置）
错误提示：
| 场景 | 错误提示 |
|---|---|
| 文章加载失败 | "文章加载失败，请重试" |
| 图片加载失败 | 显示默认占位图 |
16. 消息中心模块
16.1 消息列表页面
页面布局：
+----------------------------------+
| < 消息中心 |
+----------------------------------+
| [全部] [系统通知] [方案推送] |
+----------------------------------+
| [头像] 系统消息 |
| 向您推荐了新的艾灸方案 |
| 2025-03-27 21:37 |
| [●未读] |
+----------------------------------+
| [头像] 孙佳敏 |
| 向您推荐了新的艾灸方案 |
| 2025-03-26 22:36 |
| |
+----------------------------------+
| [头像] 钱博雯 |
| 向您推荐了新的艾灸方案 |
| 2025-03-26 00:57 |
| |
+----------------------------------+
操作流程 - 查看消息：
步骤1：进入消息中心
→ 从个人中心点击"系统消息"进入
→ 默认显示"全部"Tab
→ 调用接口获取消息列表
→ 显示未读消息红点
步骤2：筛选消息
→ 点击Tab切换：全部/系统通知/方案推送
→ 切换时刷新列表
步骤3：点击消息
→ 标记为已读（红点消失）
→ 调用已读接口
→ 根据消息类型跳转：
- 方案推送：跳转到对应方案详情
- 系统通知：显示通知详情
步骤4：下拉刷新
→ 刷新消息列表
→ 同步未读消息数
操作流程 - 未读消息处理：
APP启动时：
→ 调用接口查询未读消息数量
→ 数量>0：在个人中心"系统消息"项显示红点+数字
→ 数量=0：不显示红点
收到推送时：
→ 显示系统通知栏推送
→ APP内未读数+1
→ 如果APP在前台，显示Toast提示
错误提示：
| 场景 | 错误提示 |
|---|---|
| 消息加载失败 | "消息加载失败，请重试" |
| 标记已读失败 | 本地先标记，后台异步同步 |
17. 个人中心模块
17.1 个人中心首页
页面布局：
+----------------------------------+
| |
| 15066998888 |
| 这是简介 |
| [圆形头像] |
| |
+----------------------------------+
| ⭐ 个性化方案 > |
+----------------------------------+
| 🔔 系统消息 > |
+----------------------------------+
| ⬆️ 版本升级 > |
+----------------------------------+
| ❓ 帮助 > |
+----------------------------------+
| 📋 使用记录 > |
+----------------------------------+
| ⬅️ 退出登录 > |
+----------------------------------+
| [首页] [发现] [健康] [我的] |
+----------------------------------+
17.2 个性化方案
操作流程：
步骤1：点击"个性化方案"
→ 跳转到"我的方案"列表页
→ 同13.1方案列表操作
17.3 系统消息
操作流程：
步骤1：点击"系统消息"
→ 跳转到消息中心页
→ 同16.1消息列表操作
→ 进入后自动标记该类消息为已读
17.4 版本升级
页面布局：
+----------------------------------+
| < 版本信息 |
+----------------------------------+
| |
| [APP图标] |
| |
| 研年健康平台 |
| V1.0 |
| |
| +------------------------------+ |
| | 检查更新 | |
| +------------------------------+ |
+----------------------------------+
操作流程 - 检查更新：
步骤1：点击"检查更新"
→ 按钮变为loading
→ 调用版本检测接口
参数：当前平台(iOS/Android/HarmonyOS)、当前版本号
返回：是否有更新、最新版本号、下载URL、更新类型
步骤2：处理检查结果
情况A：已是最新版
→ 提示"当前已是最新版本"
情况B：可选更新
→ 弹窗：
标题："发现新版本 VX.X.X"
内容：更新文案
按钮："暂不更新" / "立即更新"
→ 点击"立即更新"：跳转应用商店/下载URL
情况C：强制更新
→ 弹窗（不可关闭）：
标题："重要更新"
内容："当前版本已不可用，请更新到最新版本"
按钮："立即更新"（唯一选项）
→ 点击后跳转应用商店
→ 不更新则无法继续使用APP
步骤3：更新下载
→ 显示下载进度
→ 下载完成后自动安装（或提示安装）
详细错误提示：
| 场景 | 错误提示 |
|---|---|
| 检查更新失败 | "检查更新失败，请检查网络" |
| 下载失败 | "下载失败，请重试" |
| 安装失败 | "安装失败，请手动安装" |
17.5 帮助中心
页面布局 - FAQ列表：
+----------------------------------+
| < 全部问题 |
+----------------------------------+
| 常见问题 |
| |
| 1. 如何注销 > |
+----------------------------------+
| 2. 如何删除设备 > |
+----------------------------------+
| 3. 如何关闭消息推送 > |
+----------------------------------+
| 4. 搜索不到蓝牙 > |
+----------------------------------+
| 5. 连不上设备 > |
+----------------------------------+
页面布局 - 问题详情：
+----------------------------------+
| < 问题解答 |
+----------------------------------+
| 连不上设备 |
| |
| 1. 检查设备是否接通电源 |
| 2. 确认设备是否收到过外力碰撞， |
| 若有可能已损坏，可联系售后 |
| 维修，售后电话400-000-0000 |
| 3. 检查手机蓝牙是否开启 |
| 4. 确保设备在10米范围内 |
| 5. 尝试重启设备和手机蓝牙 |
+----------------------------------+
操作流程：
步骤1：点击"帮助"
→ 进入FAQ列表页
步骤2：点击问题项
→ 进入问题详情页
→ 显示完整的解答内容
步骤3：返回
→ 点击返回回到列表页
FAQ内容清单：
| 序号 | 问题 | 答案要点 |
|---|---|---|
| 1 | 如何注销 | 个人中心→退出登录 |
| 2 | 如何删除设备 | 首页→长按设备卡片→删除，或进入设备详情解除绑定 |
| 3 | 如何关闭消息推送 | 手机系统设置→通知管理→研年健康→关闭推送 |
| 4 | 搜索不到蓝牙 | 检查蓝牙开启、设备电源、距离10米内、设备未被他手机连接 |
| 5 | 连不上设备 | 检查电源、重启设备、重启蓝牙、确认设备未被占用 |
17.6 使用记录
页面布局：
+----------------------------------+
| < 使用记录 |
+----------------------------------+
| 2025年3月 |
+----------------------------------+
| 我的艾灸椅 |
| 操作记录 |
| 2025-03-31 13:37 |
+----------------------------------+
| 我的艾灸椅 |
| 操作记录 |
| 2025-03-31 05:11 |
+----------------------------------+
| 我的艾灸椅 |
| 操作记录 |
| 2025-03-30 17:23 |
+----------------------------------+
操作流程：
步骤1：点击"使用记录"
→ 进入使用记录页
→ 调用接口获取历史记录
→ 按时间倒序排列
→ 按月分组显示
步骤2：浏览记录
→ 上下滑动
→ 上拉加载更多（分页）
→ 下拉刷新
步骤3：点击记录项
→ 进入记录详情页（可选）
→ 显示：设备/时间/功效/穴位/时长/温度
错误提示：
| 场景 | 错误提示 |
|---|---|
| 记录加载失败 | "加载失败，请重试" |
| 暂无记录 | "暂无使用记录"（空状态） |
17.7 退出登录
操作流程：
步骤1：点击"退出登录"
→ 底部弹出确认面板
→ 标题："确定退出登录？"
→ 按钮："取消" / "退出登录"（红色）
步骤2：点击"取消"
→ 关闭面板，留在当前页
步骤3：点击"退出登录"
→ 清除本地Token
→ 清除本地用户信息（保留设备绑定信息）
→ 跳转到登录页
→ 下次需重新登录
详细错误提示：
| 场景 | 错误提示 |
|---|---|
| 退出时网络异常 | 本地清除数据，不影响退出 |
| 清除数据失败 | 强制清除，跳转到登录页 |
18. 版本升级模块
18.1 自动检查更新
操作流程：
触发时机：
1. APP冷启动时（一天内只检查一次）
2. 用户手动点击"检查更新"
步骤1：调用版本检测接口
→ 参数：平台类型、当前版本号
→ 返回：最新版本信息
步骤2：版本对比
→ 当前版本 < 最新版本：提示更新
→ 当前版本 = 最新版本：不提示
→ 当前版本 > 最新版本：不提示（可能是测试版）
步骤3：更新策略
→ 强制更新：阻断使用，必须更新
→ 可选更新：用户可选择不更新
→ 静默更新：后台下载，下次启动生效
18.2 版本管理后台配置
后台支持配置的字段：
| 字段 | 说明 |
|---|---|
| 平台 | iOS / Android / HarmonyOS |
| 版本号 | 如 1.0.0 |
| 更新类型 | 强制更新 / 可选更新 / 静默更新 |
| 下载地址 | App Store链接 或 APK下载URL |
| 更新文案 | 显示给用户看的更新说明 |
| 最低支持版本 | 低于此版本必须更新 |
19. 蓝牙通信规范
19.1 蓝牙连接状态机
[未初始化] --openAdapter--> [已初始化]
[已初始化] --startScan--> [扫描中]
[扫描中] --foundDevice--> [发现设备]
[发现设备] --connect--> [连接中]
[连接中] --success--> [已连接]
[连接中] --fail--> [连接失败]
[连接失败] --retry--> [连接中]
[已连接] --disconnect--> [已断开]
[已断开] --autoReconnect--> [连接中]
[已连接] --switchDevice--> [连接中]
19.2 蓝牙操作流程
连接流程：
步骤1：初始化蓝牙适配器
→ uni.openBluetoothAdapter()
→ 成功：进入步骤2
→ 失败：提示用户开启蓝牙
步骤2：开始搜索设备
→ uni.startBluetoothDevicesDiscovery()
→ 设置allowDuplicatesKey: false
→ 设置interval: 1000
步骤3：监听发现设备
→ uni.onBluetoothDeviceFound()
→ 过滤设备名称（包含"艾灸椅"或指定UUID）
→ 收集设备列表
步骤4：停止搜索
→ uni.stopBluetoothDevicesDiscovery()
→ 30秒超时自动停止
步骤5：连接设备
→ uni.createBLEConnection()
→ 设置timeout: 10000
→ 成功：进入步骤6
→ 失败：提示重试
步骤6：发现服务
→ uni.getBLEDeviceServices()
→ 找到指定Service UUID
步骤7：发现特征值
→ uni.getBLEDeviceCharacteristics()
→ 找到：
- 写特征值（APP→设备指令）
- 读/通知特征值（设备→APP状态）
步骤8：开启通知
→ uni.notifyBLECharacteristicValueChange()
→ 监听设备主动上报
步骤9：监听数据
→ uni.onBLECharacteristicValueChange()
→ 解析设备上报数据，更新UI
19.3 蓝牙指令清单
连接管理类：
| 指令 | 命令字 | 说明 |
|---|---|---|
| 设备发现 | 0x01 | 搜索附近艾灸椅 |
| 建立连接 | 0x02 | 与指定设备建立BLE连接 |
| 断开连接 | 0x03 | 主动断开连接 |
| 心跳保活 | 0x04 | 维持连接状态 |
| 操控权请求 | 0x05 | 请求设备操控权 |
| 操控权释放 | 0x06 | 释放设备操控权 |
艾灸控制类：
| 指令 | 命令字 | 说明 |
|---|---|---|
| 一键启动 | 0x10 | 参数：用户ID/指纹ID/方案ID |
| 开始艾灸 | 0x11 | 启动当前方案 |
| 暂停艾灸 | 0x12 | 灸头后退2cm，暂停计时 |
| 继续艾灸 | 0x13 | 恢复施灸和计时 |
| 结束艾灸 | 0x14 | 灸头归位，停止加热 |
| 下发灸方 | 0x15 | 发送完整艾灸工艺数据包 |
参数控制类：
| 指令 | 命令字 | 说明 |
|---|---|---|
| 座椅角度 | 0x20 | 参数：目标角度(90-150) |
| 音量控制 | 0x21 | 参数：音量百分比(0-100) |
| 音效选择 | 0x22 | 参数：音效编号(1-8) |
| 音效播放控制 | 0x23 | 参数：播放/暂停/停止 |
| 温度设置 | 0x24 | 参数：目标温度(38-44) |
数据采集类：
| 指令 | 命令字 | 说明 |
|---|---|---|
| 读取艾材余量 | 0x30 | 返回剩余数量 |
| 读取废料舱状态 | 0x31 | 返回容量百分比 |
| 读取滤芯状态 | 0x32 | 返回寿命百分比 |
| 读取温度 | 0x33 | 返回当前温度 |
| 读取执行进度 | 0x34 | 返回当前穴位/剩余时长/手法 |
| 读取设备状态 | 0x35 | 返回设备整体状态 |
用户管理类：
| 指令 | 命令字 | 说明 |
|---|---|---|
| 指纹录入 | 0x40 | 启动设备指纹采集 |
| 指纹查询 | 0x41 | 查询已绑定指纹列表 |
| 方案同步 | 0x42 | 将方案同步到设备本地 |
| 方案查询 | 0x43 | 查询设备已存储的方案 |
19.4 数据上报格式
设备状态周期性上报（每2秒）：
数据格式：
[当前穴位编号: 2B]
[剩余时长(秒): 2B]
[当前温度(℃): 1B]
[当前手法: 1B] (0=悬定灸, 1=雀啄灸, 2=回旋灸)
[设备状态: 1B] (0=待机, 1=预热, 2=运行, 3=暂停, 4=完成, 5=异常)
[错误码: 1B] (0=无错误, 1=艾材不足, 2=废料满, 3=超温, 4=异物)
[艾材余量: 1B]
[废料舱百分比: 1B]
[滤芯百分比: 1B]
[预热进度: 1B] (0-100, 非预热时为0)
[座椅当前角度: 1B]
艾灸工艺数据包格式：
[包头: 0xAA 0x55] (2B固定)
[命令字: 0x15] (1B)
[数据长度: 2B]
[穴位数量: 1B] (1-3)
[
[穴位编号: 2B]
[施灸时长(秒): 2B]
[施灸温度: 1B]
[施灸手法: 1B]
] × 穴位数量
[校验和: 1B]
19.5 蓝牙错误处理
| 错误码 | 说明 | 处理方式 |
|---|---|---|
| 10000 | 未初始化蓝牙适配器 | 重新初始化 |
| 10001 | 当前蓝牙适配器不可用 | 提示开启蓝牙 |
| 10002 | 没有找到指定设备 | 重新搜索 |
| 10003 | 连接失败 | 重试连接 |
| 10004 | 没有找到指定服务 | 设备不兼容 |
| 10005 | 没有找到指定特征值 | 设备固件异常 |
| 10006 | 当前连接已断开 | 自动重连 |
| 10007 | 当前特征值不支持此操作 | 设备版本过低 |
| 10008 | 其余所有系统上报的异常 | 通用提示 |
| 10009 | Android系统特有，系统版本低于4.3不支持BLE | 提示升级系统 |
20. 后台接口清单
20.1 认证模块
POST /api/auth/send-sms
请求参数：
phone: string (必填, 11位手机号)
响应：
code: 200成功
message: "验证码已发送"
错误：
400: 手机号格式错误
429: 发送过于频繁
500: 服务器内部错误
POST /api/auth/verify-login
请求参数：
phone: string (必填)
code: string (必填, 6位验证码)
platform: string (ios/android/harmonyos)
deviceId: string (设备唯一标识)
响应：
token: string (长期有效)
userId: string
isNewUser: boolean
userInfo: object
错误：
400: 验证码错误或已过期
429: 验证次数过多
POST /api/auth/third-party-login
请求参数：
type: string (wechat/apple)
authCode: string
platform: string
响应：同verify-login
20.2 用户模块
POST /api/user/profile
请求参数：
name: string (1-20字符)
gender: number (0=女, 1=男)
age: number (1-120)
height: number (50-250, cm)
weight: number (10-300, kg)
响应：userInfo对象
GET /api/user/list
响应：
users: array [{id, name, gender, age, height, weight, bodyData}]
maxCount: 10
POST /api/user
请求参数：同profile
响应：新建的用户对象
错误：
409: 用户数量已达上限(10人)
PUT /api/user/{id}
请求参数：同profile
响应：更新后的用户对象
DELETE /api/user/{id}
响应：204 No Content
错误：
400: 不能删除最后一个用户
404: 用户不存在
POST /api/user/body-data
请求参数：
userId: string
shoulderHeight: number (肩高, cm)
shoulderWidth: number (肩宽, cm)
weight: number (kg)
响应：
success: true
acupoints: object (穴位坐标计算结果)
20.3 设备模块
GET /api/user/devices
响应：
devices: array [{
id, name, macAddress,
connectStatus, lastConnectTime,
materialCount, wasteLevel, filterLevel
}]
POST /api/user/devices/bind
请求参数：
deviceName: string
macAddress: string
model: string
响应：绑定的设备对象
错误：
409: 设备已被其他账号绑定
409: 绑定数量已达上限(5台)
DELETE /api/user/devices/{id}
响应：204
POST /api/user/devices/switch
请求参数：
deviceId: string
响应：当前设备对象
20.4 算法模块
POST /api/algorithm/acupoint-calculate
请求参数：
userId: string
bodyData: {
shoulderHeight: number
shoulderWidth: number
weight: number
}
响应：
acupoints: array [{
code: string (穴位编码)
name: string (穴位名称)
x: number (X坐标, mm)
y: number (Y坐标, mm)
z: number (Z坐标, mm)
}]
POST /api/algorithm/moxa-plan
请求参数：
userId: string
efficacy: string (作用类型)
acupoints: array (穴位坐标)
响应：
plan: {
name: string
totalDuration: number (总时长, 秒)
acupoints: array [{
code, name, duration, temperature, technique
}]
}
20.5 方案模块
GET /api/plan/list
请求参数：
userId: string (可选, 不传则查询公用方案)
type: string (personal/public/directed)
page: number
pageSize: number
响应：
total: number
list: array [{
id, name, author, type,
totalDuration, acupointCount,
acupoints: array,
createTime
}]
GET /api/plan/{id}
响应：方案详情对象
POST /api/plan/save
请求参数：
userId: string
name: string (1-30字符)
acupoints: array [{
code, duration, temperature, technique, order
}]
totalDuration: number
响应：保存的方案对象
POST /api/plan/copy
请求参数：
planId: string
userId: string
响应：复制的方案对象
错误：
403: 无权复制该方案
404: 方案不存在
DELETE /api/plan/{id}
错误：
403: 无权删除（非本人方案）
409: 方案正在执行中
20.6 穴位模块
GET /api/acupoint/list
响应：
acupoints: array [{
code, name,
location: string (定位描述)
effect: string (作用描述)
defaultX, defaultY, defaultZ
}]
20.7 消息模块
GET /api/message/list
请求参数：
type: string (all/system/plan)
page: number
pageSize: number
响应：
total: number
unreadCount: number
list: array [{
id, type, title, content,
sender, sendTime, isRead,
relatedId, relatedType
}]
POST /api/message/read
请求参数：
messageIds: array
响应：更新的消息列表
GET /api/message/unread-count
响应：{ count: number }
20.8 版本模块
GET /api/version/check
请求参数：
platform: string
currentVersion: string
响应：
hasUpdate: boolean
isForce: boolean
latestVersion: string
downloadUrl: string
updateLog: string
minSupportedVersion: string
20.9 记录模块
POST /api/record/report
请求参数：
userId: string
deviceId: string
planId: string (可选)
efficacy: string (可选)
acupoints: array
totalDuration: number
avgTemperature: number
startTime: timestamp
endTime: timestamp
响应：{ id: string }
GET /api/record/list
请求参数：
userId: string
startDate: string
endDate: string
page: number
pageSize: number
响应：
total: number
list: array [{
id, deviceName, planName,
efficacy, acupoints, totalDuration,
avgTemperature, startTime, endTime
}]
20.10 推荐模块
GET /api/recommend/hot
请求参数：
userId: string (可选)
season: string (可选, 春夏秋冬)
响应：推荐方案列表
GET /api/recommend/personal
请求参数：
userId: string (必填)
响应：
basedOn: string (推荐理由)
plans: array
20.11 内容模块
GET /api/article/list
请求参数：
category: string
page: number
pageSize: number
响应：文章列表
GET /api/article/{id}
响应：文章详情
20.12 推送模块
POST /api/push/bind-token
请求参数：
platform: string
pushToken: string
deviceId: string
响应：{ success: true }
21. 全局错误码与提示文案
21.1 系统级错误码
| 错误码 | 错误描述 | 用户提示 | 处理方式 |
|---|---|---|---|
| 200 | 成功 | - | 正常流程 |
| 400 | 请求参数错误 | "请求参数有误，请检查后重试" | 检查表单 |
| 401 | 未授权/Token失效 | "登录已过期，请重新登录" | 跳转登录页 |
| 403 | 无权访问 | "无权进行此操作" | 阻止操作 |
| 404 | 资源不存在 | "请求的内容不存在" | 返回上一页 |
| 409 | 资源冲突 | "操作冲突，请刷新后重试" | 刷新页面 |
| 429 | 请求过于频繁 | "操作过于频繁，请稍后再试" | 延迟重试 |
| 500 | 服务器内部错误 | "服务器繁忙，请稍后再试" | 重试 |
| 502 | 网关错误 | "网络连接不稳定，请重试" | 重试 |
| 503 | 服务不可用 | "服务暂时不可用" | 稍后重试 |
| 504 | 网关超时 | "请求超时，请检查网络" | 重试 |
21.2 业务错误码
| 错误码 | 场景 | 用户提示 |
|---|---|---|
| 1001 | 手机号格式错误 | "请输入正确的11位手机号" |
| 1002 | 验证码错误 | "验证码错误，请重新输入" |
| 1003 | 验证码过期 | "验证码已过期，请重新获取" |
| 1004 | 发送验证码过于频繁 | "发送过于频繁，请{seconds}秒后重试" |
| 1005 | 用户数量已达上限 | "最多可添加10个用户" |
| 1006 | 不能删除最后一个用户 | "至少保留一个用户" |
| 1007 | 设备绑定数量已达上限 | "每个账号最多绑定5台设备" |
| 1008 | 设备已被其他账号绑定 | "该设备已被其他账号绑定" |
| 1009 | 方案穴位数超限 | "单次最多可选择3个穴位" |
| 1010 | 方案总时长超限 | "总时长不超过30分钟" |
| 1011 | 艾材不足 | "艾材不足，无法启动艾灸" |
| 1012 | 废料舱已满 | "废料舱已满，无法启动艾灸" |
| 1013 | 设备正在被操控 | "当前设备正在被其他手机操控" |
| 1014 | 蓝牙未连接 | "设备未连接，请连接后重试" |
| 1015 | 方案正在执行中 | "该方案正在执行，无法删除" |
| 1016 | 无权操作此方案 | "无权操作此方案" |
| 1017 | 体形数据不完整 | "请先完善体形信息" |
| 1018 | 预热超时 | "预热超时，请检查设备后重试" |
21.3 网络错误提示
| 场景 | 用户提示 | 处理方式 |
|---|---|---|
| 无网络连接 | "网络连接失败，请检查网络设置" | 提供设置入口 |
| 网络超时 | "网络请求超时，请重试" | 提供重试按钮 |
| 网络不稳定 | "网络不稳定，请稍后再试" | 自动重试1次 |
| 服务器维护 | "系统维护中，请稍后再试" | 显示维护页面 |
| DNS解析失败 | "网络连接异常，请检查网络" | 重试 |
| SSL证书错误 | "网络安全验证失败" | 提示安全风险 |
21.4 设备端错误提示
| 错误码 | 触发条件 | 提示方式 | 提示文案 |
|---|---|---|---|
| D001 | 艾材余量=3 | Toast | "艾材余量不足，剩余3个，请及时补充" |
| D002 | 艾材余量=1 | 弹窗 | "艾材即将用完，只剩1个，建议补充后再使用" |
| D003 | 艾材余量=0 | 弹窗+禁用 | "艾材已用完，无法启动艾灸，请补充艾材" |
| D004 | 废料舱=80% | Toast | "废料舱即将满仓，请及时清理" |
| D005 | 废料舱=100% | 弹窗+禁用 | "废料舱已满，无法启动艾灸，请清理废料舱" |
| D006 | 滤芯=80% | Toast | "滤芯使用寿命即将到期，建议更换" |
| D007 | 滤芯=100% | 弹窗 | "滤芯已到期，请更换滤芯以保证使用效果" |
| D008 | 检测到异物 | 弹窗+暂停 | "检测到有异物，已暂停艾灸，清理后重试" |
| D009 | 无法启动 | 弹窗 | "无法启动设备，请检查艾灸盒状态或是否正确连接" |
| D010 | 耗材ID不符 | 弹窗 | "艾灸耗材ID不符，请检查艾灸盒或尝试重启设备" |
| D011 | 设备断电 | 弹窗 | "设备已断电，艾灸已终止" |
| D012 | 温度超上限 | Toast | "温度过高，已自动切换手法防止灼伤" |
| D013 | 蓝牙断开 | Toast | "蓝牙连接断开，正在尝试重连..." |
| D014 | 操控权冲突 | Toast | "当前设备正在被其他手机操控" |
| D015 | 指纹不匹配 | Toast | "指纹不匹配，请重试" |
| D016 | 预热失败 | 弹窗 | "预热失败，请检查设备后重试" |
21.5 操作确认弹窗文案
| 操作 | 弹窗标题 | 弹窗内容 | 确认按钮 |
|---|---|---|---|
| 删除方案 | 确认删除 | 确定删除方案"XXX"？删除后无法恢复 | 删除（红） |
| 删除用户 | 确认删除 | 确定删除用户"XXX"？ | 删除（红） |
| 结束艾灸 | 确认结束 | 确定结束本次艾灸？ | 结束（红） |
| 退出登录 | 确认退出 | 确定退出登录？ | 退出（红） |
| 解绑设备 | 确认解绑 | 确定解绑设备"XXX"？ | 解绑（红） |
| 覆盖保存 | 确认覆盖 | 该名称方案已存在，是否覆盖？ | 覆盖 |
| 离开编辑页 | 确认离开 | 当前编辑未保存，确定离开？ | 离开（红） |
21.6 状态文案汇总
| 状态 | 显示文案 |
|---|---|
| 蓝牙未连接 | "蓝牙未连接" |
| 蓝牙已连接 | "蓝牙已连接" |
| 蓝牙连接中 | "蓝牙连接中..." |
| 正在预热 | "正在预热 {X}%" |
| 已完成预热 | "已完成预热 100%" |
| 正在艾灸 | "正在艾灸" |
| 已暂停 | "已暂停 剩余{XX:XX}" |
| 等待开始 | "等待开始 {XX:XX}" |
| 艾灸已完成 | "艾灸已完成" |
| 设备异常 | "设备异常：{错误原因}" |
| 加载中 | "加载中..." |
| 数据同步中 | "数据同步中..." |
| 方案保存成功 | "方案保存成功" |
| 方案删除成功 | "方案删除成功" |
| 用户切换成功 | "已切换至用户：{用户名}" |
| 设备添加成功 | "设备添加成功" |
| 设备解绑成功 | "设备解绑成功" |
22. 页面清单与路由表
22.1 页面路由表
| 页面ID | 页面名称 | 路径 | 类型 | 需登录 | 需蓝牙 |
|---|---|---|---|---|---|
| P001 | 隐私政策弹窗 | /pages/privacy/popup | 弹窗 | 否 | 否 |
| P002 | 隐私政策详情 | /pages/privacy/detail | 页面 | 否 | 否 |
| P003 | 登录页 | /pages/login/index | 页面 | 否 | 否 |
| P004 | 补充信息 | /pages/user/profile-fill | 页面 | 是 | 否 |
| P005 | 首页-设备列表 | /pages/home/index | Tab页 | 是 | 否 |
| P006 | 添加设备 | /pages/device/add | 页面 | 是 | 是 |
| P007 | 设备详情 | /pages/device/detail | 页面 | 是 | 是 |
| P008 | 用户管理 | /pages/user/list | 页面 | 是 | 否 |
| P009 | 体形录入 | /pages/user/body-data | 页面 | 是 | 否 |
| P010 | 指纹录入 | /pages/user/fingerprint | 页面 | 是 | 是 |
| P011 | 耗材管理 | /pages/device/consumable | 页面 | 是 | 是 |
| P012 | 座椅角度 | /pages/device/seat-angle | 页面 | 是 | 是 |
| P013 | 模式选择 | /pages/moxa/mode-select | 底部弹窗 | 是 | 否 |
| P014 | 功效选择 | /pages/moxa/efficacy-select | 页面 | 是 | 否 |
| P015 | 穴位编辑 | /pages/moxa/acupoint-edit | 页面 | 是 | 否 |
| P016 | 艾灸执行 | /pages/moxa/executing | 页面 | 是 | 是 |
| P017 | 音效选择 | /pages/moxa/sound-select | 底部弹窗 | 是 | 是 |
| P018 | 方案确认 | /pages/moxa/plan-confirm | 弹窗 | 是 | 否 |
| P019 | 预热中 | /pages/moxa/preheating | 页面 | 是 | 是 |
| P020 | 我的方案 | /pages/plan/list | 页面 | 是 | 否 |
| P021 | 方案详情 | /pages/plan/detail | 页面 | 是 | 否 |
| P022 | 发现首页 | /pages/discover/index | Tab页 | 是 | 否 |
| P023 | 专家方案 | /pages/discover/expert | 页面 | 是 | 否 |
| P024 | 方案详情(发现) | /pages/discover/plan-detail | 页面 | 是 | 否 |
| P025 | 健康推荐 | /pages/health/index | Tab页 | 是 | 否 |
| P026 | 文章详情 | /pages/health/article-detail | 页面 | 是 | 否 |
| P027 | 消息中心 | /pages/message/list | 页面 | 是 | 否 |
| P028 | 消息详情 | /pages/message/detail | 页面 | 是 | 否 |
| P029 | 个人中心 | /pages/mine/index | Tab页 | 是 | 否 |
| P030 | 版本信息 | /pages/mine/version | 页面 | 是 | 否 |
| P031 | 帮助中心 | /pages/mine/help | 页面 | 是 | 否 |
| P032 | 问题详情 | /pages/mine/help-detail | 页面 | 是 | 否 |
| P033 | 使用记录 | /pages/mine/records | 页面 | 是 | 否 |
| P034 | 记录详情 | /pages/mine/record-detail | 页面 | 是 | 否 |
22.2 路由跳转规范
页面跳转方式：
- Tab切换：uni.switchTab()
- 普通跳转：uni.navigateTo()
- 重定向（不保留历史）：uni.redirectTo()
- 返回：uni.navigateBack()
- 返回Tab页：uni.switchTab()
页面返回规则：
- 普通页面 → navigateBack()
- 需要刷新上一页 → navigateBack() + 上一页onShow刷新
- 跳转到Tab页 → switchTab()
登录拦截：
- 需登录页面：检查Token
- 无Token → 保存当前路径 → 跳转登录页
- 登录成功 → 恢复原路径
22.3 页面状态保持
| 页面 | 状态保持策略 |
|---|---|
| 设备详情 | 保持蓝牙连接状态，onShow时刷新状态 |
| 艾灸执行 | 后台运行保持连接，返回页面恢复状态显示 |
| 方案编辑 | 页面隐藏时保存草稿，onShow时恢复 |
| 消息列表 | onShow时刷新未读数 |
| 使用记录 | 保持分页位置 |
附录
A. 功效与穴位映射表（参考）
| 功效 | 推荐穴位 | 默认温度 | 默认手法 |
|---|---|---|---|
| 驱寒 | 大椎、命门、关元 | 42℃ | 悬定灸 |
| 祛风 | 风池、风门、肺俞 | 40℃ | 雀啄灸 |
| 祛湿 | 足三里、阴陵泉、脾俞 | 40℃ | 悬定灸 |
| 化瘀 | 血海、膈俞、肝俞 | 42℃ | 回旋灸 |
| 化痰 | 丰隆、膻中、中脘 | 40℃ | 雀啄灸 |
| 活血 | 心俞、厥阴俞、膻中 | 42℃ | 悬定灸 |
| 扶阳 | 肾俞、命门、腰阳关 | 44℃ | 悬定灸 |
| 养颜 | 百会、四白、迎香 | 38℃ | 雀啄灸 |
B. 音效列表详情
| 编号 | 名称 | 时长 | 类型 |
|---|---|---|---|
| 1 | 河流 | 30分钟 | 自然水声 |
| 2 | 夏雨 | 30分钟 | 雨声 |
| 3 | 森林 | 30分钟 | 森林环境 |
| 4 | 鸟鸣 | 30分钟 | 鸟鸣声 |
| 5 | 漂流 | 30分钟 | 流水声 |
| 6 | 雨滴 | 30分钟 | 细雨声 |
| 7 | 炉火 | 30分钟 | 火焰声 |
| 8 | 海浪 | 30分钟 | 海浪声 |
C. 温度与手法对照
| 温度 | 适用手法 | 说明 |
|---|---|---|
| 38℃ | 雀啄灸 | 温和，适合面部/敏感部位 |
| 40℃ | 悬定灸 | 标准温度，适合大部分穴位 |
| 42℃ | 悬定灸/回旋灸 | 较强刺激，适合背部大穴 |
| 44℃ | 悬定灸 | 强刺激，适合耐受部位 |
D. 艾灸手法说明
| 手法 | 描述 | 适用场景 |
|---|---|---|
| 悬定灸 | 灸头固定于穴位上方不动 | 常规施灸 |
| 雀啄灸 | 灸头快速上下提插 | 防灼伤/敏感部位 |
| 回旋灸 | 灸头在穴位上方画圈 | 大面积温热 |
E. 开发排期建议
| 阶段 | 内容 | 建议工期 |
|---|---|---|
| 第一阶段 | 框架搭建 + 登录注册 + 用户管理 | 1周 |
| 第二阶段 | 蓝牙模块 + 设备管理 + 连接绑定 | 1周 |
| 第三阶段 | 艾灸功能（三种模式）+ 穴位编辑 | 1.5周 |
| 第四阶段 | 方案管理 + 发现模块 | 1周 |
| 第五阶段 | 消息中心 + 个人中心 + 版本升级 | 0.5周 |
| 第六阶段 | 联调测试 + 优化修复 | 1周 |
| 合计 | 6周 |