platforms/docs/03-用户端App需求.md

# 用户端需求（业主/消费者 App）

## 1. 产品入口与导航

Flutter App 使用底部导航：智能瓶阀控制、商城、收藏、订单、我的。消息中心作为“我的记录”和通知入口提供，不单独占用底部导航。未登录用户可浏览受限内容；涉及设备、订单、钱包、押金和地址时必须完成登录。

产品设计稿的默认登录页使用“手机号 + 验证码”方式，支持记住登录状态和忘记密码入口；用户名密码登录可作为兼容能力保留。验证码登录应具备频控、图形/行为校验和设备风控；登录前必须展示用户协议和隐私政策，并记录用户同意的协议版本。

### 首次进入与安全宣导

- 首次登录或安全宣导内容更新后，展示可配置的“智能瓶阀控制功能介绍”，至少支持功能介绍、安全案例、法律法规和安全注意事项等内容分类。
- 注意事项应明确低电量、离线、泄漏报警、通风、远离火源、定期检查和自动关闭的安全提示；用户确认阅读后才进入主界面。
- 宣导内容、展示频率、是否强制阅读及版本号由平台后台配置，并记录阅读确认；紧急告警不受宣导弹窗阻塞。

## 2. 首页与设备

| 功能 | 需求 | 验收要点 |
| --- | --- | --- |
| 定位 | 获取当前位置并允许手动选择地址/气站服务区域 | 授权失败有手动入口，不以定位失败阻塞设备使用 |
| 内容 | 轮播图、公告、安全宣传、安全视频列表 | 后台上下架后按缓存策略刷新；外链有风险提示 |
| 智能瓶阀列表 | 显示名称、地址、在线状态、开关状态、最近告警、设备数量 | 可按地址/状态筛选；离线状态显著可见 |
| 扫码添加 | 扫码或输入设备码，选择安装地址和设备昵称 | 校验设备归属、激活、服务区域和重复绑定 |
| 设备接入 | 扫码添加、手动输入、蓝牙连接与设备校验 | 展示设备 ID、名称、安装位置；绑定前需用户确认，蓝牙权限失败有明确引导 |
| 控制 | 开/关阀、操作确认、命令状态和历史 | 高风险事件限制开阀；命令必须有最终回执或超时状态 |
| 群组控制 | 按厨房、热水器、暖气等区域/用途对多个智能瓶阀分组，支持全开、全关、编辑和删除 | 全开必须逐设备校验安全事件、在线和权限；任一设备失败需返回明细，不能将群控标记为全部成功 |
| 状态详情 | 电量、电池温度、环境压力、其他参数、趋势和更新时间 | 单位、阈值、数据延迟、传感器异常清晰展示 |
| 气瓶信息 | 气瓶规格、钢瓶号、充装日期、充装单位、充装数量、有效期和制造厂信息 | 数据来源和更新时间可追溯；过期或异常气瓶显示风险提示和处理入口 |
| 安全记录 | 显示未处理数量、等级、时间、处理进度和证据 | 可进入详情、联系平台、申请复检；不可删除系统安全记录 |
| 紧急报警 | 报警触发状态、安全提示、紧急联系人和紧急电话 | 显示火警、报警、急救和可燃气体服务热线；号码由平台/区域配置，允许一键拨打 |
| 一键报修 | 泄漏、阀门故障、报警器故障、其他问题；故障描述、语音输入、联系人、地址、现场照片 | 当前定位和照片采集时间自动写入报修单；默认最多上传 3 张现场照片，具体上限后台可配置 |

### 设备页面的关键交互

- 关阀操作展示影响提示；开阀操作展示当前安全检查和限制状态。
- 设备离线、低电量、传感器故障、未激活分别显示不同文案和解决建议。
- 支持家庭共享作为扩展：设备所有者可授权成员查看或控制；控制权限应单独授予并可随时撤销。
- 设备状态卡片应展示在线状态、电池电量、环境压力、温度、自动关闭时间、气瓶余量/规格及最后更新时间；无数据须显示“暂未上报”而非使用历史数据冒充实时状态。
- 设备告警触发时，优先展示关阀执行结果、风险说明、紧急电话、通风/撤离指引和报修入口；用户不能通过群控或单设备开阀绕过高风险限制。

## 3. 商城、订单与售后

- 商品分类由后台一级分类驱动；商品列表展示图、名称、售价、划线价、已售数量与库存状态。
- 设计稿中的商城支持全部、可燃气体灶具、热水器、软管等分类、关键词搜索、收藏和商品卡片内数量加减；库存不足或超出限购时禁用继续加购并说明原因。
- 商品详情包括轮播图、图文详情、规格、服务说明、适用条件、售后政策、客服、收藏、加入购物车、立即购买。
- 购物车支持单选、全选、数量调整、删除、优惠估算和失效商品提示。
- 气瓶订单须选择配送公司、气瓶规格与数量、预约配送时段或自定义日期；实时展示各规格库存、配送费、订单总数、商品总额和应付合计。库存不足时不得提交订单。
- 提交订单须选择收货/安装地址、优惠券、预约配送/安装时间、支付方式；支付方式支持微信、支付宝、余额，具体以渠道开通为准。余额支付必须校验支付密码、可用余额、幂等支付单和风控状态。
- 订单详情展示订单号、商品、总金额、优惠、支付方式、合同、履约时间、服务人员联系脱敏信息、进度、配送轨迹和售后入口。
- 订单分为全部、待支付、已支付/待履约、已完成、已取消；实际页面应兼容订单内多个服务任务的细分状态。已支付订单可按规则申请退单、评价订单、查看配送详情和查看电子发票。
- 用户可发起售后，选择类型、原因、图片/视频、期望方案；平台须在后台处理并向用户推送进度。

