patbond-doc/docs/development/iterations/iteration-2/01-pm-task-breakdown.md

# Patbond 第二迭代任务分解（M2 宠物健康档案）

> 作者：Senior Project Manager
> 日期：2026-09-07
> 依据：`patbond-doc/docs/development/development-plan.md`（第 7 节 M2、第 6.2 节 Pets 接口、第 9/10 节质量门禁与 DoD）、`iterations/iteration-1/20-iteration-1-summary.md`（收官总结与遗留清单）、`docs/architecture/decisions.md`（ADR-001~008）、`docs/database/patbond_postgresql.sql`（`pet_health` schema 8 张表）
> 编号约定：本迭代工单以 `T2-` 前缀编号（T2-01 起），避免与第一迭代 T0-x/T1~T12 冲突。
> 范围声明：严格限定为 M2 宠物健康档案。社区（M3）、AI 创作（M4）、预约（M5）不在本迭代范围；发现范围外需求一律记入 backlog。

---

## 1. 范围界定与依据

### 1.1 开发计划 M2 原文（正典依据）

开发计划第 7 节 M2 定义（引用原文要点）：

- 目标："替换 Flutter 档案页的本地宠物和疫苗数据。"
- "实现宠物、照护权限、体重、疫苗、健康事件和提醒接口。"
- "校验当前用户对宠物的 owner/caregiver/viewer 权限。"
- "Flutter 接入真实列表、详情、编辑、加载、空态和错误态。"
- "体重、疫苗进度、下次接种和月度花费从事实表聚合生成。"
- 验收标准："数据可跨设备读取；无权限用户不能访问宠物；并发更新返回明确冲突；关键流程具备 API 集成测试和 Flutter 组件测试。"

第 6.2 节第一批接口中属于本迭代的端点：

| 端点 | 用途 |
| --- | --- |
| `GET/POST /api/v1/pets` | 查询、新建宠物 |
| `GET/PATCH /api/v1/pets/{petId}` | 宠物详情与更新 |
| `GET/POST /api/v1/pets/{petId}/weights` | 体重记录 |
| `GET/POST/PATCH /api/v1/pets/{petId}/vaccinations` | 疫苗记录 |
| `GET/POST /api/v1/pets/{petId}/health-events` | 健康时间线 |

数据模型依据：`pet_health` schema 共 8 张表（breeds、pets、pet_owners、pet_weight_records、vaccine_catalog、pet_vaccinations、health_events、health_event_media、care_reminders——含关联表 9 个对象），字段、约束、状态机均已在 bootstrap SQL 定稿评审。

### 1.2 与第一迭代总结口径的差异（须拍板，见 §4）

第一迭代总结把 M2 目标写为"档案 CRUD、照片管理、体重/**体温**记录、疫苗/驱虫提醒"，与开发计划 M2 原文存在三处扩张，PM 逐条对照数据模型后的结论：

1. **照片管理**：`pets.avatar_asset_id`、`pet_vaccinations.certificate_asset_id`、`health_event_media` 均引用 `media.assets`，但媒体上传流程（M1 后半段的 `POST /api/v1/media/uploads`）第一迭代未实现，且**对象存储供应商至今未拍板**（第一迭代决策清单 D4 遗留）。照片管理不是 M2 原文要求，纳入与否见决策 D2-1。
2. **体温记录**：`pet_health` schema **没有体温表**。最接近的承载是 `health_events` 的 `measurement` 事件类型。是否需要结构化体温数据见决策 D2-4，本拆解默认不建新表。
3. **驱虫提醒**：数据模型已支持（`health_events.event_type='deworming'` + `care_reminders.reminder_type='deworming'`），属 M2 原文"提醒接口"范围内，纳入。

### 1.3 本迭代 MVP 范围（PM 建议口径，待 §4 拍板确认）

