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

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

1. 产品入口与导航

首期 Flutter App 使用“首页、商城、订单、我的”四栏底部导航：首页承载安全内容、公告和服务归属，避免把尚无 Client API 的设备控制与收藏伪装成可用主入口。智能瓶阀控制和收藏在对应服务端契约落地后再进入导航。未登录用户可浏览公开内容与商品；涉及订单、钱包、合同、工单和地址时必须完成登录。

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

首次进入与安全宣导

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

2. 首页与设备

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

设备页面的关键交互

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

3. 商城、订单与售后

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

配送轨迹展示

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

电子发票

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

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

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

押金退还

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

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

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

6. 首期 Client API 落地边界（2026-07）

• 用户端 API 固定为 /heqi/client/v1/user，令牌客户端为 user_app，不得与任何后台或工作人员令牌互用。
• 首期实现手机号密码/验证码登录、普通注册、邀请注册、资料、地址、服务归属、已发布内容与阅读确认、商城下单和余额支付、物流查询/确认收货、供气合同及订单查询、工单、钱包充值/提现/银行卡。邀请注册可携带气站 identity 和可选配送点 identity，服务端在事务内校验组织关系并建立唯一服务归属。
• 充值先创建待支付订单；仅开发配置允许 Mock 支付确认，确认后才写余额及不可变流水。微信和支付宝未配置渠道时必须明确返回不可用，不得模拟成功。Android/iOS 通过渠道 SDK 调起支付宝 App 支付和微信 App 支付；Web 使用支付宝手机网站支付或微信 JSAPI。客户端回传仅用于提示并轮询服务端支付状态，不能直接推进订单。
• 用户可在未履约订单的退款窗口内选择订单项和数量提交退款原因；金额由服务端按实付分摊核定。退款申请、审核结果和钱包入账状态均可在订单页查看。
• 商城订单交易状态与物流状态分离；物流单号、公司、发货和收货时间由服务端保存，用户只能查看本人订单并确认收货。
• 首期不伪造设备控制、安全事件、押金、消息、发票、收藏、紧急联系人、账户注销和完整售后能力；文档中这些能力保留为后续迭代，不得以静态成功响应冒充已实现。

7. Flutter 开发说明

7.1 平台、工程与原型边界

• 用户端交付 Android、iOS、Web；Web 作为浏览器入口，不延伸为桌面端或小程序兼容层。平台差异通过适配器隔离，不在业务页面散落 Platform.isAndroid、Platform.isIOS 判断。Web 生产部署必须使用 HTTPS，并通过 --dart-define=API_BASE_URL=... 注入 API 地址。
• 生产工程按规划放在 apps/user_app；当前 ui 目录是基于产品设计图制作的交互原型，仅用于视觉、信息架构和流程确认，不得把其中的演示数据或模拟成功状态当作业务实现。
• Flutter 与 Dart 版本由工程根目录的版本管理文件和 CI 固定；升级 SDK、Gradle、Kotlin、Xcode、CocoaPods 或插件时必须单独验证 Android/iOS/Web 构建、权限和深链。
• 应用令牌的 client claim 固定为 user_app，API 根路径固定为 /heqi/client/v1/user；不得复用 service_app 或任何管理后台会话。

7.2 分层结构与依赖方向

采用“按功能组织 UI、按类型组织 Data/Domain”的 MVVM + Repository 结构：

apps/user_app/lib/
  app/
    app.dart                     # MaterialApp.router、主题、语言
    router.dart                  # go_router、鉴权与协议确认守卫
    dependencies.dart            # Service/Repository/ViewModel 装配
  data/
    models/                      # API DTO，不直接进入 Widget
    services/                    # HTTP、扫码、蓝牙、推送、受控存储适配
    repositories/                # 缓存、重试、DTO 到领域模型转换
  domain/
    models/                      # 不可变领域模型
    use_cases/                   # 控阀、下单、余额支付等复杂规则编排
  ui/
    core/                        # 主题、字体、间距、通用状态与组件
    features/
      auth/
      home/
      shop/
      order/
      wallet/
      profile/

• View 只负责渲染、动画、无障碍语义和导航，不直接发 HTTP、写缓存或决定业务状态。
• ViewModel 暴露不可变 UI state 和明确命令；Repository 是远端与本地数据的单一事实入口；跨 Repository 或高风险流程才抽取 Use Case。
• Service 必须无业务状态，负责封装 HTTP、扫码、蓝牙、推送、相机和安全存储等外部边界；平台插件通过接口注入，便于 Android/iOS 替换与测试。
• DTO、领域模型、UI state 分离。HTTP、日志、深链和 Flutter 页面统一使用 identity，不得暴露或接受数据库自增 id。

