Files

交付用户端首期页面、配套接口、后台资源及测试文档。用户APP构建、静态分析和三个管理后台构建通过；完整测试仍有2项失败，后端模型注释检查未通过，详见交付记录。

2026-09-13 00:57:32 +08:00

58 KiB

Raw Permalink Blame History

用户端 App 全量功能开发文档 v1.1

2026-09-11图19增补：新增商城/气瓶订单支付确认页，金额、商品快照、钱包余额和可用动作以服务端为准。余额扣款在同一事务内校验六位支付密码、更新订单与钱包、写入支付单和账单，重试使用幂等号返回首次结果。优惠券缺少接口，明确显示“暂未开放”；当前测试账号无待付款订单，未执行远程真实扣款。详见支付确认日志。

2026-09-11图28、39、40增补：钱包提现和银行卡入口已从占位接入真实Client API，新增脱敏银行卡列表、绑定、默认到账卡、安全解绑、提现记录、支付密码校验、幂等申请和二次确认。银行卡增加is_default字段及默认切换接口；外部银行回执、短信供应商、押金、优惠券和待退款仍待补齐，详见钱包提现与银行卡日志。

阅读确认接口增加可选content_version精确匹配及幂等内容核对，充值页面尚待接入；见协议版本确认。

充值重试已增加服务端入账查询，避免已到账订单再次拉起渠道，见充值重试入账检查。

2026-09-11最新Flutter全量回归135项通过，充值页新增320/390窄屏及1.3倍字体检查通过；这不代表1:1视觉或真实支付验收，见充值窄屏回归。

充值金额控件按图38补充自定义入口、清空和确认金额，测试通过；当前修改尚未重新部署，视觉仍未通过，见充值金额控件。

2026-09-11充值配置后端和表单Web构建已更新到本地预览12426/18572；修复到账后余额刷新失败的错误提示。构建及回归测试通过，浏览器视觉和真实渠道验证仍待完成，见到账提示修复。

充值表单 /wallet/recharge 已在代码中接入钱包，包含金额、渠道、协议和原请求恢复交互；部署、协议版本留痕和视觉核对尚未完成，见充值表单接入。

充值数据层新增按环境与账号隔离的待确认请求存储，以及先存后发、到账确认后清除的恢复流程；页面接入和支付关闭处理未完成，详见充值请求恢复。

2026-09-11补充钱包充值记录页面 /wallet/recharge-records，支持分页、去重、刷新和失败保留数据；新增交互测试、钱包回归与金额测试共6项通过，静态检查和Web构建通过。充值表单及真实渠道流程未完成，详见充值记录页面。

充值后续接口已增加本人记录分页、按充值标识查询及按请求号恢复结果；创建接口拒绝同请求号更改金额或渠道，真实支付响应增加充值业务标识。远程回滚测试确认Mock重复回调只入账一次，尚不代表图38页面及真实渠道流程完成。详见充值查询与幂等记录。

2026-09-11当前状态：新增图28钱包主页与账单收支筛选、游标分页、详情和金额隐藏。共17张部分实现、41张尚无对应完整页面、0张严格全功能及1:1通过；下方9月8日记录为历史批次。新接口GET /wallet/bills限定本人钱包、兼容旧充值方向in，保留旧/wallet/records。没有资金写入或数据库迁移；充值、提现和其他资产口径仍待补齐。见钱包与账单日志。

2026-09-08 纠偏补充：一级页面按“部分实现”记录；新增资料编辑、真实头像上传、地址管理、商品详情、购物车、收藏、结算页、商城及供气订单详情、供气合同列表、设置与登录密码、报修表单和工单详情，复用品牌及宣传原图。16 张设计已有部分能力、42 张尚无完整页面，0 张通过严格全功能与 1:1 验收。详见设置日志、订单详情日志、收藏日志、购物车日志、头像与视觉日志、地址日志、结算日志、工单日志、报修提交日志。

图32已替换为独立合同列表，可搜索、筛选真实状态并读取正文；修复后端合同ID误查订单明细的问题。本人受控PDF下载已通过浏览器真实落盘、哈希及渲染验证，独立测试合同/文件已清理；原生保存对话框、签署及合同服务仍待补。见合同列表日志、附件日志。

