docs(openspec): 护理员 APP Flutter change 提案

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

openspec/changes/nurse-app-flutter/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-10-15

openspec/changes/nurse-app-flutter/design.md

@@ -0,0 +1,29 @@
+## Context
+
+C3 后端 record/abnormal/order.today 已就绪。护理员 APP（Flutter）是录入主战场。技术栈 Riverpod+dio+sqflite+go_router。
+
+## Goals / Non-Goals
+
+**Goals:** 登录、M1 今日任务、M2 服务执行、拍照分档、异常上报、扑空、离线队列。
+
+**Non-Goals:** 家属端、质控/派单、结算金额。
+
+## Decisions
+
+1. 技术栈 Riverpod+dio+sqflite+go_router，token 落 shared_preferences。
+2. feature-first 目录：core/（api/db/router/theme/auth）+ features/{auth,today,service,abnormal}/。
+3. API base 可配置（--dart-define）；统一响应 {code,message,data}；token Authorization: Bearer。
+4. 离线队列 sqflite + client_md5 + POST /record/offline/sync。
+5. 签到/签退时间不传（服务器取时）；定位失败不阻塞；必拍未拍 3001 双保险（前端签退前置 + 后端硬拒）。
+
+## 数据流
+
+登录 → GET /order/today → POST /record/checkin → item/save → photo/upload → checkout；POST /abnormal（异常/扑空）；离线 sync。
+
+## Risks
+
+离线幂等（client_md5）；必拍未拍双保险；照片压缩 ≤500KB。
+
+## 验收
+
+nurse01 登录 → 今日任务 → 签到勾项目拍照签退 → 留痕 submitted；异常/扑空落库；断网补传。

openspec/changes/nurse-app-flutter/proposal.md

@@ -0,0 +1,19 @@
+## Why
+
+C0–C5 已落地后端 + 机构管理后台，履约留痕的录入接口（record/abnormal/order.today）已就绪。护理员 APP（Flutter）是履约留痕的录入主战场，本期交付 PRD §四「护理员移动端 APP」全量。
+
+## What Changes
+
+- 新增 Flutter 客户端 `sources/ec_flutter`（Riverpod+dio+sqflite+go_router）。
+- 登录（租户+账号+密码）、M1 今日任务、M2 服务执行（签到→勾项目→拍照→签退）、拍照分档（必拍强制+压疮标签+拒拍出路）、异常上报（9 宫格）、扑空（未遇）、离线队列+自动补传。
+
+## Capabilities
+
+### New Capabilities
+
+- `frontend/nurse-app`: 护理员 APP——登录/今日任务/服务执行/拍照分档/异常上报/扑空/离线补传。
+
+## Impact
+
+- 新增 ec_flutter 客户端（本地 git，远程后补）。
+- 依赖：C3 的 record/abnormal/order.today 后端接口（无后端改动）。

openspec/changes/nurse-app-flutter/specs/frontend/nurse-app/spec.md

