50 KiB
50 KiB
服务端 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 事实源优先级
发生冲突时按以下顺序处理：
- 人身安全、资金、隐私、权限和审计等服务端强制规则。
docs/04-服务端App需求.md、docs/02-核心业务流程.md、docs/11-数据接口与安全.md。- 本文档中的接口、状态机、兼容和验收约束。
- 三个“最新参考产品设计”目录及其产品设计说明。
- 当前 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 架构与目录规划
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 作业前检查
{
"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 任务详情与允许动作
{
"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 幂等动作响应
{
"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 统一业务错误
{
"error_code": "RESOURCE_VERSION_CONFLICT",
"message": "任务已被更新，请刷新后继续",
"retryable": false,
"field_errors": {},
"current_resource_version": 9,
"allowed_actions": ["refresh"]
}
客户端只根据 error_code 驱动流程，中文 message 用于展示，不解析服务端英文或中文文案判断业务状态。
9. 领域状态机与强制规则
9.1 安装维修
已分派 -> 执行中 -> 待用户确认 -> 已完成
| |
+-> 异常暂停 <-+
异常暂停 -> 执行中
- 安装、维修必须具备施工前、施工中、施工后证据和用户签名。
- 条件不合格、测试失败或高风险结果不得直接进入待确认或已完成。
- 备件领用、消耗和退回必须形成库存事务，客户端不能直接修改库存余额。
- 电子保修卡只能由已完成安装或满足规则的维修事实生成。
9.2 配送
待接单 -> 已接单 -> 已排单 -> 配送中 -> 已到达
-> 气瓶已核验 -> 安检完成
-> 待收款 -> 待签收 -> 已完成
任一执行态 -> 异常暂停 -> 原执行态
- 现有数字状态
20 -> 33 -> 34 -> 23保持兼容；新增细分状态通过字符串码和扩展事件表达，避免破坏旧系统。 - 气瓶必须先校验再绑定订单，错瓶、召回瓶、重复瓶或非可用库存一律阻断。
- 轨迹缺失允许补传，但不得伪造时间；围栏异常必须记录定位精度和人工审核结论。
- 收款、押金、空瓶和签收全部确认后才允许完成配送。
9.3 安全检查
已分派 -> 已到场 -> 检查中 -> 待评定
-> 合格 -> 已完成
-> 不合格 -> 隐患待整改 -> 待复检 -> 已关闭
-> 一级高风险 -> 现场管控 -> 抢险移交 -> 隐患待整改
-> 用户拒检 -> 拒检归档/改约
- 风险枚举固定为
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 逐页验收
每张设计图必须映射到以下六项，缺一项不得标记完成：
- 可访问路由和正确返回路径。
- 真实或契约模拟的接口数据，不使用写死成功结果。
- 正常、加载、空、错误、离线和无权限状态。
- 服务端状态与
allowed_actions驱动的操作按钮。 - 对应 Widget、仓储或集成测试。
- 与目标图同尺寸的截图及差异评审记录。
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、接口、状态机、离线、安全、测试和分阶段交付要求 |