platforms/docs/项目文档_服务端APP三岗位产品设计与开发_v1.0.md

# 项目文档：服务端 APP 三岗位产品设计与开发 v1.0

## 1. 项目概述

### 1.1 项目名称

服务端 APP 安装维修、配送、安全检查三岗位 UI 优化与功能完善。

### 1.2 目标

以三个“最新参考产品设计”目录为目标界面，升级现有 Flutter `apps/service_app`。保留当前真实登录、角色识别、准入、任务、取证、草稿和接口能力，通过扩展路由、领域状态机、专用页面与服务端接口补齐业务闭环。

### 1.3 目标设计目录

- `doc/服务端APP-安装端-最新参考产品设计`：40 张页面。
- `doc/服务端APP-配送端-最新参考产品设计`：42 张页面。
- `doc/服务端APP-安全检查端-最新参考产品设计`：40 张页面。

上述图片是目标状态，不是当前完成状态。各岗位目录中的《产品设计说明》提供逐页功能和验收要求。

## 2. 当前系统状态

### 2.1 已有能力

- Flutter 单应用支持登录后按角色进入安装维修、配送或安全检查岗位。
- 路由已有 `/login`、`/preflight`、`/tasks/:identity`、`/tasks/:identity/evidence`、`/work`、`/records`、`/me`。
- 仓储层已有个人资料、作业前检查、钱包、考勤、任务列表与详情。
- 通用工单已有开始、异常、恢复和结果提交。
- 配送已有轨迹追加、到达和签收提交。
- 证据文件可上传，本地草稿具备加密保存基础。

### 2.2 主要差距

- 当前路由以通用页面为主，无法承载三个岗位各自的完整步骤、字段和异常分支。
- 后端接口尚未覆盖岗位申请、每日培训、详细资质、排单、气瓶、收款、隐患、整改、复检、提现、知识库、人工支持等目标能力。
- 任务状态和 `allowed_actions` 不完整，客户端容易出现“页面有按钮但服务端不可执行”的风险。
- 记录、统计、个人资料、通知和离线冲突仍需领域化。
- 当前完成状态不能由图片推断，必须以代码、接口和自动化测试为准。

## 3. 技术栈与运行环境

- 客户端：Flutter、Dart、GoRouter、现有网络与本地存储封装。
- 服务端：沿用项目现有 `/heqi/client/v1/staff` API 体系。
- 本地数据：延续现有加密草稿机制，新增附件队列、重试、冲突版本和清理策略。
- 运行环境：项目当前 Flutter 与 Android 构建环境；不得为本次 UI 优化替换应用框架。

## 4. 目录结构建议

```text
apps/service_app/lib/
├── app/
│   ├── router.dart                    # 现有路由入口，扩展岗位子路由
│   └── dependencies.dart              # 仓储、草稿、会话等依赖
├── data/
│   ├── models/                        # 任务、证据、风险、气瓶、结算模型
│   └── repositories/
│       └── service_repository.dart    # 保留现有方法并扩展岗位接口
├── domain/
│   ├── installation/                  # 安装维修状态与动作
│   ├── delivery/                      # 配送与空瓶状态与动作
│   ├── inspection/                    # 安检、隐患、整改和复检
│   └── shared/                        # 身份、准入、钱包、通知、离线
└── ui/
    ├── design_system/                 # 颜色、文字、间距、按钮、状态标签
    ├── features/shared/               # 登录、准入、消息、钱包、个人中心
    ├── features/installation/         # 安装维修专用页面
    ├── features/delivery/             # 配送专用页面
    └── features/inspection/           # 安检专用页面
```

原则：通过新增目录、页面和方法扩展现有实现；保留公共接口与现有路由兼容层，避免一次性重写。

## 5. 共享设计系统

| 项目 | 规范 |
| --- | --- |
| 主色 | `#2563EB` |
| 页面背景 | `#F7F8FA` |
| 成功 | `#16875D` |
| 提醒 | `#B86400` |
| 危险 | `#C7352A` |
| 页面边距 | 20px 视觉基准，代码按 Flutter 逻辑像素适配 |
| 圆角 | 最大 8px，除头像、状态点、开关等固有圆形控件 |
| 图标 | Material 或项目既有图标库，禁止手绘占位符 |
| 禁止项 | 紫色、紫色渐变、光晕、AI 图形、AI 文案、装饰性大卡片 |

## 6. 路由与模块规划

### 6.1 共享路由

- 登录、岗位申请、作业前检查、准入阻断、每日培训。
- 消息、钱包、提现、银行卡、离线队列、个人资料、二维码、设置、人工支持、知识库和反馈。
- 共享页面通过角色配置切换标题、字段、权限和接口，不硬编码岗位文案。

### 6.2 安装维修模块

- 工单列表与详情、使用条件、材料、安装、测试、前期安检、签名、收款、完成。
- 维修执行、安全检查、异常恢复、巡检、复检、备件、保修和回访。

