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`；不提供注册，只允许后台已创建、启用且岗位受支持的账户登录。
- 首期岗位为配送、安装维修、安检。安装/维修工单只分派给安装维修人员，安检/复检只分派给安检人员，客服类工单不进入工作人员 App。
- 工单统一复用 `cs_ticket`，状态为待分派、已分派、处理中、异常、待用户确认、已完成或已取消。工作人员只能操作分派给本人的工单；现场结果必须包含定位、原始采集时间、上传资源地址和幂等号。
- 安装和维修至少提交前、中、后图片及用户签名；安检和复检至少提交一张图片、结果及用户签名。单次最多六张图片、三段视频。不合规或高风险结论只能进入异常，不能提交待用户确认。
- 配送人员只操作分派给本人的供气配送订单，可开始配送、批量补传轨迹、到达校验、异常/恢复和提交签收；不能修改订单金额。到达以订单地址坐标和配置地理围栏为准。
- 工作人员钱包与用户钱包复用统一模型，支持余额、充值订单、不可变流水、提现及银行卡；服务收入只能由已完成业务事实产生，客户端不能直接增加余额。