补充移动端产品设计与全量开发文档

docs/README.md

@@ -19,6 +19,14 @@
 | [11-数据接口与安全](11-数据接口与安全.md) | 数据域、接口约定、物联网协议、安全及合规要求 |
 | [12-验收与迭代规划](12-验收与迭代规划.md) | MVP 边界、验收标准、非功能要求与版本路线图 |
 
+## 专题实施文档
+
+| 文档 | 用途 |
+| --- | --- |
+| [用户端 App 全量功能开发](项目文档_用户端APP全量功能开发_v1.0.md) | 将最新 58 张用户端产品设计图落实为页面路由、UI 规范、Client API、数据模型、测试和分阶段交付方案 |
+| [用户端 App 全量开发 AI 提示词](开发提示词_用户端APP全量功能开发_v1.0.md) | 可直接交给开发 AI 使用，包含项目路径、设计与需求事实源、开发批次、接口规则、视觉验收、测试和交付要求 |
+| [服务端 App 三岗位全量功能开发](项目文档_服务端APP三岗位全量功能开发_v1.0.md) | 将安装维修、配送、安全检查共 122 张最新设计图落实为角色路由、UI、Staff Client API、状态机、离线、安全、测试和交付方案 |
+
 ## 阅读与维护规则
 
 - “应/必须”表示上线验收项；“建议”表示增强项；“可选”表示扩展能力。

docs/开发提示词_用户端APP全量功能开发_v1.0.md

@@ -0,0 +1,274 @@
+# 用户端 App 全量功能开发 AI 提示词 v1.0
+
+## 1. 使用方式
+
+在 Codex 或其他具备本机代码访问能力的开发 AI 中，将工作目录设为 `D:\5k\platforms`，然后把第 3 节“主提示词”完整发送给 AI。
+
+首次运行从 A1 批次开始。后续继续开发时仍可使用同一提示词，AI 应读取进度文档后从第一个未完成批次继续，不重复已完成工作。
+
+## 2. 路径速查
+
+### 2.1 代码路径
+
+| 内容 | 绝对路径 |
+| --- | --- |
+| 项目根目录 | `D:\5k\platforms` |
+| 仓库开发规范 | `D:\5k\platforms\AGENTS.md` |
+| Flutter 用户端 | `D:\5k\platforms\apps\user_app` |
+| Flutter 共享设计系统 | `D:\5k\platforms\apps\heqi_design_system` |
+| 用户端路由 | `D:\5k\platforms\apps\user_app\lib\app\router.dart` |
+| 用户端 API Repository | `D:\5k\platforms\apps\user_app\lib\data\repositories\client_repository.dart` |
+| 用户端 HTTP 客户端 | `D:\5k\platforms\apps\user_app\lib\data\services\api_client.dart` |
+| 用户端领域模型 | `D:\5k\platforms\apps\user_app\lib\domain\models\client_models.dart` |
+| 用户端 UI | `D:\5k\platforms\apps\user_app\lib\ui` |
+| 用户端测试 | `D:\5k\platforms\apps\user_app\test` |
+| Go API | `D:\5k\platforms\backend\api` |
+| 用户端 Client API 逻辑 | `D:\5k\platforms\backend\api\internal\logic\client\user` |
+| Client API 路由 | `D:\5k\platforms\backend\api\internal\routers\client.go` |
+| 数据模型 | `D:\5k\platforms\backend\api\internal\models` |
+| 模拟数据 | `D:\5k\platforms\backend\api\internal\seed\mock.go` |
+| 平台配置后台 | `D:\5k\platforms\frontend\platform_admin` |
+
+### 2.2 产品设计与文档路径
+
+| 优先级 | 内容 | 绝对路径 |
+| ---: | --- | --- |
+| 1 | 用户端全量开发主文档 | `D:\5k\platforms\docs\项目文档_用户端APP全量功能开发_v1.0.md` |
+| 2 | 最新产品设计图，49 个编号组、58 张 PNG | `D:\5k\platforms\doc\用户端APP-最新参考产品设计` |
+| 3 | 最新设计说明 | `D:\5k\platforms\doc\用户端APP-最新参考产品设计\产品设计说明_用户端APP_v1.1.md` |
+| 4 | 用户端正式需求 | `D:\5k\platforms\docs\03-用户端App需求.md` |
+| 5 | 核心跨系统流程 | `D:\5k\platforms\docs\02-核心业务流程.md` |
+| 6 | 接口、安全和隐私规则 | `D:\5k\platforms\docs\11-数据接口与安全.md` |
+| 7 | 验收场景 | `D:\5k\platforms\docs\12-验收与迭代规划.md` |
+| 8 | 技术与命名规范 | `D:\5k\platforms\docs\10-技术实现规划.md` |
+| 9 | 移动端设计系统 | `D:\5k\platforms\docs\13-移动端Design-System.md` |
+| 10 | 原产品设计，仅用于核对历史功能 | `D:\5k\platforms\doc\用户端APP-产品设计` |
+
+业务规则发生冲突时，以安全、支付、权限、隐私等服务端规则和正式需求为准；页面布局、信息层级和视觉样式以“最新参考产品设计”为准。原设计只用于确认是否遗漏历史功能，不能覆盖已经确认的新设计。
+
+## 3. 主提示词
+
+````text
+你现在负责“瓶安芯用户端 App”全量开发。不要只输出计划、审计报告或示例代码，要在现有仓库中实际完成代码、接口、测试、视觉核对和文档更新。
+
+一、工作目录与目标
+
+- 仓库根目录：D:\5k\platforms
+- Flutter 用户端：D:\5k\platforms\apps\user_app
+- 共享设计系统：D:\5k\platforms\apps\heqi_design_system
+- Go API：D:\5k\platforms\backend\api
+- 平台配置后台：D:\5k\platforms\frontend\platform_admin
+- 用户端 API 根路径：/heqi/client/v1/user
+- 目标：将 58 张最新产品设计图逐步开发为真实可操作的 Flutter 页面，并同步补齐所需 Go Client API、数据库模型、后台配置和自动化测试。
+
+二、开始前必须完整阅读
+
+1. D:\5k\platforms\AGENTS.md
+2. D:\5k\platforms\docs\README.md
+3. D:\5k\platforms\docs\项目文档_用户端APP全量功能开发_v1.0.md
+4. D:\5k\platforms\doc\用户端APP-最新参考产品设计\产品设计说明_用户端APP_v1.1.md
+5. D:\5k\platforms\docs\03-用户端App需求.md
+6. D:\5k\platforms\docs\02-核心业务流程.md
+7. D:\5k\platforms\docs\10-技术实现规划.md
+8. D:\5k\platforms\docs\11-数据接口与安全.md
+9. D:\5k\platforms\docs\12-验收与迭代规划.md
+10. D:\5k\platforms\docs\13-移动端Design-System.md
+
+设计参考目录：D:\5k\platforms\doc\用户端APP-最新参考产品设计
+
+原设计目录：D:\5k\platforms\doc\用户端APP-产品设计
+
+每开发一个页面，必须先打开最新目录中同编号 PNG，确认布局、文案层级、状态、控件和导航；原设计只用于检查历史功能是否漏掉。不要凭记忆或仅根据文件名制作页面。
+
+三、事实源优先级
+
+1. 当前任务中的明确要求。
+2. 人身安全、设备控制、资金、合同、权限、隐私和审计等服务端规则。
+3. docs/03、docs/02、docs/10、docs/11、docs/12 的正式约束。
+4. 项目文档_用户端APP全量功能开发_v1.0.md。
+5. 用户端APP-最新参考产品设计中的图片和 v1.1 说明。
+6. 当前代码实现。
+7. 原产品设计。
+
+视觉冲突按最新设计处理；业务冲突按服务端规则处理。任何会影响数据兼容、接口或业务口径的冲突都要写入开发进度和操作日志，不能静默选择。
+
+四、当前真实基线
+
+当前 Flutter 已经有登录、注册、首页、商城、订单、个人中心、合同记录、钱包记录、会话恢复和四栏底部导航，但页面数量远少于 58 张设计图。当前 ClientRepository 已接入公开内容、商品、用户资料、头像、钱包、地址、商城订单、燃气订单、合同、工单、流水、退款、支付、服务归属、创建地址、创建工单和创建商城订单等基础能力。
+
+当前大量业务对象仍通过通用 ClientRecord 和 raw Map 承载。新增页面应逐步使用强类型 DTO、领域模型、Repository 和 ViewModel，但旧页面完成迁移与回归前不能删除兼容代码。
+
+设备控制、安全事件、押金、消息、发票、收藏、紧急联系人、账户注销和完整售后等能力尚未全部落地。不能用静态成功页、延时动画、硬编码金额或本地修改状态冒充服务端实现。
+
+五、开发账号与本地环境
+
+仅在本地 Mock 数据环境使用：
+
+- 用户手机号：13800000001
+- 登录密码：Mock@123456
+- Mock 数据来源：D:\5k\platforms\backend\api\internal\seed\mock.go
+- 本地 API：http://127.0.0.1:12426
+- Android 模拟器访问宿主机：http://10.0.2.2:12426
+
+若 Mock 数据尚未写入，先检查数据库配置和已有数据，再在 D:\5k\platforms\backend\api 中使用与后端相同的本地环境配置执行 `go run ./cmd/cli/main.go mock-data`；该命令必须幂等，不能清库或覆盖用户数据。不得把 Mock 账号、密码或模拟支付逻辑带入生产配置和 Release 功能入口。
+
+六、不可破坏的规则
+
+- 先执行 git status，保留工作区中已有和未跟踪的设计图、文档及用户改动，不清理、不重置、不覆盖无关文件。
+- 保持 apps/user_app、apps/heqi_design_system 和现有技术栈，不新建另一套 App，不整体重写。
+- 保留 /login、/register、/home、/shop、/orders、/me 和现有 Client API 的向下兼容性。
+- 所有金额使用整数分；所有公开资源使用 identity，客户端不提交数据库自增 ID。
+- 状态、权限、金额、库存、设备控制、支付和安全判断由服务端确认，前端只展示服务端结果和 allowed_actions。
+- 写操作必须幂等；设备命令请求成功不等于执行成功，没有最终回执时只能显示“处理中”或“待确认”。
+- 高风险告警未解除时不能开阀，任何群控、自动规则或客户端缓存都不能绕过。
+- 支付、退款、提现、押金、合同、安全事件、设备命令和敏感访问必须可审计。
+- 手机号、地址、证件、银行卡、定位、照片、视频和合同执行最小权限、脱敏和受控访问。
+- 不物理删除资金、安全、订单、设备命令和审计事实。
+- 所有代码注释使用中文；新增 SQL 表和字段都添加准确中文 COMMENT，枚举和 JSON 结构写全。
+- 单个代码文件尽量不超过 1500 行，按功能拆分，不堆进 router.dart、client_repository.dart 或单个页面。
+
+七、UI 实施要求
+
+- 最新视觉参考：D:\5k\platforms\doc\用户端APP-最新参考产品设计
+- 主色 #2563EB，背景 #F7F8FA，成功 #16875D，警告 #B86400，危险 #C7352A。
+- 禁止紫色、渐变、AI 元素、Emoji、玻璃拟态、发光、三维装饰和无业务意义大卡片。
+- 一级导航固定为：首页、商城、订单、我的；二级页使用返回导航，不重复显示底栏。
+- 复用 heqi_design_system 和已有组件，已有能力不得重复实现。
+- 页面必须有 loading、content、empty、error、refreshing；写操作还要有 submitting、conflict、duplicate、unknown-result 和 retry 状态。
+- 图片中的人员、金额、设备状态、日期和成功提示只是设计样例，运行页面必须读取真实接口或明确的测试 Fixture。
+- 不允许把整张设计图当背景图实现页面。所有按钮、列表、Tab、筛选、表单、开关和导航都必须是真实组件并可操作。
+- 视觉比对基准为 390×844，同时验证 320、360、390、430 宽度和 1.3 倍文本缩放。
+- 每完成一页，使用相同数据、视口和状态生成实现截图，与对应设计图并排比较；修复间距、字体、圆角、边框、图标、溢出和底栏遮挡后再标记通过。
+
+八、正确的实施方式
+
+1. 先检查代码和后端路由，建立“已有、部分、缺失”事实表，不把文档规划误认为当前实现。
+2. 运行改动前基线测试，记录已有失败，不能把旧失败算成本次完成。
+3. 读取或创建 D:\5k\platforms\docs\开发进度_用户端APP全量功能开发.md，找到第一个未完成批次。
+4. 一次只完成一个可独立验收的批次，但必须包含所需 Flutter、Go API、模型、测试和文档，不留下只有 UI 没有真实行为的半成品。
+5. 页面需要新接口时先定义契约、错误码、权限、幂等和状态机，再实现 Go 接口及测试，最后接入 Flutter。
+6. 涉及内容、价格、规则、通知、发票或运营开关时，同时补平台后台配置；不要在 App 中写死运营数据。
+7. 每个批次完成后运行最小充分测试、视觉对照、更新开发进度和中文操作日志，然后继续下一批次。
+8. 发现业务口径未确认时，只暂停受影响动作，继续完成不依赖该口径的页面、模型、只读状态和测试；不得自行固化政策。
+
+九、批次顺序
+
+A1：公共底座与五个一级页面
+
+- 统一主题、公共状态组件、页面脚手架和四栏导航。
+- 按 01-登录页.png、03-首页.png、11-燃气商城.png、20-订单中心.png、25-个人中心.png 优化现有页面。
+- 保持真实登录、服务归属、公开内容、商品、订单、钱包摘要和头像能力。
+- 补强类型基础模型、加载/空/错误状态和对应 Widget 测试。
+
+A2：现有业务闭环优化
+
+- 开发或完善 14 提交订单、19 支付确认、21 订单详情、28 钱包、29 地址、32 合同、38 充值、39 提现、40 银行卡、41 个人资料、42 报修详情。
+- 保持现有 API 兼容，补详情、分页、地址编辑、支付结果查询、错误码和幂等测试。
+
+B：设备与安全闭环
+
+- 开发 04 至 10、34、35、44 页面。
+- 打通设备绑定、扫码/蓝牙/手输、遥测、命令回执、告警、紧急联系人、分组控制和定时关阀。
+- 通过 AC-01 至 AC-05、AC-12、AC-15、AC-22、AC-23、AC-25。
+
+C：交易、押金与服务履约
+
+- 开发或完善 12 至 18、22 至 24、36、48、49 页面。
+- 打通商品详情、购物车、收藏、气瓶下单、押金与退押、配送详情、轨迹、发票、售后、评价和巡检预约。
+- 金额、库存、支付、退押、退款、履约和发票均以服务端事实为准。
+
+D：内容、消息与扩展能力
+
+- 开发 02 及 02-1 至 02-3、26、27、30、31、33、43 及 43-1 至 43-4、45、46、47 页面。
+- 完成内容版本、气价、阅读确认、消息、家庭共享、保修卡、设备月报和安全考试。
+
+不要一次创建 58 个空页面或静态路由。按以上顺序做真实的垂直切片，完成一个批次才进入下一个批次。若进度文档显示某批次已通过，直接从第一个未完成批次继续。
+
+十、接口和数据实现要求
+
+- 严格按照“项目文档_用户端APP全量功能开发_v1.0.md”第 6 至第 10 节实施 Client API、领域模型、状态机、设备命令、支付和安全规则。
+- 后端路由注册在 backend/api/internal/routers/client.go；业务逻辑放入 backend/api/internal/logic/client/user 的对应领域文件；模型放 backend/api/internal/models。
+- 不把复杂业务继续全部塞进 client_repository.dart。保留兼容门面，逐步拆分 auth、home、device、safety、shop、order、wallet、content 等 Repository。
+- 新页面不得依赖 raw Map 读取关键状态、金额、权限或设备数据。
+- 列表统一分页；详情响应包含 status_code、status_name、version 和 allowed_actions，并兼容现有字段。
+- 修改模型或路由后同步路由测试、契约和平台后台资源；涉及平台后台时执行 contract:sync 和 contract:check。
+
+十一、验证命令
+
+Flutter 用户端按实际改动执行：
+
+- cd D:\5k\platforms\apps\user_app
+- flutter analyze
+- flutter test --no-pub
+- flutter build web --release --no-pub --dart-define=API_BASE_URL=http://127.0.0.1:12426
+- 涉及移动插件时再验证 flutter build apk --debug；具备 macOS 环境时验证 iOS Simulator。
+
+Go API 按实际改动执行：
+
+- cd D:\5k\platforms\backend\api
+- go test ./...
+- go vet ./...
+- go build ./cmd/main/main.go
+
+平台后台发生改动时执行：
+
+- cd D:\5k\platforms\frontend\platform_admin
+- pnpm contract:sync
+- pnpm type:check
+- pnpm lint
+- pnpm contract:check
+- pnpm build
+
+不要用全仓自动修复或格式化掩盖业务改动。测试不能运行时说明具体环境原因，并继续完成能执行的定向检查。
+
+十二、进度与交付
+
+维护 D:\5k\platforms\docs\开发进度_用户端APP全量功能开发.md，至少记录：
+
+- 58 张图片逐页状态：未开始、开发中、待接口、已实现、已验收。
+- 页面路由、对应接口、测试文件和视觉截图路径。
+- 当前批次、已完成内容、阻塞项、风险和下一批起点。
+
+每个批次新增中文操作日志，记录操作时间、修改文件与函数、变更前后行为、测试结果、边界案例和风险。重大结构或接口变更同步更新项目文档。
+
+最终回复必须包含：
+
+- 本批次实际完成的页面与真实功能。
+- 修改文件和关键行为变化。
+- 新增或变更接口。
+- 实际运行的测试及结果。
+- 视觉比对结果和截图路径。
+- 尚未完成或需要业务确认的内容。
+
+十三、现在开始
+
+先读取规范、主开发文档、最新设计说明和当前代码，检查 git status 并运行基线测试。随后不要停在分析阶段：如果没有已有进度记录，立即实施 A1“公共底座与五个一级页面”；如果已有进度记录，从第一个未完成批次继续。完成本批次代码、真实接口接入、测试、视觉核对、进度文档和操作日志后再汇报。
+````
+
+## 4. 开发顺序说明
+
+推荐从 A1 开始，而不是直接制作设备控制或支付页面，原因如下：
+
+- 登录、首页、商城、订单和个人中心已经具备真实接口基础，可以先建立稳定的 UI、路由和状态组件。
+- 后续 58 张页面都会复用 A1 的主题、列表、状态、金额、错误和导航能力。
+- 先完成真实页面骨架，可以尽早发现设计系统、响应结构和路由兼容问题。
+- 设备、资金与安全能力风险较高，必须等契约、幂等、审计和状态机明确后再接入。
+
+## 5. 本地联调速查
+
+开发环境 Mock 用户：
+
+| 项目 | 值 |
+| --- | --- |
+| 手机号 | `13800000001` |
+| 密码 | `Mock@123456` |
+| API | `http://127.0.0.1:12426` |
+| Android 模拟器 API | `http://10.0.2.2:12426` |
+
+账号只适用于执行过 `mock-data` 的本地开发库。凭据来源为 `backend/api/internal/seed/mock.go`，不得用于生产环境或写入生产配置。
+
+## 6. 变更记录
+
+| 版本 | 日期 | 内容 |
+| --- | --- | --- |
+| v1.0 | 2026-09-07 | 建立用户端 App 全量开发 AI 主提示词，明确路径、事实源、开发批次、真实接口、视觉验收、测试和交付要求 |

