777 lines
58 KiB
Markdown
777 lines
58 KiB
Markdown
# 用户端 App 全量功能开发文档 v1.1
|
||
|
||
2026-09-11图19增补：新增商城/气瓶订单支付确认页，金额、商品快照、钱包余额和可用动作以服务端为准。余额扣款在同一事务内校验六位支付密码、更新订单与钱包、写入支付单和账单，重试使用幂等号返回首次结果。优惠券缺少接口，明确显示“暂未开放”；当前测试账号无待付款订单，未执行远程真实扣款。详见[支付确认日志](开发日志_订单支付确认_20260911.md)。
|
||
|
||
2026-09-11图28、39、40增补：钱包提现和银行卡入口已从占位接入真实Client API，新增脱敏银行卡列表、绑定、默认到账卡、安全解绑、提现记录、支付密码校验、幂等申请和二次确认。银行卡增加`is_default`字段及默认切换接口；外部银行回执、短信供应商、押金、优惠券和待退款仍待补齐，详见[钱包提现与银行卡日志](开发日志_钱包提现与银行卡_20260911.md)。
|
||
|
||
阅读确认接口增加可选content_version精确匹配及幂等内容核对，充值页面尚待接入；见[协议版本确认](操作日志_用户端APP_协议版本确认_20260911.md)。
|
||
|
||
充值重试已增加服务端入账查询，避免已到账订单再次拉起渠道，见[充值重试入账检查](操作日志_用户端APP_充值重试入账检查_20260911.md)。
|
||
|
||
2026-09-11最新Flutter全量回归135项通过，充值页新增320/390窄屏及1.3倍字体检查通过；这不代表1:1视觉或真实支付验收，见[充值窄屏回归](操作日志_用户端APP_充值窄屏回归_20260911.md)。
|
||
|
||
充值金额控件按图38补充自定义入口、清空和确认金额，测试通过；当前修改尚未重新部署，视觉仍未通过，见[充值金额控件](操作日志_用户端APP_充值金额控件_20260911.md)。
|
||
|
||
2026-09-11充值配置后端和表单Web构建已更新到本地预览12426/18572；修复到账后余额刷新失败的错误提示。构建及回归测试通过，浏览器视觉和真实渠道验证仍待完成，见[到账提示修复](操作日志_用户端APP_充值到账提示修复_20260911.md)。
|
||
|
||
充值表单 `/wallet/recharge` 已在代码中接入钱包，包含金额、渠道、协议和原请求恢复交互；部署、协议版本留痕和视觉核对尚未完成，见[充值表单接入](操作日志_用户端APP_充值表单接入_20260911.md)。
|
||
|
||
充值数据层新增按环境与账号隔离的待确认请求存储，以及先存后发、到账确认后清除的恢复流程；页面接入和支付关闭处理未完成，详见[充值请求恢复](操作日志_用户端APP_充值请求恢复_20260911.md)。
|
||
|
||
2026-09-11补充钱包充值记录页面 `/wallet/recharge-records`，支持分页、去重、刷新和失败保留数据；新增交互测试、钱包回归与金额测试共6项通过，静态检查和Web构建通过。充值表单及真实渠道流程未完成，详见[充值记录页面](操作日志_用户端APP_充值记录页面_20260911.md)。
|
||
|
||
充值后续接口已增加本人记录分页、按充值标识查询及按请求号恢复结果；创建接口拒绝同请求号更改金额或渠道，真实支付响应增加充值业务标识。远程回滚测试确认Mock重复回调只入账一次，尚不代表图38页面及真实渠道流程完成。详见[充值查询与幂等记录](操作日志_用户端APP_充值查询与幂等_20260911.md)。
|
||
|
||
2026-09-11当前状态：新增图28钱包主页与账单收支筛选、游标分页、详情和金额隐藏。共17张部分实现、41张尚无对应完整页面、0张严格全功能及1:1通过；下方9月8日记录为历史批次。新接口`GET /wallet/bills`限定本人钱包、兼容旧充值方向`in`，保留旧`/wallet/records`。没有资金写入或数据库迁移；充值、提现和其他资产口径仍待补齐。见[钱包与账单日志](操作日志_用户端APP_钱包与账单_20260911.md)。
|
||
|
||
2026-09-08 纠偏补充：一级页面按“部分实现”记录；新增资料编辑、真实头像上传、地址管理、商品详情、购物车、收藏、结算页、商城及供气订单详情、供气合同列表、设置与登录密码、报修表单和工单详情，复用品牌及宣传原图。16 张设计已有部分能力、42 张尚无完整页面，0 张通过严格全功能与 1:1 验收。详见 [设置日志](操作日志_用户端APP_设置与登录密码_20260908.md)、[订单详情日志](操作日志_用户端APP_订单详情_20260908.md)、[收藏日志](操作日志_用户端APP_商品收藏_20260908.md)、[购物车日志](操作日志_用户端APP_购物车_20260908.md)、[头像与视觉日志](操作日志_用户端APP_头像与视觉纠偏_20260907.md)、[地址日志](操作日志_用户端APP_地址管理_20260907.md)、[结算日志](操作日志_用户端APP_结算流程_20260907.md)、[工单日志](操作日志_用户端APP_工单操作_20260907.md)、[报修提交日志](操作日志_用户端APP_报修提交_20260907.md)。
|
||
|
||
图32已替换为独立合同列表，可搜索、筛选真实状态并读取正文；修复后端合同ID误查订单明细的问题。本人受控PDF下载已通过浏览器真实落盘、哈希及渲染验证，独立测试合同/文件已清理；原生保存对话框、签署及合同服务仍待补。见 [合同列表日志](操作日志_用户端APP_供气合同列表_20260908.md)、[附件日志](操作日志_用户端APP_合同附件下载_20260908.md)。
|
||
|
||
头像使用现有 `POST /upload/avatar` 上传本人 JPG/PNG（最大 2MB），再通过 `PUT /heqi/client/v1/user/auth/profile` 保存。省略 avatar 保留原图，变更 URI 必须归当前账户；读取继续使用受保护的 `GET auth/avatar`。无需数据库迁移；旧客户端保留旧 URI 或清空头像的行为兼容。
|
||
|
||
## 1. 项目概述
|
||
|
||
图32新增本人合同变更记录：读取服务端不可变的生效/续期/终止状态及有效期快照，支持重试和空态；内部人员及原因不公开。另已接入合同申请、气站答复、取消及用户确认，原合同条款不会被申请流程直接修改；仍不等于电子签署审计。见 [变更记录日志](操作日志_用户端APP_合同变更记录_20260908.md)、[合同申请日志](操作日志_用户端APP_合同申请与个人中心复核_20260908.md)。
|
||
|
||
图21供气订单分支：新增本人订单详情、状态历史、实际支付记录及合同正文读取；状态34由本人确认后事务记录签收、完成订单并释放占用，状态23重复确认无副作用。无数据库迁移，远程回滚测试确认无临时记录。常规时间轴已横向对齐，商品素材、押金、配送地图及受控联系仍未完成；图32正文弹层不算完整合同页面。详见 [供气详情日志](操作日志_用户端APP_供气订单详情_20260908.md)。
|
||
|
||
图21商城订单分支：新增`GET shop/orders/:identity`和`/shop/orders/:identity`页面，订单详情独立读取本人历史快照，不以当前商品或当前地址覆盖成交事实。`OrderActionHandler`从原订单页抽出，列表与详情共用确认、退款、支付和请求号重试规则；原列表“查看操作”继续保留，点击商品订单可进入详情。无数据库迁移和新依赖，气瓶订单详情及原图押金/合同等内容尚未完成。
|
||
|
||
图16押金管理：新增 `deposit_policy`、`deposit_record`、登录用户的 `GET /deposits` 和 App `/deposits` 页面，总后台同步增加押金规则与只读押金记录入口。远程当前没有规则或记录，所以真实 App 显示零金额空态，不使用产品稿示例值。退瓶闭环已在图17批次接入。
|
||
|
||
图17退瓶退押金：新增 `deposit_return_request`、`/deposits/return`、用户幂等提交/查询/取消接口和后台“退瓶处理”。后台确认回收、验收扣减和退款入账由严格状态机约束，退款、钱包余额、押金状态及资金流水同事务落库。当前真实账号无押金记录，未为演示伪造资金数据；最近安检结论继续标记“暂未开放”。
|
||
|
||
图18气瓶下单：新增 `/gas/order`、服务端报价接口和用户幂等创建接口。页面只展示本人有效合同中未占用的实体气瓶，金额由合同价、后台押金规则和合同配送费计算；支付成功后再将订单押金快照转为正式押金记录。远程账号缺少押金规则时保留规格并提示“押金规则暂未配置”，禁止继续提交。
|
||
|
||
图13与图15推荐已接通`GET shop/recommendations`，购物车内嵌推荐，收藏通过底部“猜你喜欢”打开弹层。只推荐有库存的有效商品，过滤本人购物车与收藏场景已收藏商品；按关联分类优先和更新时间排序，不编造销量或画像。客户端条件加购、分页失败重试、详情返回刷新购物车，复用原仓储接口；无新依赖和数据库变更。见 [推荐商品日志](操作日志_用户端APP_推荐商品_20260908.md)。
|
||
|
||
图15收藏已新增EcFavorite、受用户JWT保护的查询与条件状态接口，以及独立`/favorites`。每账户每商品唯一，取消归档而非删除，下架商品仍保留。商城/详情复用FavoriteButton，服务端确认后同步图标；跨账号迟到响应不广播。新增迁移命令`go run ./cmd/cli migrate-ec-favorite`只创建收藏表并写注释，不能以全库迁移替代。
|
||
|
||
图13购物车使用既有ec_cart表，不新增远程字段；GET shop/cart、GET/PUT shop/cart/items/:identity 已落地，数量零归档而非物理删除。服务端比较公开revision并以账户行锁串行处理，客户端提交绝对数量。`/cart/checkout` 复用结算页，多商品订单按固定顺序锁定商品、校验购物车快照，并在同一事务扣库存和移除已结算条目。原单商品接口保持兼容。
|
||
|
||
图12商品详情：新增匿名详情接口与 `/products/:identity`，图片和参数来自后台，数量随游客登录回跳进入结算。售罄可看不可买，下架明确提示；未补造规格、销量、押金或配送承诺。见 [商品详情日志](操作日志_用户端APP_商品详情_20260908.md)。
|
||
|
||
图05语音输入已接入系统识别服务及Android/iOS用途声明，识别结果写入可编辑故障描述，错误、权限和离页取消有回归覆盖。真实设备麦克风与识别效果仍待验收。见 [语音输入日志](操作日志_用户端APP_报修语音输入_20260908.md)。
|
||
|
||
图05视觉扩展：编号步骤、故障表单分区、三格照片和可操作联系地址预览已接入。实现与源图继续并排核对，尚未通过严格1:1。见 [视觉对齐日志](操作日志_用户端APP_报修视觉对齐_20260908.md)。
|
||
|
||
报修草稿扩展：`RepairDraftStore` 沿用安全存储保存表单与照片URI，按认证账户和API地址隔离。暂存失败保留当前输入；恢复不会自动提交，结果未知时沿用原请求号。`GET /heqi/client/v1/user/ticket-photos/:name` 仅读取本账户文件。未提交草稿恢复时重新检查本人地址，损坏草稿须明确清除。见 [草稿日志](操作日志_用户端APP_报修草稿_20260907.md)。
|
||
|
||
报修照片扩展：已实现选图、预览、删除、上传、工单关联及本人鉴权读取，浏览器真实提交链路通过；原始拍摄时间、定位和完整视觉验收未完成。见 [报修照片日志](操作日志_用户端APP_报修照片_20260907.md)。
|
||
|
||
订单操作扩展：商城取消与确认收货已接入可执行按钮，修复收货状态校验与重复操作边界。图20仍未完整实现，详见 [订单操作日志](操作日志_用户端APP_订单操作_20260907.md)。
|
||
|
||
### 1.1 项目名称
|
||
|
||
瓶安芯用户端 App 产品设计落地与全量功能开发。
|
||
|
||
### 1.2 文档目标
|
||
|
||
本文档以 `doc/用户端APP-最新参考产品设计` 中 49 个主编号页面组、58 张 PNG 设计图为视觉事实源，结合现有 Flutter 用户端、Go Client API、平台总后台及正式需求，指导研发完成以下工作：
|
||
|
||
- 按设计图统一优化用户端 UI，不改变已经确认的蓝白视觉方向。
|
||
- 保留现有真实登录、内容、商城、订单、合同、工单、钱包和地址能力。
|
||
- 补齐设备控制、安全闭环、押金、消息、发票、收藏、家庭共享和扩展服务能力。
|
||
- 完善用户端 Client API、平台后台配置、数据模型、状态机和异常处理。
|
||
- 建立逐页面验收、接口测试、Widget 测试和关键业务集成测试。
|
||
|
||
### 1.3 事实源优先级
|
||
|
||
发生冲突时按以下顺序处理：
|
||
|
||
1. 安全、支付、隐私、合同和设备控制的服务端规则。
|
||
2. `docs/03-用户端App需求.md`、`docs/02-核心业务流程.md` 和 `docs/11-数据接口与安全.md`。
|
||
3. 本文档定义的接口与实施约束。
|
||
4. `doc/用户端APP-最新参考产品设计` 中对应页面设计图。
|
||
5. 当前 Flutter 页面实现。
|
||
|
||
设计图决定页面布局、信息层级和交互入口，不得用设计图中的示例金额、状态、日期或成功结果替代服务端事实。
|
||
|
||
### 1.4 当前状态
|
||
|
||
当前用户端已经具备以下真实基础能力：
|
||
|
||
- 手机号密码和验证码登录、注册、找回密码及会话失效处理。
|
||
- 首页公开内容、当前服务归属和下拉刷新。
|
||
- 公开商品列表、商城订单创建、订单列表、取消、支付、退款和确认收货。
|
||
- 供气合同列表、燃气订单列表、取消、支付和退款。
|
||
- 工单列表、创建、确认和取消。
|
||
- 用户资料、头像读取、地址列表与新增。
|
||
- 钱包余额、流水、充值、支付密码、银行卡和提现。
|
||
- 已发布内容查询和阅读确认。
|
||
|
||
当前用户端主要使用通用 `ClientRecord` 承载多个业务对象，页面集中在登录、首页、商城、订单、我的和两个记录列表，尚未形成与 58 张设计图对应的完整路由、领域模型和页面模块。
|
||
|
||
### 1.5 技术栈与运行环境
|
||
|
||
| 层级 | 当前技术 | 开发要求 |
|
||
| --- | --- | --- |
|
||
| 用户端 | Flutter、Dart 3.12、Material 3 | Android、iOS、Web 共用业务层，平台能力通过适配器隔离 |
|
||
| 路由 | `go_router` | 保留 `StatefulShellRoute.indexedStack` 四栏导航，二级页使用独立路由 |
|
||
| UI 基础 | `heqi_design_system` | 统一复用颜色、间距、圆角、按钮、状态和消息组件 |
|
||
| 网络 | `http`、现有 `ApiClient` | 保留统一响应解析、错误码和会话失效逻辑 |
|
||
| 安全存储 | `flutter_secure_storage` | 仅保存令牌及必要敏感临时凭据 |
|
||
| 支付 | `fluwx`、`tobias`、Web JSAPI | 客户端回传不推进支付事实，必须查询服务端状态 |
|
||
| 后端 | Go、Gin、GORM、PostgreSQL、Redis | 新接口继续放在 `/heqi/client/v1/user`，保持 v1 向下兼容 |
|
||
| 管理后台 | Vue 3、TypeScript、Arco Design | 补齐内容、通知、价格、规则和扩展服务配置 |
|
||
|
||
本地运行：
|
||
|
||
```bash
|
||
cd apps/user_app
|
||
flutter pub get
|
||
flutter run --dart-define=API_BASE_URL=http://10.0.2.2:12426
|
||
```
|
||
|
||
Release 环境必须通过 `--dart-define=API_BASE_URL=https://...` 注入 HTTPS API 地址。
|
||
|
||
## 2. 目录结构规划
|
||
|
||
在不破坏现有代码的前提下逐步扩展为按业务模块组织的结构：
|
||
|
||
```text
|
||
platforms/
|
||
├── apps/
|
||
│ ├── heqi_design_system/ # 多端共用设计 Token 和基础组件
|
||
│ └── user_app/
|
||
│ ├── lib/
|
||
│ │ ├── app/ # 启动、依赖、路由和根级守卫
|
||
│ │ ├── data/
|
||
│ │ │ ├── dto/ # Client API 请求与响应 DTO
|
||
│ │ │ ├── repositories/ # 领域仓储实现
|
||
│ │ │ └── services/ # HTTP、扫码、蓝牙、定位、推送和支付适配
|
||
│ │ ├── domain/
|
||
│ │ │ ├── models/ # 用户、设备、安全、内容、订单和资金模型
|
||
│ │ │ └── use_cases/ # 控阀、下单、退款、退押等关键业务编排
|
||
│ │ └── ui/
|
||
│ │ ├── core/ # 主题、公共状态页和可访问性组件
|
||
│ │ └── features/ # 按页面域拆分的 UI 和 ViewModel
|
||
│ ├── test/ # 单元、Widget 和契约测试
|
||
│ └── integration_test/ # 核心用户旅程测试
|
||
├── backend/
|
||
│ └── api/internal/
|
||
│ ├── models/ # 数据模型与迁移
|
||
│ ├── logic/client/user/ # 用户端 Client API 业务逻辑
|
||
│ └── routers/client.go # 用户端路由注册
|
||
├── frontend/platform_admin/ # 平台内容、规则和运营配置后台
|
||
├── doc/用户端APP-最新参考产品设计/ # 58 张视觉事实源
|
||
└── docs/ # 需求、技术、接口、验收和项目文档
|
||
```
|
||
|
||
迁移原则：先新增强类型 DTO、领域模型和 Feature，不一次性删除 `ClientRecord`；旧页面完成迁移和回归后再清理无引用代码。
|
||
|
||
## 3. UI 优化实施规范
|
||
|
||
### 3.1 视觉基线
|
||
|
||
- 用户端主色使用 `HeqiColors.consumerPrimary`，值为 `#2563EB`。
|
||
- 背景使用 `#F7F8FA`，成功、警告、危险色继续使用设计系统 Token。
|
||
- 间距以 4dp 为基础网格，页面水平安全边距默认 16dp。
|
||
- 触控区域不得小于 48dp，主按钮高度使用 52dp。
|
||
- 一级页面保留“首页、商城、订单、我的”四栏底部导航；二级页面只保留返回导航。
|
||
- 禁止新增紫色、渐变、AI 元素、玻璃拟态、发光、Emoji 和无业务意义装饰。
|
||
- 业务图标优先使用 Material Icons；商品、宣传和视频封面必须使用真实后台资源。
|
||
|
||
### 3.2 公共组件
|
||
|
||
在 `heqi_design_system` 或用户端 `ui/core` 中扩展以下组件，已存在的组件不得重复实现：
|
||
|
||
| 组件 | 用途 |
|
||
| --- | --- |
|
||
| `AppScaffold` | 统一 SafeArea、页面背景、标题栏和最大内容宽度 |
|
||
| `AsyncContent` | 统一 `initial/loading/content/empty/error/refreshing` 状态 |
|
||
| `StatusPill` | 订单、安全、设备、资金和阅读状态标签 |
|
||
| `SectionHeader` | 标题、说明和“查看全部”入口 |
|
||
| `ServiceRelationCard` | 所属气站与服务配送点展示 |
|
||
| `DeviceStatusCard` | 在线、阀门、电量、告警和更新时间 |
|
||
| `MoneyBreakdown` | 商品、优惠、运费、押金、退款和应付金额拆分 |
|
||
| `TimelineView` | 订单、配送、工单、安全事件和审核进度 |
|
||
| `SensitiveText` | 手机号、银行卡、证件和人员信息脱敏展示 |
|
||
| `EvidencePicker` | 图片、视频、定位和采集时间的受控取证 |
|
||
| `RiskConfirmationSheet` | 开阀、群控、解绑、退押和资金操作二次确认 |
|
||
|
||
### 3.3 页面状态要求
|
||
|
||
每个异步页面必须覆盖：
|
||
|
||
- 首次加载、骨架或进度状态。
|
||
- 正常内容、下拉刷新和分页加载。
|
||
- 空数据及明确的下一步入口。
|
||
- 网络失败、权限失败、会话失效和服务不可用。
|
||
- 写操作提交中、成功、失败、冲突、重复请求和结果待确认。
|
||
|
||
不得用 Toast 或静态成功页代替服务端最终状态。设备命令、支付、退款、提现和退押在无最终回执时只能显示“处理中”或“待确认”。
|
||
|
||
### 3.4 适配与无障碍
|
||
|
||
- 以 390×844 逻辑像素作为设计比对基准，同时验证 320、360、390、430 宽度。
|
||
- 文本缩放 1.3 倍时不得遮挡按钮、价格、状态和安全提示。
|
||
- 状态不能只依赖颜色，必须同时提供图标或文字。
|
||
- Tab、筛选、底部操作区和软键盘出现时不得导致内容重叠。
|
||
- Android 返回键、iOS 返回手势和 Web 浏览器前进后退必须保持路由一致。
|
||
|
||
## 4. 页面、路由与开发范围
|
||
|
||
状态说明：`保留优化` 表示已有主要 API 或页面；`接口扩展` 表示已有领域能力但不足以完成设计；`新增闭环` 表示需要新增用户端、Client API 和后台配置。
|
||
|
||
### 4.1 入口、首页与设备
|
||
|
||
| 编号 | 页面与设计图 | 建议路由 | 开发状态 | 主要工作 |
|
||
| --- | --- | --- | --- | --- |
|
||
| 01 | `01-登录页.png` | `/login` | 保留优化 | 对齐验证码/密码切换、协议、记住状态、忘记密码和错误定位 |
|
||
| 02 | `02-智能角阀功能介绍.png`、`02-1-安全案例.png`、`02-2-法律法规.png`、`02-3-气价信息.png` | `/onboarding/safety?tab=` | 接口扩展 | 内容版本、强制阅读、展示频率、气价信息和根级守卫 |
|
||
| 03 | `03-首页.png` | `/home` | 保留优化 | 合并服务归属、内容、设备摘要、快捷服务和公告入口 |
|
||
| 04 | `04-智能角阀控制.png` | `/devices/:identity` | 新增闭环 | 状态、遥测、安全检查、开关阀命令和最终回执 |
|
||
| 05 | `05-一键报修.png` | `/repairs/new` | 接口扩展 | 故障分类、证据、语音转写、地址、定位和紧急提示 |
|
||
| 06 | `06-1-扫码添加确认.png`、`06-2-蓝牙连接设备.png`、`06-3-手动输入设备码.png` | `/devices/add/:method` | 新增闭环 | 三种并存入口、设备校验、绑定确认和失败恢复 |
|
||
| 07 | `07-气瓶基本信息.png` | `/cylinders/:identity` | 新增闭环 | 气瓶规格、充装、制造、有效期、来源和异常提示 |
|
||
| 08 | `08-设备分组控制.png` | `/device-groups` | 部分闭环 | 分组 CRUD、设备归组已完成；逐设备群控和安全检查待物联网接口 |
|
||
| 09 | `09-安全告警与报警器.png` | `/safety/alarms` | 新增闭环 | 报警器状态、告警、测试、联动关阀和紧急电话 |
|
||
| 10 | `10-紧急联系人.png` | `/safety/contacts` | 新增闭环 | 联系顺序、通知渠道、设备查看/控制授权和审计 |
|
||
|
||
### 4.2 商城、押金与购买
|
||
|
||
| 编号 | 页面与设计图 | 建议路由 | 开发状态 | 主要工作 |
|
||
| --- | --- | --- | --- | --- |
|
||
| 11 | `11-燃气商城.png` | `/shop` | 保留优化 | 分类、搜索、商品卡、库存、收藏和购物车数量 |
|
||
| 12 | `12-商品详情.png` | `/products/:identity` | 部分实现 | 真实图片/参数/库存、数量、分享、收藏、加购和结算已接入；规格组合依赖后台配置，配送预约与保障标准暂未开放 |
|
||
| 13 | `13-购物车.png` | `/cart` | 接口扩展 | 选择、数量、删除、失效商品、价格试算和结算 |
|
||
| 14 | `14-提交订单.png` | `/checkout` | 接口扩展 | 地址、预约、优惠、费用、发票、备注和支付方式 |
|
||
| 15 | `15-我的收藏.png` | `/favorites` | 新增闭环 | 收藏列表、取消、下架保留和加入购物车 |
|
||
| 16 | `16-押金管理.png` | `/deposits` | 新增闭环 | 押金汇总、明细、使用中、退款中和已退回 |
|
||
| 17 | `17-退瓶退押金.png` | `/deposits/return` | 首期闭环已完成 | 对象选择、上门回收、验收、扣减和退款去向；最近安检结论暂未开放 |
|
||
| 18 | `18-气瓶下单.png` | `/gas-orders/new` | 新增闭环 | 气站、规格、库存、配送时段、换气和押金试算 |
|
||
| 19 | `19-支付确认.png` | `/payment/:business/:identity` | 已建立，继续对齐 | 渠道选择、余额密码、二次确认、调起渠道和服务端支付结果 |
|
||
|
||
### 4.3 订单、配送与售后
|
||
|
||
| 编号 | 页面与设计图 | 建议路由 | 开发状态 | 主要工作 |
|
||
| --- | --- | --- | --- | --- |
|
||
| 20 | `20-订单中心.png` | `/orders` | 保留优化 | 气瓶/商城/报修聚合、状态筛选和可用操作 |
|
||
| 21 | `21-订单详情.png` | `/orders/:business/:identity` | 接口扩展 | 商品、金额、支付、合同、履约、人员和售后入口 |
|
||
| 22 | `22-配送详情.png` | `/gas/orders/:identity/delivery` | 首期部分实现 | 配送员、有效资质、配送点、预约和交付状态已接入；车辆资质、受控联系和真实头像资源仍待补 |
|
||
| 23 | `23-配送轨迹.png` | `/gas/orders/:identity/delivery/track` | 首期部分实现 | 本人订单、约百米简化轨迹、更新时间、历史节点与刷新已接入；受控电话和配送问题上报仍待补 |
|
||
| 24 | `24-电子发票.png` | `/invoice/:business/:identity` | 二期入口已实现 | 本人订单事实和完整表单结构可见，统一标“即将开放”；抬头、申请、状态、预览和下载授权待二期 |
|
||
| 35 | `35-安全记录详情.png` | `/safety/events/:identity` | 新增闭环 | 风险等级、关阀结果、证据、时间线、整改和复检 |
|
||
| 36 | `36-申请售后.png` | `/after-sales/new` | 接口扩展 | 类型、原因、方案、证据、联系人和退款审核 |
|
||
| 42 | `42-报修工单详情.png` | `/repairs/:identity` | 接口扩展 | 工单详情、进度、证据、工程师、改期、取消和确认 |
|
||
| 48 | `48-服务评价.png` | `/reviews/new` | 新增闭环 | 总体/分项评分、标签、凭证和安全交付确认 |
|
||
| 49 | `49-预约安全巡检.png` | `/inspections/new` | 新增闭环 | 服务、设备、日期时段、联系人、周期规则和取消改期 |
|
||
|
||
### 4.4 个人中心、账户与消息
|
||
|
||
| 编号 | 页面与设计图 | 建议路由 | 开发状态 | 主要工作 |
|
||
| --- | --- | --- | --- | --- |
|
||
| 25 | `25-个人中心.png` | `/me` | 保留优化 | 资料、钱包、订单、设备、安全家庭和常用入口 |
|
||
| 26 | `26-我的记录.png` | `/records` | 接口扩展 | 用气、设备、告警、报修、押金和发票聚合索引 |
|
||
| 27 | `27-用气统计.png` | `/usage` | 新增闭环 | 日周月年趋势、构成、安全趋势、明细和数据口径 |
|
||
| 28 | `28-我的钱包.png` | `/wallet` | 保留优化 | 余额、可提现余额、押金、充值、提现、银行卡和账单 |
|
||
| 29 | `29-地址管理.png` | `/addresses` | 接口扩展 | 列表、新增、编辑、删除、默认地址和服务范围校验 |
|
||
| 30 | `30-消息中心.png` | `/messages` | 新增闭环 | 安全、订单、服务、公告、已读和对象跳转 |
|
||
| 31 | `31-设置.png` | `/settings` | 接口扩展 | 账号、通知、权限、支付密码、协议、退出和注销 |
|
||
| 32 | `32-供气合同.png` | `/contracts` | 接口扩展 | 列表、详情、下载、签署、变更、到期和续签 |
|
||
| 33 | `33-家庭成员与设备共享.png` | `/family` | 新增闭环 | 成员邀请、设备范围、查看/控制授权和撤销 |
|
||
| 34 | `34-我的设备.png` | `/devices` | 部分闭环 | 搜索、分类、分组已完成；在线状态、快捷控制和添加待接口 |
|
||
| 37 | `37-邀请注册.png` | `/invite/:token` | 接口扩展 | 邀请解析、登录/注册、地址确认、归属建立和异常提示 |
|
||
| 38 | `38-余额充值.png` | `/wallet/recharge` | 保留优化 | 套餐、自定义金额、渠道、限额和结果轮询 |
|
||
| 39 | `39-余额提现.png` | `/wallet/withdraw` | 保留优化 | 到账卡、金额、手续费、支付密码、审核和受限余额 |
|
||
| 40 | `40-银行卡管理.png` | `/wallet/banks` | 保留优化 | 列表、绑定、默认到账卡、实名校验和解绑二次确认 |
|
||
| 41 | `41-个人资料.png` | `/me/profile` | 接口扩展 | 头像、昵称、手机号、认证、服务归属和默认地址 |
|
||
|
||
### 4.5 内容、安全设置与扩展能力
|
||
|
||
| 编号 | 页面与设计图 | 建议路由 | 开发状态 | 主要工作 |
|
||
| --- | --- | --- | --- | --- |
|
||
| 43 | `43-安全内容中心.png`、`43-1-安全宣传.png`、`43-2-安全视频.png`、`43-3-法律法规.png`、`43-4-平台公告.png` | `/safety-content?tab=` | 接口扩展 | 宣传、视频、法规、公告、搜索、筛选、详情和阅读状态 |
|
||
| 44 | `44-自动关阀设置.png` | `/devices/:identity/close-schedules` | 新增闭环 | 规则、周期、提前提醒、启停、执行记录和告警优先 |
|
||
| 45 | `45-电子保修卡.png` | `/devices/:identity/warranty` | 新增闭环 | 保修期限、范围、服务商、维修记录和凭证 |
|
||
| 46 | `46-设备健康月报.png` | `/devices/:identity/reports/:period` | 新增闭环 | 健康评分、在线率、异常、趋势、来源和更新时间 |
|
||
| 47 | `47-安全知识考试.png` | `/safety/exams/:identity` | 新增闭环 | 题目版本、计时、进度、及格规则、提交和结果 |
|
||
|
||
## 5. Flutter 实施方案
|
||
|
||
### 5.1 分层与状态
|
||
|
||
- UI 只负责渲染与收集输入，不直接拼接接口请求。
|
||
- 每个 Feature 使用独立 ViewModel，保持现有 `ChangeNotifier` 模式，状态对象不可变。
|
||
- Repository 返回强类型领域模型；新页面不得继续通过 `raw` Map 读取关键业务字段。
|
||
- 开阀、群控、支付、退款、退押和提现放入 Use Case，统一处理幂等号、二次确认和状态轮询。
|
||
- 相机、相册、扫码、蓝牙、定位、推送、文件下载和支付均定义抽象接口，并分别提供 Android、iOS、Web 适配。
|
||
|
||
### 5.2 路由与守卫
|
||
|
||
- 根级公开路由：登录、注册、邀请解析、公开商品、公开内容。
|
||
- 登录保护路由：设备、订单、钱包、地址、合同、工单、消息、共享和个人资料。
|
||
- 首次宣导守卫在登录成功且会话恢复后执行；未完成当前强制版本阅读时跳转 `/onboarding/safety`。
|
||
- 登录回跳只接受站内绝对路径，禁止外部 URL、协议相对路径和登录循环。
|
||
- 推送和深链只携带业务类型、对象 `identity` 和短期签名上下文，页面打开后重新读取服务端状态。
|
||
|
||
### 5.3 缓存策略
|
||
|
||
| 数据 | 缓存策略 |
|
||
| --- | --- |
|
||
| 内容、法规和公告 | 按内容版本和 ETag 缓存；后台上下架后允许失效 |
|
||
| 商品和分类 | 短时缓存；提交订单前必须重新询价和校验库存 |
|
||
| 服务归属 | 登录后缓存，切换地址、扫码邀请或服务关系变更后失效 |
|
||
| 设备遥测 | 仅保存最后展示快照，必须显示采集时间和数据延迟 |
|
||
| 订单、支付、资金、安全事件 | 本地只缓存展示数据，不得覆盖服务端事实 |
|
||
| 图片和视频 | 使用受控 URL、磁盘缓存上限和过期清理，不持久化敏感取证资源 |
|
||
|
||
## 6. Client API 设计
|
||
|
||
### 6.1 通用约定
|
||
|
||
- 基础路径继续使用 `/heqi/client/v1/user`，现有接口不得改名或改变已有字段语义。
|
||
- 列表统一支持 `page`、`page_size`，响应包含 `items`、`page`、`page_size`、`total`；现有裸数组接口在兼容期继续返回原结构，新页面通过新增分页接口或 `view=page` 使用分页结构。
|
||
- 查询对象统一使用 UUID V7 `identity`，禁止向客户端暴露数据库自增主键。
|
||
- 时间使用 RFC 3339，金额使用整数分，数量使用明确单位。
|
||
- 写接口通过 `Idempotency-Key` 或请求体 `request_no` 保证幂等。
|
||
- 错误响应使用稳定业务码、中文安全文案和可选 `details`；前端不得解析英文错误文案驱动流程。
|
||
- 设备、资金、安全事件、合同和隐私数据全部执行服务端对象归属校验。
|
||
|
||
### 6.2 保留的现有接口
|
||
|
||
以下接口继续保持兼容，并按设计需要补充非破坏性字段：
|
||
|
||
| 接口族 | 现有能力 |
|
||
| --- | --- |
|
||
| `/auth/*` | 验证码、注册、登录、找回密码、资料、头像和修改密码 |
|
||
| `/public/gas-stations`、`/public/delivery-points` | 注册及邀请流程的服务组织选择 |
|
||
| `/public/contents` | 已发布内容列表和 `content_type` 筛选 |
|
||
| `/contents/read-confirmations` | 内容版本阅读确认 |
|
||
| `/public/products` | 已发布商品列表 |
|
||
| `/service-relation` | 当前所属气站和服务配送点 |
|
||
| `/gas/contracts`、`/gas/orders/*` | 供气合同、燃气订单、取消、支付和退款 |
|
||
| `/shop/orders/*` | 商城订单创建、列表、取消、支付、退款和确认收货 |
|
||
| `/tickets/*` | 工单列表、创建、确认和取消 |
|
||
| `/refunds` | 用户退款列表 |
|
||
| `/wallet/*` | 钱包、流水、充值、支付密码、银行卡和提现 |
|
||
|
||
### 6.3 内容与宣导接口
|
||
|
||
| 方法与路径 | 用途 | 实施类型 |
|
||
| --- | --- | --- |
|
||
| `GET /public/contents` | 增加关键词、分类、置顶、发布时间和服务范围筛选 | 扩展 |
|
||
| `GET /public/contents/:identity` | 内容详情，返回正文、媒体、版本和外链信息 | 新增 |
|
||
| `GET /contents/read-statuses` | 批量返回当前用户对内容版本的已读状态 | 新增 |
|
||
| `POST /contents/read-confirmations` | 保留现有阅读确认，增加展示场景字段 | 兼容扩展 |
|
||
| `GET /onboarding/current` | 返回当前宣导版本、标签、强制标志和展示频率 | 新增 |
|
||
| `GET /gas-prices/current` | 按服务归属返回气瓶价格、押金、配送费和更新时间 | 新增 |
|
||
|
||
内容类型保留现有 `notice`、`agreement`，新增 `onboarding`、`safety_case`、`safety_article`、`safety_video`、`regulation` 和 `price_notice`。未知历史类型不得静默转换。
|
||
|
||
### 6.4 设备与安全接口
|
||
|
||
| 方法与路径 | 用途 |
|
||
| --- | --- |
|
||
| `GET /devices` | 本人及已授权设备列表、筛选和设备摘要 |
|
||
| `GET /devices/:identity` | 设备详情、在线状态、阀门状态和最后更新时间 |
|
||
| `GET /devices/:identity/telemetry` | 当前遥测和趋势数据 |
|
||
| `POST /devices/verify` | 扫码或手工设备码预校验 |
|
||
| `POST /devices/bindings` | 确认安装地址、昵称和服务关系后绑定 |
|
||
| `DELETE /devices/:identity/binding` | 受限解绑，返回阻断原因和冷静期 |
|
||
| `POST /devices/:identity/commands` | 创建开阀、关阀或测试命令 |
|
||
| `GET /device-commands/:identity` | 查询命令投递、设备回执、失败或超时状态 |
|
||
| `GET/POST /device-groups`、`PUT/DELETE /device-groups/:identity`、`PUT /devices/:identity/group` | 本人设备分组资料及设备归组 |
|
||
| `POST /device-groups/:identity/commands` | 群控并返回逐设备结果 |
|
||
| `GET /devices/:identity/cylinder` | 当前关联气瓶及充装、制造和有效期信息 |
|
||
| `GET /alarm-devices` | 报警器列表、状态和最近告警 |
|
||
| `POST /alarm-devices/:identity/tests` | 发起报警器测试并查询结果 |
|
||
| `GET /safety/events` | 当前用户安全事件列表 |
|
||
| `GET /safety/events/:identity` | 事件详情、证据、处置和复检状态 |
|
||
| `POST /safety/events/:identity/rechecks` | 申请复检 |
|
||
| `GET/POST/PUT/DELETE /emergency-contacts` | 紧急联系人管理 |
|
||
| `PUT /emergency-contacts/:identity/permissions` | 通知顺序和设备查看/控制授权 |
|
||
| `GET/POST/PUT/DELETE /devices/:identity/close-schedules` | 自动关阀规则管理 |
|
||
| `GET /devices/:identity/close-schedules/executions` | 定时规则执行历史 |
|
||
|
||
设备命令响应必须包含 `command_identity`、`command_type`、`command_status`、`requested_at`、`sent_at`、`acknowledged_at`、`failure_code` 和 `failure_message`。`command_status` 至少支持 `pending`、`sent`、`acknowledged`、`failed`、`timeout`、`cancelled`。
|
||
|
||
### 6.5 商城、气瓶、押金和支付接口
|
||
|
||
| 方法与路径 | 用途 |
|
||
| --- | --- |
|
||
| `GET /public/categories` | 商城一级分类和排序 |
|
||
| `GET /public/products` | 扩展关键词、分类、库存和分页，不破坏现有列表 |
|
||
| `GET /public/products/:identity` | 商品图片、规格、属性、服务和售后详情 |
|
||
| `GET /shop/cart`、`GET/PUT /shop/cart/items/:identity` | 已实现购物车查询、按商品读取版本、设置绝对数量/勾选；数量0归档 |
|
||
| `POST /cart/quote` | 库存、优惠、运费、服务费和押金试算 |
|
||
| `GET /shop/favorites`、`GET/PUT /shop/favorites/items/:identity` | 已落地；分页列表、单品状态、收藏/取消的绝对状态及版本 |
|
||
| `POST /shop/orders/quote` | 商城结算前服务端询价 |
|
||
| `POST /gas/orders/quote` | 气站、气瓶规格、库存、换气和押金试算 |
|
||
| `POST /gas/orders` | 创建气瓶预约订单 |
|
||
| `GET /deposits` | 押金汇总和明细 |
|
||
| `POST /deposit-refunds/quote` | 按设备、气瓶和状态计算预计退款 |
|
||
| `POST /deposit-refunds` | 创建退瓶退押申请 |
|
||
| `GET /deposit-refunds/:identity` | 回收、验收、扣减和退款进度 |
|
||
| `GET /payments/:identity` | 查询统一支付尝试状态 |
|
||
|
||
金额响应至少拆分 `goods_amount`、`discount_amount`、`delivery_fee`、`service_fee`、`deposit_amount`、`payable_amount`。押金不能计入普通商品可开票收入。
|
||
|
||
### 6.6 订单、配送、售后和服务接口
|
||
|
||
| 方法与路径 | 用途 |
|
||
| --- | --- |
|
||
| `GET /orders` | 统一聚合商城、气瓶和报修订单摘要 |
|
||
| `GET /orders/:business/:identity` | 统一订单详情和允许操作 |
|
||
| `GET /orders/:business/:identity/delivery` | 配送人员、车辆、预约和交付状态 |
|
||
| `GET /orders/:business/:identity/tracks` | 本人订单的简化轨迹和历史节点 |
|
||
| `GET /tickets/:identity` | 用户工单详情、进度和证据 |
|
||
| `POST /tickets/:identity/reschedule` | 在规则允许时申请改期 |
|
||
| `POST /after-sales` | 创建完整售后申请 |
|
||
| `GET /after-sales/:identity` | 售后审核、退货、退款和处理记录 |
|
||
| `GET /invoices/eligible-orders` | 查询可开票订单和金额 |
|
||
| `POST /invoices` | 创建发票申请 |
|
||
| `GET /invoices/:identity` | 开具、作废、红冲和文件状态 |
|
||
| `POST /invoices/:identity/download-ticket` | 获取短期预览或下载凭证 |
|
||
| `POST /reviews` | 创建订单或服务评价，保证一单一次有效评价 |
|
||
| `GET /inspection-services` | 可预约巡检服务、规则和费用 |
|
||
| `POST /inspection-appointments` | 创建巡检预约 |
|
||
| `PUT /inspection-appointments/:identity` | 在规则允许时改期 |
|
||
| `DELETE /inspection-appointments/:identity` | 在规则允许时取消 |
|
||
|
||
轨迹响应只返回当前订单履约所需位置，不返回配送员非履约时间的个人轨迹。
|
||
|
||
### 6.7 用户、消息、共享与扩展接口
|
||
|
||
| 方法与路径 | 用途 |
|
||
| --- | --- |
|
||
| `PUT/DELETE /addresses/:identity` | 编辑、删除地址并校验默认地址约束 |
|
||
| `POST /addresses/:identity/default` | 设置默认地址 |
|
||
| `GET /messages` | 按安全、订单、服务和公告筛选消息 |
|
||
| `POST /messages/read` | 批量标记已读 |
|
||
| `GET/PUT /notification-preferences` | 通知偏好；安全通知不可关闭 |
|
||
| `GET /records/summary` | 我的记录各业务分类数量与最近记录 |
|
||
| `GET /usage-statistics` | 按日周月年返回用气量、单位、口径和更新时间 |
|
||
| `GET/POST/DELETE /family-members` | 家庭成员邀请、接受和移除 |
|
||
| `PUT /family-members/:identity/device-permissions` | 授予或撤销设备查看/控制权限 |
|
||
| `GET /devices/:identity/warranty` | 电子保修卡和维修历史 |
|
||
| `GET /devices/:identity/health-reports` | 健康月报列表和详情 |
|
||
| `GET /safety/exams/current` | 当前考试、题目版本和及格规则 |
|
||
| `POST /safety/exams/:identity/attempts` | 创建答题尝试 |
|
||
| `POST /safety/exam-attempts/:identity/submit` | 幂等提交并返回结果 |
|
||
| `POST /account/cancellation-requests` | 账号注销申请和阻断原因 |
|
||
|
||
## 7. 数据模型规划
|
||
|
||
### 7.1 内容域
|
||
|
||
现有 `cms_content` 保留 `content_type`、`title`、`body`、`version_no` 和 `publish_status`，通过迁移增加：
|
||
|
||
- `summary`：列表摘要。
|
||
- `category_code`：内容二级分类。
|
||
- `cover_uri`：受控封面资源。
|
||
- `video_uri`、`video_duration_seconds`：视频资源和时长。
|
||
- `external_url`、`external_domain`：法规或外部资料链接及展示域名。
|
||
- `published_at`、`effective_at`：发布时间和法规生效时间。
|
||
- `is_pinned`、`must_read`、`sort_no`：置顶、强制阅读和排序。
|
||
- `source_name`：发布来源。
|
||
|
||
新增 `cms_content_scope` 保存内容适用的平台、气站、配送点和服务区域；新增 `cms_content_media` 保存多媒体资源、排序、类型和完整性信息。阅读记录继续使用 `cms_content_read`，唯一约束保持“用户 + 内容 + 版本”。
|
||
|
||
### 7.2 用户、设备与安全域
|
||
|
||
| 实体 | 职责与关键字段 |
|
||
| --- | --- |
|
||
| `usr_device_binding` | 用户、设备、地址、昵称、绑定状态、来源和时间 |
|
||
| `user_device_group` | 用户设备分组名称、幂等请求和排序；不承载控制权限 |
|
||
| `usr_device_group_member` | 分组和设备唯一关系 |
|
||
| `usr_emergency_contact` | 联系人、脱敏电话、通知顺序和启用状态 |
|
||
| `usr_device_share` | 所有者、成员、设备、查看/控制权限、有效期和撤销时间 |
|
||
| `dev_close_schedule` | 设备、执行时间、重复周期、提醒、时区和启停状态 |
|
||
| `dev_close_schedule_execution` | 每次调度、命令、回执和失败原因 |
|
||
| `saf_event` | 风险等级、来源设备、状态、自动关阀结果和 SLA |
|
||
| `saf_event_evidence` | 证据类型、受控 URI、采集时间、来源和哈希 |
|
||
| `dev_usage_stat` | 周期、用量、单位、数据来源、计算版本和更新时间 |
|
||
| `dev_health_report` | 报告周期、健康评分、在线率、异常和生成版本 |
|
||
| `dev_warranty` | 保修起止时间、范围、服务商和关联设备 |
|
||
|
||
### 7.3 交易、资金与服务域
|
||
|
||
| 实体 | 职责与关键字段 |
|
||
| --- | --- |
|
||
| `ec_favorite` | 用户与商品唯一收藏关系，下架后保留历史 |
|
||
| `wal_deposit` | 押金对象、规格、数量、单价、原始金额和状态 |
|
||
| `wal_deposit_refund` | 退押申请、预计金额、验收、扣减、实际退款和去向 |
|
||
| `ord_invoice` | 购买方、订单范围、可开票金额、状态和第三方回执 |
|
||
| `ord_invoice_file` | 发票文件、哈希、短期授权和版本 |
|
||
| `ord_after_sale` | 售后类型、原因、方案、审核和退款关系 |
|
||
| `ord_service_review` | 订单、服务人员、评分、标签和安全确认 |
|
||
| `ord_inspection_appointment` | 服务、设备、地址、日期、时段、周期和状态 |
|
||
| `msg_notification` | 消息类型、接收用户、对象、标题、正文、优先级和发送状态 |
|
||
| `msg_notification_read` | 用户消息阅读时间和设备信息 |
|
||
| `msg_notification_preference` | 用户通知渠道与免打扰配置 |
|
||
|
||
所有新增迁移必须为表和字段提供中文数据库 COMMENT；枚举字段 COMMENT 必须列出所有允许值，JSON 字段必须说明结构。
|
||
|
||
## 8. 平台总后台完善
|
||
|
||
平台后台不能只保留通用 `cms_content` 的“公告、协议”选择，需要扩展以下运营能力：
|
||
|
||
- 内容管理：类型、摘要、正文、封面、视频、法规链接、版本、适用范围、排序、置顶、强制阅读、草稿、发布和下架。
|
||
- 气价管理：气站、气瓶规格、商品价格、押金、配送费、有效期和变更记录。
|
||
- 安全规则：告警等级、自动关阀、开阀限制、紧急电话、通知升级和 SLA。
|
||
- 设备规则：绑定限制、分组上限、定时关阀、保修模板和健康报告口径。
|
||
- 消息与推送：模板、渠道、对象范围、跳转目标、发送状态和失败重试。
|
||
- 巡检服务：服务内容、可预约区域、时间段、周期、费用、改期和取消规则。
|
||
- 考试管理：题库、版本、考试时长、及格线、危险题约束和发布状态。
|
||
|
||
后台修改上述配置必须记录操作前后值、操作者、原因和发布时间。已被订单、报告、考试或阅读确认引用的版本不得物理删除。
|
||
|
||
## 9. 关键状态机与业务约束
|
||
|
||
### 9.1 设备命令
|
||
|
||
```text
|
||
pending -> sent -> acknowledged
|
||
-> failed
|
||
-> timeout
|
||
pending/sent -> cancelled（仅服务端允许且设备尚未执行）
|
||
```
|
||
|
||
开阀前服务端必须校验账户、设备归属、共享权限、在线状态、未解除高风险事件、传感器状态和安装条件。前端按钮禁用不能替代服务端校验。
|
||
|
||
### 9.2 订单与支付
|
||
|
||
- 订单状态和支付状态分离；订单创建成功不代表支付成功。
|
||
- 支付回调重复到达不得重复扣款、建单或推进履约。
|
||
- 支付超时、客户端退出或渠道返回未知结果时，页面轮询服务端支付状态。
|
||
- 商品、优惠、库存、押金和运费在提交前重新试算，客户端金额仅供展示。
|
||
|
||
### 9.3 押金退款
|
||
|
||
```text
|
||
draft -> submitted -> pickup_pending -> inspecting -> reviewing
|
||
-> refunded
|
||
-> rejected
|
||
-> cancelled
|
||
```
|
||
|
||
实际退款必须关联原始押金、回收对象、验收结果、扣减明细、审核记录和退款流水。
|
||
|
||
### 9.4 安全事件
|
||
|
||
```text
|
||
open -> acknowledged -> handling -> rectified -> recheck_pending -> closed
|
||
\-> escalated
|
||
```
|
||
|
||
安全事件不可由用户删除。高风险事件关闭前不得通过单设备、群控或定时规则重新开阀。
|
||
|
||
### 9.5 内容与考试
|
||
|
||
- 内容草稿不能进入用户端；发布新版本后按 `must_read` 和展示频率触发宣导。
|
||
- 法规外链跳转前展示域名与风险提示，只允许 HTTPS 和后台白名单域名。
|
||
- 考试尝试绑定题目版本；计时以服务端时间为准，提交操作幂等。
|
||
|
||
## 10. 安全、隐私与异常处理
|
||
|
||
- 用户只能读取本人、本人订单或明确授权家庭成员范围内的数据。
|
||
- 手机号、联系人、配送员、银行卡和证件默认脱敏；拨号使用受控联系能力。
|
||
- 定位只在用户主动选择地址、报修取证或查看本人配送订单时使用。
|
||
- 图片和视频上传校验扩展名、MIME、文件头、大小、完整解码和恶意内容；下载使用短期授权。
|
||
- 日志、埋点、崩溃信息和剪贴板不得记录令牌、支付密码、完整手机号、地址、银行卡和精确定位。
|
||
- 401 及鉴权业务码继续由现有会话层统一清理，业务页面不得重复弹出英文错误。
|
||
- 429 展示稍后重试和剩余等待时间；409 展示服务端当前状态和刷新入口；未知错误使用统一中文文案并保留 `request_id`。
|
||
- 安全通知不可关闭；普通营销通知可按渠道关闭或进入免打扰时段。
|
||
|
||
## 11. 测试与验收
|
||
|
||
### 11.1 Flutter 测试
|
||
|
||
- Repository 测试：正常、空数据、错误码、分页、字段缺失和兼容旧响应。
|
||
- ViewModel 测试：加载、刷新、提交、防重复点击、失败恢复和会话失效。
|
||
- Widget 测试：Tab、筛选、表单校验、键盘、长文本、文本缩放和无障碍语义。
|
||
- Golden 测试：以设计图归一化到 390×844，对首页、四栏主页面、设备详情、内容中心和订单详情做像素比对。
|
||
- 集成测试：登录回跳、首次宣导、设备绑定、关阀/开阀、下单支付、订单配送、报修、退款、充值、提现和消息深链。
|
||
|
||
### 11.2 后端测试
|
||
|
||
- 路由测试覆盖匿名/登录、错误 Client claim、越权对象、归档对象和跨用户访问。
|
||
- 状态机测试覆盖非法跳转、重复请求、并发更新和超时恢复。
|
||
- 幂等测试覆盖订单、支付、退款、充值、提现、退押、报修、设备命令、内容确认和考试提交。
|
||
- 数据测试覆盖金额守恒、押金扣减、钱包流水、库存冻结、命令 Outbox 和审计日志。
|
||
- 上传测试覆盖伪造扩展名、超限文件、损坏媒体、病毒检测失败和过期授权。
|
||
|
||
### 11.3 UI 验收
|
||
|
||
每张设计图至少验证：
|
||
|
||
- 页面路由、返回行为和底部导航符合设计层级。
|
||
- 首屏结构、标题、间距、颜色、圆角、图标和主要信息层级与设计一致。
|
||
- 加载、空数据、错误、离线、无权限、禁用和长数据状态均可使用。
|
||
- 金额、单位、时间、更新时间、来源和状态来自真实接口。
|
||
- 危险操作有二次确认、明确阻断原因和最终回执。
|
||
- 320 至 430 宽度、Android、iOS 和 Web 不出现文字截断或控件重叠。
|
||
|
||
### 11.4 必跑命令
|
||
|
||
```bash
|
||
cd apps/user_app
|
||
flutter analyze
|
||
flutter test
|
||
flutter build apk --debug
|
||
flutter build ios --simulator --no-codesign
|
||
flutter build web --release --dart-define=API_BASE_URL=https://api.example.com
|
||
|
||
cd backend/api
|
||
go test ./...
|
||
go vet ./...
|
||
go build ./cmd/main
|
||
```
|
||
|
||
涉及平台后台时同时执行其类型检查、静态契约检查、单元测试和生产构建。
|
||
|
||
## 12. 分阶段交付
|
||
|
||
### 阶段 A：基础架构与现有功能 UI 对齐
|
||
|
||
- 建立 Feature 目录、强类型 DTO、公共异步状态组件和完整路由骨架。
|
||
- 优化 01、03、11、14、19、20、25、28、29、32、37 至 42 页面。
|
||
- 保持现有 Client API 兼容，补齐详情、分页、地址编辑和支付状态查询。
|
||
|
||
完成标准：现有真实能力全部可用，Release 不出现静态成功功能，核心页面通过 Golden 与回归测试。
|
||
|
||
### 阶段 B：设备安全闭环
|
||
|
||
- 开发 04 至 10、34、35、44 页面。
|
||
- 打通设备绑定、遥测、命令回执、告警、紧急联系人、分组和定时关阀。
|
||
- 完成高风险开阀拦截、自动关阀和审计链路。
|
||
|
||
完成标准：通过 AC-01 至 AC-05、AC-12、AC-15、AC-22 和 AC-25。
|
||
|
||
### 阶段 C：交易、押金与服务履约
|
||
|
||
- 完善 12 至 18、21 至 24、36、48、49 页面。
|
||
- 打通购物车、收藏、气瓶下单、押金、配送详情、轨迹、发票、售后、评价和巡检预约。
|
||
|
||
完成标准：金额、库存、支付、履约、退押、退款和发票均以服务端事实为准，通过 AC-07、AC-11、AC-13、AC-14 和 AC-18。
|
||
|
||
### 阶段 D：内容、消息与增值能力
|
||
|
||
- 完善 02、26、27、30、31、33、43、45、46、47 页面。
|
||
- 打通内容分类、气价、消息、家庭共享、保修、月报和考试后台配置。
|
||
|
||
完成标准：内容版本、阅读确认、通知偏好、授权撤销、报告口径和考试版本可追溯。
|
||
|
||
## 13. 上线与回滚
|
||
|
||
- 新接口、表字段和页面入口使用功能开关按用户、气站或区域灰度。
|
||
- 数据库迁移只新增表或可空字段；扩大枚举时先部署服务端兼容，再部署后台和 App。
|
||
- 旧 API 在至少一个稳定 App 版本周期内保留，禁止先删除再升级客户端。
|
||
- 设备控制、支付、押金和安全事件上线前完成故障演练、审计验证和人工回退流程。
|
||
- 回滚只关闭新入口和新写入，已产生的订单、资金、安全、阅读及审计事实继续可查。
|
||
|
||
## 14. 待确认事项
|
||
|
||
以下事项必须在对应阶段开发前确认：
|
||
|
||
1. 气价、押金和配送费的权威来源、适用区域、生效时间及历史版本。
|
||
2. 安全视频是宣教视频还是现场取证视频；两者必须使用不同权限和留存策略。
|
||
3. 法律法规外链白名单、地方适用范围和版本更新责任人。
|
||
4. 智能瓶阀厂商协议、设备证书、离线行为、命令回执和超时语义。
|
||
5. 开阀责任、自动关阀优先级、人工审批和安全事件关闭条件。
|
||
6. 微信、支付宝、余额支付及退款渠道的正式商户配置。
|
||
7. 退瓶验收、押金扣减、退款去向和争议处理规则。
|
||
8. 地图与受控联系供应商、轨迹刷新频率和定位留存周期。
|
||
9. 发票服务商、税务口径、文件授权和红冲流程。
|
||
10. 巡检服务范围、费用、周期、改期和取消规则。
|
||
|
||
未确认事项不得通过前端默认值固化为业务规则。
|
||
|
||
## 15. 核心文件说明
|
||
|
||
| 文件 | 职责 |
|
||
| --- | --- |
|
||
| `apps/user_app/lib/app/router.dart` | 当前用户端路由、四栏导航和鉴权回跳 |
|
||
| `apps/user_app/lib/data/services/api_client.dart` | HTTP、统一响应、业务错误和会话失效 |
|
||
| `apps/user_app/lib/data/repositories/client_repository.dart` | 当前用户端 Client API 访问入口 |
|
||
| `apps/user_app/lib/domain/models/client_models.dart` | 当前通用记录、用户和钱包模型 |
|
||
| `apps/user_app/lib/ui/core/app_theme.dart` | 用户端设计系统主题适配 |
|
||
| `apps/heqi_design_system/lib/src/tokens.dart` | 色彩、间距、圆角、尺寸和动效 Token |
|
||
| `backend/api/internal/routers/client.go` | 用户端和工作人员端 Client API 路由 |
|
||
| `backend/api/internal/logic/client/user/` | 用户端认证、内容、商城、订单、工单和服务归属逻辑 |
|
||
| `backend/api/internal/models/` | 现有业务数据模型和迁移注册 |
|
||
| `frontend/platform_admin/src/api/resources.ts` | 平台资源字段和内容管理配置 |
|
||
|
||
## 16. 维护指南
|
||
|
||
- 新页面先在本文件登记路由、业务对象、接口和验收，再进入开发。
|
||
- 新增接口必须同步请求/响应示例、错误码、鉴权范围和幂等要求。
|
||
- 新增状态值必须同时更新数据库 COMMENT、Go 常量、Flutter 枚举、后台中文映射和测试。
|
||
- 设计修改后只更新受影响页面及关联组件，不无关重构其他模块。
|
||
- 完成一个阶段后更新本文档版本、当前实现状态、测试结果和已知问题。
|
||
|
||
## 17. 变更记录
|
||
|
||
| 版本 | 日期 | 变更内容 |
|
||
| --- | --- | --- |
|
||
| v1.1 | 2026-09-07 | A1 实现、兼容接口、远程联调及未完成视觉项见第 18 节 |
|
||
| v1.0 | 2026-09-06 | 根据 58 张最新参考设计图建立全量开发范围、路由、UI 规范、Client API、数据模型、测试和分阶段交付计划 |
|
||
|
||
## 18. A1 实施增补（2026-09-07）
|
||
|
||
本节记录当前代码事实；第 2 至 12 节其余规划不表示已经实现。v1.0 原文件保留作为归档。本版本为 v1.1，逐页状态以 [开发进度](开发进度_用户端APP全量功能开发.md) 为准。
|
||
|
||
### 18.1 已落地结构
|
||
|
||
```text
|
||
apps/user_app/lib/
|
||
├── data/repositories/primary_repository.dart # 公开内容、服务归属与商品强类型适配
|
||
├── domain/models/primary_models.dart # 内容、商品、归属摘要
|
||
├── domain/models/order_summary.dart # 订单金额、快照与服务端可用动作
|
||
├── ui/core/async_content.dart # 首次加载、保留旧数据刷新、错误与重试
|
||
├── ui/core/feature_entry.dart # 明确保留未开放业务入口
|
||
├── ui/core/text_entry_dialog.dart # 弹窗独立管理控制器与空输入校验
|
||
├── ui/features/auth/login_support.dart # 已发布协议查看、现有密码重置流程
|
||
└── ui/features/orders/order_list.dart # 订单筛选与摘要展示
|
||
backend/api/internal/logic/client/user/
|
||
├── list_response.go # 可选分页与旧数组兼容
|
||
└── login_consent.go # 同意版本校验与已有阅读表幂等留痕
|
||
```
|
||
|
||
沿用 Flutter、Go/Gin/GORM、PostgreSQL、Redis 及已有平台资源。开发环境使用仓库配置的远程数据库和缓存；本机运行 API 与 Web 预览。没有新增数据库表、移动插件或第三方依赖。共享包版本 0.1.1。
|
||
|
||
### 18.2 A1 增量接口契约
|
||
|
||
根路径：/heqi/client/v1/user。响应继续使用 code、message、details、timeseq；公开资源剔除内部 id。
|
||
|
||
| 接口 | 增量 | 兼容与安全 |
|
||
| --- | --- | --- |
|
||
| GET public/products | category_identity、category_name、image_url；可选 page/page_size | 无分页参数仍返回数组；只关联商品图片及分类，修复原先误查商城订单明细的问题 |
|
||
| GET shop/orders、GET gas/orders | status_code、status_name、allowed_actions、items；可选分页 | 只查本人订单；金额为整数分；最终动作仍由写接口重新校验 |
|
||
| POST auth/login | 可选 consents 数组：identity、version、shown_at（RFC3339） | 旧客户端省略仍可登录；新客户端在显式确认后提交；只接受当前已发布 agreement 版本 |
|
||
| 原有验证码、密码重置、下单、退款、支付、地址与工单接口 | 路由及请求字段保持兼容 | A1 继续复用；完整详情及资金状态查询属于 A2 |
|
||
|
||
分页范围：page 1–100000，page_size 1–100；传分页参数时 details 为 {items,page,page_size,has_more}；多查一条判断后续页。不支持 total。非法参数返回既有 ErrInvalidArgument（1704）。
|
||
|
||
新客户端兼容层先读完各页再筛选；大数据量优化留给 A2。未提供 allowed_actions 的旧响应不自行推导可支付/退款。服务端当前动作仅表达候选能力，业务写入仍进行最终状态、支付和退款条件校验。
|
||
|
||
consents 在同一数据库事务内锁定已发布版本，并通过 cms_content_read 的（user_account_id,cms_content_id,version_no）唯一键去重。shown_at 保留客户端展示时间，confirmed_at 由服务端记录。版本失效、缺少展示时间或非法内容类型返回 1704。本次未新增法律条款或伪造已发布协议。
|
||
|
||
### 18.3 业务与视觉冲突记录
|
||
|
||
1. 未开放设备、安全、押金、消息等入口不隐藏，点击解释当前不可办理；不显示样例电量、押金、认证状态或通知数。
|
||
2. 最新商城网格优先于旧 Design System 文档的商品 Row；共用主题 API 不变，服务端 App 回归验证。
|
||
3. 订单按最新设计调整为气瓶订单、商城订单、报修工单三个主 Tab；原退款列表从订单筛选区的“退款/售后”打开。原订单/退款接口保留，旧构造参数映射兼容，退款后重新打开列表读取最新服务端状态。
|
||
4. 商城单品与购物车已使用独立提交订单页，可选择地址、读取气站和钱包、编辑备注，并在创建成功后进入支付确认页。预约、优惠、押金缺服务端能力，界面显示“暂未开放”；电子发票属于二期，显示“即将开放”。
|
||
5. 供气订单详情按最新设计重排配送状态、地址、商品、费用、订单信息和服务操作。合同正文及签收继续使用既有真实接口；配送轨迹、受控电话与押金属于首期缺口，申请售后属于二期，页面分别标识。
|
||
6. 商品详情读取后台商品图片和属性，按最新设计补齐商品信息、规格、配送、保障、说明与底部操作分组。分享复制当前深链；后台未配置规格或参数时如实显示，配送预约和服务标准属于首期缺口。
|
||
5. 37 邀请注册补入 A2，原 /register 不删除。
|
||
6. 用户明确使用远程 PostgreSQL、Redis，覆盖原任务“本地 Mock”措辞造成的歧义。地址管理已定向增加三个字段；未执行全库迁移、清库或导入 seed。
|
||
|
||
### 18.4 验证与维护
|
||
|
||
查看 [操作日志](操作日志_用户端APP_A1_20260907.md) 与 [视觉记录](视觉验收/A1/视觉验收记录_A1.md)。A1 五页为部分实现，不等于 58 页全量完成或 A1 严格视觉验收通过。
|
||
|
||
新增页面继续在领域适配层解析兼容 raw，页面不可读 raw 金额、权限和状态。列表异常不得转为空成功；刷新失败保留上次内容并提示。提交结果未知时保留原请求号，完整跨重启恢复归 A2。
|
||
|
||
截图使用 test/support/a1_fixture.dart 的明确测试数据；运行入口 lib 不导入 Fixture。视觉脚本在 Windows 读取微软雅黑，字体缺失时需提供等价中文字体后重跑，不能用空方块截图验收。
|
||
|
||
本地预览：http://127.0.0.1:18571；API：http://127.0.0.1:12426。开发服务运行于本机，但持久事实仍在原远程数据库。凭据仅从既有开发配置读取，不复制到本文件。
|
||
|
||
2026-09-08支付密码扩展：设置页新增`/settings/payment-password`，复用本人钱包与验证码接口，支持六位数字密码首次设置、旧密码修改及验证码找回。后端采用散列条件更新、Redis原子验证码消费和五次输错锁定；远程独立夹具回滚验证通过，Flutter全量117项测试通过。真实短信尚缺供应商配置，不能将Mock收码流程算生产完成。接口字段、维护方式和验证边界见[支付密码操作日志](操作日志_用户端APP_支付密码_20260908.md)。
|
||
|
||
2026-09-12图26扩展：个人中心新增`/records`“我的记录”入口，聚合本人供气订单和报修工单，支持本月概览、类型筛选和详情跳转。设备操作与告警记录缺首期权威接口，保留入口并提示“暂未开放”；发票记录属二期，提示“即将开放”。详见[开发日志](开发日志_我的记录聚合页_20260912.md)。
|