platforms/docs/项目文档_用户端APP全量功能开发_v1.0.md

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

## 1. 项目概述

### 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` | `/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 返回强类型领域模型；新页面不得继续通过 `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/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 设备命令

```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.0 | 2026-09-06 | 根据 58 张最新参考设计图建立全量开发范围、路由、UI 规范、Client API、数据模型、测试和分阶段交付计划 |