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

服务端 App 需求

1. 定位与角色模型

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

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

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

账户、资质、上班与培训

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

2. 配送工作台

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

2.1 配送任务页面与排序

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

2.2 配送与空瓶回收闭环

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

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

3. 安装维修工作台

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

3.1 维修工单闭环

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

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

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

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

4. 安检工作台

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

4.1 安检任务与隐患整改

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

5. 统一状态与权限

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

• 任务状态迁移由服务端校验角色、资质、组织、时段、区域及前置条件。
• 弱网可查看已分配任务和暂存现场材料；关阀、设备激活、任务完结、资金动作必须以服务端确认结果为准。
• 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。生产工程按规划放在 apps/service_app；当前 ui 目录是配送、安装维修、安检三类原型的交互实现，不连接真实定位、相机、蓝牙、支付或业务 API。
• 三类岗位共用一个 Flutter 应用和登录体系，每个账号仅有一个服务岗位，令牌 client claim 固定为 service_app 并携带唯一 role_code。岗位变更必须由后台完成并重新登录换取令牌；客户端不提供角色切换。
• 工作人员 API 根路径固定为 /heqi/client/v1/staff。客户端不得访问用户端、平台后台、气站后台或配送点后台的令牌与接口。
• 首期后端不提供工作人员自助注册时，Flutter 注册页面不得伪造成功；若未来开放申请，只能创建待审核账户，不能直接授予岗位能力。

9.2 分层结构与角色化功能

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

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 平台适配

能力	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 构建；定位、相机、蓝牙、推送、后台任务、App Links/Universal Links 和安全存储改动必须真机回归。