3.7 KiB
3.7 KiB
护理员 APP（Flutter）· 设计文档
本文是护理员 APP 的设计背景，规范权威见
openspec/changes/nurse-app-flutter/与 PRD §四（护理员移动端 APP）。
Context
C0–C5 已落地后端（ec-nest）+ 机构管理后台（ec-admin）。护理员 APP（Flutter）是履约留痕的录入主战场——C3 的签到/签退/项目/照片/异常接口就是为它准备的。本期用 nurse01 测试账号 + TY20261015 测试机构验收。
Goals / Non-Goals
Goals：登录、M1 今日任务、M2 服务执行（签到→勾项目→拍照→签退）、拍照分档（必拍强制+压疮标签+拒拍出路）、异常上报（9 宫格）、扑空（未遇）、离线队列+自动补传。
Non-Goals：家属端（UniAPP）、质控/派单（APP 不做，PRD 明确「改计划是质控员的事，APP 不提供」）、结算金额展示（本期无结算）。
Decisions
- 技术栈：Riverpod（状态管理）+ dio（HTTP）+ sqflite（本地离线队列）+ go_router（路由）。shared_preferences 存 token。
- 目录：feature-first——
lib/core/（api/db/router/theme/auth）+lib/features/{auth,today,service,abnormal}/。 - API 对接：base
http://localhost:3000/api/v1（--dart-define可覆盖）；统一响应{code,message,data}，code=0成功、非 0 抛业务错误（message含规则号如 3001/1001）；token 走Authorization: Bearer。 - 离线队列：签到/签退/勾项目/照片/异常全部本地 sqflite 落队 + 生成
client_md5；联网后POST /record/offline/sync幂等补传（md5 去重）；照片文件本地暂存、补传后保留 ≥7 天。 - 服务器取时：签到/签退时间不传（后端生成）；定位失败不阻塞（标「未获取」）；必拍未拍后端 3001 硬拒 → APP 在签退按钮前置校验 + 拒拍出路（选原因放行）。
- 措辞纪律：留痕口径「签到/签退/服务执行」，禁用「打卡/考勤」；异常上报不禁用「报警」。
数据流
- 登录（租户 code + 账号 + 密码）→ token 落 shared_preferences → 之后请求带 token。
- M1：
GET /order/today→ 今日工单卡片（老人/时段/项目/状态）。 - M2：点卡片 → 签到
POST /record/checkin（定位+自动时间）→ 勾项目POST /record/item/save（默认全勾 done，exec_result ∈ done/undo_not_done/undo_refused）→ 拍照POST /record/photo/upload（必拍强制+压疮标签+拒拍出路）→ 签退POST /record/checkout。 - 异常：
POST /abnormal（abnormal_type 必选，其余可选）。 - 扑空：
POST /abnormal（abnormal_type=not_met + 到访时间/定位/原因必留）→ 工单转 not_met。 - 离线：本地队列 +
client_md5+POST /record/offline/sync。
界面（大字 ≥20pt、常态 ≤3 击、首屏即任务）
- 登录页：租户/账号/密码。
- 今日任务：卡片列表（今日待办 + 已完成 + 未遇），点卡片进服务执行。
- 服务执行：签到超大按钮 → 项目勾选列表（默认全勾）→ 签退超大按钮（必拍项未拍则禁用+提示）。
- 异常上报：9 宫格分类（必选）+ 描述/语音/照片（可选）。
- 扑空：未遇按钮 → 到访时间（自动）/定位（自动）/原因（必选下拉）。
Risks / Trade-offs
- [离线补传幂等] → client_md5 唯一 + 后端幂等。
- [必拍未拍] → 前端签退前置校验 + 后端 3001 双保险。
- [照片体积] → 前端压缩 ≤500KB 再传。
验收（用 TY20261015 测试机构）
nurse01 登录 → 看到张护理今日工单 → 签到 → 勾项目 → 拍照 → 签退 → 后端留痕 submitted；异常上报/扑空落库；断网签到 → 恢复联网补传。