diff --git a/docs/development/feature-checklist.md b/docs/development/feature-checklist.md index 4f9b678..8d3132b 100644 --- a/docs/development/feature-checklist.md +++ b/docs/development/feature-checklist.md @@ -1,8 +1,8 @@ -# 功能完成清单（第一迭代） +# 功能完成清单 > 目的：直观呈现哪些功能**已完成且有自动化测试**、哪些**部分完成**、哪些**尚未开始**，方便针对性验证与回归。 > 维护约定：每波工单合入后由执行人更新本清单；状态以 `dev` 分支 + 门禁全绿为准。 -> 最后更新：2026-09-04（第三波两端合龙 + 工程化补波：patbond-api `6528a06` 75 测试、patbond-flutter `da25804` 30 测试，均门禁全绿；compose 编排冒烟实测通过） +> 最后更新：2026-09-08（M2 第三波收口：patbond-api `64c9b72` 191 测试、patbond-flutter `ba50332` 272 测试，均门禁全绿；三次 compose 实测无契约偏差；M2 条目见第 7~9 节） 图例：✅ 已完成且已测试 ｜ 🟡 部分完成/有已知限制 ｜ ⬜ 未开始 @@ -120,3 +120,54 @@ curl -s -X POST http://127.0.0.1:8081/api/v1/auth/logout \ # /internal 无凭证应 401 curl -s -i http://127.0.0.1:8082/internal/users/by-username/demo_user | head -1 ``` + +--- + +# M2 宠物健康档案（第二迭代） + +## 7. 宠物域后端（patbond-pet，:8083） + +| 功能 | 状态 | 自动化测试 | 说明 | +| --- | --- | --- | --- | +| Flyway V3 pet_health 8 表 + V4 字典种子（28 品种/10 疫苗） | ✅ | 迁移验证 8 例（干净 postgres:18 全量 V1..V4） | 4 条 marketplace 跨 schema FK 剥离标注 M5 补回，有测试断言 FK 不存在 | +| patbond-pet 独立模块（ADR-009）挂 pom + compose | ✅ | 骨架测试 + compose 实测 | /health 探活；迁移链仍归 patbond-user 单链 | +| 宠物 CRUD + breeds 目录（T2-03） | ✅ | 23 例（六类路径 + 三角色矩阵） | 创建者自动 primary owner；PATCH version 乐观锁 40902；芯片号唯一 40903 | +| `PetAccessService` 三档权限闸口（READ/WRITE/MANAGE，ADR-015） | ✅ | 三角色矩阵 + caregiver 写正向用例 | 防枚举：无关系/不存在/已软删一律 404/40401 响应逐字一致（有测试断言） | +| 体重记录 + cursor 分页（T2-04） | ✅ | 8 例（分页不丢不重/同刻跨页专项） | `{items,nextCursor,hasMore}` 信封为全 API 分页正典；weight_kg (0,500] | +| 疫苗目录 + 疫苗记录 + 状态机（T2-05） | ✅ | 12 例 | scheduled→completed/cancelled；剂次唯一 40904；规则违反 42201；cancel 释放占位可重建 | +| 健康事件六类 + 时间线分页 + 顶层 PATCH（T2-06） | ✅ | 11 例 | amountCents 整数分非负；禁 float 静默截断；记录级防枚举 40402 | +| 照护提醒四类 + 状态流转（T2-07） | ✅ | 10 例 | pending→completed/dismissed；completed 必带 completedAt（42202）；仅数据接口不推送 | +| 档案摘要四聚合（T2-08） | ✅ | 12 例（空数据/双时区跨月/cancelled 不计/多宠隔离/零写入红线） | 实时聚合不持久化展示串；tz 参数（IANA）缺省 UTC；无记录 null 语义 | +| 写接口幂等（Idempotency-Key 可选头，四个 POST） | ✅ | 幂等重试用例 | 键派生确定性主键 + ON CONFLICT，零迁移 | +| 契约一致性测试（v1.2.0 字节级快照） | ✅ | 全响应矩阵 + mutation 自证 + 版本守卫 | 契约未声明字段即报漂移；升版须同步快照否则 CI 红；已抓修 1 项漂移（sex 必填） | +| 照片/附件（头像、疫苗证书、事件附件） | ⬜ | — | ADR-010 剪出 M2，待对象存储选型；health_event_media 表未建（纯增量后补零成本） | +| 照护人邀请/绑定流程 | ⬜ | — | ADR-015 后置；权限校验已用测试数据覆盖三角色 | +| auth 域契约测试补齐 | ⬜ | — | 机制可直接复用（报告 20 §建议），另立工单 | + +## 8. 宠物域客户端（patbond-flutter） + +| 功能 | 状态 | 说明 | +| --- | --- | --- | +| pets 数据层（契约 18 操作 DTO/Client/Repository 全覆盖，T2-11） | ✅ | 8 新错误码类型化异常；三服务分端口直连共享 TokenRefresher 单飞；DTO 映射 62 例测试 | +| 宠物列表/详情/建档/编辑页真实数据（T2-12） | ✅ | 四态齐备有 widget 测试；40902 自动取新 version 重提；40903 字段级报错；品种目录 + 自定义互斥；demo 数据消亡 | +| 体重录入 + 历史列表（cursor 分页，T2-13） | ✅ | 契约区间前端校验 + 后端兜底；加载更多/翻页失败保留重试 | +| 疫苗登记/列表 + 完成/取消流转 + 厂商批号补录（T2-13/14） | ✅ | 状态-日期规则双重前端拦截 + 42201/40904 兜底；按系列分组三态 TagPill | +| 摘要接数（最新体重/疫苗进度/下一针/月度花费）替换 demo 展示串 | ✅ | null → 空态而非 0/0（测试锁定）；月度花费透传设备时区 tz | +| 健康事件时间线（六类、按月分组、元/分换算）+ 录入/编辑（T2-14） | ✅ | 金额换算单测锁定；40902 自动重提 | +| 照护提醒列表/创建/完成/忽略（T2-14） | ✅ | 逾期红标双通道；档案页「健康提醒」卡真实数据驱动（demo 硬编码移除） | +| 跨设备读取验收（M2 验收标准） | ✅ | compose 实测：同账号新会话全量可见；第二账号四路访问均 40401 | +| DEBT-1 TagPill 对比度债偿还（ADR-014） | ✅ | 深变体映射四组全达 WCAG AA；既有调用零参数回归 | +| 单宠直进/切换器、归档入口、sterilizedOn 编辑 | 🟡 | 三项交互细节待拍板（报告 23 §8） | + +## 9. 埋点体系（M2 演进） + +| 功能 | 状态 | 说明 | +| --- | --- | --- | +| M1 遗留清偿：生产接线/eventId v7/SessionTracker/page_viewed | ✅ | 第一波交付（报告 10，12/12 验收）；生产事件流自 M1 以来首次非零 | +| events 契约补录（v1.1.0）+ 上传端口纠正 + 毒丸批次防护 | ✅ | 4xx 永久拒绝不重试；离开前台冲刷（低活跃用户事件不再滞留） | +| 分段持久化队列（shared_preferences，500 条 at-least-once） | ✅ | 冷启动恢复离线积压；损坏段容错；按段拼批 ≤50 | +| 事件字典 v2 白名单（pet 域 3 + health_record 域 7） | ✅ | 后端白名单 + 边界测试（api@64c9b72）；page_viewed 正稿核对零修正 | +| 客户端挂接：pet 域 3 事件 + health_record 域 6 事件 + pet_form 等页名 | ✅ | 强类型封装（pet_analytics/health_record_analytics）；deleted 留待删除端点 | +| Android 真机落库验证 + SessionTracker 30min 手测 | 🟡 | 桌面端全链路已通（platform 枚举拒绝属契约内）；真机验证按方案 A 挂起待设备 | +| 队列完善：30s 定时冲刷、退避/429、anonymousId 持久化 | ⬜ | 报告 15 §4 遗留；429 依赖后端限流实现（报告 09 出入清单） | + diff --git a/docs/development/iterations/iteration-2/index.md b/docs/development/iterations/iteration-2/index.md new file mode 100644 index 0000000..9450089 --- /dev/null +++ b/docs/development/iterations/iteration-2/index.md @@ -0,0 +1,56 @@ +# 第二迭代进展看板 + +> 目标：M2 宠物健康档案——宠物 CRUD + owner/caregiver/viewer 权限 + 体重/疫苗/健康事件/提醒 + 档案聚合，Flutter 档案页全量替换 demo 数据，依据[开发实施计划](../../development-plan.md)第 7 节。 +> 更新日期：2026-09-08（第三波收口，待第四波 E2E 收官）。本页是团队共享的进度事实来源，每波工作交付后更新。 + +## 当前状态一览 + +| 状态 | 内容 | +| --- | --- | +| ✅ 第一波 | M1 遗留埋点清偿（接线/SessionTracker/page_viewed/持久化队列前置）+ 契约补录 events + Flyway V3/V4 + patbond-pet 骨架 | +| ✅ 第二波 | 后端接口纵切 T2-03~08（pets 域 18 操作）+ 契约冻结 v1.2.0 + 契约一致性测试入 CI | +| ✅ 第三波 | Flutter 页面接入 T2-11~14（档案 demo 数据消亡、四态齐备）+ 埋点字典 v2 端到端 + DEBT-1 偿还 | +| 🔜 第四波 | T2-18 E2E 烟囱收官战（需真机/联调配合）→ T2-19 收官总结 | +| ⚠️ 遗留 | 真机补验（Android 事件落库 + SessionTracker 30min，第一波方案 A 挂起）；T2-12 §8 三项交互待拍板；auth 域契约测试；埋点队列完善（30s 定时冲刷/退避/anonymousId 持久化） | + +## 测试与契约演进 + +| 时点 | patbond-api | patbond-flutter | openapi.yaml | +| --- | --- | --- | --- | +| M2 开工基线 | 82 | 34 | v1.0.0（5 路径） | +| 第一波收口 | 95 | 51 | v1.1.0（+events） | +| 第二波收口 | 182 | 64 | **v1.2.0 冻结**（18 路径/24 操作/45 schema） | +| 第三波收口 | **191** | **272** | v1.2.0（契约测试锁定零漂移） | + +## 已完成（附提交） + +**开工分析（报告 01~08）**：八角色并行评估，Reality Checker 裁定 CONDITIONAL PASS（5 项放行条件），ADR-009~015 拍板入档（`patbond-doc@1891d9b`）。 + +**第一波：埋点修复 + 后端地基（报告 09~12）** + +- 契约补录 `POST /api/v1/events`（v1.1.0，`patbond-doc@2ceab6b`，关闭 D-1）。 +- Flutter 埋点链修复：生产接线、eventId v7、SessionTracker、page_viewed、events 端口纠正（8082）、离开前台冲刷、毒丸批次防护，34→51 测试（`patbond-flutter@1afec6a`）；桌面端全链路实测打通——生产事件流自 M1 以来首次非零。 +- Flyway V3 pet_health 8 表（4 条跨 schema FK 剥离标注 M5 补回）+ V4 字典种子（28 品种/10 疫苗）+ patbond-pet 模块骨架（ADR-009）+ health_record_action 移除（ADR-013），82→95 测试（`patbond-api@58576f8`）。 +- E2E 脚本 7/7 回归通过；注册页 +86 前缀体验修复。真机验证按方案 A 挂起不阻塞。 + +**第二波：后端纵切 + 契约冻结（报告 13~21）** + +- T2-03 宠物 CRUD + `PetAccessService` 三档权限闸口 + 防枚举 404（`patbond-api@8fbf444`）。 +- T2-04~07 体重/疫苗/健康事件/提醒接口：cursor 分页正典、疫苗状态机 + 剂次唯一、幂等键派生主键、六类事件 + 四类提醒、新错误码 40903/40904/42201/42202（`825dde3`→`3b27f9f`）。 +- T2-08 摘要四聚合口径定型（tz 参数）（`00f7dbd`）。 +- T2-09 契约冻结 v1.2.0（草案 22 项修正全有实现依据，`patbond-doc@511617b`）+ 契约一致性测试（字节级快照 + mutation 自证，抓修 1 项漂移，`patbond-api@d026f2f`）。 +- 并行：埋点持久化队列（分段 at-least-once，51→64 测试，`patbond-flutter@33b993c`）。 + +**第三波：Flutter 页面接入（报告 22~27）** + +- T2-11 pets 数据层：契约 18 操作全覆盖 + 8 错误码类型化（`patbond-flutter@7fb9031`）。 +- T2-12 宠物列表/详情/表单：四态齐备、40902 自动重提、DEBT-1 偿还、pet 域埋点（`97a1f46`）。 +- T2-13 体重/疫苗模块 + summary 接数替换 demo；跨设备验收实测通过（`c91f18a`）。 +- T2-14 时间线/提醒页 + 月度花费 tz + T2-13 遗留全消化（`ba50332`）。 +- 埋点白名单 v2 +10 事件（`patbond-api@64c9b72`）；三次 compose 实测均无契约偏差。 + +## 相关文档 + +- [后端模块结构与职责](../../../architecture/backend-modules.md)（M2 起新增的权威速览） +- [技术决策记录](../../../architecture/decisions.md)（ADR-009~015 为 M2 决策） +- 契约：`docs/api/openapi.yaml` v1.2.0（冻结纪律见报告 19） diff --git a/mkdocs.yml b/mkdocs.yml index 4197eb3..186b3a3 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -31,6 +31,7 @@ nav: - 19 埋点系统实现报告: development/iterations/iteration-1/19-analytics-implementation-report.md - 20 第一迭代收官总结: development/iterations/iteration-1/20-iteration-1-summary.md - 第二迭代: + - 进展看板: development/iterations/iteration-2/index.md - 01 任务分解: development/iterations/iteration-2/01-pm-task-breakdown.md - 02 后端技术评估: development/iterations/iteration-2/02-backend-technical-assessment.md - 03 Flutter 技术评估: development/iterations/iteration-2/03-flutter-technical-assessment.md