178 lines
18 KiB
Markdown
178 lines
18 KiB
Markdown
# 用户端需求（业主/消费者 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 支付确认，确认后才写余额及不可变流水。微信和支付宝未配置渠道时必须明确返回不可用，不得模拟成功。
|
||
- 商城订单交易状态与物流状态分离；物流单号、公司、发货和收货时间由服务端保存，用户只能查看本人订单并确认收货。
|
||
- 首期不伪造设备控制、安全事件、押金、消息、发票、收藏、紧急联系人、账户注销和完整售后能力；文档中这些能力保留为后续迭代，不得以静态成功响应冒充已实现。
|
||
|
||
## 7. Flutter 开发说明
|
||
|
||
### 7.1 平台、工程与原型边界
|
||
|
||
- 用户端只交付 Android、iOS，不建设 Flutter Web、桌面端或小程序兼容层。平台差异通过适配器隔离，不在业务页面散落 `Platform.isAndroid`、`Platform.isIOS` 判断。
|
||
- 生产工程按规划放在 `apps/user_app`；当前 `ui` 目录是基于产品设计图制作的交互原型，仅用于视觉、信息架构和流程确认，不得把其中的演示数据或模拟成功状态当作业务实现。
|
||
- Flutter 与 Dart 版本由工程根目录的版本管理文件和 CI 固定；升级 SDK、Gradle、Kotlin、Xcode、CocoaPods 或插件时必须单独验证 Android/iOS 构建、权限和深链。
|
||
- 应用令牌的 client claim 固定为 `user_app`，API 根路径固定为 `/heqi/client/v1/user`；不得复用 `service_app` 或任何管理后台会话。
|
||
|
||
### 7.2 分层结构与依赖方向
|
||
|
||
采用“按功能组织 UI、按类型组织 Data/Domain”的 MVVM + Repository 结构：
|
||
|
||
```text
|
||
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 支持的安全存储；日志、崩溃报告、埋点和剪贴板不得记录令牌、支付密码、完整手机号、地址或定位。
|
||
- 普通缓存只保存可恢复数据并设置版本与过期时间。安全事件、资金、订单和设备命令的服务端事实不能由本地缓存覆盖；退出登录时按数据分类清理。
|
||
- 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 构建；涉及相机、蓝牙、推送、支付、Universal Links/App Links 的改动还须执行对应真机回归。
|