docs: 护理员 APP Flutter 设计文档

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

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；异常上报/扑空落库；断网签到 → 恢复联网补传。