- **纳入**：宠物 CRUD（含品种目录）、pet_owners 权限校验框架、体重记录、疫苗记录（含疫苗目录、系列/剂次、scheduled→completed 状态机）、健康事件时间线、照护提醒（app 内列表，无推送）、四项聚合（最新体重、疫苗进度、下次接种、月度花费）、Flutter 档案页全量替换真实数据、两项高优先遗留埋点。
- **默认剪出（待拍板）**：照片/媒体上传、体温专表、共同照护人邀请流程（权限**校验**必须实现，邀请**交互**可后置）、提醒推送通知（通知系统属 M6）。

---

## 2. 工单列表

预估规模口径沿用第一迭代：S ≈ 半天内，M ≈ 1-2 天，L ≈ 3-5 天（含测试与文档）。

### A 组：数据与工程基础（后端）

#### T2-01 Flyway V3：pet_health schema baseline 与种子数据分离
- **仓库**：patbond-api（迁移脚本），patbond-doc（迁移说明）
- **描述**：从 bootstrap SQL 提取 `pet_health` 全部表结构为 Flyway V3 迁移；breeds、vaccine_catalog 的开发种子数据独立为不进生产的脚本（沿用第一迭代 identity/media 的做法）。
- **关键技术裁剪（必须遵守）**：bootstrap SQL 第 1156~1166 行为 `pet_vaccinations`/`health_events` 的 `provider_id`、`booking_id` 增加了指向 `marketplace.providers`/`marketplace.bookings` 的外键。marketplace schema 属 M5，本迭代**不迁移**，V3 必须**剥离这四条跨 schema 外键**（字段保留为裸 uuid 可空列），M5 迁移 marketplace 时再以新版本迁移补回。同理 `updated_at` 触发器依赖的公共函数需确认已在 V1 建立或随 V3 建立。
- **验收标准**：
  - 全新 postgres:18（Testcontainers）上 V1→V2→V3 全量迁移一次成功，表结构与 bootstrap SQL 一致（跨 schema 外键除外，差异写入迁移说明）。
  - 种子数据脚本与结构迁移分离，不进正式环境。
  - `./mvnw clean test` 全绿（既有 82 测试不回归）。
- **依赖**：无（第一波首项）。
- **规模**：M

#### T2-02 宠物健康后端模块骨架与鉴权接入
- **仓库**：patbond-api
- **描述**：按开发计划 4.1 节"按迭代增加宠物健康模块；模块边界与数据库 schema 对齐"，建立宠物健康业务模块（新建 Maven 模块 vs 并入现有服务见决策 D2-2，未拍板前先按 PM 建议方案搭骨架）；复用第一迭代 JWT 资源侧校验，实现"当前用户"解析注入；模块只读写 `pet_health` schema。
- **验收标准**：
  - 模块编译入构建链，`./mvnw clean test` 全绿。
  - 携带有效 access token 的请求能解析出当前用户 UUID；无 token / 过期 token 返回 401 + 既有错误码契约（40100 系）。
  - Docker Compose 编排同步纳入新模块（若 D2-2 选独立服务）。
- **依赖**：D2-2 拍板（可先按建议方案开工，方案变更成本在骨架期最低）。
- **规模**：M

### B 组：后端接口纵切

#### T2-03 宠物 CRUD 与 pet_owners 权限框架
- **仓库**：patbond-api
- **描述**：实现 `GET/POST /api/v1/pets`、`GET/PATCH /api/v1/pets/{petId}` 与品种目录查询（breeds 只读列表，按 species 过滤）。创建宠物时当前用户自动成为 `pet_owners` 的 primary owner；所有 `/pets/**` 请求经统一权限校验（owner/caregiver 可写、viewer 只读、无关系 404/403，语义在契约中定死）；`PATCH` 使用 `version` 乐观锁，冲突返回明确错误码；`status` 流转（active/archived 等）按数据库约束实现；软删除语义遵守 `ck_pets_deleted` 约束。
- **验收标准**：
  - 创建→列表→详情→更新→归档全链路走真实 PostgreSQL，重启不丢数据。
  - 无权限用户访问他人宠物被拒绝（错误码与 HTTP 状态码在契约定死并有测试）。
  - 并发更新（version 过期）返回明确冲突错误，有集成测试。
  - breed_id 与 custom_breed_name 互斥校验（`ck_pets_breed`）应用层与数据库一致。
