40 KiB
40 KiB
用户端 App 全量功能开发文档 v1.0
1. 项目概述
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 |
/devices/groups |
新增闭环 | 分组 CRUD、成员维护、逐设备群控结果和失败明细 |
| 09 | 09-安全告警与报警器.png |
/safety/alarms |
新增闭环 | 报警器状态、告警、测试、联动关阀和紧急电话 |
| 10 | 10-紧急联系人.png |
/safety/contacts |
新增闭环 | 联系顺序、通知渠道、设备查看/控制授权和审计 |
4.2 商城、押金与购买
| 编号 | 页面与设计图 | 建议路由 | 开发状态 | 主要工作 |
|---|---|---|---|---|
| 11 | 11-燃气商城.png |
/shop |
保留优化 | 分类、搜索、商品卡、库存、收藏和购物车数量 |
| 12 | 12-商品详情.png |
/shop/products/:identity |
接口扩展 | 图片、规格、服务、售后、库存、收藏、加购和购买 |
| 13 | 13-购物车.png |
/cart |
接口扩展 | 选择、数量、删除、失效商品、价格试算和结算 |
| 14 | 14-提交订单.png |
/checkout |
接口扩展 | 地址、预约、优惠、费用、发票、备注和支付方式 |
| 15 | 15-我的收藏.png |
/favorites |
新增闭环 | 收藏列表、取消、下架保留和加入购物车 |
| 16 | 16-押金管理.png |
/deposits |
新增闭环 | 押金汇总、明细、使用中、退款中和已退回 |
| 17 | 17-退瓶退押金.png |
/deposits/refund |
新增闭环 | 对象选择、上门回收、验收、扣减和退款去向 |
| 18 | 18-气瓶下单.png |
/gas-orders/new |
新增闭环 | 气站、规格、库存、配送时段、换气和押金试算 |
| 19 | 19-支付确认.png |
/payments/:identity |
保留优化 | 渠道选择、余额密码、调起渠道和支付状态轮询 |
4.3 订单、配送与售后
| 编号 | 页面与设计图 | 建议路由 | 开发状态 | 主要工作 |
|---|---|---|---|---|
| 20 | 20-订单中心.png |
/orders |
保留优化 | 气瓶/商城/报修聚合、状态筛选和可用操作 |
| 21 | 21-订单详情.png |
/orders/:business/:identity |
接口扩展 | 商品、金额、支付、合同、履约、人员和售后入口 |
| 22 | 22-配送详情.png |
/orders/:business/:identity/delivery |
接口扩展 | 配送员、车辆资质、受控联系、预约和交付状态 |
| 23 | 23-配送轨迹.png |
/orders/:business/:identity/tracks |
接口扩展 | 最近位置、简化轨迹、预计时间、更新时间和历史节点 |
| 24 | 24-电子发票.png |
/invoices |
新增闭环 | 可开票订单、抬头、申请、状态、预览和下载授权 |
| 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 返回强类型领域模型；新页面不得继续通过
rawMap 读取关键业务字段。 - 开阀、群控、支付、退款、退押和提现放入 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/PUT/DELETE /device-groups |
设备分组及成员维护 |
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/POST/PUT/DELETE /cart/items |
购物车查询、加入、改量和删除 |
POST /cart/quote |
库存、优惠、运费、服务费和押金试算 |
GET/POST/DELETE /favorites |
收藏列表、添加和取消 |
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 |
用户、设备、地址、昵称、绑定状态、来源和时间 |
usr_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.0 | 2026-09-06 | 根据 58 张最新参考设计图建立全量开发范围、路由、UI 规范、Client API、数据模型、测试和分阶段交付计划 |