头像使用现有 POST /upload/avatar 上传本人 JPG/PNG（最大 2MB），再通过 PUT /heqi/client/v1/user/auth/profile 保存。省略 avatar 保留原图，变更 URI 必须归当前账户；读取继续使用受保护的 GET auth/avatar。无需数据库迁移；旧客户端保留旧 URI 或清空头像的行为兼容。

1. 项目概述

图32新增本人合同变更记录：读取服务端不可变的生效/续期/终止状态及有效期快照，支持重试和空态；内部人员及原因不公开。另已接入合同申请、气站答复、取消及用户确认，原合同条款不会被申请流程直接修改；仍不等于电子签署审计。见变更记录日志、合同申请日志。

图21供气订单分支：新增本人订单详情、状态历史、实际支付记录及合同正文读取；状态34由本人确认后事务记录签收、完成订单并释放占用，状态23重复确认无副作用。无数据库迁移，远程回滚测试确认无临时记录。常规时间轴已横向对齐，商品素材、押金、配送地图及受控联系仍未完成；图32正文弹层不算完整合同页面。详见供气详情日志。

图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，购物车内嵌推荐，收藏通过底部“猜你喜欢”打开弹层。只推荐有库存的有效商品，过滤本人购物车与收藏场景已收藏商品；按关联分类优先和更新时间排序，不编造销量或画像。客户端条件加购、分页失败重试、详情返回刷新购物车，复用原仓储接口；无新依赖和数据库变更。见推荐商品日志。

图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，图片和参数来自后台，数量随游客登录回跳进入结算。售罄可看不可买，下架明确提示；未补造规格、销量、押金或配送承诺。见商品详情日志。

图05语音输入已接入系统识别服务及Android/iOS用途声明，识别结果写入可编辑故障描述，错误、权限和离页取消有回归覆盖。真实设备麦克风与识别效果仍待验收。见语音输入日志。

图05视觉扩展：编号步骤、故障表单分区、三格照片和可操作联系地址预览已接入。实现与源图继续并排核对，尚未通过严格1:1。见视觉对齐日志。

报修草稿扩展：RepairDraftStore 沿用安全存储保存表单与照片URI，按认证账户和API地址隔离。暂存失败保留当前输入；恢复不会自动提交，结果未知时沿用原请求号。GET /heqi/client/v1/user/ticket-photos/:name 仅读取本账户文件。未提交草稿恢复时重新检查本人地址，损坏草稿须明确清除。见草稿日志。

报修照片扩展：已实现选图、预览、删除、上传、工单关联及本人鉴权读取，浏览器真实提交链路通过；原始拍摄时间、定位和完整视觉验收未完成。见报修照片日志。

订单操作扩展：商城取消与确认收货已接入可执行按钮，修复收货状态校验与重复操作边界。图20仍未完整实现，详见订单操作日志。

1.1 项目名称

瓶安芯用户端 App 产品设计落地与全量功能开发。

1.2 文档目标

本文档以 doc/用户端APP-最新参考产品设计 中 49 个主编号页面组、58 张 PNG 设计图为视觉事实源，结合现有 Flutter 用户端、Go Client API、平台总后台及正式需求，指导研发完成以下工作：

按设计图统一优化用户端 UI，不改变已经确认的蓝白视觉方向。
保留现有真实登录、内容、商城、订单、合同、工单、钱包和地址能力。
补齐设备控制、安全闭环、押金、消息、发票、收藏、家庭共享和扩展服务能力。
完善用户端 Client API、平台后台配置、数据模型、状态机和异常处理。
建立逐页面验收、接口测试、Widget 测试和关键业务集成测试。

1.3 事实源优先级

发生冲突时按以下顺序处理：

安全、支付、隐私、合同和设备控制的服务端规则。
docs/03-用户端App需求.md、docs/02-核心业务流程.md 和 docs/11-数据接口与安全.md。
本文档定义的接口与实施约束。
doc/用户端APP-最新参考产品设计 中对应页面设计图。
当前 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	补齐内容、通知、价格、规则和扩展服务配置