- **依赖**：T2-01、T2-02。
- **规模**：L

#### T2-04 体重记录接口
- **仓库**：patbond-api
- **描述**：`GET/POST /api/v1/pets/{petId}/weights`。列表 cursor 分页（`measured_at DESC, id DESC`，与既有索引对齐）；创建校验 `weight_kg` 区间（>0 且 ≤500）；写接口支持 `Idempotency-Key`（第 6.1 节要求）。
- **验收标准**：
  - 分页不丢失不重复；参数越界返回规范错误体。
  - 相同 Idempotency-Key 重试不产生重复记录，有测试。
  - 权限校验复用 T2-03 框架（viewer 只读）。
- **依赖**：T2-03。
- **规模**：M

#### T2-05 疫苗目录与疫苗记录接口
- **仓库**：patbond-api
- **描述**：vaccine_catalog 只读查询（按 species）；`GET/POST/PATCH /api/v1/pets/{petId}/vaccinations`：series_key + dose_no 唯一性（非 cancelled）、scheduled/completed/cancelled 状态机及日期约束（`ck_vaccination_dates`）、`next_due_on` 维护、`version` 乐观锁。`certificate_asset_id`、`provider_id`、`booking_id` 本迭代不开放写入（照片待 D2-1、预约属 M5），字段在契约中不出现或标记只读。
- **验收标准**：
  - 状态机非法迁移被拒绝并返回稳定错误码；同系列同剂次重复登记返回冲突。
  - completed 必须带 administered_on、scheduled 必须带 planned_on（与数据库约束一致，应用层先行校验）。
  - 集成测试覆盖成功、参数错误、不存在、无权限、并发冲突、幂等重试六类路径（第 9 节要求）。
- **依赖**：T2-03。
- **规模**：L

#### T2-06 健康事件时间线接口
- **仓库**：patbond-api
- **描述**：`GET/POST /api/v1/pets/{petId}/health-events`，建议补 `PATCH /api/v1/health-events/{eventId}`（编辑标题/备注/金额，乐观锁）。六类事件类型（medical/feeding/deworming/grooming/measurement/note）；`amount_cents` 整数分（第 4.3 节）；`occurred_at DESC` cursor 分页；`created_by_user_id` 记录操作者。`health_event_media` 本迭代不实现（随 D2-1）。
- **验收标准**：
  - 时间线分页正确；金额只收整数分且非负。
  - 事件类型白名单校验与数据库约束一致。
  - 六类测试路径覆盖同 T2-05。
- **依赖**：T2-03。
- **规模**：M

#### T2-07 照护提醒接口
- **仓库**：patbond-api
- **描述**：care_reminders 的列表/创建/状态流转（pending→completed/dismissed，completed 必须写 completed_at，与 `ck_care_reminder_completed` 一致）。四类提醒类型（deworming/checkup/medication/other）。**仅 app 内数据接口，不做推送**（通知系统属 M6，见决策 D2-5）。
- **验收标准**：
  - 提醒可创建、按 due_at 查询待办、标记完成/忽略；状态与 completed_at 一致性有测试。
  - 权限校验复用 T2-03 框架。
- **依赖**：T2-03。
- **规模**：M

#### T2-08 档案聚合摘要接口
- **仓库**：patbond-api
- **描述**：实现档案页摘要所需聚合（建议 `GET /api/v1/pets/{petId}/summary`）：最新体重、疫苗进度（completed 剂次/总剂次）、下次接种（scheduled 中最近 planned_on 或最近 next_due_on）、当月花费（health_events.amount_cents 按月求和）。全部从事实表实时聚合，**不持久化展示字符串**（第 4.3 节红线）；聚合口径逐项写入契约描述。
- **验收标准**：
  - 各聚合值有集成测试锁定口径（含空数据、跨月边界、cancelled 疫苗不计入）。
  - 时间按 `timestamptz` 存储、ISO 8601 传输，月度边界按客户端传入时区或明确定义的服务端口径（写入契约，避免歧义）。