7.3 路由与导航

• 使用 MaterialApp.router 与 go_router。首期底部四栏使用 StatefulShellRoute.indexedStack 保持各分支的滚动位置和页面栈：
  • /home：安全内容、公告与当前服务归属
  • /shop、/shop/products/:identity、/cart、/checkout
  • /orders、/orders/:identity、/orders/:identity/delivery
  • /me、/me/wallet、/me/records、/me/settings
• /valves 与 /favorites 属于后续路由；对应 Client API 未落地前不得注册可操作页面或用 Mock 数据占据主导航。
• 登录、协议版本确认和首次安全宣导使用根级守卫；涉及设备、订单、钱包、地址的页面必须在 redirect 中校验会话，不能依靠按钮隐藏。
• 邀请二维码、订单通知、支付结果和安全通知使用白名单深链。Android App Links 与 iOS Universal Links 均须校验域名归属；深链参数只接受 identity 和短期签名上下文。
• 高风险开阀被拦截时导航到可解释的限制页面或安全事件详情，不允许通过返回栈、群控入口或手工深链绕过。

7.4 状态、请求与错误处理

• 所有异步页面统一使用 initial/loading/content/empty/error/refreshing 状态；写操作另有 submitting/succeeded/failed/conflict，禁止用一个全局 isLoading 遮蔽不同请求。
• 设备命令 UI 至少表示待发送、已发送、设备已确认、执行失败、超时待确认、已撤销。创建命令成功后按命令 identity 查询回执；超时只能显示“待确认”，不能回退为“已成功”。
• 写请求生成并持久化幂等键；重试复用原键。余额支付、充值、提现、订单提交、报修和设备命令均不得因页面重建或网络重连重复创建事实。
• ViewModel 根据稳定错误码映射可操作文案与恢复入口；不得解析后端错误文案驱动流程。401/403、状态冲突、限流、外部依赖不可用和未知错误分别处理。
• 金额以最小货币单位整数进入领域层，只在格式化组件中转换为展示文本；时间统一解析为 UTC 并按用户时区展示，同时保留数据更新时间。

7.5 本地数据、安全与平台能力

• 访问令牌、刷新令牌和支付相关临时凭据只进入 Android Keystore / iOS Keychain 支持的安全存储，Web 仅可在 HTTPS 域名使用浏览器安全存储；日志、崩溃报告、埋点和剪贴板不得记录令牌、支付密码、完整手机号、地址或定位。
• 普通缓存只保存可恢复数据并设置版本与过期时间。安全事件、资金、订单和设备命令的服务端事实不能由本地缓存覆盖；退出登录时按数据分类清理。
• Android/iOS 的相机、相册、蓝牙、定位、通知权限均采用使用时申请和拒绝后降级。定位失败提供手动地址入口；蓝牙失败提供扫码或手动设备码入口。
• 推送点击必须先恢复会话并重新向服务端读取对象状态；通知载荷不得包含完整地址、手机号、支付信息或可直接执行设备控制的凭证。
• 屏幕截图、应用切后台和最近任务缩略图对支付密码、银行卡、证件等页面按风险实施遮挡；是否禁止安全事件页面截图由合规评审决定。

7.6 视觉、无障碍与测试

• 设计基线以 doc/用户端APP-产品设计 和 ui/?app=user 为准：安全蓝为主色，瓶阀状态、告警与命令回执优先于营销内容。危险、警告、成功不能只靠颜色表达。
• 使用统一 ThemeExtension 管理颜色、圆角、间距、阴影和状态色；正文最小字号、动态字体缩放、44×44 logical pixels 触控目标、屏幕阅读器语义和对比度必须在 Android/iOS 真机验证。
• ViewModel、Use Case、Repository 覆盖单元测试；瓶阀状态、支付、登录守卫和错误恢复覆盖 Widget 测试；扫码绑定、开关阀回执、下单支付、订单轨迹覆盖集成测试。
• 每次合并至少执行 flutter analyze、flutter test、Android debug 构建、iOS Simulator 构建和 Web release 构建；涉及相机、蓝牙、推送、支付、Universal Links/App Links 的改动还须执行对应真机或浏览器回归。