设备活动弹窗功能需求分析

设备活动弹窗功能需求分析

一、需求概述

在扫码或直接使用设备时，根据设备详情接口中的新字段 hasPromotion 判断是否有活动，然后使用 promotionId 字段访问新接口来获取活动详情并展示活动弹窗。

二、相关页面梳理

1. 设备模型页面（选择工作模式页面）

• 页面路径 ：lib/app/pages/ruleDevice/deviceModel/
• 控制器 ：lib/app/pages/ruleDevice/deviceModel/controllers/device_model_controller.dart
• 视图 ：lib/app/pages/ruleDevice/deviceModel/views/device_model_view.dart
• 功能：用户选择工作模式后点击"立即使用"进入下单流程
• 适用设备：洗衣机(C0001)、洗鞋机(C0003)、烘干机(C0004)

2. 设备操控页面（洗衣/洗鞋/烘干）

• 页面路径 ：lib/app/pages/deviceOperate/
• 控制器 ：lib/app/pages/deviceOperate/controllers/device_operate_controller.dart
• 功能：提供扫一扫、附近设备、设备订单、优惠券等操作入口

3. 水设备操控页面（饮水机）

• 页面路径 ：lib/app/pages/waterControl/
• 控制器 ：lib/app/pages/waterControl/controllers/water_control_controller.dart
• 功能：饮水机设备操控页面

4. 淋浴设备操控页面

• 页面路径 ：lib/app/pages/showerControl/
• 控制器 ：lib/app/pages/showerControl/controllers/shower_control_controller.dart
• 功能：淋浴设备操控页面

5. 吹风机操控页面

• 页面路径 ：lib/app/pages/blowControl/
• 控制器 ：lib/app/pages/blowControl/controllers/blow_control_controller.dart
• 功能：吹风机设备操控页面

6. 扫码设备逻辑

• 文件路径 ：lib/app/service/scanDevice.dart
• 功能：处理扫码设备逻辑，根据设备类型跳转到对应页面

三、相关接口梳理

1. 设备详情接口（需新增字段）

• 接口路径 ：/shareDevice/device/getByDeviceCode
• API文件 ：lib/app/api/shareDevice/device.dart
• 方法 ：DeviceApi.getByDeviceCode(String deviceCode)
• 返回模型 ：DeviceInfoModel（位于 lib/app/model/shareDevice/deviceOrder/DeviceOrderModel.dart）
• 需新增字段 ：
  • hasPromotion: 是否有活动（bool/int类型）
  • promotionId: 活动ID（String/int类型）

2. 活动详情接口（新接口）

• 接口路径 ：待定（建议 /promotion/getDetail 或类似路径）
• API文件 ：需新建（建议 lib/app/api/promotion/ 目录）
• 功能：根据 promotionId 获取活动详情信息
• 返回数据：活动详情信息，包括活动标题、描述、图片、优惠规则等

四、功能流程梳理

统一活动判断流程

flowchart TD subgraph 入口方式 A1[用户扫码] --> B1[scanDevice扫码处理] A2[用户直接进入设备页面] --> B2[页面初始化] end B1 --> C[跳转到对应设备页面] B2 --> C C --> D[设备页面加载设备详情] D --> E{判断hasPromotion} E -->|有活动| F[获取promotionId] F --> G[调用活动详情接口] G --> H[展示活动弹窗] E -->|无活动| I[正常显示设备页面]

3. 具体实现步骤

1. 修改DeviceInfoModel ：添加 hasPromotion 和 promotionId 字段
2. 创建活动API：定义活动详情接口请求方法
3. 创建活动Model：定义活动详情数据结构
4. 修改页面逻辑 ：
   • 在设备模型页面控制器中添加活动判断逻辑
   • 在扫码设备逻辑中添加活动判断逻辑
5. 创建活动弹窗组件：展示活动详情信息

五、页面交互设计建议

1. 活动弹窗展示时机

• 在设备使用页面上：当设备页面加载设备详情后，判断有活动时展示活动弹窗

2. 活动弹窗内容

• 活动标题
• 活动图片（参考截图中的优惠券图片）
• 活动描述
• 优惠规则/金额
• 行动按钮（如"立即领取"、"知道了"等）

3. 弹窗交互逻辑

• 用户关闭弹窗后继续正常流程
• 如果用户点击行动按钮，执行相应操作（如领取优惠券）

六、技术实现要点

1. 模型层修改

// 在DeviceInfoModel中添加字段
int? hasPromotion;  // 是否有活动
String? promotionId; // 活动ID

// 在fromJson和toJson方法中添加对应解析

2. API层新增

// 新建活动API类
class PromotionApi {
  static Future<PromotionDetailModel> getDetail(String promotionId) async {
    final response = await HttpUtils.post(
        path: "/promotion/getDetail", data: {'promotionId': promotionId});
    final PromotionDetailModel result = PromotionDetailModel.fromJson(response);
    return result;
  }
}

3. 页面控制器修改

// 在DeviceModelController中添加活动判断逻辑
void checkPromotion() async {
  final deviceInfo = await DeviceApi.getByDeviceCode(deviceCode.value);
  if (deviceInfo.hasPromotion == 1 && deviceInfo.promotionId != null) {
    // 获取活动详情
    final promotionDetail = await PromotionApi.getDetail(deviceInfo.promotionId!);
    // 展示活动弹窗
    showPromotionDialog(promotionDetail);
  }
}

七、测试要点

1. 正常流程测试：扫码/直接进入设备页面 → 设备页面加载设备详情 → 判断活动 → 展示弹窗 → 继续流程
2. 无活动流程测试：设备无活动时正常跳转
3. 接口异常测试：活动详情接口请求失败时的处理
4. 弹窗交互测试：弹窗展示、关闭、按钮点击等功能
5. 不同设备类型测试：各种设备类型下的活动弹窗功能

八、注意事项

1. 兼容性：确保新增字段不影响现有功能
2. 性能：活动详情接口请求应异步处理，避免阻塞页面加载
3. 用户体验：活动弹窗不应影响正常操作流程
4. 错误处理：网络请求失败时应有降级处理方案
5. 国际化：活动内容可能需要支持多语言