- **依赖**：T2-04、T2-05、T2-06。
- **规模**：M

### C 组：契约与测试

#### T2-09 OpenAPI 契约扩展与冻结
- **仓库**：patbond-doc（`docs/api/openapi.yaml`），patbond-api（契约测试保证一致）
- **描述**：在既有 5 端点契约上扩展 pets 域全部端点（宠物、品种、体重、疫苗、目录、事件、提醒、摘要）。沿用既定规范：`/api/v1` 前缀、camelCase、UUID 字符串、统一信封、稳定业务错误码（pets 域新错误码段与 401/403/404/409 语义定死）、cursor 分页参数形态、`Idempotency-Key`、`version` 字段。**起草与 T2-03~05 并行，冻结须在 T2-03 权限/错误语义与 T2-08 聚合字段定型之后**——冻结是第三波前端联调的放行闸门（沿用第一迭代验证过的模式）。
- **验收标准**：
  - 契约文件评审通过；契约测试在 CI 中验证实际响应与文档一致。
  - `mkdocs build --strict` 通过（契约文件更新不涉及导航变更）。
  - 冻结后任何字段变更须显著上报，两端同步修改。
- **依赖**：T2-03（错误/权限语义）、T2-08（聚合字段）；起草仅依赖 §1.1 端点表。
- **规模**：M

#### T2-10 后端集成测试滚动补齐与 CI
- **仓库**：patbond-api
- **描述**：随 B 组各工单滚动补齐 Testcontainers（postgres:18）集成测试，交付前每单必须全绿（沿用第一迭代"每波 `./mvnw clean test` 必绿"纪律）；V3 迁移在全新实例执行一次的校验并入 CI。本单为横切验收单，不单独排人。
- **验收标准**：
  - 每个业务接口覆盖成功、参数错误、资源不存在、无权限、并发冲突、幂等重试（第 9 节六类）。
  - **caregiver/viewer 权限路径必须有测试覆盖**：邀请流程若按 D2-3 后置，则用测试数据直接写 pet_owners 构造三种角色场景，避免"权限代码存在但从未被验证"。
  - Gitea Actions ci.yml 全绿；CI 时长若超 10 分钟记录并评估分层。
- **依赖**：随 T2-03~T2-08 滚动。
- **规模**：M（分摊在各单内）

### D 组：Flutter 客户端

#### T2-11 pets feature 状态拆分与 API Client
- **仓库**：patbond-flutter
- **描述**：按开发计划 4.2 节把宠物档案状态从 `AppState` 拆出独立 pets feature（Controller → Repository → API Client 分层，对齐第一迭代 auth feature 的既有结构）；依据 T2-09 冻结契约实现 DTO 与 Client（宠物、品种、体重、疫苗、事件、提醒、摘要），统一错误码解析复用既有网络层与 token 拦截。
- **验收标准**：
  - DTO 映射有单元测试；错误响应映射为类型化错误。
  - 不再从 `AppState` 读写宠物/疫苗 demo 数据（体重、疫苗进度等展示字符串全部改为由服务端事实字段计算）。
- **依赖**：T2-09 冻结。UI 无关的分层骨架可提前与后端并行。
- **规模**：M

#### T2-12 宠物列表、详情与编辑页接入真实数据
- **仓库**：patbond-flutter
- **描述**：档案页（`lib/features/pets/pets_page.dart`）替换为真实列表/详情/创建/编辑：品种选择（目录接口 + 自定义品种互斥）、性别/生日/芯片号等字段对齐数据模型；**所有网络页面覆盖 loading、empty、error、retry 四态**（第 9 节硬要求）；编辑冲突（409）给出明确的用户提示与刷新路径。头像照片按 D2-1 裁决处理（默认保留本地占位图，不做上传）。
- **验收标准**：
  - 新用户空态 → 建档 → 列表/详情展示全链路走真实后端。
  - 四态齐备并有 widget 测试；乐观锁冲突提示有测试。