docs/操作日志_服务端APP三岗位开发文档_20260906.md

@@ -0,0 +1,44 @@
+# 操作日志：服务端 App 三岗位开发文档
+
+操作时间：2026-09-06 17:49:13  
+操作类型：新增  
+影响模块：服务端 App 产品设计落地、Flutter 开发规划、Staff Client API 规划
+
+## 操作前状态
+
+- 安装维修端、配送端、安全检查端最新产品设计图已生成，共 122 张。
+- 已有《服务端 APP 三岗位产品设计与开发》高层说明，但未逐页落到路由、接口、状态和验收。
+- 当前 Flutter 仅有通用任务页面和三栏导航，Go Staff Client API 只覆盖基础登录、准入、任务、配送、钱包和取证能力。
+
+## 具体操作
+
+- 核对三个最新产品设计目录及岗位产品设计说明。
+- 核对 `apps/service_app` 当前路由、领域模型、Repository 和离线草稿能力。
+- 核对 `backend/api/internal/routers/client.go` 中已注册 Staff Client API。
+- 新增全量开发文档，逐项覆盖 40 个安装维修页面、42 个配送页面和 40 个安全检查页面。
+- 明确蓝色主题、无紫色、无 AI 元素的视觉要求，并记录与旧移动端设计系统的冲突处理。
+- 补充接口规划、状态机、数据模型、离线、安全、测试、阶段计划和完成定义。
+
+## 操作后状态
+
+- 已形成可供产品、Flutter、后端和测试共同评审的全量开发基线。
+- 文档明确区分“已有、部分、待开发”，未将设计图误记为已实现功能。
+- 未修改现有业务代码、数据库或接口行为。
+
+## 文件变更
+
+- 新增 `docs/项目文档_服务端APP三岗位全量功能开发_v1.0.md`。
+- 新增 `docs/操作日志_服务端APP三岗位开发文档_20260906.md`。
+- 更新 `docs/README.md` 的专题实施文档索引。
+
+## 验证结果
+
+- 已检查 Markdown 表格、标题层级、页面数量、角色编码和现有 API 路径。
+- 已确认全量文档小于 1500 行。
+- 未运行 Flutter 或 Go 测试，因为本次只新增文档，不改变可执行代码。
+
+## 风险评估
+
+- 新增接口均为目标设计，开发前仍需完成产品口径、权限和数据库评审。
+- 旧设计系统中的服务端紫色主题与最新设计冲突，实施 P0 时必须同步代码和文档，并验证用户端主题无回归。
+- 三岗位共享基础设施但业务状态机不同，开发时不可继续扩展为一个通用动态表单。

docs/操作日志_用户端APP开发提示词_20260907.md

