platforms/docs/04-服务端App需求.md

# 服务端 App 需求

## 1. 定位与角色模型

服务端 App 是安装维修员、安检员和配送员共用的 Flutter 移动应用。“服务端”在本文指服务人员端，并非后端服务。首期采用“一账号一角色”：用户登录后由平台返回唯一岗位、资质及所属气站/配送点，客户端不得自行切换或拼装角色上下文。

设计稿要求不同角色使用同一登录与账户体系，但加载不同的底部导航和工作台：配送员使用“订单、任务、用户、我的”，安装维修员使用“工单、巡检、记录、我的”，安检员使用“任务、记录、隐患、我的”。导航、数据和接口均按当前角色、组织、服务区域与资质过滤。

| 共同能力 | 说明 |
| --- | --- |
| 认证与上下班 | 验证码/密码登录、设备风控、角色切换、上班状态、服务区域、消息 |
| 待办中心 | 按风险、预约时间、SLA、距离展示待办；支持接单、拒绝、改派和异常上报 |
| 任务详情 | 订单/工单信息、用户地址、商品/设备摘要、预约、风险提示、导航、受控联系 |
| 现场取证 | 相机、相册、定位、签名、签收码、检查表、离线草稿；上传需记录采集时间与任务 ID |
| 收益与账户 | 当前余额、待结算、钱包流水、提现申请、审核结果、协议、个人资料与投诉建议 |

### 账户、资质、上班与培训

- 登录支持用户名密码、记住登录状态、忘记密码、用户协议和隐私政策确认。注册页可申请配送员、安装维修员或安检员角色，但注册成功仅创建待审核账号；平台审核通过并校验资质后才可接单。
- 服务人员资料包括姓名、手机号、工号、工作单位、身份证明、角色对应从业证号、证书到期日和证件照片。配送员额外维护配送车辆车牌、颜色、车型及车辆照片；安装维修/安检人员维护专业资质、培训和工具能力。证件图片默认最多 6 张，数量和类型可配置。
- 上班/下班记录当前时间、状态、角色、地点和设备信息。未上班、超出服务区、资质失效或未完成每日培训时不得接新单；已接任务须完成、改派或按规则申请下班。
- 每日安全知识培训在首次进入工作台时弹出，按角色题库下发单选/多选题，记录题目版本、答案、结果、完成时间和次数。未完成培训时可浏览任务但默认不能开始执行；是否允许补训由平台配置。

## 2. 配送工作台

- 展示待配送、配送中、已送达、异常订单及预计收入；仅接收所属配送点和服务区域内的任务。
- 接单后可导航、报到、联系用户、提交签收码/签名/照片等交接证明；重复提交必须幂等。
- 配送中按任务状态和平台策略上报配送轨迹：至少记录接单、出发、到达配送区域、到达地址、签收/失败等事件；运行中位置上报包含定位时间、经纬度、精度、速度/方向（如可用）和来源。
- App 在后台运行、弱网或定位权限变化时应明确提示。弱网时本地加密缓存轨迹点并按时间顺序补传；禁止篡改采集时间。用户或运营端看到的“实时位置”必须标注最后更新时间。
- 地址无法到达、用户不在、货损、超服务区进入异常工单，不得直接标记配送完成。
- 配送完成后把交接信息回传订单系统；如订单还需安装，只将配送任务置完成，不提前完成主订单。

### 2.1 配送任务页面与排序

- 订单页显示待配送新订单与待回收空瓶任务，包含订单/任务号、用户姓名与脱敏联系电话、地址/地图入口、气瓶规格与数量、气瓶押金、订单金额、预约时间、超时/紧急标识和接单按钮。
- 任务页支持“按时间排单”和“按路线排单”。路线排序使用配送员当前位置、服务区域、预约窗口与路线规划结果；平台人工调度优先级高于 App 本地排序。
- 用户页允许配送员在本点授权范围内按姓名、电话或地址检索服务用户，查看月度/年度用瓶数量与金额、气瓶/押金摘要、配送历史、随瓶安检结果、用户评价和报表导出入口；无关用户信息不得查询或导出。

### 2.2 配送与空瓶回收闭环

```text
查看订单 -> 开始配送 -> 导航并确认到达 -> 扫描/录入气瓶 -> 随瓶安检取证 -> 确认收款 -> 完成配送
空瓶回收：查看回收任务 -> 蓝牙连接（如需） -> 扫描/录入空瓶 -> 确认回收 -> 更新押金和库存状态
```