- **依赖**：T2-11；UI 稿可在第一波先行出设计（含四态与空态）。
- **规模**：L

#### T2-13 体重与疫苗模块接入
- **仓库**：patbond-flutter
- **描述**：体重录入与历史列表（分页加载）；疫苗登记（选目录、系列/剂次、计划/完成状态）、疫苗进度与"下一针"改从 T2-08 摘要接口取数（替换 demo 的 `vaccines.reminderVaccine` 等本地字符串）。
- **验收标准**：
  - 体重与疫苗数据在另一登录设备（或清空本地数据重登）可见——对应 M2"跨设备读取"验收。
  - 疫苗状态机操作的非法路径（如未填接种日期就标完成）被前端拦截且后端兜底。
  - 相关 widget/单元测试补齐。
- **依赖**：T2-11、T2-12。
- **规模**：L

#### T2-14 健康时间线与提醒页接入
- **仓库**：patbond-flutter
- **描述**：健康事件时间线（六类事件、金额录入以元展示/整数分传输、分页）；照护提醒列表与完成/忽略操作；档案页"月度花费"改从摘要接口取数。demo 中硬编码的"健康提醒：已经半年没有进行体内外驱虫"改为真实提醒数据驱动。
- **验收标准**：
  - 时间线与提醒四态齐备；金额展示与传输换算有单元测试。
  - 无提醒/无事件时空态正确。
- **依赖**：T2-11、T2-12。
- **规模**：M

### E 组：遗留项与收口

#### T2-15 遗留埋点：sessionId 生命周期（高优先，第一波插入）
- **仓库**：patbond-flutter
- **描述**：第一迭代遗留 §1：引入 `WidgetsBindingObserver` 监听 app 前后台切换，定义会话超时与 sessionId 重建规则，修复"sessionId 只在退出时清空"的缺陷。
- **验收标准**：进后台超时回前台生成新 sessionId；规则有单元测试；不依赖 M2 契约，可与后端第一波并行。
- **依赖**：无。
- **规模**：S

#### T2-16 遗留埋点：page_viewed 路由埋点（高优先，第一波插入）
- **仓库**：patbond-flutter
- **描述**：第一迭代遗留 §2：接入 `RouteObserver` 挂接 `page_viewed` 事件（事件定义沿用报告 13 规范）。
- **验收标准**：主要页面路由切换产生 page_viewed 事件并能落库（复用既有 /api/v1/events 链路）；有测试。
- **依赖**：无。
- **规模**：S

#### T2-17 埋点：health_record_action 挂接与 M2 事件
- **仓库**：patbond-flutter（挂接），patbond-doc（事件表更新）
- **描述**：第一迭代预留的 `health_record_action` 挂接点在 M2 档案功能落地后接通（建档、体重录入、疫苗登记、事件记录等动作）；后端事件白名单同步扩充。埋点不得含健康敏感明文（沿用隐私红线）。
- **验收标准**：关键健康操作产生事件并落库；白名单与文档同步；有测试。
- **依赖**：T2-12~T2-14（随页面落地滚动挂接）。
- **规模**：S

#### T2-18 E2E 烟囱测试与真机联调收官
- **仓库**：patbond-flutter（用例），patbond-api（compose 环境），patbond-doc（证据归档）
- **描述**：沿用第一迭代收官战模式：compose 起后端 → 真实链路烟囱：登录 → 建档 → 记体重 → 登记疫苗 → 记健康事件 → 摘要数值核对 → 第二账号访问该宠物被拒 → 第二设备（或重装态）同账号读到全部数据。收集 HTTP transcript（脱敏）、数据库查询证据、门禁输出。
- **验收标准**：烟囱场景全绿；契约偏差 0 个；M2 四条验收标准（跨设备、无权限拒绝、并发冲突明确、双端测试齐备）逐条有证据。
- **依赖**：T2-05、T2-08、T2-13、T2-14。
- **规模**：M