@@ -0,0 +1,54 @@
+## Purpose
+
+定义护理员 APP（Flutter）的交互与行为——登录、今日任务、服务执行、拍照分档、异常上报、扑空、离线补传。
+
+## ADDED Requirements
+
+### Requirement: 登录
+APP MUST 支持租户 code + 账号 + 密码登录，token 持久化，后续请求带 token。
+
+#### Scenario: 登录
+- **WHEN** 护理员输入租户/账号/密码登录
+- **THEN** 进入今日任务页，token 落本地
+
+### Requirement: 今日任务（M1）
+APP MUST 展示本人今日工单（老人/时段/项目/状态），点卡片进入服务执行。
+
+#### Scenario: 看今日任务
+- **WHEN** 护理员打开 APP
+- **THEN** 首屏即今日工单卡片
+
+### Requirement: 服务执行（M2）
+APP MUST 支持签到（自动定位+时间）→ 勾项目（默认全勾，exec_result 三态）→ 拍照 → 签退（自动算时长）。签到/签退时间不传客户端值（服务器取时）。
+
+#### Scenario: 签到签退
+- **WHEN** 护理员点签到再点签退
+- **THEN** 自动记录时间/定位/时长，后端生成留痕
+
+### Requirement: 拍照分档
+APP MUST 支持必拍/免拍/可拍三档；必拍项强制拍照 + 压疮结构化标签；必拍未拍签退按钮不可点；提供「无法拍摄」拒拍出路（选原因放行）。
+
+#### Scenario: 必拍强制
+- **WHEN** 必拍项未拍照
+- **THEN** 签退按钮不可点，提示「这项需要拍一张照片」
+
+### Requirement: 异常上报
+APP MUST 支持异常上报（9 宫格分类必选，描述/语音/照片可选）。
+
+#### Scenario: 分类必选
+- **WHEN** 护理员上报异常只选分类
+- **THEN** 允许提交
+
+### Requirement: 扑空（未遇）
+APP MUST 支持扑空专门形态：到访时间（自动）/定位（自动）/原因（必选），工单转 not_met。
+
+#### Scenario: 扑空留证据
+- **WHEN** 护理员登记未遇
+- **THEN** 到访时间+定位+原因必留，工单转 not_met
+
+### Requirement: 离线队列
+APP MUST 支持离线签到/签退/勾项目/照片/异常（本地队列 + client_md5），恢复联网后自动补传（幂等去重）。
+
+#### Scenario: 离线补传
+- **WHEN** 断网时签到，恢复联网
+- **THEN** 自动补传且不重复（client_md5 去重）

openspec/changes/nurse-app-flutter/tasks.md

@@ -0,0 +1,30 @@
+# Tasks — nurse-app-flutter
+
+## 1. 工程骨架
+
+- [ ] 1.1 pubspec.yaml 加依赖：riverpod/flutter_riverpod、dio、sqflite、shared_preferences、go_router、path_provider、image_picker（拍照）、geolocator（定位）、crypto（md5）。
+- [ ] 1.2 lib/core：api（dio 封装 + 统一响应解包 + token 拦截器）、db（sqflite 离线队列表）、router（go_router）、auth（token 存储）、theme。
+
+## 2. 登录
+
+- [ ] 2.1 登录页（租户/账号/密码）+ `POST /auth/login` + token 落 shared_preferences + go_router 跳今日任务。
+
+## 3. M1 今日任务 + M2 服务执行
+
+- [ ] 3.1 今日任务页：`GET /order/today` 卡片列表（老人/时段/项目/状态），点卡片进服务执行。
+- [ ] 3.2 服务执行页：签到 `POST /record/checkin`（定位 geolocator + 自动时间，不传 checkin_time）→ 项目勾选 `POST /record/item/save`（默认全勾 done，exec_result 三态）→ 拍照 `POST /record/photo/upload`（image_picker + 压缩 ≤500KB + 必拍强制 + 压疮标签 + 拒拍出路）→ 签退 `POST /record/checkout`（必拍未拍前置校验 + 3001 提示）。
+
+## 4. 异常上报 + 扑空
+
+- [ ] 4.1 异常上报：9 宫格分类（必选）+ 描述/语音/照片（可选），`POST /abnormal`。
+- [ ] 4.2 扑空：未遇按钮 → 到访时间（自动）/定位（自动）/原因（必选下拉），`POST /abnormal`（not_met）。
+
+## 5. 离线队列
+
+- [ ] 5.1 sqflite 离线队列表：签到/签退/勾项目/照片/异常本地落队 + client_md5（crypto）。
+- [ ] 5.2 联网检测 + 自动补传 `POST /record/offline/sync`（md5 去重）；照片本地暂存补传后保留 ≥7 天。
+
+## 6. 验证
+
+- [ ] 6.1 `flutter analyze` + `flutter test` 通过。
+- [ ] 6.2 用 nurse01/TY20261015 冒烟：登录 → 今日任务 → 签到勾项目拍照签退 → 留痕 submitted；异常/扑空；断网补传。