# 研年艾灸椅APP需求文档（详细版） > 文档版本：v2.0 > 整理日期：2026-05-25 > 项目说明：后台和算法已完成，本文档用于指导APP前端开发 > 技术栈：UniApp框架（非UniAppX），支持iOS/Android/HarmonyOS跨平台 --- ## 目录 - [1. 项目概述与架构](#1-项目概述与架构) - [2. 技术框架规范](#2-技术框架规范) - [3. 全局交互规范](#3-全局交互规范) - [4. 启动与引导模块](#4-启动与引导模块) - [5. 登录注册模块](#5-登录注册模块) - [6. 用户管理模块](#6-用户管理模块) - [7. 设备管理模块](#7-设备管理模块) - [8. 首页-设备控制模块](#8-首页-设备控制模块) - [9. 无艾灸模式（休闲模式）](#9-无艾灸模式休闲模式) - [10. 专业模式（一键艾灸）](#10-专业模式一键艾灸) - [11. 自定义模式](#11-自定义模式) - [12. 艾灸执行过程](#12-艾灸执行过程) - [13. 我的方案管理](#13-我的方案管理) - [14. 发现模块](#14-发现模块) - [15. 健康模块](#15-健康模块) - [16. 消息中心模块](#16-消息中心模块) - [17. 个人中心模块](#17-个人中心模块) - [18. 版本升级模块](#18-版本升级模块) - [19. 蓝牙通信规范](#19-蓝牙通信规范) - [20. 后台接口清单](#20-后台接口清单) - [21. 全局错误码与提示文案](#21-全局错误码与提示文案) - [22. 页面清单与路由表](#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周** |