#### T2-19 文档与迭代收口
- **仓库**：patbond-doc
- **描述**：OpenAPI 定稿归档、feature-checklist 增补 M2 条目、迭代报告归档、任务板更新与收官总结。iteration-2 报告目录的 `mkdocs.yml` 导航条目由文档维护者在收口提交时统一添加（本拆解报告本身不改 mkdocs.yml）。
- **验收标准**：`mkdocs build --strict` 通过；报告索引完整可还原全貌。
- **依赖**：各波交付。
- **规模**：S

---

## 3. 波次划分与关键路径

沿用第一迭代验证过的"波次并行 + 契约冻结先行"模式。

### 第一波（并行开工，无互锁）

| 并行线 | 工单 | 说明 |
| --- | --- | --- |
| 后端数据基础 | T2-01 → T2-02 | 关键路径起点，一人连续负责 |
| 契约起草 | T2-09（起草态） | 按 §1.1 端点表 + 数据模型先出草案，随 T2-03 收敛 |
| 前端遗留埋点 | T2-15、T2-16 | 与 M2 契约零耦合，第一波消化掉两项高优先遗留 |
| UI 设计 | 档案页/四态/空态设计稿（供 T2-12） | 不占关键路径 |

### 第二波（后端纵切，契约收敛）

| 并行线 | 工单 | 说明 |
| --- | --- | --- |
| 后端主线 | T2-03 → T2-04/T2-05/T2-06/T2-07（03 后三线可并行）→ T2-08 | T2-03 权限框架是全部业务单的前置 |
| 前端骨架 | T2-11 的分层骨架（不依赖契约的部分） | Repository/状态骨架先行 |
| 测试滚动 | T2-10 | 随各单交付即测即绿即提交 |

**波末闸门：T2-09 契约冻结**（条件：T2-03 权限/错误语义定型 + T2-08 聚合字段定型）。不冻结不放行第三波前端联调，偏差须显著上报。

### 第三波（冻结契约下两端并行）

| 并行线 | 工单 | 说明 |
| --- | --- | --- |
| 前端主线 | T2-11（完成）→ T2-12 → T2-13 / T2-14 | 12 完成后 13、14 可两人并行 |
| 后端旁路 | 契约测试补齐、种子数据完善、性能核对 | 不占关键路径 |
| 埋点 | T2-17 | 随页面落地滚动挂接 |

### 第四波（收官）

T2-18 E2E 烟囱 → T2-19 文档收口 → 任务板更新与验收报告。

### 关键路径

```text
T2-01 → T2-02 → T2-03(L) → T2-05(L) → T2-08 → [T2-09 冻结] → T2-11 → T2-12(L) → T2-13(L) → T2-18
```

四个 L 工单串在关键路径上，是周期决定因素。压缩手段：T2-09 草案与 T2-11 骨架前移（已排入一、二波）；T2-04/06/07 走旁路不占主线；T2-12 的 UI 稿第一波先行。

---

## 4. 需要用户拍板的决策清单

以下决策 PM 只给建议，**不替用户拍板**。D2-1~D2-3 直接影响工单定稿，建议开工前优先裁决。