本地运行：

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. 目录结构规划

在不破坏现有代码的前提下逐步扩展为按业务模块组织的结构：

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 设备命令

pending -> sent -> acknowledged
              -> failed
              -> timeout
pending/sent -> cancelled（仅服务端允许且设备尚未执行）

开阀前服务端必须校验账户、设备归属、共享权限、在线状态、未解除高风险事件、传感器状态和安装条件。前端按钮禁用不能替代服务端校验。

9.2 订单与支付

订单状态和支付状态分离；订单创建成功不代表支付成功。
支付回调重复到达不得重复扣款、建单或推进履约。
支付超时、客户端退出或渠道返回未知结果时，页面轮询服务端支付状态。
商品、优惠、库存、押金和运费在提交前重新试算，客户端金额仅供展示。

9.3 押金退款

draft -> submitted -> pickup_pending -> inspecting -> reviewing
      -> refunded
      -> rejected
      -> cancelled

实际退款必须关联原始押金、回收对象、验收结果、扣减明细、审核记录和退款流水。

9.4 安全事件

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 必跑命令

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. 待确认事项

以下事项必须在对应阶段开发前确认：

气价、押金和配送费的权威来源、适用区域、生效时间及历史版本。
安全视频是宣教视频还是现场取证视频；两者必须使用不同权限和留存策略。
法律法规外链白名单、地方适用范围和版本更新责任人。
智能瓶阀厂商协议、设备证书、离线行为、命令回执和超时语义。
开阀责任、自动关阀优先级、人工审批和安全事件关闭条件。
微信、支付宝、余额支付及退款渠道的正式商户配置。
退瓶验收、押金扣减、退款去向和争议处理规则。
地图与受控联系供应商、轨迹刷新频率和定位留存周期。
发票服务商、税务口径、文件授权和红冲流程。
巡检服务范围、费用、周期、改期和取消规则。

未确认事项不得通过前端默认值固化为业务规则。

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，逐页状态以开发进度为准。

18.1 已落地结构

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 业务与视觉冲突记录

未开放设备、安全、押金、消息等入口不隐藏，点击解释当前不可办理；不显示样例电量、押金、认证状态或通知数。
最新商城网格优先于旧 Design System 文档的商品 Row；共用主题 API 不变，服务端 App 回归验证。
订单按最新设计调整为气瓶订单、商城订单、报修工单三个主 Tab；原退款列表从订单筛选区的“退款/售后”打开。原订单/退款接口保留，旧构造参数映射兼容，退款后重新打开列表读取最新服务端状态。
商城单品与购物车已使用独立提交订单页，可选择地址、读取气站和钱包、编辑备注，并在创建成功后进入支付确认页。预约、优惠、押金缺服务端能力，界面显示“暂未开放”；电子发票属于二期，显示“即将开放”。
供气订单详情按最新设计重排配送状态、地址、商品、费用、订单信息和服务操作。合同正文及签收继续使用既有真实接口；配送轨迹、受控电话与押金属于首期缺口，申请售后属于二期，页面分别标识。
商品详情读取后台商品图片和属性，按最新设计补齐商品信息、规格、配送、保障、说明与底部操作分组。分享复制当前深链；后台未配置规格或参数时如实显示，配送预约和服务标准属于首期缺口。
37 邀请注册补入 A2，原 /register 不删除。
用户明确使用远程 PostgreSQL、Redis，覆盖原任务“本地 Mock”措辞造成的歧义。地址管理已定向增加三个字段；未执行全库迁移、清库或导入 seed。

18.4 验证与维护

查看操作日志与视觉记录。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收码流程算生产完成。接口字段、维护方式和验证边界见支付密码操作日志。

2026-09-12图26扩展：个人中心新增/records“我的记录”入口，聚合本人供气订单和报修工单，支持本月概览、类型筛选和详情跳转。设备操作与告警记录缺首期权威接口，保留入口并提示“暂未开放”；发票记录属二期，提示“即将开放”。详见开发日志。

58 KiB Raw Permalink Blame History Unescape Escape