Files

T

CI / docs-build (push) Successful in 1m19s

Details

- 13~18 后端纵切六单报告（T2-03~08，测试 95→182）
- 14 + openapi-pets-draft.yaml 契约起草档案
- 19 契约冻结报告（v1.2.0，22 项草案修正对照）
- 20 契约一致性测试（快照机制 + 1 漂移修复）
- 21 第二波收口总表（定型语义汇总，第三波接入依据）
- mkdocs build --strict 通过

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

2026-09-08 10:40:27 +08:00

4.1 KiB

Raw Permalink Blame History

M2 第二波收口报告:后端接口纵切与契约冻结

执行日期:2026-09-07 ~ 2026-09-08 参与方:Senior Developer(后端)× 4 批次 / API Platform Engineer × 2 / Frontend Developer / 主会话协调 交付形态:pets 域 18 操作全实现、契约冻结 v1.2.0、契约一致性测试入 CI

0. 执行概要

第二波目标:后端接口纵切(T2-03~T2-08)→ 契约冻结(T2-09)→ 为第三波 Flutter 接入放行。

结果:全部完成。 patbond-api 测试 95 → 182 全绿,openapi.yaml 冻结至 v1.2.0(18 路径/24 操作/45 schema),契约一致性测试(全响应矩阵 + mutation 自证)纳入 CI。并行完成 Flutter 埋点持久化队列(51→64 测试)。

工单	交付	提交(api dev)	测试增量
T2-03 宠物 CRUD + 权限框架	权限闸口三档 + 防枚举 404	8fbf444	95→118
T2-04/05 体重 + 疫苗	cursor 分页正典 + 状态机 + 幂等	825dde3 / 4c2653c	118→138
T2-06/07 健康事件 + 提醒	六类事件 + 四类提醒 + 42202	d8303bf / 3b27f9f	138→159
T2-08 聚合摘要	四聚合口径定型(tz 参数)	00f7dbd	159→171
T2-09 契约冻结	openapi v1.2.0(doc main@511617b)	—	—
T2-09 契约测试	快照 + 严格校验器 + 1 漂移修复	d026f2f	171→182
埋点持久化队列	分段 at-least-once(flutter dev@33b993c)	—	51→64

1. 定型的关键语义(第三波 Flutter 接入的依据)

权限:PetAccessService.require 三档——READ(三角色)/WRITE(owner+caregiver)/MANAGE(仅 owner);无关系/不存在/已软删一律 404/40401 响应逐字一致(防枚举);记录级顶层短路径 404/40402
错误码新增 8 个:40300/40401/40402/40902/40903(芯片号冲突)/40904(疫苗剂次冲突)/42201(疫苗规则)/42202(提醒规则)
分页正典:cursor 信封 {items, nextCursor, hasMore},limit 1~100 默认 20(体重、健康事件);疫苗/提醒列表不分页
幂等:Idempotency-Key 可选头(weights/vaccinations/health-events/care-reminders 四个 POST),键派生确定性主键 + ON CONFLICT,零迁移
创建 201;PATCH 不支持清空回 null;响应主键统一裸 id
PetSummary:四聚合对象,无记录 null 语义,tz 参数(IANA)缺省 UTC,口径逐字入契约

2. 契约冻结纪律(自 v1.2.0 起生效)

docs/api/openapi.yaml 为唯一事实源;冻结后任何字段变更须显著上报、两端同步
api 侧持有字节级冻结快照(patbond-pet/src/test/resources/contract/openapi-v1.2.0.yaml),守卫测试锁版本号与规模(18 路径/24 操作/45 schema),契约升版须同步快照否则 CI 红
契约测试为全响应矩阵覆盖:契约声明的每个(操作,状态码)单元格都被真实请求触发并结构校验;「契约未声明的字段即报漂移」

3. 修复与发现

契约漂移 1 项(已修):CreatePetRequest.sex 契约必填、实现原静默补 unknown → 按冻结契约改 @NotBlank
草案→冻结修正 22 项(19 号报告 §2 对照表,均有 13/16/17/18 号定型依据)
收紧:pet 服务禁用 Jackson float→int 静默截断(amountCents: 45.5 → 40000)
Idempotency-Key 拍板措辞出入说明:拍板列三个 POST,实现与冻结按 16 号定型表收录四个(vaccinations 也支持且有测试锁定),属拍板本意内(可选头)的完整收录

4. 遗留(下波或后续)

第三波 Flutter 接入(T2-11 起):契约已冻结,DTO/Client 可开工
auth 域 6 操作无契约测试(M1 交付时无此机制,机制可直接复用,建议另立工单)
埋点队列:30 秒定时冲刷、退避/429、anonymousId 持久化(15 号报告 §4)
09 号报告的实现-规范 5 处出入(64KB 上限、429 限流等)仍待排期评估
真机联调补验(第一波方案 A 挂起项):事件落库确认 + SessionTracker 30min 手测
提醒 PATCH 409 并发守卫为契约测试唯一豁免格(单线程无法确定性构造)

5. 三仓状态(收口时点)

仓库	HEAD	测试
patbond-api	dev@d026f2f	182/182
patbond-flutter	dev@33b993c	64/64
patbond-doc	main@511617b(契约)+ 本收口提交	strict 通过

4.1 KiB Raw Permalink Blame History Unescape Escape