- 到达环节展示地图导航和“确认送达”；服务端校验地理围栏、时间窗口与任务状态。围栏异常可提交原因和证据，不能直接跳过。
- 气瓶扫描支持蓝牙连接智能瓶阀设备、扫码和手动录入。每个气瓶记录设备/钢瓶编码、规格、扫描时间、操作人和任务；重复扫描、规格不符、已在其他任务中或状态异常时必须拦截。
- 随瓶安检必须采集 1-6 张照片（默认要求 6 张，后台可配置）并自动写入定位与时间水印；照片类型包括配送前、配送中、配送后、气瓶特写、安装现场、安检现场和其他。视频支持 0-3 段可选采集，同样写入定位与时间水印。
- 随瓶安检记录气瓶、管道、阀门和使用环境结论，均为必填合格/不合格项；不合格时必须创建关联安全事件/整改任务，禁止直接完成配送。
- 收款确认展示订单原始金额、气瓶押金、应收合计、用户已支付金额和本次确认金额。配送员只能确认已核验的支付结果或平台授权的线下收款，不能修改订单金额；所有差异进入异常对账。
- 空瓶回收完成后更新气瓶状态、押金状态、回收时间和库存去向。逾期回收、瓶码不符、损坏或未归还须记录异常原因并转平台/气站处理。

## 3. 安装维修工作台

- 处理安装、维修、复检任务，展示设备编码、商品/部件、预约、安装价格、历史安全事件和必备工具提示。
- 现场按后台下发的版本化检查表记录安装位置、可燃气体管道连接、密封、泄漏/压力、通信、电池、固定、防护及用户告知。
- 合格时记录设备激活/回执、耗材、工时、用户确认；不合格时必须填写等级、问题、整改建议和证据，创建或关联安全事件。
- 高风险不合格时突出显示停止作业、关阀和紧急联系指引；服务人员无权绕过关阀限制或伪造完成。

### 3.1 维修工单闭环

- 维修任务流程为“详情 -> 执行 -> 安检 -> 完成 -> 收款”。任务详情显示工单号、类型（如阀门维修、管道维修）、地址、维修等级、时限、剩余时间、优先级和状态；紧急工单突出显示并参与超时升级。
- 执行维修时必须选择照片类型并上传维修前/维修中/维修后证据；安全检查至少覆盖设备运行、安全功能、管道密封、压力表/压力、泄漏和报警器。检查表由后台按设备型号和任务类型版本化下发。
- 维修完成后要求用户电子签字确认。涉及收费的维修单应展示材料、数量、单价、服务费、押金、应收和实收；收款确认后才可进入完成状态，支付差异转异常处理。

### 3.2 新装智能瓶阀/设备闭环

```text
详情 -> 确认使用条件 -> 准备材料 -> 执行安装 -> 测试安装 -> 前期安检 -> 完成 -> 收款
```

- 使用条件确认至少包括通风良好、远离火源和热源、安装位置便于操作维护、用户已了解安全知识、用户同意遵守使用规定。任一不符合时不能进入安装，必须记录不符合项、照片证据、整改期限和用户签字。
- 备料页选择报警器、可燃气体管道、阀门、密封垫圈、连接接头等材料及数量，实时计算材料费、押金和合计。材料主数据、价格和可选范围由平台/气站下发，服务人员不能手改单价。
- 安装步骤至少包括关闭原阀、拆除旧设备（如有）、安装新设备/报警器、连接管道、安装阀门和接头、检查所有连接点；每个任务可按设备型号配置强制步骤和取证要求。
- 测试安装至少包括开启阀门、检查报警器运行、使用测漏液检查连接点、检查阀门开关灵活性、测试气流量/通信回执、确认无泄漏。任一不通过不得激活设备或完成安装。
- 前期安检结论为合规或不合规，并要求用户签字；完成后创建材料消耗、安装记录、设备激活结果和收入待结算记录。

## 4. 安检工作台

- 接收平台或可燃气体站分配的安检申请、复检和区域抽查，按待检查、待整改、已整改、超时筛选。
- 在现场填写检查项、合格/不合格结论、1/2/3 级建议、描述、照片/视频、用户签收和定位。
- 检查不合格后通知用户和平台，生成整改时限与复检任务；用户拒检需记录原因和证据，不得伪造检查结果。
- 地图仅展示完成任务所需的模糊点位和区域，禁止导出无关用户位置。

### 4.1 安检任务与隐患整改

