From fceb2545718281458a1cb45b6b6c935aa90c3561 Mon Sep 17 00:00:00 2001 From: liuyun Date: Thu, 15 Oct 2026 08:41:29 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=8A=A4=E7=90=86=E5=91=98=20APP=20Flu?= =?UTF-8?q?tter=20=E8=AE=BE=E8=AE=A1=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 4.8 --- .../2026-10-15-护理员APP-Flutter-design.md | 49 +++++++++++++++++++ 1 file changed, 49 insertions(+) create mode 100644 docs/superpowers/specs/2026-10-15-护理员APP-Flutter-design.md diff --git a/docs/superpowers/specs/2026-10-15-护理员APP-Flutter-design.md b/docs/superpowers/specs/2026-10-15-护理员APP-Flutter-design.md new file mode 100644 index 0000000..b8fe85b --- /dev/null +++ b/docs/superpowers/specs/2026-10-15-护理员APP-Flutter-design.md @@ -0,0 +1,49 @@ +# 护理员 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 + +1. **技术栈**：Riverpod（状态管理）+ dio（HTTP）+ sqflite（本地离线队列）+ go_router（路由）。shared_preferences 存 token。 +2. **目录**：feature-first——`lib/core/`（api/db/router/theme/auth）+ `lib/features/{auth,today,service,abnormal}/`。 +3. **API 对接**：base `http://localhost:3000/api/v1`（`--dart-define` 可覆盖）；统一响应 `{code,message,data}`，`code=0` 成功、非 0 抛业务错误（`message` 含规则号如 3001/1001）；token 走 `Authorization: Bearer`。 +4. **离线队列**：签到/签退/勾项目/照片/异常全部本地 sqflite 落队 + 生成 `client_md5`；联网后 `POST /record/offline/sync` 幂等补传（md5 去重）；照片文件本地暂存、补传后保留 ≥7 天。 +5. **服务器取时**：签到/签退时间**不传**（后端生成）；定位失败不阻塞（标「未获取」）；必拍未拍后端 3001 硬拒 → APP 在签退按钮前置校验 + 拒拍出路（选原因放行）。 +6. **措辞纪律**：留痕口径「签到/签退/服务执行」，禁用「打卡/考勤」；异常上报不禁用「报警」。 + +## 数据流 + +- 登录（租户 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；异常上报/扑空落库；断网签到 → 恢复联网补传。