695 lines
50 KiB
Markdown
695 lines
50 KiB
Markdown
# 服务端 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 架构与目录规划
|
||
|
||
```text
|
||
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 作业前检查
|
||
|
||
```json
|
||
{
|
||
"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 任务详情与允许动作
|
||
|
||
```json
|
||
{
|
||
"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 幂等动作响应
|
||
|
||
```json
|
||
{
|
||
"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 统一业务错误
|
||
|
||
```json
|
||
{
|
||
"error_code": "RESOURCE_VERSION_CONFLICT",
|
||
"message": "任务已被更新，请刷新后继续",
|
||
"retryable": false,
|
||
"field_errors": {},
|
||
"current_resource_version": 9,
|
||
"allowed_actions": ["refresh"]
|
||
}
|
||
```
|
||
|
||
客户端只根据 `error_code` 驱动流程，中文 `message` 用于展示，不解析服务端英文或中文文案判断业务状态。
|
||
|
||
## 9. 领域状态机与强制规则
|
||
|
||
### 9.1 安装维修
|
||
|
||
```text
|
||
已分派 -> 执行中 -> 待用户确认 -> 已完成
|
||
| |
|
||
+-> 异常暂停 <-+
|
||
异常暂停 -> 执行中
|
||
```
|
||
|
||
- 安装、维修必须具备施工前、施工中、施工后证据和用户签名。
|
||
- 条件不合格、测试失败或高风险结果不得直接进入待确认或已完成。
|
||
- 备件领用、消耗和退回必须形成库存事务，客户端不能直接修改库存余额。
|
||
- 电子保修卡只能由已完成安装或满足规则的维修事实生成。
|
||
|
||
### 9.2 配送
|
||
|
||
```text
|
||
待接单 -> 已接单 -> 已排单 -> 配送中 -> 已到达
|
||
-> 气瓶已核验 -> 安检完成
|
||
-> 待收款 -> 待签收 -> 已完成
|
||
任一执行态 -> 异常暂停 -> 原执行态
|
||
```
|
||
|
||
- 现有数字状态 `20 -> 33 -> 34 -> 23` 保持兼容；新增细分状态通过字符串码和扩展事件表达，避免破坏旧系统。
|
||
- 气瓶必须先校验再绑定订单，错瓶、召回瓶、重复瓶或非可用库存一律阻断。
|
||
- 轨迹缺失允许补传，但不得伪造时间；围栏异常必须记录定位精度和人工审核结论。
|
||
- 收款、押金、空瓶和签收全部确认后才允许完成配送。
|
||
|
||
### 9.3 安全检查
|
||
|
||
```text
|
||
已分派 -> 已到场 -> 检查中 -> 待评定
|
||
-> 合格 -> 已完成
|
||
-> 不合格 -> 隐患待整改 -> 待复检 -> 已关闭
|
||
-> 一级高风险 -> 现场管控 -> 抢险移交 -> 隐患待整改
|
||
-> 用户拒检 -> 拒检归档/改约
|
||
```
|
||
|
||
- 风险枚举固定为 `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、接口、状态机、离线、安全、测试和分阶段交付要求 |
|