- 安检任务按距离/计划时间排序，展示常规安检、专项安检、地址、最近安检时间、计划时间、状态和开始检查入口；开始前校验安检区域地理围栏。
- 工单流程为“详情 -> 执行 -> 安检 -> 完成”。检查表分为用气设备清单（如计量、报警、智能瓶阀、管道、工具、热水器）和用气环境清单（如通风、易燃物、安装规范、管道腐蚀、泄漏、报警器状态），项目由后台配置。
- 安检照片默认最多/目标 6 张，必须选择照片类型（安检前、安检中、安检后、设备、环境、管道、阀门、其他），自动添加地址和时间水印。用户电子签字可保存、清除和重新签署，签名与检查结论绑定。
- 结果为不合规时必须选择风险等级：一级高风险立即整改、二级中风险限期整改、三级低风险建议整改。界面可允许问题描述选填，但一级、二级事件的后台规则应要求补充不合格项或整改说明。
- 完成检查后生成隐患条目，状态至少含待处理、处理中、已整改、已关闭/已超时；整改完成可由安检员或授权复核人标记，须保留整改照片、用户签字和时间。

## 5. 统一状态与权限

```text
待分配 -> 待接单 -> 已接单 -> 已到达 -> 处理中 -> 待审核/待确认 -> 已完成
                                      └-> 异常处理/待整改 -> 复检 -> 已完成
任意非终态 -> 已取消（记录取消方、原因、责任归属）
```

- 任务状态迁移由服务端校验角色、资质、组织、时段、区域及前置条件。
- 弱网可查看已分配任务和暂存现场材料；关阀、设备激活、任务完结、资金动作必须以服务端确认结果为准。
- App 不展示其他组织的订单、完整支付流水或超出任务必要范围的个人信息。

## 6. 记录、收入、个人中心与帮助

- 记录页按角色展示安检历史/隐患、设备安装记录、维修记录、配送记录和空瓶回收记录。每条记录可进入详情查看任务状态、照片/视频、签名、材料、安检结果、收费、用户评价与整改状态。
- 账户管理展示总收入、本月收入、本年收入、服务/安装/配送工单收入、待结算和可提现余额；支持提现申请、提现历史、添加/管理银行卡。提现按平台审核与线下/三方打款规则执行。
- 统计页展示角色相关的任务数、完成率、及时率、收入、押金代收/退还、评价和异常率；口径、时间范围和数据更新时间必须明确。
- 个人设置支持消息通知、声音提示、震动反馈、头像、资料、帮助和退出登录。帮助中心包含角色对应的常见问题和视频教程，例如开始处理工单、阀门/管道维修、新装设备、随瓶安检、拍照取证、用户签字和提现。
- 每位服务人员可生成推荐二维码，用于经平台批准的服务人员招募或推广。二维码内容可编辑、分享和停用，但不得包含个人证件、银行卡、长期登录凭证或可越权的角色授权信息。

## 7. 服务质量扩展

- 资质到期、培训考试、工具/车辆检查、评分、服务超时和异常率看板。
- 维修知识库、远程专家会诊、备件领用、语音转写、电子保修卡和用户回访。

## 8. 首期 Client API 落地边界（2026-07）

- 工作人员 API 固定为 `/heqi/client/v1/staff`，令牌客户端为 `service_app`；不提供注册，只允许后台已创建、启用且岗位受支持的账户登录。
- 三类岗位均属于同一 Staff Client API：安装维修和安检使用 `/tickets` 工单接口；配送使用 `/delivery/orders`、开始配送、轨迹批量补传、到达围栏校验、异常/恢复和提交签收接口。所有查询和动作只允许访问当前账号被分派的对象。
- 登录后调用 `/preflight`。首期真实校验账号、唯一岗位、所属组织、资质有效期和上班状态；每日培训、服务区域与授权设备尚未配置时返回 `not_configured`，客户端必须明确展示，不能显示为“已通过”。
- 首期岗位为配送、安装维修、安检。安装/维修工单只分派给安装维修人员，安检/复检只分派给安检人员，客服类工单不进入工作人员 App。
- 工单统一复用 `cs_ticket`，状态为待分派、已分派、处理中、异常、待用户确认、已完成或已取消。工作人员只能操作分派给本人的工单；现场结果必须包含定位、原始采集时间、上传资源地址和幂等号。
- 安装和维修至少提交前、中、后图片及用户签名；安检和复检至少提交一张图片、结果及用户签名。单次最多六张图片、三段视频。不合规或高风险结论只能进入异常，不能提交待用户确认。
- 配送人员只操作分派给本人的供气配送订单，可开始配送、批量补传轨迹、到达校验、异常/恢复和提交签收；不能修改订单金额。到达以订单地址坐标和配置地理围栏为准。
- 工作人员钱包与用户钱包复用统一模型，支持余额、充值订单、不可变流水、提现及银行卡；服务收入只能由已完成业务事实产生，客户端不能直接增加余额。

