feat: add Flutter mobile clients and staff delivery API

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

@@ -2,7 +2,7 @@
 
 ## 1. 产品入口与导航
 
-Flutter App 使用底部导航：智能瓶阀控制、商城、收藏、订单、我的。消息中心作为“我的记录”和通知入口提供，不单独占用底部导航。未登录用户可浏览受限内容；涉及设备、订单、钱包、押金和地址时必须完成登录。
+首期 Flutter App 使用“首页、商城、订单、我的”四栏底部导航：首页承载安全内容、公告和服务归属，避免把尚无 Client API 的设备控制与收藏伪装成可用主入口。智能瓶阀控制和收藏在对应服务端契约落地后再进入导航。未登录用户可浏览公开内容与商品；涉及订单、钱包、合同、工单和地址时必须完成登录。
 
 产品设计稿的默认登录页使用“手机号 + 验证码”方式，支持记住登录状态和忘记密码入口；用户名密码登录可作为兼容能力保留。验证码登录应具备频控、图形/行为校验和设备风控；登录前必须展示用户协议和隐私政策，并记录用户同意的协议版本。
 
@@ -98,3 +98,80 @@ Flutter App 使用底部导航：智能瓶阀控制、商城、收藏、订单
 - 充值先创建待支付订单；仅开发配置允许 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 的改动还须执行对应真机回归。