| # | 决策事项 | 影响 | PM 建议（仅供参考） |
| --- | --- | --- | --- |
| D2-1 | **照片/媒体是否纳入 M2**：宠物头像上传、疫苗证书、健康事件附件均依赖媒体上传流程（M1 遗留未做）与对象存储供应商（第一迭代 D4 至今未定） | 阻塞 T2-12 头像、T2-05 证书字段、health_event_media；若纳入需增补媒体上传专项工单（约 +1 L） | M2 首版**不含**照片上传，档案先跑通结构化数据；对象存储选型（建议 S3 兼容，如自建 MinIO 起步）拍板后以独立专项插入 M2 末波或 M3 |
| D2-2 | **后端模块归属**：新建独立宠物健康服务（对齐"模块边界与 schema 对齐"+ 独立部署）vs 作为模块并入 patbond-user 进程（降低双人团队运维面） | 决定 T2-02 骨架形态、compose 编排、CI 构建时长 | 新建 Maven 模块 `patbond-pet`（独立数据所有权），**部署形态倾向与 user 同进程或同 compose 独立容器均可接受**，请结合第一迭代 D2（单体 vs 多服务）一并裁决 |
| D2-3 | **共同照护人邀请流程是否入 M2**：pet_owners 支持 owner/caregiver/viewer，但"邀请另一个用户"需要检索用户、发出/接受邀请等交互 | 决定 T2-03 是否扩为含邀请端点（约 +1 M）与前端邀请页 | M2 只做"创建者即 primary owner"+ 完整权限**校验**框架（测试数据覆盖三角色），邀请**交互**后置 M3+；这样 M2 验收标准"无权限用户不能访问"仍可完整验证 |
| D2-4 | **体温记录**：迭代一总结提及，但数据模型无体温表 | 若要结构化体温需新表与新迁移（超出已评审模型） | 用 `health_events` 的 `measurement` 类型承载文字化记录，不建新表；若产品明确要体温曲线图，另立数据模型变更提案再排期 |
| D2-5 | **提醒的通知形态**：care_reminders 首版是否仅 app 内列表（无系统推送/本地通知） | 推送涉及通知渠道选型（platform.notifications 属 M6） | 首版仅 app 内列表 + 到期排序展示；推送后置 M6 |
| D2-6 | **breeds / vaccine_catalog 目录数据来源**：开发种子够用，但正式目录（犬猫品种表、疫苗名录）内容与量级谁提供、何时定稿 | 不阻塞开发（seed 兜底），影响上线数据质量 | 开发期用 seed（每 species 各 10~20 条常见项）；正式目录数据作为独立内容任务由产品侧供稿 |
| D2-7 | **宠物删除语义**：前端提供什么入口——归档（archived）/ 软删除（deleted）/ 不提供 | 影响 T2-03 状态流转范围与 T2-12 交互 | 首版仅提供"归档"，软删除接口保留但前端不出入口，避免误删争议 |
| D2-8 | **中优先遗留是否纳入 M2**：access token 黑名单、/internal 改 mTLS、auth_sessions 清理调优、埋点完善其余项（队列持久化等） | 纳入则挤占 M2 周期 | **不纳入**，维持技术债清单，M3 或加固阶段统一处理（TagPill 设计债同此） |

---

## 5. 遗留项插入位置汇总

| 遗留项（第一迭代总结编号） | 优先级 | 插入位置 |
| --- | --- | --- |
| 埋点 sessionId 生命周期（§1） | 高 | **T2-15，第一波**，独立工单 |
| page_viewed 路由埋点（§2） | 高 | **T2-16，第一波**，独立工单 |
| health_record_action 挂接（§7 之一） | 中（M2 天然落点） | **T2-17，第三波**随页面滚动挂接 |
| access token 黑名单（§4） | 中 | 不入 M2（待 D2-8 确认），技术债清单 |
| /internal 改 mTLS（§5） | 中 | 不入 M2（待 D2-8 确认），需先补 ADR |
| auth_sessions 清理调优（§6） | 中 | 不入 M2，性能阶段处理 |
| 埋点完善其余 4 项（§7） | 中 | 不入 M2；后端事件查询端点若 T2-17 验证需要可顺手做，超出即止 |
| TagPill 对比度设计债（§8） | 低 | 不入 M2，设计系统升级时统一处理 |

---

## 6. 风险清单