## 9. Flutter 开发说明

### 9.1 平台、角色与工程边界

- 服务人员端交付 Android、iOS、Web。生产工程按规划放在 `apps/service_app`；Web 只支持浏览器前台授权的位置与相机能力，不作为后台定位或后台任务的替代方案。当前 `ui` 目录是配送、安装维修、安检三类原型的交互实现，不连接真实定位、相机、蓝牙、支付或业务 API。
- 三类岗位共用一个 Flutter 应用和登录体系，每个账号仅有一个服务岗位，令牌 client claim 固定为 `service_app` 并携带唯一 `role_code`。岗位变更必须由后台完成并重新登录换取令牌；客户端不提供角色切换。
- 工作人员 API 根路径固定为 `/heqi/client/v1/staff`。客户端不得访问用户端、平台后台、气站后台或配送点后台的令牌与接口。
- 首期后端不提供工作人员自助注册时，Flutter 注册页面不得伪造成功；若未来开放申请，只能创建待审核账户，不能直接授予岗位能力。

### 9.2 分层结构与角色化功能

采用 MVVM + Repository，UI、业务编排和数据边界严格分离：

```text
apps/service_app/lib/
  app/
    app.dart
    router.dart                  # go_router、岗位与作业前置守卫
    role_context.dart            # 当前唯一岗位、组织和服务区域
    dependencies.dart
  data/
    models/
    services/                    # API、定位、相机、蓝牙、上传、安全存储
    repositories/                # 任务、取证、轨迹、钱包、离线队列
    offline/                     # 加密草稿、Outbox、冲突与补传
  domain/
    models/
    use_cases/                   # 到场、扫描、安检、安装、完成任务
  ui/
    core/                        # 角色主题、通用状态、取证组件
    features/
      auth/
      workbench/
      delivery/
      installation/
      inspection/
      evidence/
      hazard/
      records/
      wallet/
      profile/
```

- 共用任务卡、步骤器、相机、签名、弱网提示等展示组件；配送、安装维修、安检分别拥有独立 ViewModel、Use Case、检查表解释器和状态机，不得用一个万能表单加前端条件判断代替领域规则。
- View 不直接更新任务状态、金额、风险等级或本地数据库。ViewModel 只发起命令并呈现服务端返回状态；Repository 负责 API、本地加密草稿、上传队列和领域模型转换。
- 检查表、强制取证项、材料清单和步骤顺序由服务端版本化下发。客户端缓存模板版本，提交时带模板 `identity` 和版本；过期模板必须进入冲突处理，不能静默套用新模板。
- 所有任务、证据、轨迹、人员、组织和钱包引用只使用 `identity`；数据库内部自增 ID 不进入 Flutter 模型、日志、深链或离线队列。

### 9.3 路由、底部导航与守卫

- 使用 `MaterialApp.router` 与 `go_router`。登录后先进入 `/preflight`，统一校验账户启用、岗位、组织、资质、每日培训、上班状态、服务区域和授权设备，再进入角色工作台。
- 首期角色底部导航使用 `StatefulShellRoute.indexedStack`，只暴露有真实 Client API 的入口：
  - 配送员：`/work`（本人配送订单）、`/records`（已完成记录）、`/me`
  - 安装维修员与安检员：`/work`（本人工单）、`/records`（已完成记录）、`/me`
- 任务详情统一使用 `/tasks/:identity`，具体步骤使用 `/tasks/:identity/steps/:stepCode`；路由解析后仍须从服务端读取任务类型、当前状态和允许动作，不能信任路径中的角色或步骤。
- 未完成培训、未上班、资质失效、超出服务区或任务未分派给本人时，守卫导航到明确的阻断页；返回栈、通知深链和手工 URL 均不能绕过。
- 普通退出时若存在未提交草稿，必须先返回上传或二次确认放弃并安全删除；令牌失效或异常退出时按账号加密封存，只有同一账号重新认证后可恢复，换账号不可见。

### 9.4 任务状态与现场作业

- 每类任务由独立状态模型驱动，UI 只展示服务端返回的 `allowed_actions`。按钮禁用、步骤条位置和本地完成标记不构成业务校验。
- 配送流程至少实现订单确认、导航到场、围栏校验、气瓶扫描、随瓶安检、收款确认、签收/回收；安装流程按使用条件、备料、安装、测试、前期安检、用户确认、收款执行；安检流程按详情、执行、检查、风险等级、签名、隐患/复检执行。
- 不合格、高风险、测试失败、围栏异常、金额差异、证据缺失和设备回执不确定时只能进入异常、待整改或待确认，不能由客户端跳到已完成。
- 关阀、设备激活、任务完结、收款和提现均显示服务端确认状态。请求成功、文件进入上传队列或本地步骤完成不得显示为最终成功。
- 检查项使用稳定代码；照片类型、材料、风险等级和错误原因由契约映射，禁止根据中文标题或错误文案驱动状态流转。

