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

服务端 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 架构与目录规划

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 逐页验收

每张设计图必须映射到以下六项，缺一项不得标记完成：

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、接口、状态机、离线、安全、测试和分阶段交付要求