@@ -0,0 +1,43 @@
+# 操作日志：用户端 App 开发提示词
+
+操作时间：2026-09-07 18:50:44  
+操作类型：新增  
+影响模块：用户端 App 开发启动、文档索引
+
+## 操作前状态
+
+- 用户端最新参考产品设计已有 49 个主编号页面组、58 张 PNG。
+- 已有用户端全量功能开发文档，但缺少一份可直接交给开发 AI 执行的总提示词。
+- 当前 Flutter 用户端已有真实登录、首页、商城、订单、个人中心和部分记录能力。
+
+## 具体操作
+
+- 核对 Flutter 用户端、共享设计系统、Go Client API、数据模型、模拟数据和平台后台路径。
+- 核对最新产品设计说明、正式需求、跨系统流程、安全、验收和全量开发文档。
+- 新增可直接使用的 AI 主提示词，写明事实源优先级、开发批次、接口规则、视觉要求、测试和交付格式。
+- 写入本地 Mock 用户账号来源和联调地址，并明确不得进入生产配置。
+- 更新 `docs/README.md` 专题实施文档索引。
+
+## 操作后状态
+
+- 开发 AI 可从 `D:\5k\platforms` 直接按提示词开始 A1 批次。
+- 提示词要求先读取现状、保护已有改动，再进行实际编码，不允许只生成计划或静态成功页面。
+- 未修改 Flutter、Go、数据库或平台后台业务代码。
+
+## 文件变更
+
+- 新增 `docs/开发提示词_用户端APP全量功能开发_v1.0.md`。
+- 新增 `docs/操作日志_用户端APP开发提示词_20260907.md`。
+- 更新 `docs/README.md`。
+
+## 验证结果
+
+- 已核对全部引用路径存在。
+- 已核对最新设计目录包含 58 张 PNG。
+- 已核对 Mock 用户手机号与密码来源。
+- 本次仅新增文档，未运行 Flutter 或 Go 测试。
+
+## 风险评估
+
+- 全量功能开发跨越 Flutter、API、数据库和后台配置，必须按批次交付，不能一次创建大量空页面。
+- 设备、安全和资金能力必须先完成服务端契约与审计，禁止由客户端模拟成功。

docs/项目文档_服务端APP三岗位产品设计与开发_v1.0.md

@@ -0,0 +1,182 @@
+# 项目文档：服务端 APP 三岗位产品设计与开发 v1.0
+
+## 1. 项目概述
+
+### 1.1 项目名称
+
+服务端 APP 安装维修、配送、安全检查三岗位 UI 优化与功能完善。
+
+### 1.2 目标
+
+以三个“最新参考产品设计”目录为目标界面，升级现有 Flutter `apps/service_app`。保留当前真实登录、角色识别、准入、任务、取证、草稿和接口能力，通过扩展路由、领域状态机、专用页面与服务端接口补齐业务闭环。
+
+### 1.3 目标设计目录
+
+- `doc/服务端APP-安装端-最新参考产品设计`：40 张页面。
+- `doc/服务端APP-配送端-最新参考产品设计`：42 张页面。
+- `doc/服务端APP-安全检查端-最新参考产品设计`：40 张页面。
+
+上述图片是目标状态，不是当前完成状态。各岗位目录中的《产品设计说明》提供逐页功能和验收要求。
+
+## 2. 当前系统状态
+
+### 2.1 已有能力
+
+- Flutter 单应用支持登录后按角色进入安装维修、配送或安全检查岗位。
+- 路由已有 `/login`、`/preflight`、`/tasks/:identity`、`/tasks/:identity/evidence`、`/work`、`/records`、`/me`。
+- 仓储层已有个人资料、作业前检查、钱包、考勤、任务列表与详情。
+- 通用工单已有开始、异常、恢复和结果提交。
+- 配送已有轨迹追加、到达和签收提交。
+- 证据文件可上传，本地草稿具备加密保存基础。
+
+### 2.2 主要差距
+
+- 当前路由以通用页面为主，无法承载三个岗位各自的完整步骤、字段和异常分支。
+- 后端接口尚未覆盖岗位申请、每日培训、详细资质、排单、气瓶、收款、隐患、整改、复检、提现、知识库、人工支持等目标能力。
+- 任务状态和 `allowed_actions` 不完整，客户端容易出现“页面有按钮但服务端不可执行”的风险。
+- 记录、统计、个人资料、通知和离线冲突仍需领域化。
+- 当前完成状态不能由图片推断，必须以代码、接口和自动化测试为准。
+
+## 3. 技术栈与运行环境
+
+- 客户端：Flutter、Dart、GoRouter、现有网络与本地存储封装。
+- 服务端：沿用项目现有 `/heqi/client/v1/staff` API 体系。
+- 本地数据：延续现有加密草稿机制，新增附件队列、重试、冲突版本和清理策略。
+- 运行环境：项目当前 Flutter 与 Android 构建环境；不得为本次 UI 优化替换应用框架。
+
+## 4. 目录结构建议
+
+```text
+apps/service_app/lib/
+├── app/
+│   ├── router.dart                    # 现有路由入口，扩展岗位子路由
+│   └── dependencies.dart              # 仓储、草稿、会话等依赖
+├── data/
+│   ├── models/                        # 任务、证据、风险、气瓶、结算模型
+│   └── repositories/
+│       └── service_repository.dart    # 保留现有方法并扩展岗位接口
+├── domain/
+│   ├── installation/                  # 安装维修状态与动作
+│   ├── delivery/                      # 配送与空瓶状态与动作
+│   ├── inspection/                    # 安检、隐患、整改和复检
+│   └── shared/                        # 身份、准入、钱包、通知、离线
+└── ui/
+    ├── design_system/                 # 颜色、文字、间距、按钮、状态标签
+    ├── features/shared/               # 登录、准入、消息、钱包、个人中心
+    ├── features/installation/         # 安装维修专用页面
+    ├── features/delivery/             # 配送专用页面
+    └── features/inspection/           # 安检专用页面
+```
+
+原则：通过新增目录、页面和方法扩展现有实现；保留公共接口与现有路由兼容层，避免一次性重写。
+
+## 5. 共享设计系统
+
+| 项目 | 规范 |
+| --- | --- |
+| 主色 | `#2563EB` |
+| 页面背景 | `#F7F8FA` |
+| 成功 | `#16875D` |
+| 提醒 | `#B86400` |
+| 危险 | `#C7352A` |
+| 页面边距 | 20px 视觉基准，代码按 Flutter 逻辑像素适配 |
+| 圆角 | 最大 8px，除头像、状态点、开关等固有圆形控件 |
+| 图标 | Material 或项目既有图标库，禁止手绘占位符 |
+| 禁止项 | 紫色、紫色渐变、光晕、AI 图形、AI 文案、装饰性大卡片 |
+
+## 6. 路由与模块规划
+
+### 6.1 共享路由
+
+- 登录、岗位申请、作业前检查、准入阻断、每日培训。
+- 消息、钱包、提现、银行卡、离线队列、个人资料、二维码、设置、人工支持、知识库和反馈。
+- 共享页面通过角色配置切换标题、字段、权限和接口，不硬编码岗位文案。
+
+### 6.2 安装维修模块
+
+- 工单列表与详情、使用条件、材料、安装、测试、前期安检、签名、收款、完成。
+- 维修执行、安全检查、异常恢复、巡检、复检、备件、保修和回访。
+
+### 6.3 配送模块
+
+- 订单、接单改派、时间排单、路线排单、导航到达、围栏异常。
+- 气瓶扫描、随瓶安检、取证、收款、签收、空瓶回收、蓝牙设备和轨迹补传。
+- 服务用户、配送记录与配送统计。
+
+### 6.4 安全检查模块
+
+- 任务、到场、设备、环境、取证、签名、合格结果和完成。
+- 不合格、风险分级、一级高风险处置、整改通知、隐患、整改、复检和拒检。
+- 区域抽查、安检记录与安检统计。
+
+## 7. 服务端接口规划
+
+### 7.1 兼容原则
+
+- 保留现有路径和响应字段，新增字段均允许旧客户端忽略。
+- 新动作优先添加子资源或动作端点，不改变现有 `start`、`exception`、`recover`、`submit-result` 语义。
+- 所有变更动作接收幂等键并返回服务端版本号、最终状态和 `allowed_actions`。
+- 错误响应返回稳定错误码、用户可读消息、是否可重试和必要的当前资源快照。
+
+### 7.2 共享接口组
+
+- 岗位申请与审核、角色和组织、资质与到期提醒。
+- 作业前检查、考勤、培训、授权设备和阻断原因。
+- 钱包明细、提现、银行卡、消息、知识库、人工服务请求和反馈。
+- 附件初始化、分片上传、完成确认、校验失败和断点续传。
+
+### 7.3 岗位专用接口组
+
+- 安装维修：条件、材料、步骤、测试、签名、收款、备件、保修与回访。
+- 配送：接单、改派、排单、气瓶、围栏、安检、收款、签收、空瓶、押金和轨迹。
+- 安检：检查项、测量值、风险分级、抢险联动、整改单、隐患、整改、复检和拒检。
+
+## 8. 数据模型要求
+
+- 所有任务包含 `id`、`role_code`、`status`、`version`、`allowed_actions`、计划时间、用户与脱敏地址。
+- 所有状态事件包含操作人、角色、设备、客户端时间、服务端时间、定位与幂等键。
+- 证据包含类型、业务步骤、文件哈希、大小、MIME、拍摄时间、定位精度、本地状态和服务端文件标识。
+- 金额使用最小货币单位整数，分别记录商品、押金、优惠、线上、线下、已核验、待核验和差额。
+- 风险字段固定枚举并带规则版本，禁止自由文本替代等级。
+- 数据库新增字段必须提供中文 `COMMENT`；枚举字段列出全部值，JSON 字段说明结构。
+
+## 9. 离线与安全
+
+- 草稿、附件和签名使用系统安全存储管理的密钥加密，日志不记录明文手机号、地址、签名或文件内容。
+- 离线队列按资源和动作排序；相同幂等键只执行一次。
+- 冲突时展示本地版本、服务端版本和差异，不静默覆盖。
+- 退出登录、切换账号和清理缓存前检查未同步数据并阻断危险操作。
+- 地图列表默认显示模糊点位，精确地址仅在授权任务详情展示。
+
+## 10. 分阶段开发计划
+
+| 阶段 | 范围 | 完成标准 |
+| --- | --- | --- |
+| P0 | 共享设计系统、角色路由、准入、状态与错误模型 | 三岗位可登录并进入正确工作台，现有功能无回归 |
+| P1 | 三岗位核心任务主链路 | 安装、配送、安检各有一条正常链路端到端完成 |
+| P2 | 高风险与异常链路 | 阻断、失败、拒检、一级风险、改派、围栏异常可闭环 |
+| P3 | 离线、证据、冲突与幂等 | 弱网、断网、重复提交和版本冲突测试通过 |
+| P4 | 钱包、记录、统计、资质与支持 | 目标目录全部页面有对应路由、接口或明确只读状态 |
+| P5 | 全量视觉与回归 | 逐页截图比对、无障碍、性能、安全和兼容性验收通过 |
+
+## 11. 测试策略
+
+- 单元测试：金额、风险分级、允许动作、状态转换、幂等和冲突合并。
+- 仓储测试：现有 API 兼容、新接口解析、错误码、重试和超时。
+- Widget 测试：表单校验、按钮状态、长文本、空列表、失败和离线提示。
+- 集成测试：三岗位正常链路及关键异常链路。
+- 安全测试：越权、敏感信息、日志泄露、本地加密、附件伪造和重复提交。
+- 视觉回归：目标图片与相同状态、相同逻辑尺寸的 Flutter 截图并排比较。
+
+## 12. 验收与发布
+
+- 每张目标图片必须映射到页面、路由、状态、接口和测试，不以“已经画图”代替开发完成。
+- 原有真实登录、任务、取证、草稿和配送接口行为必须保持兼容。
+- 关键接口必须先在测试环境验证，再分岗位灰度发布。
+- 发布前完成数据库变更审核、接口文档、移动端回归、异常演练和回滚方案。
+
+## 13. 变更记录
+
+| 版本 | 日期 | 内容 |
+| --- | --- | --- |
+| v1.0 | 2026-09-06 | 建立三岗位目标产品设计与开发对照，明确共享架构、接口、状态机、离线、安全、测试和发布要求 |