| # | 风险 | 影响 | 缓解措施 |
| --- | --- | --- | --- |
| R1 | **未提交/未推送风险**（第一迭代 R3 教训：两天工作量曾只存在于工作区） | 误操作全损；协作与 CI 失效 | 沿用已验证纪律：**每波每单交付即提交即推送**；PM 任务板每波核对三仓 `git status`。开工时基线：三仓工作区干净、与远端同步（2026-09-07 已核实） |
| R2 | **契约偏差风险**：pets 域端点数量约为第一迭代 4 倍，聚合字段口径（月度边界、进度分母）最易两端理解不一 | 联调返工 | 冻结闸门制度不放松；聚合口径在契约中逐字段写清（含时区口径）；偏差显著上报，禁止任一端私改 |
| R3 | **V3 迁移照抄 bootstrap SQL 的跨 schema 外键**（第 1156~1166 行引用 marketplace） | 迁移在干净库直接失败，或被迫提前迁移 marketplace | 已写入 T2-01 描述为强制裁剪项；迁移说明记录差异与 M5 补回计划；Testcontainers 全新库验证兜底 |
| R4 | **对象存储未定拖累范围**：若 D2-1 拍板"要照片"而供应商未定 | T2-12/T2-05 范围反复 | 决策清单置顶 D2-1；默认口径按"不含照片"排期，拍板含照片则显式加 1 个 L 工单并顺延 |
| R5 | **权限路径测试盲区**：邀请流程后置时，caregiver/viewer 无自然产生入口 | "权限代码存在但从未验证"，M2 验收标准落空 | T2-10 明确要求用测试数据直接构造三角色场景；E2E（T2-18）含第二账号拒绝场景 |
| R6 | **范围膨胀**：迭代一总结口径（照片/体温）比开发计划 M2 原文宽 | 周期失控、返工 | 本报告 §1.2 已逐条对照数据模型澄清；一切扩张走 §4 拍板，未拍板按 PM 建议默认剪出 |
| R7 | **CI 时长增长**：测试数将从 82 大幅增加，Testcontainers 全跑 | CI 反馈变慢、门禁被绕过 | T2-10 记录每波 CI 时长，超 10 分钟评估按模块分层执行；不降低"提交前全绿"标准 |
| R8 | **单接口面过宽的估算风险**：疫苗状态机 + 系列/剂次约束复杂度接近第一迭代 JWT 会话单 | T2-05 拖关键路径 | T2-05 已按 L 估算并置于关键路径显式管理；catalog 只读部分可先行拆出交付 |
| R9 | **文档导航遗漏**：iteration-2 目录需入 mkdocs 导航，但本迭代规则限制随手改 mkdocs.yml | `mkdocs build --strict` 门禁或导航缺失 | 归入 T2-19 由文档维护者收口提交时统一处理，收口清单显式含此项 |

---

## 7. 质量要求（对全部工单生效）

- 遵守开发计划第 10 节 DoD：不依赖 Demo 常量；权限、校验、幂等、并发已处理；文档同步更新；干净环境可复现。
- 沿用既定契约规范：camelCase、UUID 字符串、ISO 8601 + timestamptz、金额整数分、统一信封与稳定错误码、cursor 分页、Idempotency-Key、version 乐观锁。
- 不提交任何密码、token、密钥；日志与埋点不含健康敏感明文与手机号全文。
- 自动化测试一律 Testcontainers postgres:18（ADR-006/008）；每单交付 `./mvnw clean test` / `flutter analyze` + `flutter test` 全绿。
- 所有网络页面四态（loading/empty/error/retry）齐备。
- 本迭代不实现社区、AI、预约的任何接口或页面；范围外需求记 backlog。

## 8. 工单统计

- 工单总数：**19**（数据与工程基础 2 + 后端接口 6 + 契约与测试 2 + Flutter 4 + 遗留与收口 5）
- 规模分布：S × 5、M × 10、L × 4
- 关键路径长度：9 个工单（T2-01 → T2-02 → T2-03 → T2-05 → T2-08 → 冻结 → T2-11 → T2-12 → T2-13 → T2-18），其中 L × 4
- 待拍板决策：**8 项**（D2-1~D2-8，前三项建议开工前裁决）