### 配送轨迹展示

- 配送订单在配送员接单后展示状态时间线：待配送、已接单、已出发、配送中、即将到达、已送达/签收或配送异常。
- 配送中可展示最近位置、路线进度和预计送达时间；位置刷新频率、定位精度和最后更新时间必须明确展示。无有效位置时显示“暂未获取位置”，不伪造实时轨迹。
- 用户仅可查看与本人订单关联的配送轨迹，并在订单完成后按平台的数据留存策略展示历史。为保护配送员隐私，默认展示配送服务位置与路线进度，不展示配送员个人活动轨迹。
- 订单改派、地址变更、异常退回或取消时，保留历史节点并展示原因；新配送任务从新的接单节点继续记录。
- 配送详情除轨迹外，应展示配送员姓名、脱敏电话/受控呼叫入口、配送公司、配送点/服务电话、预约时段、预计送达时间和交接状态。

### 电子发票

- 用户可按单次订单、月度或年度筛选可开票订单，查看可开票金额、发票数量、购买方抬头、税号、地址和联系电话。
- 发票申请、开具、作废、红冲等状态以开票服务回执为准；电子发票支持预览和保存至相册/下载，访问链接需短期授权。

## 4. 钱包、消息与个人中心

| 模块 | 必要功能 | 规则 |
| --- | --- | --- |
| 钱包 | 充值套餐、自定义充值、余额、余额明细、提现申请与支付密码 | 充值结果以渠道回调为准；自定义金额有上下限和风控；提现范围与审核规则由平台配置 |
| 押金管理 | 气瓶押金、报警器押金、押金汇总、明细、退瓶退押金 | 按设备/气瓶规格、数量、单价、使用状态和开始时间核算；退押金结果以现场验收和平台审核为准 |
| 用气统计 | 月度/年度用气量、平均用气量、图表、明细和报表导出 | 数据来源、统计周期、单位和最后更新时间须明确；无数据展示空状态 |
| 消息 | 系统通知、订单通知、安全通知、消息中心 | 安全通知不可关闭；支持已读、跳转对象和通知偏好 |
| 地址 | 列表、新增、编辑、默认地址 | 地址包含联系人、电话、详细地址、地理坐标与服务范围校验 |
| 收藏 | 收藏商品、取消收藏、收藏列表 | 下架商品保留历史但不可购买 |
| 客服 | 电话客服、在线客服 | 电话号码/服务时段由后台配置；紧急安全问题优先展示紧急联系人 |
| 邀请注册 | 扫描气站或配送点邀请二维码，完成注册/登录、服务地址确认及服务关系建立 | 二维码过期、已停用、次数耗尽或地址超出服务范围时展示明确提示；不重复创建账号 |
| 我的记录 | 消息中心、订单、押金、退款、报修、报警、用气统计、收藏 | 记录按对象和状态筛选；历史安全、资金和订单记录遵循留存策略，不允许用户篡改 |
| 紧急联系人 | 新增、编辑、删除紧急联系人；授权其查看或控制指定设备 | 漏气报警自动关阀后通知紧急联系人；控制授权单独确认、可撤销并保留审计 |
| 设置 | 昵称、头像、支付密码、设备管理、紧急联系人、自动关闭时间、通知、免打扰、发票信息、主题、通用设置、协议、关于、退出、注销 | 定时关闭设置不得绕过告警关阀规则；注销严格遵循全局规则，协议需有版本与同意记录 |

### 押金退还

- 用户从押金管理进入“退瓶退押金”，选择气瓶/设备、规格、数量及完好或损坏状态，系统实时展示预计退还押金。
- 退款申请生成后进入待验收/待审核；设备序列号、使用时长、原始押金、扣减原因、实际退款和退款去向必须可追溯。
- 用户确认退瓶后，押金退回账户余额或原支付路径的规则由平台配置；存在未完成订单、安全事件或争议时应拦截或转人工处理。

## 5. 产品设计对齐与扩展需求

- 设备共享与家庭成员管理、电子保修卡、用气/设备健康月报。
- 一键紧急关阀、告警静默时段（不影响高风险告警）、语音/无障碍辅助。
- 安全知识考试、服务评价、发票申请、预约改期、订阅式巡检服务。
- 后续可扩展设备蓝牙离线诊断、气瓶换新提醒、余量预测、异常用气提醒、电子保修卡和家庭成员用气对比。