### 6.3 配送模块

- 订单、接单改派、时间排单、路线排单、导航到达、围栏异常。
- 气瓶扫描、随瓶安检、取证、收款、签收、空瓶回收、蓝牙设备和轨迹补传。
- 服务用户、配送记录与配送统计。

### 6.4 安全检查模块

- 任务、到场、设备、环境、取证、签名、合格结果和完成。
- 不合格、风险分级、一级高风险处置、整改通知、隐患、整改、复检和拒检。
- 区域抽查、安检记录与安检统计。

## 7. 服务端接口规划

### 7.1 兼容原则

- 保留现有路径和响应字段，新增字段均允许旧客户端忽略。
- 新动作优先添加子资源或动作端点，不改变现有 `start`、`exception`、`recover`、`submit-result` 语义。
- 所有变更动作接收幂等键并返回服务端版本号、最终状态和 `allowed_actions`。
- 错误响应返回稳定错误码、用户可读消息、是否可重试和必要的当前资源快照。

### 7.2 共享接口组

- 岗位申请与审核、角色和组织、资质与到期提醒。
- 作业前检查、考勤、培训、授权设备和阻断原因。
- 钱包明细、提现、银行卡、消息、知识库、人工服务请求和反馈。
- 附件初始化、分片上传、完成确认、校验失败和断点续传。

### 7.3 岗位专用接口组

- 安装维修：条件、材料、步骤、测试、签名、收款、备件、保修与回访。
- 配送：接单、改派、排单、气瓶、围栏、安检、收款、签收、空瓶、押金和轨迹。
- 安检：检查项、测量值、风险分级、抢险联动、整改单、隐患、整改、复检和拒检。

## 8. 数据模型要求

- 所有任务包含 `id`、`role_code`、`status`、`version`、`allowed_actions`、计划时间、用户与脱敏地址。
- 所有状态事件包含操作人、角色、设备、客户端时间、服务端时间、定位与幂等键。
- 证据包含类型、业务步骤、文件哈希、大小、MIME、拍摄时间、定位精度、本地状态和服务端文件标识。
- 金额使用最小货币单位整数，分别记录商品、押金、优惠、线上、线下、已核验、待核验和差额。
- 风险字段固定枚举并带规则版本，禁止自由文本替代等级。
- 数据库新增字段必须提供中文 `COMMENT`；枚举字段列出全部值，JSON 字段说明结构。

## 9. 离线与安全

- 草稿、附件和签名使用系统安全存储管理的密钥加密，日志不记录明文手机号、地址、签名或文件内容。
- 离线队列按资源和动作排序；相同幂等键只执行一次。
- 冲突时展示本地版本、服务端版本和差异，不静默覆盖。
- 退出登录、切换账号和清理缓存前检查未同步数据并阻断危险操作。
- 地图列表默认显示模糊点位，精确地址仅在授权任务详情展示。

## 10. 分阶段开发计划

| 阶段 | 范围 | 完成标准 |
| --- | --- | --- |
| P0 | 共享设计系统、角色路由、准入、状态与错误模型 | 三岗位可登录并进入正确工作台，现有功能无回归 |
| P1 | 三岗位核心任务主链路 | 安装、配送、安检各有一条正常链路端到端完成 |
| P2 | 高风险与异常链路 | 阻断、失败、拒检、一级风险、改派、围栏异常可闭环 |
| P3 | 离线、证据、冲突与幂等 | 弱网、断网、重复提交和版本冲突测试通过 |
| P4 | 钱包、记录、统计、资质与支持 | 目标目录全部页面有对应路由、接口或明确只读状态 |
| P5 | 全量视觉与回归 | 逐页截图比对、无障碍、性能、安全和兼容性验收通过 |

## 11. 测试策略

- 单元测试：金额、风险分级、允许动作、状态转换、幂等和冲突合并。
- 仓储测试：现有 API 兼容、新接口解析、错误码、重试和超时。
- Widget 测试：表单校验、按钮状态、长文本、空列表、失败和离线提示。
- 集成测试：三岗位正常链路及关键异常链路。
- 安全测试：越权、敏感信息、日志泄露、本地加密、附件伪造和重复提交。
- 视觉回归：目标图片与相同状态、相同逻辑尺寸的 Flutter 截图并排比较。

## 12. 验收与发布

- 每张目标图片必须映射到页面、路由、状态、接口和测试，不以“已经画图”代替开发完成。
- 原有真实登录、任务、取证、草稿和配送接口行为必须保持兼容。
- 关键接口必须先在测试环境验证，再分岗位灰度发布。
- 发布前完成数据库变更审核、接口文档、移动端回归、异常演练和回滚方案。

## 13. 变更记录

| 版本 | 日期 | 内容 |
| --- | --- | --- |
| v1.0 | 2026-09-06 | 建立三岗位目标产品设计与开发对照，明确共享架构、接口、状态机、离线、安全、测试和发布要求 |