### 9.5 离线队列、定位与证据

- 离线能力只覆盖已分配任务的只读信息和现场草稿。关阀、激活、资金、最终完结等动作必须在线确认；离线时明确告知“已暂存/待补传”，不能显示“已完成”。
- 本地使用平台安全存储保护数据库密钥，任务草稿、轨迹点、照片/视频元数据、签名、扫描结果和收款确认采用加密数据库或加密文件。退出角色或账户时按服务端留存策略处理，不能只删索引留下明文文件。
- 每个离线写入包含本地操作 `identity`、业务对象 `identity`、幂等键、原始采集时间、来源、完整性标记和内容哈希。补传保留原始时间，按依赖顺序投递，409/版本冲突进入人工可见的冲突队列。
- 文件先落加密暂存区并记录哈希，获得短期上传授权后上传；业务提交只引用上传成功的资源 URI。失败重试不得重复创建证据，后台删除或拒绝的附件不得被本地队列重新“复活”。
- 配送定位仅在履约期间、满足权限与任务状态时采集。Android 前台服务和 iOS 后台定位必须显示系统要求的可见提示；权限撤销、精度不足、后台受限和长时间无点位均写入任务状态。
- 用户签名画布保存矢量笔画或可验证位图及哈希，并与结论、任务、操作者和采集时间绑定；禁止复用其他任务签名。

### 9.6 Android/iOS 平台适配

Web 生产部署必须使用 HTTPS，并通过 `--dart-define=API_BASE_URL=...` 注入 API 地址。浏览器草稿和附件只保存 AES-GCM 密文；不支持 Android/iOS 的持续后台定位与后台任务保障。

| 能力 | Android | iOS |
| --- | --- | --- |
| 相机/相册 | 运行时按用途申请 Camera/Photo Picker，使用系统选择器优先 | 使用相机和 Photos 限定访问，解释用途并处理 Limited 状态 |
| 蓝牙扫描 | 按系统版本申请 Nearby Devices/Bluetooth 权限 | 配置 Bluetooth 用途说明，仅在任务步骤内扫描 |
| 定位 | 前台精确定位；配送后台轨迹使用合规前台服务与常驻通知 | 先申请 When In Use，确需配送后台定位时再升级并配置 Background Modes |
| 通知 | 创建安全、任务、上传三类通知渠道，高风险安全通知不可静默关闭 | 分类注册通知操作，点击后重新读取任务和权限 |
| 文件暂存 | App 私有目录、加密数据库，禁止写公共目录 | Application Support/Library 私有目录，排除不必要云备份 |
| 深链 | App Links 校验域名与签名证书 | Universal Links 配置 Associated Domains |

- 权限说明必须与实际采集行为一致。拒绝权限时给出可恢复路径；不得因相机或精确定位权限失败伪造照片、地址或到场结果。
- 地图、导航、蓝牙、相机和签名通过抽象 Service 注入；Android/iOS 实现返回统一领域结果和稳定错误码。

### 9.7 视觉、性能与测试

- 设计基线以 `doc/服务端APP-配送端-产品设计`、`doc/服务端APP-安装端-产品设计`、`doc/服务端APP-安全检查端-产品设计` 和 `ui/?app=service&role=...` 为准。统一使用紫色作业框架，安检关键成功动作可使用安全绿色；风险等级必须同时展示文字、图标和颜色。
- 任务详情优先展示任务号、类型、预约/SLA、地址、脱敏联系人、风险与允许动作。固定底部操作按钮不得遮挡检查项、签名或系统安全区。
- 长清单使用惰性列表和分段保存；照片视频缩略图解码、压缩和上传移出 UI isolate。后台轨迹、上传和补传必须受电量、网络与系统调度约束，不用常驻无限循环。
- ViewModel、Use Case、Repository、离线队列和冲突处理覆盖单元测试；角色/组织守卫、步骤前置、风险结论和弱网状态覆盖 Widget 测试；三角色主闭环覆盖 Android/iOS 集成测试。
- 每次合并至少执行 `flutter analyze`、`flutter test`、Android debug 构建、iOS Simulator 构建和 Web release 构建；定位、相机、蓝牙、推送、后台任务、App Links/Universal Links 和安全存储改动必须真机或浏览器回归。