9.6 KiB
9.6 KiB
项目文档：服务端 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/staffAPI 体系。 - 本地数据：延续现有加密草稿机制，新增附件队列、重试、冲突版本和清理策略。
- 运行环境：项目当前 Flutter 与 Android 构建环境；不得为本次 UI 优化替换应用框架。
4. 目录结构建议
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 | 建立三岗位目标产品设计与开发对照，明确共享架构、接口、状态机、离线、安全、测试和发布要求 |