lixi
222990e587
CI / docs-build (push) Successful in 1m19s
- 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>
65 lines
4.1 KiB
Markdown
65 lines
4.1 KiB
Markdown
# 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. 遗留(下波或后续)
|
||
|
||
1. **第三波 Flutter 接入**(T2-11 起):契约已冻结,DTO/Client 可开工
|
||
2. auth 域 6 操作无契约测试(M1 交付时无此机制,机制可直接复用,建议另立工单)
|
||
3. 埋点队列:30 秒定时冲刷、退避/429、anonymousId 持久化(15 号报告 §4)
|
||
4. 09 号报告的实现-规范 5 处出入(64KB 上限、429 限流等)仍待排期评估
|
||
5. 真机联调补验(第一波方案 A 挂起项):事件落库确认 + SessionTracker 30min 手测
|
||
6. 提醒 PATCH 409 并发守卫为契约测试唯一豁免格(单线程无法确定性构造)
|
||
|
||
## 5. 三仓状态(收口时点)
|
||
|
||
| 仓库 | HEAD | 测试 |
|
||
|------|------|------|
|
||
| patbond-api | dev@d026f2f | 182/182 |
|
||
| patbond-flutter | dev@33b993c | 64/64 |
|
||
| patbond-doc | main@511617b(契约)+ 本收口提交 | strict 通过 |
|