docs/项目文档_服务端APP三岗位全量功能开发_v1.0.md

@@ -0,0 +1,694 @@
+# 服务端 App 三岗位全量功能开发文档 v1.0
+
+## 1. 项目概述
+
+### 1.1 项目名称
+
+瓶安芯服务端 App 安装维修、配送、安全检查三岗位产品设计落地与全量功能开发。
+
+### 1.2 文档目标
+
+本文档以三个“最新参考产品设计”目录中的 122 张页面设计图为目标界面，结合现有 Flutter `apps/service_app`、Go Staff Client API、正式需求和当前数据库模型，指导研发完成以下工作：
+
+- 按已确认设计图优化三岗位 UI，保留蓝白、正式、简洁的移动端视觉方向。
+- 保留现有真实登录、角色识别、作业前检查、任务、取证、轨迹、签收、钱包和加密草稿能力。
+- 将通用任务页面扩展为安装维修、配送和安全检查三套独立业务流程。
+- 补齐岗位申请、每日培训、消息、资质、排单、气瓶、收款、隐患、整改、复检、统计、提现、知识库和人工支持等接口闭环。
+- 建立逐设计图的路由、状态、接口、异常处理、测试和发布验收标准。
+
+### 1.3 设计事实源
+
+| 岗位 | 设计目录 | 页面数量 | 角色编码 |
+| --- | --- | ---: | --- |
+| 安装维修 | `doc/服务端APP-安装端-最新参考产品设计` | 40 | `installer` |
+| 配送 | `doc/服务端APP-配送端-最新参考产品设计` | 42 | `delivery` |
+| 安全检查 | `doc/服务端APP-安全检查端-最新参考产品设计` | 40 | `operations` |
+
+设计图是目标状态，不代表页面、接口或数据库已经实现。图中的人员、地址、金额、日期、任务编号和成功状态均为演示数据，开发时必须以服务端返回结果为准。
+
+### 1.4 事实源优先级
+
+发生冲突时按以下顺序处理：
+
+1. 人身安全、资金、隐私、权限和审计等服务端强制规则。
+2. `docs/04-服务端App需求.md`、`docs/02-核心业务流程.md`、`docs/11-数据接口与安全.md`。
+3. 本文档中的接口、状态机、兼容和验收约束。
+4. 三个“最新参考产品设计”目录及其产品设计说明。
+5. 当前 Flutter 与 Go 实现。
+
+`docs/13-移动端Design-System.md` 中服务端 App 的紫色主色与本次已确认设计冲突。本项目以蓝色 `#2563EB` 为准，P0 阶段必须同步更新设计系统代码和该文档；用户端现有蓝色主题不得受影响。
+
+## 2. 当前实现基线
+
+### 2.1 已有 Flutter 能力
+
+当前 `apps/service_app` 不是空项目，已经具备以下真实能力：
+
+- 登录、会话恢复、令牌失效处理和角色识别。
+- `/preflight` 作业前检查及上下班打卡。
+- `/work`、`/records`、`/me` 三栏导航。
+- `/tasks/:identity` 通用任务详情和 `/tasks/:identity/evidence` 通用取证。
+- 安装维修与安检读取 `/tickets`；配送读取 `/delivery/orders`。
+- 工单开始、异常、恢复、结果提交；配送开始、轨迹、到达、异常、恢复和签收。
+- 图片或视频上传、签名媒体类型、定位采集和加密草稿基础。
+- 钱包概览读取。
+
+### 2.2 已有 Staff Client API
+
+基础路径为 `/heqi/client/v1/staff`。以下接口已在 `backend/api/internal/routers/client.go` 注册，必须保持兼容：
+
+| 方法与路径 | 当前能力 | 说明 |
+| --- | --- | --- |
+| `POST /auth/verification-code` | 已有 | 工作人员验证码 |
+| `POST /auth/login` | 已有 | 密码或验证码登录，仅支持三种岗位角色 |
+| `POST /auth/reset-password` | 已有 | 验证码重置密码 |
+| `GET /auth/profile` | 已有 | 人员、手机号、岗位、工作状态 |
+| `PUT /auth/password` | 已有 | 修改登录密码 |
+| `GET /preflight` | 部分 | 账号、角色、组织、资质、出勤已检查；培训、区域、授权设备为 `not_configured` |
+| `POST /attendance` | 已有 | 上下班打卡，进行中任务会阻止下班 |
+| `GET /tickets`、`GET /tickets/:identity` | 已有 | 安装、维修、安检、复检工单 |
+| `POST /tickets/:identity/start` | 已有 | 已分派工单开始执行 |
+| `POST /tickets/:identity/exception` | 已有 | 工单异常暂停 |
+| `POST /tickets/:identity/recover` | 已有 | 异常工单恢复 |
+| `POST /tickets/:identity/submit-result` | 部分 | 结果、结论、证据和签名；不足以承载全部分步表单 |
+| `GET /delivery/orders`、`GET /delivery/orders/:identity` | 已有 | 当前配送员订单与明细 |
+| `POST /delivery/orders/:identity/start` | 已有 | 开始配送 |
+| `POST /delivery/orders/:identity/tracks` | 已有 | 1 至 100 个轨迹点批量追加 |
+| `POST /delivery/orders/:identity/arrive` | 已有 | 定位和围栏校验后到达 |
+| `POST /delivery/orders/:identity/exception` | 已有 | 配送异常暂停 |
+| `POST /delivery/orders/:identity/recover` | 已有 | 配送恢复 |
+| `POST /delivery/orders/:identity/submit-receipt` | 部分 | 收件人、签名凭证和完成；未含完整气瓶、安检、收款、空瓶数据 |
+| `/wallet`、`/wallet/records` | 已有 | 钱包和流水 |
+| `/wallet/recharges` | 已有 | 充值基础接口，工作人员端是否开放由产品权限控制 |
+| `/wallet/banks` | 已有 | 银行卡列表、绑定和解绑 |
+| `/wallet/withdrawals` | 已有 | 提现列表和申请 |
+
+### 2.3 主要差距
+
+| 范围 | 当前状态 | 开发要求 |
+| --- | --- | --- |
+| 导航与路由 | 仅三栏和通用任务页 | 按角色配置四栏导航，保留旧路由兼容跳转 |
+| 领域模型 | `WorkItem.raw` 承载大量动态字段 | 新页面使用强类型 DTO、领域模型和状态对象 |
+| 工单动作 | 客户端对 ticket 动作有本地硬编码 | 服务端为 ticket 补齐 `allowed_actions` 和字符串状态码 |
+| 岗位流程 | 安装、维修、安检共用通用详情和取证 | 拆分独立 Feature、ViewModel、Use Case 和状态机 |
+| 准入 | 三项仍为 `not_configured` | 接入每日培训、服务区域、授权设备及岗位专用检查 |
+| 证据 | 可上传但缺统一会话、哈希和同步明细 | 补分步证据、原始时间、哈希、重试和冲突处理 |
+| 资金 | 后端接口较完整，客户端仅钱包概览 | 补流水、提现、银行卡、对账、收款确认页面 |
+| 内容与支持 | 未发现对应 Staff API 与页面 | 新增消息、知识库、人工支持、反馈和会诊 |
+
+## 3. 开发边界与兼容原则
+
+- 使用现有 Flutter 单应用和三角色账号体系，不拆成三个安装包。
+- 一个工作人员账号只允许一个服务角色；客户端不得提供本地切换岗位功能。
+- 保留现有 `/work`、`/records`、`/me`、`/tasks/:identity` 和 `submit-result` 等公共入口与接口，新增角色路由后提供兼容重定向。
+- 新接口继续使用 `/heqi/client/v1/staff`，不得更改已有字段语义；新增字段应允许旧客户端忽略。
+- 安装维修与安全检查继续以 `/tickets` 为任务事实源；配送继续以 `/delivery/orders` 为订单事实源。
+- 客户端只展示服务端返回的 `allowed_actions`，不得根据按钮顺序或本地状态猜测可执行动作。
+- 高风险、收款、签收、库存、提现和最终完成必须在线取得服务端确认；断网时只能保存草稿或待同步动作。
+- 所有新增表、字段、枚举和 JSON 数据都必须按项目规范提供中文数据库注释。
+
+## 4. UI 优化实施规范
+
+### 4.1 视觉基线
+
+| 项目 | 目标规范 |
+| --- | --- |
+| 主色 | `#2563EB`，服务端三岗位统一使用 |
+| 页面背景 | `#F7F8FA` |
+| 成功 | `#16875D` |
+| 提醒 | `#B86400` |
+| 高风险与失败 | `#C7352A` |
+| 页面边距 | 20dp 视觉基准，小屏可降至 16dp |
+| 圆角 | 业务卡片和输入框最大 8dp；头像、状态点和开关可保持固有圆形 |
+| 触控区 | 不小于 48dp；主按钮高度 52dp |
+| 图标 | 优先 Material Icons 或现有图标库，不使用手绘占位图标 |
+| 禁止项 | 紫色、紫色渐变、发光、玻璃拟态、AI 图形、AI 助手、AI 文案、无业务意义装饰 |
+
+### 4.2 角色导航
+
+底部导航与已确认工作台设计保持一致：
+
+| 角色 | 一级导航 |
+| --- | --- |
+| 安装维修 | 工单、巡检、记录、我的 |
+| 配送 | 订单、任务、用户、我的 |
+| 安全检查 | 任务、记录、隐患、我的 |
+
+导航使用角色配置生成，不在同一 Widget 内堆叠多层岗位判断。二级作业页不显示底部导航，返回时恢复原列表筛选、滚动位置和分页状态。
+
+### 4.3 公共组件
+
+优先扩展 `apps/heqi_design_system`，角色专用组合组件放入 `apps/service_app/lib/ui/core`：
+
+| 组件 | 职责 |
+| --- | --- |
+| `ServiceAppScaffold` | SafeArea、背景、标题栏、底部操作区和键盘避让 |
+| `AsyncContent` | 首次加载、刷新、分页、空数据、错误和重试 |
+| `RoleNavigationBar` | 三角色四栏导航配置 |
+| `StatusPill` | 状态文字、图标和语义色，不只依赖颜色 |
+| `TaskSummaryHeader` | 编号、类型、SLA、地址、用户和允许动作 |
+| `ChecklistSection` | 版本化检查项、必填、测量值、结果和问题说明 |
+| `EvidencePicker` | 图片、视频、签名、拍摄时间、定位和上传状态 |
+| `MoneyBreakdown` | 应收、线上、线下、押金、差额和核验状态 |
+| `TimelineView` | 任务、隐患、整改、复检、轨迹和审核事件 |
+| `SyncStatusBar` | 草稿、上传、失败、冲突和最后同步时间 |
+| `RiskActionPanel` | 风险等级、强制动作、阻断原因和人工升级 |
+
+不得重复造已有组件，不得在卡片中再嵌套装饰性卡片。首页以可扫描信息和快捷动作优先，一屏只保留一个主操作。
+
+### 4.4 页面状态与适配
+
+每个异步页面必须覆盖 `initial/loading/content/empty/error/refreshing/offline/conflict/submitting`。写操作还必须覆盖重复提交、服务端拒绝、结果未知和成功回执。
+
+- 以 390×844 逻辑像素进行主视觉比对，同时测试 320、360、390、430 宽度。
+- 文本缩放 1.3 倍后，任务编号、风险、金额、状态和按钮不得遮挡或截断关键含义。
+- 底部操作区需避开系统手势区和软键盘，长表单允许滚动至错误字段。
+- 地图、相机、扫码、蓝牙、定位和通知权限被拒绝时必须提供明确恢复入口。
+- 暗色主题如保留，主色也必须为蓝色，不得回退到紫色。
+
+## 5. Flutter 架构与目录规划
+
+```text
+apps/service_app/lib/
+├── app/
+│   ├── router.dart                         # 根路由、鉴权、准入和兼容跳转
+│   ├── role_navigation.dart                # 三角色一级导航配置
+│   └── dependencies.dart                   # Repository、平台适配器和会话依赖
+├── data/
+│   ├── dto/                                # 请求、响应和分页 DTO
+│   ├── repositories/
+│   │   ├── staff_repository.dart           # 资料、准入、消息、资金和内容
+│   │   ├── installation_repository.dart    # 安装维修、巡检、备件和保修
+│   │   ├── delivery_repository.dart        # 配送、气瓶、空瓶、轨迹和用户
+│   │   └── inspection_repository.dart      # 安检、隐患、整改和复检
+│   ├── offline/                            # 加密草稿、附件队列、冲突和清理
+│   └── services/                           # HTTP、定位、扫码、蓝牙、通知和文件
+├── domain/
+│   ├── shared/                             # 人员、资质、准入、钱包和消息
+│   ├── installation/                       # 安装维修状态机和 Use Case
+│   ├── delivery/                           # 配送状态机和 Use Case
+│   └── inspection/                         # 风险、隐患、整改和复检 Use Case
+└── ui/
+    ├── core/                               # 主题和公共状态组件
+    └── features/
+        ├── shared/                         # 登录、准入、消息、钱包、我的和支持
+        ├── installation/                   # 安装维修 40 页对应 Feature
+        ├── delivery/                       # 配送 42 页对应 Feature
+        └── inspection/                     # 安全检查 40 页对应 Feature
+```
+
+迁移时先保留 `ServiceRepository` 作为兼容门面，再把实现逐步转发至四个领域 Repository。旧页面完成替换和回归前不得删除。
+
+## 6. 页面与开发范围
+
+状态定义：`已有` 表示主要页面和接口已存在；`部分` 表示只有通用页面或部分 API；`待开发` 表示当前代码中未发现完整页面或接口。
+
+### 6.1 安装维修端 40 页
+
+| 编号与页面 | 建议路由 | 状态 | UI、逻辑与接口工作 |
+| --- | --- | --- | --- |
+| 01 登录页 | `/login` | 部分 | 对齐蓝白登录设计、密码/验证码、协议、忘记密码和字段级错误 |
+| 02 岗位申请 | `/role-application` | 待开发 | 组织、岗位、证照、审核进度及申请接口 |
+| 03 作业前检查 | `/preflight` | 部分 | 接入培训、区域、授权设备、工具和定位检查 |
+| 04 准入阻断 | `/preflight/blocked` | 部分 | 按阻断码提供打卡、补资质、培训、设备处理入口 |
+| 05 每日安全培训 | `/training/daily` | 待开发 | 题目版本、进度、作答、及格和留痕 |
+| 06 安装维修工作台 | `/installation/work` | 待开发 | 在岗、待办、整改、优先工单、草稿和消息摘要 |
+| 07 消息中心 | `/messages?role=installer` | 待开发 | 工单、安全、系统、结算分类及已读状态 |
+| 08 工单列表 | `/installation/tickets` | 部分 | 新装、维修筛选，分页、搜索、SLA、空态和刷新 |
+| 09 新装工单详情 | `/installation/tickets/:identity` | 部分 | 用户、脱敏地址、计划、要求、历史、动作和版本 |
+| 10 维修工单详情 | `/installation/tickets/:identity` | 部分 | 故障、历史维修、风险、材料及允许动作 |
+| 11 使用条件确认 | `/installation/tickets/:identity/steps/conditions` | 待开发 | 版本化场地、管线、通风、电源检查清单 |
+| 12 条件不合格与整改 | `/installation/tickets/:identity/steps/rectification` | 待开发 | 不合格项、证据、整改、改约和异常分支 |
+| 13 准备材料 | `/installation/tickets/:identity/steps/materials` | 待开发 | 材料需求、库存、扫码、领用、缺件和替代审批 |
+| 14 执行安装与取证 | `/installation/tickets/:identity/steps/install` | 部分 | 分步骤施工、前中后证据、草稿和同步 |
+| 15 安装测试 | `/installation/tickets/:identity/steps/test` | 待开发 | 气密、点火、压力、运行测试及测量单位 |
+| 16 测试失败处理 | `/installation/tickets/:identity/steps/test-failure` | 待开发 | 失败项、返工、暂停、上报和禁止完成 |
+| 17 前期安检 | `/installation/tickets/:identity/steps/safety` | 待开发 | 设备、环境和检漏清单，引用规则版本 |
+| 18 用户签名 | `/installation/tickets/:identity/steps/signature` | 部分 | 告知内容版本、手写签名、签名人和时间留痕 |
+| 19 收款确认 | `/installation/tickets/:identity/steps/payment` | 待开发 | 应收拆分、线上状态、线下凭证、差额审核 |
+| 20 安装完成 | `/installation/tickets/:identity/completion` | 部分 | 服务端完成回执、保修卡、回访和下一任务 |
+| 21 维修执行与取证 | `/installation/tickets/:identity/steps/repair` | 部分 | 故障处理步骤、零件、前中后取证和结论 |
+| 22 维修安全检查 | `/installation/tickets/:identity/steps/repair-safety` | 待开发 | 修复后检漏、试运行、结果和失败阻断 |
+| 23 异常上报与恢复 | `/installation/tickets/:identity/exception` | 部分 | 原因码、说明、证据、暂停、审核和恢复版本校验 |
+| 24 巡检及复检任务 | `/installation/inspections` | 部分 | 巡检、复检列表、计划、整改关联和专用步骤 |
+| 25 作业记录 | `/installation/records` | 部分 | 已完成、异常、取消筛选和分页 |
+| 26 记录详情 | `/installation/records/:identity` | 待开发 | 时间线、步骤、证据、签名、款项和文档 |
+| 27 统计看板 | `/installation/statistics` | 待开发 | 作业量、准时率、质量、返工、收入及口径说明 |
+| 28 钱包 | `/wallet` | 部分 | 钱包、收入分类、余额限制和流水入口 |
+| 29 提现申请与记录 | `/wallet/withdrawals` | 部分 | 金额、到账卡、手续费、支付密码和审核状态 |
+| 30 银行卡管理 | `/wallet/banks` | 部分 | 实名卡、绑定、默认卡、解绑二次确认和错误码 |
+| 31 离线草稿与同步记录 | `/sync` | 部分 | 草稿、附件、重试、冲突、失败原因和清理保护 |
+| 32 个人中心 | `/me` | 部分 | 资料、资质、钱包、统计、支持和设置入口 |
+| 33 个人资料与资质 | `/me/profile` | 部分 | 组织、区域、证照、能力、到期提醒和受控编辑 |
+| 34 推荐二维码 | `/me/referral` | 待开发 | 服务申请二维码、有效期、来源和使用记录 |
+| 35 设置与通知 | `/settings` | 待开发 | 通知、权限、离线保护、密码、协议和退出 |
+| 36 服务支持中心 | `/support` | 待开发 | 人工客服、组织电话、抢险电话、服务请求和 FAQ |
+| 37 维修知识库与视频教程 | `/knowledge?role=installer` | 待开发 | 规范、案例、视频、搜索、收藏和学习进度 |
+| 38 远程专家会诊 | `/expert-consultations` | 待开发 | 人工专家音视频、资料授权、会诊意见和审计 |
+| 39 备件领用 | `/installation/spares` | 待开发 | 申请、扫码、库存、领用、消耗、退回和审批 |
+| 40 电子保修卡与用户回访 | `/installation/warranties` | 待开发 | 保修范围、期限、状态、维修历史、回访和评价 |
+
+### 6.2 配送端 42 页
+
+| 编号与页面 | 建议路由 | 状态 | UI、逻辑与接口工作 |
+| --- | --- | --- | --- |
+| 01 登录页 | `/login` | 部分 | 复用共享登录，按设计统一品牌和错误状态 |
+| 02 岗位申请 | `/role-application` | 待开发 | 配送点、车辆、驾驶及从业资质、审核进度 |
+| 03 作业前检查 | `/preflight` | 部分 | 出勤、培训、车辆、设备、区域、定位和网络 |
+| 04 准入阻断 | `/preflight/blocked` | 部分 | 展示车辆、资质、培训、设备等阻断原因和处理入口 |
+| 05 每日安全培训 | `/training/daily` | 待开发 | 配送题库、版本、作答、及格和留痕 |
+| 06 配送工作台 | `/delivery/work` | 待开发 | 在岗、订单统计、今日路线、待办、异常和快捷入口 |
+| 07 消息中心 | `/messages?role=delivery` | 待开发 | 订单、路线、安全、系统、结算消息和对象跳转 |
+| 08 配送订单列表 | `/delivery/orders` | 部分 | 状态筛选、分页、SLA、距离、搜索和允许动作 |
+| 09 配送订单详情 | `/delivery/orders/:identity` | 部分 | 用户、脱敏联系、地址、商品、气瓶、付款和状态时间线 |
+| 10 接单与改派 | `/delivery/orders/:identity/assignment` | 待开发 | 接单、拒单原因、改派申请、审核和重新加载状态 |
+| 11 按时间排单 | `/delivery/schedule?mode=time` | 待开发 | 时间窗、顺序、冲突、锁定版本和批量确认 |
+| 12 按路线排单 | `/delivery/schedule?mode=route` | 待开发 | 地图站点、里程、路线建议、人工调序和版本冲突 |
+| 13 导航与到达 | `/delivery/orders/:identity/arrival` | 部分 | 外部导航、受控联系、定位质量、围栏和到达回执 |
+| 14 围栏异常处理 | `/delivery/orders/:identity/geofence-exception` | 部分 | 超距、定位异常、证据、人工审核和重试 |
+| 15 气瓶扫描录入 | `/delivery/orders/:identity/cylinders` | 待开发 | 扫码、规格、所属、库存、订单匹配和重复校验 |
+| 16 扫描异常拦截 | `/delivery/orders/:identity/cylinders/errors` | 待开发 | 错瓶、重复、失效、召回、无库存和处置建议 |
+| 17 随瓶安检 | `/delivery/orders/:identity/safety-check` | 待开发 | 环境、连接、设备、检漏和规则版本 |
+| 18 安检不合格与整改 | `/delivery/orders/:identity/safety-issue` | 待开发 | 风险分级、证据、整改、拒绝交付和异常上报 |
+| 19 配送取证 | `/delivery/orders/:identity/evidence` | 部分 | 配送前中后、瓶体、安装、安检照片视频和同步 |
+| 20 收款确认 | `/delivery/orders/:identity/payment` | 待开发 | 应收、押金、线上、线下、凭证和差额对账 |
+| 21 签收确认 | `/delivery/orders/:identity/receipt` | 部分 | 签收码或签名、交付清单、拒签和服务端验证 |
+| 22 配送完成 | `/delivery/orders/:identity/completion` | 部分 | 库存、押金、轨迹、签收和收款全部确认后完成 |
+| 23 空瓶回收任务 | `/delivery/returns` | 待开发 | 回收地址、计划、数量、押金和状态 |
+| 24 蓝牙设备连接 | `/delivery/devices/pairing` | 待开发 | 权限、扫描、配对、超时、固件兼容和故障 |
+| 25 空瓶扫描与确认 | `/delivery/returns/:identity/cylinders` | 待开发 | 空瓶码、状态、所属、押金核算和回收确认 |
+| 26 回收异常处理 | `/delivery/returns/:identity/exception` | 待开发 | 错瓶、损坏、争议、证据和人工审核 |
+| 27 配送轨迹与补传 | `/delivery/tracks` | 部分 | 轨迹段、缺口、离线缓存、批量补传和重复点去重 |
+| 28 服务用户列表 | `/delivery/customers` | 待开发 | 仅授权片区用户、搜索、标签和服务状态 |
+| 29 服务用户详情 | `/delivery/customers/:identity` | 待开发 | 脱敏资料、用气、安检、配送、评价和访问审计 |
+| 30 配送记录 | `/delivery/records` | 部分 | 历史订单、状态、时间、片区和分页 |
+| 31 配送记录详情 | `/delivery/records/:identity` | 待开发 | 时间线、瓶码、取证、收款、签收、空瓶和轨迹 |
+| 32 统计看板 | `/delivery/statistics` | 待开发 | 配送量、准时率、里程、异常、回收和收入 |
+| 33 钱包 | `/wallet` | 部分 | 配送收入、奖励、余额、限制和流水 |
+| 34 提现申请与记录 | `/wallet/withdrawals` | 部分 | 复用共享资金接口和审核状态 |
+| 35 银行卡管理 | `/wallet/banks` | 部分 | 复用共享实名卡、绑定和解绑流程 |
+| 36 离线队列与冲突 | `/sync` | 部分 | 轨迹、证据、签收、草稿、失败和版本冲突 |
+| 37 个人中心 | `/me` | 部分 | 车辆、资质、钱包、统计、知识库和支持入口 |
+| 38 个人资料车辆与资质 | `/me/profile` | 部分 | 人员、车辆、证照、到期提醒和审核状态 |
+| 39 设置与通知 | `/settings` | 待开发 | 派单、路线、轨迹、安全、权限、密码和退出 |
+| 40 推荐二维码 | `/me/referral` | 待开发 | 招募或服务推广场景、有效期和记录 |
+| 41 服务支持中心 | `/support` | 待开发 | 人工客服、配送点、抢险电话和服务请求 |
+| 42 配送知识库与视频教程 | `/knowledge?role=delivery` | 待开发 | 规范、气瓶、安检、设备、视频和学习进度 |
+
+### 6.3 安全检查端 40 页
+
+| 编号与页面 | 建议路由 | 状态 | UI、逻辑与接口工作 |
+| --- | --- | --- | --- |
+| 01 登录页 | `/login` | 部分 | 复用共享登录并统一蓝白视觉 |
+| 02 岗位申请 | `/role-application` | 待开发 | 安检中心、区域、组织、资质和审核状态 |
+| 03 作业前检查 | `/preflight` | 部分 | 出勤、资质、培训、安检设备、区域、定位和网络 |
+| 04 准入阻断 | `/preflight/blocked` | 部分 | 按原因提供资质、打卡、培训和设备处理入口 |
+| 05 每日安全培训 | `/training/daily` | 待开发 | 安检题库、版本、及格规则和结果留痕 |
+| 06 安检工作台 | `/inspection/work` | 待开发 | 在岗、待安检、复检、高风险、快捷入口和消息 |
+| 07 消息中心 | `/messages?role=operations` | 待开发 | 任务、风险、整改、复检、系统和结算消息 |
+| 08 安检任务列表 | `/inspection/tasks` | 部分 | 待到场、执行中、待复检、完成筛选和分页 |
+| 09 安检任务详情 | `/inspection/tasks/:identity` | 部分 | 用户、地址、范围、历史、要求、版本和动作 |
+| 10 到场与围栏校验 | `/inspection/tasks/:identity/arrival` | 待开发 | 导航、距离、定位精度、围栏、异常和到场回执 |
+| 11 用气设备清单 | `/inspection/tasks/:identity/steps/devices` | 待开发 | 表阀、管道、灶具、热水器、检漏和测量值 |
+| 12 用气环境清单 | `/inspection/tasks/:identity/steps/environment` | 待开发 | 通风、烟道、周边、报警器、规则和问题说明 |
+| 13 现场照片与视频 | `/inspection/tasks/:identity/evidence` | 部分 | 必拍项、问题证据、原始时间、定位和上传状态 |
+| 14 用户签名 | `/inspection/tasks/:identity/signature` | 部分 | 告知内容、手写签名、拒签处理和留痕 |
+| 15 合格结果确认 | `/inspection/tasks/:identity/qualified` | 部分 | 汇总、记录单、用户通知和服务端完成确认 |
+| 16 不合格与风险分级 | `/inspection/tasks/:identity/risk-assessment` | 待开发 | 一级、二级、三级固定枚举和规则版本 |
+| 17 一级高风险处置 | `/inspection/tasks/:identity/high-risk` | 待开发 | 关阀、通风、疏散、警戒、通知、抢险移交和强制阻断 |
+| 18 整改通知单 | `/inspection/tasks/:identity/notice` | 待开发 | 隐患、期限、要求、签名、送达状态和文档 |
+| 19 安检完成 | `/inspection/tasks/:identity/completion` | 部分 | 记录、隐患、通知单、复检任务和最终回执 |
+| 20 隐患列表 | `/inspection/hazards` | 待开发 | 风险、逾期、整改、复检、搜索和分页 |
+| 21 隐患详情 | `/inspection/hazards/:identity` | 待开发 | 证据、整改要求、进度、用户、任务和审计时间线 |
+| 22 整改任务 | `/inspection/rectifications/:identity` | 待开发 | 用户资料、整改材料初审、联系和复检安排 |
+| 23 复检执行 | `/inspection/reinspections/:identity` | 部分 | 前后对比、检查项、测量、证据、结论和关闭条件 |
+| 24 用户拒检记录 | `/inspection/tasks/:identity/refusal` | 待开发 | 原因、联系记录、现场证据、见证人和后续安排 |
+| 25 区域抽查地图 | `/inspection/map` | 待开发 | 模糊点位、路线、风险、抽查任务和精确地址授权 |
+| 26 安检记录 | `/inspection/records` | 部分 | 合格、隐患、拒检、复检和历史筛选 |
+| 27 安检记录详情 | `/inspection/records/:identity` | 待开发 | 时间线、结果、证据、文档、隐患和复检进度 |
+| 28 统计看板 | `/inspection/statistics` | 待开发 | 安检量、合格率、风险、整改、复检和质量 |
+| 29 钱包 | `/wallet` | 部分 | 安检、复检、奖励、余额和流水 |
+| 30 提现申请与记录 | `/wallet/withdrawals` | 部分 | 复用共享提现接口及审核状态 |
+| 31 银行卡管理 | `/wallet/banks` | 部分 | 复用共享银行卡接口及安全校验 |
+| 32 离线草稿与冲突 | `/sync` | 部分 | 检查项、证据、附件、版本、冲突和重试 |
+| 33 个人中心 | `/me` | 部分 | 资料、钱包、工具、知识库、支持和设置入口 |
+| 34 个人资料与资质 | `/me/profile` | 部分 | 组织、区域、证照、能力、有效期和审核状态 |
+| 35 推荐二维码 | `/me/referral` | 待开发 | 官方安检预约二维码、有效期和使用记录 |
+| 36 设置与通知 | `/settings` | 待开发 | 任务、隐患、复检、高风险、权限、密码和退出 |
+| 37 服务支持中心 | `/support` | 待开发 | 人工客服、安检中心、抢险电话和服务请求 |
+| 38 安检知识库与视频教程 | `/knowledge?role=operations` | 待开发 | 规范、案例、法规、视频、搜索和学习进度 |
+| 39 远程专家会诊 | `/expert-consultations` | 待开发 | 人工专家音视频、资料授权、意见和审计 |
+| 40 问题反馈与投诉 | `/feedback` | 待开发 | 功能、数据、结算、投诉、附件、进度和结果 |
+
+## 7. Staff Client API 完善方案
+
+### 7.1 通用约定
+
+- 基础路径保持 `/heqi/client/v1/staff`。
+- 对象统一使用公开 `identity`，客户端不得接收或提交数据库自增主键。
+- 列表统一支持 `page`、`page_size`、`status_code`、`keyword`；兼容期保留已有裸数组结构，可通过新增 `view=page` 返回分页对象。
+- 时间使用 RFC 3339，金额使用整数分，距离使用米，压力和浓度必须同时返回单位。
+- 写接口通过 `Idempotency-Key` 或 `request_no` 幂等；响应返回 `resource_version`、`status_code` 和 `allowed_actions`。
+- 已有数字状态字段继续返回，同时非破坏性新增字符串 `status_code` 和 `status_name`；新 UI 不再硬编码数字状态。
+- 错误响应必须提供稳定 `error_code`、中文安全文案、`retryable`、字段错误和必要的当前资源快照。
+- 所有接口先校验当前账号角色、组织、任务归属和数据范围，再读取或变更数据。
+
+### 7.2 共享接口
+
+下表中“保留”表示当前已存在，“扩展”表示保持路径并补字段，“新增”表示本次需要实现。
+
+| 方法与路径 | 类型 | 用途 |
+| --- | --- | --- |
+| `POST /auth/login`、`GET /auth/profile` | 扩展 | 补头像受控地址、组织、资质摘要、功能开关和通知摘要 |
+| `POST /role-applications` | 新增 | 提交岗位、组织、车辆或资质申请 |
+| `GET /role-applications/current` | 新增 | 当前申请、审核节点、驳回原因和可修改字段 |
+| `GET /preflight` | 扩展 | 补培训、服务区域、授权设备及岗位专用检查 |
+| `GET /training/daily` | 新增 | 今日课程、题目版本、及格规则和历史进度 |
+| `POST /training/daily/:identity/submit` | 新增 | 幂等提交答案并返回结果和准入变化 |
+| `GET /messages` | 新增 | 分类、已读、业务对象和分页 |
+| `POST /messages/:identity/read` | 新增 | 单条已读 |
+| `POST /messages/read-all` | 新增 | 按分类批量已读 |
+| `GET /credentials` | 新增 | 当前资质、状态、到期时间和审核信息 |
+| `PUT /auth/profile` | 新增 | 仅更新服务端允许编辑的个人字段 |
+| `GET /statistics` | 新增 | 按岗位、日期和服务组织返回带口径的指标 |
+| `GET /contents` | 新增 | 知识库、视频、规范、案例和 FAQ |
+| `POST /contents/:identity/progress` | 新增 | 学习进度、完成和阅读确认 |
+| `GET /support/contacts` | 新增 | 客服、所属组织和抢险电话配置 |
+| `GET /support/requests`、`POST /support/requests` | 新增 | 人工服务请求和进度 |
+| `GET /expert-consultations`、`POST /expert-consultations` | 新增 | 人工专家会诊申请、授权资料和状态 |
+| `GET /referrals/current` | 新增 | 当前岗位可用二维码及有效期 |
+| `GET /feedback`、`POST /feedback` | 新增 | 反馈、投诉、附件和处理进度 |
+| `/wallet`、`/wallet/records` | 保留 | 钱包和流水，补岗位收入来源字段 |
+| `/wallet/banks`、`/wallet/withdrawals` | 保留 | 银行卡和提现，客户端补齐页面即可 |
+
+### 7.3 安装维修接口
+
+| 方法与路径 | 类型 | 用途 |
+| --- | --- | --- |
+| `GET /tickets`、`GET /tickets/:identity` | 扩展 | 分页、字符串状态、工作流、SLA、历史和 `allowed_actions` |
+| `POST /tickets/:identity/start`、`exception`、`recover` | 扩展 | 补幂等键、版本、定位、原因码和动作回执 |
+| `GET /tickets/:identity/workflow` | 新增 | 返回任务类型、步骤、完成度、规则版本和当前步骤 |
+| `GET /tickets/:identity/checklists/:step_code` | 新增 | 版本化条件、安装测试或安全检查清单 |
+| `PUT /tickets/:identity/checklists/:step_code` | 新增 | 保存结果、测量值、问题、证据引用和草稿版本 |
+| `GET /tickets/:identity/materials` | 新增 | 需求、库存、已领、已用和待归还材料 |
+| `POST /tickets/:identity/material-issues` | 新增 | 申请或扫码领用备件，返回库存事务结果 |
+| `POST /tickets/:identity/evidences` | 新增 | 分步绑定已上传证据，校验数量、类型、时间和哈希 |
+| `POST /tickets/:identity/signatures` | 新增 | 告知版本、签名、签名人、时间和拒签原因 |
+| `POST /tickets/:identity/payment-confirmations` | 新增 | 线上查询、线下凭证、金额差额和审核状态 |
+| `POST /tickets/:identity/submit-result` | 扩展 | 保留现有聚合提交，增加步骤完整性与版本校验 |
+| `GET /installation/inspections` | 新增 | 巡检和复检任务专用列表 |
+| `GET /installation/spares`、`POST /installation/spares/issues` | 新增 | 备件可用库存、领用、消耗和归还 |
+| `GET /installation/warranties` | 新增 | 电子保修卡及关联维修、回访记录 |
+| `POST /installation/warranties/:identity/follow-ups` | 新增 | 回访结果、问题和后续任务 |
+
+### 7.4 配送接口
+
+| 方法与路径 | 类型 | 用途 |
+| --- | --- | --- |
+| `GET /delivery/orders`、`GET /delivery/orders/:identity` | 扩展 | 分页、商品、气瓶、押金、收款、计划、状态和动作 |
+| `POST /delivery/orders/:identity/start` | 扩展 | 幂等、版本、车辆和路线批次 |
+| `POST /delivery/orders/:identity/accept` | 新增 | 接单并返回调度版本 |
+| `POST /delivery/orders/:identity/reassignment-requests` | 新增 | 拒单或改派原因、证据和审核状态 |
+| `GET /delivery/schedule`、`PUT /delivery/schedule` | 新增 | 时间或路线排单、乐观锁和冲突明细 |
+| `GET /delivery/routes/current` | 新增 | 今日路线、站点、里程、缺口和最后轨迹时间 |
+| `POST /delivery/orders/:identity/tracks` | 扩展 | 保留批量轨迹，补轨迹段、设备、幂等和去重结果 |
+| `POST /delivery/orders/:identity/arrive` | 扩展 | 返回距离、阈值、定位质量和审核要求 |
+| `POST /delivery/orders/:identity/geofence-exceptions` | 新增 | 超距或定位异常证据和人工审核 |
+| `POST /delivery/cylinders/validate-scan` | 新增 | 校验瓶码、规格、所属、库存、召回和重复状态 |
+| `PUT /delivery/orders/:identity/cylinders` | 新增 | 绑定实瓶和数量，使用资源版本防并发覆盖 |
+| `PUT /delivery/orders/:identity/safety-check` | 新增 | 随瓶安检检查项、风险和处置 |
+| `POST /delivery/orders/:identity/evidences` | 新增 | 分阶段配送证据绑定 |
+| `POST /delivery/orders/:identity/payment-confirmations` | 新增 | 商品、押金、线上、线下和差额对账 |
+| `POST /delivery/orders/:identity/submit-receipt` | 扩展 | 保留现有签收，补签收码、交付清单、拒签和前置校验 |
+| `GET /delivery/returns`、`GET /delivery/returns/:identity` | 新增 | 空瓶回收任务与详情 |
+| `POST /delivery/returns/:identity/confirm` | 新增 | 空瓶扫描、状态、押金和库存回收事务 |
+| `POST /delivery/returns/:identity/exception` | 新增 | 错瓶、损坏和押金争议 |
+| `GET /delivery/customers`、`GET /delivery/customers/:identity` | 新增 | 当前授权片区用户及脱敏详情 |
+
+### 7.5 安全检查接口
+
+| 方法与路径 | 类型 | 用途 |
+| --- | --- | --- |
+| `GET /tickets`、`GET /tickets/:identity` | 扩展 | 安检、复检专用字段、工作流、字符串状态和动作 |
+| `POST /tickets/:identity/arrive` | 新增 | 定位质量、围栏距离和到场回执 |
+| `GET /tickets/:identity/checklists/devices` | 新增 | 版本化用气设备检查项 |
+| `GET /tickets/:identity/checklists/environment` | 新增 | 版本化用气环境检查项 |
+| `PUT /tickets/:identity/checklists/:step_code` | 新增 | 结果、测量值、说明、证据和版本 |
+| `POST /tickets/:identity/evidences` | 新增 | 现场照片、视频、签名和问题证据 |
+| `POST /tickets/:identity/risk-assessments` | 新增 | 固定风险等级、规则版本和建议动作 |
+| `POST /tickets/:identity/high-risk-actions` | 新增 | 逐项记录关阀、通风、疏散、警戒、通知和移交 |
+| `POST /tickets/:identity/refusals` | 新增 | 拒检原因、联系、证据、见证和后续安排，结论保持为空 |
+| `POST /tickets/:identity/complete` | 新增 | 原子完成任务并创建隐患、整改单和复检计划 |
+| `GET /inspection/hazards`、`GET /inspection/hazards/:identity` | 新增 | 隐患列表、详情、证据、状态和时间线 |
+| `POST /inspection/hazards/:identity/rectification-reviews` | 新增 | 整改材料初审，只改变初审状态 |
+| `POST /inspection/hazards/:identity/reinspection-schedules` | 新增 | 创建或改期复检任务 |
+| `POST /inspection/reinspections/:identity/submit` | 新增 | 前后对比、检查项、证据和复检结论 |
+| `GET /inspection/map` | 新增 | 按权限返回模糊点位和任务摘要 |
+
+## 8. 核心接口契约示例
+
+### 8.1 作业前检查
+
+```json
+{
+  "role_code": "operations",
+  "work_status": "on_duty",
+  "can_work": false,
+  "checks": {
+    "account": {"status": "passed"},
+    "role": {"status": "passed", "role_code": "operations"},
+    "organization": {"status": "passed", "identity": "...", "name": "武侯安检中心"},
+    "credential": {"status": "passed", "expired_at": "2027-12-31T23:59:59+08:00"},
+    "attendance": {"status": "passed", "work_status": "on_duty"},
+    "daily_training": {"status": "blocked", "reason_code": "training_required", "action": "open_daily_training"},
+    "service_area": {"status": "passed"},
+    "authorized_device": {"status": "passed"}
+  }
+}
+```
+
+兼容期内 `not_configured` 不作为新阻断条件；只有服务端启用规则并返回 `blocked` 时客户端才阻止进入工作台。
+
+### 8.2 任务详情与允许动作
+
+```json
+{
+  "identity": "01K...",
+  "number": "AJ202609060021",
+  "role_code": "operations",
+  "business_type": "inspection",
+  "status": 18,
+  "status_code": "assigned",
+  "status_name": "已分派",
+  "resource_version": 7,
+  "current_step": "arrival",
+  "allowed_actions": ["arrive", "report_exception"],
+  "workflow": {
+    "template_identity": "01K...",
+    "template_version": 3,
+    "completed_steps": []
+  }
+}
+```
+
+### 8.3 幂等动作响应
+
+```json
+{
+  "identity": "01K...",
+  "status_code": "in_progress",
+  "resource_version": 8,
+  "allowed_actions": ["save_checklist", "upload_evidence", "report_exception"],
+  "idempotency_replayed": false,
+  "server_time": "2026-09-06T17:49:13+08:00"
+}
+```
+
+### 8.4 统一业务错误
+
+```json
+{
+  "error_code": "RESOURCE_VERSION_CONFLICT",
+  "message": "任务已被更新，请刷新后继续",
+  "retryable": false,
+  "field_errors": {},
+  "current_resource_version": 9,
+  "allowed_actions": ["refresh"]
+}
+```
+
+客户端只根据 `error_code` 驱动流程，中文 `message` 用于展示，不解析服务端英文或中文文案判断业务状态。
+
+## 9. 领域状态机与强制规则
+
+### 9.1 安装维修
+
+```text
+已分派 -> 执行中 -> 待用户确认 -> 已完成
+             |            |
+             +-> 异常暂停 <-+
+异常暂停 -> 执行中
+```
+
+- 安装、维修必须具备施工前、施工中、施工后证据和用户签名。
+- 条件不合格、测试失败或高风险结果不得直接进入待确认或已完成。
+- 备件领用、消耗和退回必须形成库存事务，客户端不能直接修改库存余额。
+- 电子保修卡只能由已完成安装或满足规则的维修事实生成。
+
+### 9.2 配送
+
+```text
+待接单 -> 已接单 -> 已排单 -> 配送中 -> 已到达
+                                      -> 气瓶已核验 -> 安检完成
+                                      -> 待收款 -> 待签收 -> 已完成
+任一执行态 -> 异常暂停 -> 原执行态
+```
+
+- 现有数字状态 `20 -> 33 -> 34 -> 23` 保持兼容；新增细分状态通过字符串码和扩展事件表达，避免破坏旧系统。
+- 气瓶必须先校验再绑定订单，错瓶、召回瓶、重复瓶或非可用库存一律阻断。
+- 轨迹缺失允许补传，但不得伪造时间；围栏异常必须记录定位精度和人工审核结论。
+- 收款、押金、空瓶和签收全部确认后才允许完成配送。
+
+### 9.3 安全检查
+
+```text
+已分派 -> 已到场 -> 检查中 -> 待评定
+                         -> 合格 -> 已完成
+                         -> 不合格 -> 隐患待整改 -> 待复检 -> 已关闭
+                         -> 一级高风险 -> 现场管控 -> 抢险移交 -> 隐患待整改
+                         -> 用户拒检 -> 拒检归档/改约
+```
+
+- 风险枚举固定为 `level_1_high`、`level_2_medium`、`level_3_low`，不得使用自由文本替代等级。
+- 一级高风险必须逐项完成现场管控和抢险移交，普通完成接口不能绕过。
+- 拒检只记录事实，不写合格或不合格结论。
+- 整改单、隐患和复检任务必须在同一服务端事务中关联，复检通过后才能关闭隐患。
+
+## 10. 数据模型与数据库规划
+
+优先复用现有 `staff_account`、`staff_credential`、`staff_attendance`、`cs_ticket`、`cs_ticket_evidence`、`gasorder_basic`、轨迹、钱包和银行卡模型。仅在现有语义无法表达时新增表。
+
+| 建议模型 | 职责 |
+| --- | --- |
+| `staff_role_application` | 岗位、组织、车辆、资质申请及审核历史 |
+| `staff_daily_training`、`staff_training_attempt` | 课程版本、答题、结果和准入记录 |
+| `staff_message`、`staff_message_read` | 岗位消息、业务对象和已读状态 |
+| `staff_workflow_instance`、`staff_step_record` | 任务模板版本、步骤状态、表单和资源版本 |
+| `staff_payment_confirmation` | 应收、线上、线下、押金、差额和审核 |
+| `delivery_order_cylinder` | 配送订单实瓶、扫码校验和库存事务关联 |
+| `delivery_return_task`、`delivery_return_cylinder` | 空瓶回收、瓶况、押金和异常 |
+| `inspection_hazard` | 风险等级、隐患、期限、状态和关联任务 |
+| `inspection_rectification_notice` | 整改要求、送达、签名和文档 |
+| `inspection_reinspection` | 复检计划、结果、证据和隐患关闭 |
+| `staff_support_request`、`expert_consultation` | 人工支持、会诊授权、意见和审计 |
+| `installation_spare_transaction` | 备件申请、领用、消耗、退回和审批 |
+| `installation_warranty_follow_up` | 保修卡关联回访、问题和后续任务 |
+
+迁移必须包含表级 `COMMENT` 和逐字段中文 `COMMENT`。枚举注释列出全部取值，JSON 字段说明结构、版本和示例；唯一键覆盖 `request_no` 或幂等键，资源表增加版本字段用于乐观锁。
+
+## 11. 离线、附件与冲突
+
+- 草稿、检查项、签名和附件元数据继续使用系统安全存储管理的密钥加密。
+- 每个草稿记录 `account_identity`、`role_code`、业务对象、步骤、模板版本、资源版本和更新时间。
+- 图片、视频和签名记录 SHA-256、MIME、大小、原始采集时间、定位、上传状态和服务端文件标识。
+- 队列按同一资源的动作顺序执行；相同 `request_no` 只允许成功一次。
+- 网络恢复后先拉取服务端版本，再执行待同步动作；版本冲突必须展示差异，不静默覆盖。
+- 登录退出、切换账号、清理缓存和卸载提示前检查未同步数据；不得将甲账号草稿展示给乙账号。
+- 最终完成、高风险处置确认、签收、库存、资金和提现不能离线伪成功，只显示“待同步”或“待确认”。
+
+## 12. 安全、权限与隐私
+
+- 精确地址、手机号、身份证、银行卡、签名、证照和现场证据按角色与任务归属最小化返回。
+- 列表默认脱敏；进入授权任务详情后按业务需要展示，访问写入审计日志。
+- 地图默认返回模糊点位，精确坐标仅对当前授权任务和规定时间窗开放。
+- 日志、埋点、崩溃报告和错误信息不得记录令牌、明文密码、完整手机号、完整地址、签名或附件内容。
+- 上传校验扩展名、真实 MIME、大小、病毒扫描、业务归属和短期访问授权。
+- 金额、库存、风险和状态转换均由服务端事务校验，客户端参数不能直接增加余额、减少库存或关闭隐患。
+- 深链和推送只携带业务类型、公开 `identity` 和短期签名；页面打开后重新鉴权并读取当前状态。
+
+## 13. 分阶段实施计划
+
+| 阶段 | 开发范围 | 完成标准 |
+| --- | --- | --- |
+| P0 视觉与契约基线 | 服务端主题改蓝、8dp 角色组件、状态码、错误模型、API 契约测试 | 无紫色；旧接口和用户端主题无回归 |
+| P1 共享骨架 | 角色导航、登录、岗位申请、准入、培训、消息、资料、设置 | 三角色登录后进入正确工作台并通过准入守卫 |
+| P2 安装维修主链路 | 01 至 24 核心工单、取证、签名、收款和异常 | 新装、维修、巡检、复检各至少一条端到端链路通过 |
+| P3 配送主链路 | 01 至 27 订单、排单、轨迹、气瓶、安检、签收和空瓶 | 正常配送、围栏异常、错瓶、拒签和回收链路通过 |
+| P4 安检主链路 | 01 至 25 检查、风险、整改单、隐患、整改、复检和拒检 | 合格、不合格、一级高风险、拒检和复检链路通过 |
+| P5 扩展能力 | 记录、统计、钱包、资质、二维码、知识库、支持、会诊、备件和保修 | 122 张设计图均有真实路由与数据状态 |
+| P6 离线与质量 | 附件队列、冲突、幂等、安全、性能、视觉与兼容回归 | 弱网、断网、重复提交、冲突和权限测试通过 |
+
+每个阶段采用接口契约先行：后端提供可运行接口及契约测试，Flutter 再接入真实数据。设计图中的静态数据不得长期保留在生产页面。
+
+## 14. 测试与验收
+
+### 14.1 自动化测试
+
+- Go 单元测试：角色与组织权限、状态转换、风险分级、围栏距离、气瓶校验、金额、库存、幂等和事务回滚。
+- 路由测试：现有 Staff 路由继续存在，新路由方法和鉴权中间件完整。
+- Flutter 单元测试：DTO 解析、字符串状态、允许动作、金额格式、离线队列和冲突策略。
+- Widget 测试：加载、空态、错误、长文本、表单校验、按钮禁用、权限拒绝和键盘避让。
+- 集成测试：三角色正常链路及关键异常链路，真实登录和模拟业务数据均可重复执行。
+- 视觉回归：以三个最新设计目录为基准，在固定数据和固定尺寸下逐页截图比对。
+
+### 14.2 必测业务场景
+
+| 岗位 | 正常场景 | 异常场景 |
+| --- | --- | --- |
+| 安装维修 | 新装、维修、巡检、复检、签名、收款、完成 | 条件不合格、测试失败、缺件、异常恢复、重复提交 |
+| 配送 | 接单、排单、到达、扫码、安检、收款、签收、空瓶回收 | 围栏异常、错瓶、召回瓶、用户不在、拒签、轨迹缺口、押金争议 |
+| 安全检查 | 合格安检、隐患、整改、复检、关闭 | 一级高风险、用户拒检、逾期整改、复检不通过、离线冲突 |
+
+### 14.3 逐页验收
+
+每张设计图必须映射到以下六项，缺一项不得标记完成：
+
+1. 可访问路由和正确返回路径。
+2. 真实或契约模拟的接口数据，不使用写死成功结果。
+3. 正常、加载、空、错误、离线和无权限状态。
+4. 服务端状态与 `allowed_actions` 驱动的操作按钮。
+5. 对应 Widget、仓储或集成测试。
+6. 与目标图同尺寸的截图及差异评审记录。
+
+## 15. 预计变更范围
+
+| 目录或文件 | 主要变更 |
+| --- | --- |
+| `apps/heqi_design_system/lib/src/tokens.dart` | 服务端主色改蓝；保留公开 Token 名称 |
+| `apps/heqi_design_system/lib/src/theme.dart` | 服务端明暗主题去紫色，补角色紧凑样式 |
+| `apps/service_app/lib/app/router.dart` | 角色路由、守卫、四栏导航和旧路由兼容 |
+| `apps/service_app/lib/app/dependencies.dart` | 注册拆分后的 Repository 和平台能力适配器 |
+| `apps/service_app/lib/data` | DTO、领域 Repository、附件和离线同步 |
+| `apps/service_app/lib/domain` | 三岗位模型、状态机和 Use Case |
+| `apps/service_app/lib/ui/features` | 122 张设计图对应共享与岗位页面 |
+| `backend/api/internal/routers/client.go` | 非破坏性注册新增 Staff Client API |
+| `backend/api/internal/logic/client/staff` | 共享、安装、配送、安检领域逻辑拆分 |
+| `backend/api/internal/models` | 复用现有模型并新增确有必要的领域表 |
+| `docs/13-移动端Design-System.md` | 同步服务端蓝色和角色组件规范 |
+
+单个代码文件尽量不超过 1500 行。后端应按 `shared.go`、`installation.go`、`delivery.go`、`inspection.go`、`support.go` 等职责拆分；Flutter 页面、ViewModel 和状态对象分文件组织。
+
+## 16. 完成定义
+
+- 三个目标目录的 122 张设计图全部有路由、真实状态、接口和测试映射。
+- 页面无紫色、紫色渐变、AI 元素或与正式作业无关的装饰。
+- 三岗位导航、页面标题、字段、检查项和异常分支不会串岗。
+- 现有真实登录、打卡、工单、配送、钱包、证据和草稿能力无回归。
+- 所有写动作幂等，冲突可见；最终状态由服务端确认。
+- 一级高风险、错瓶、资金差额、拒签和测试失败均不能绕过阻断。
+- 常用 Android 尺寸、文本缩放、弱网、断网和权限拒绝测试通过。
+- API、数据库、代码注释、操作日志和项目文档同步更新。
+
+## 17. 风险与待评审项
+
+- 岗位申请是工作人员自助申请还是后台创建后补资料，需要产品与组织权限负责人确认；未确认前不得开放越权注册。
+- 设计中的收入、奖励、提现和推荐二维码需要后台配置来源、结算规则和开关，不应由客户端写死。
+- 路线优化、蓝牙设备协议、视频会诊和地图服务涉及外部能力，开发前需确认供应商、权限和失败降级方案。
+- 安装端“巡检”与安全检查端“安检”的责任边界需由业务负责人确认，数据表可关联但状态机不能混用。
+- 图片中的日期和业务编号为设计示例，测试数据应使用相对日期或固定测试时钟，避免上线后展示过期内容。
+
+## 18. 变更记录
+
+| 版本 | 日期 | 内容 |
+| --- | --- | --- |
+| v1.0 | 2026-09-06 | 根据安装维修 40 页、配送 42 页和安全检查 40 页产品设计建立全量开发文档，明确现状、页面路由、UI、接口、状态机、离线、安全、测试和分阶段交付要求 |

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

@@ -0,0 +1,650 @@
+# 用户端 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、数据模型、测试和分阶段交付计划 |