# 08 v0.4.0 发布前 E2E 回归门禁

> 作者：QA（Frontend Developer 角色执行）
> 日期：2026-09-14
> 任务：v0.4.0 发布 checklist 第 2 步「compose 全栈起，跑 E2E 烟囱脚本，全场景 PASS」
> 输入基线：patbond-api dev@`3cd8005`（379 测试）、patbond-flutter dev@`6945436`（597 测试）、
> 契约 `openapi.yaml` **v1.4.0**（32 路径 / 45 操作 / 75 schema）
> 提交：`test_e2e_m35_manual.dart` 新增，已推 `origin/dev`（见 §7）
> 结论先行：**门禁 PASS。四份脚本 42/42 场景全绿（M1 7/7、M2 11/11、M3 14/14、M3.5 新写 10/10），
> 共 234 条断言零失败；契约偏差 **0**；M3.5 新增对外面 8 项逐项验证通过；三门禁命令全绿
> （analyze 0 issue、format 0 changed、flutter test 597 passed）。patbond-api 与 patbond-doc
> 代码/契约零改动。**

---

## 1. 结论表：四份脚本场景通过数

| 脚本 | 迭代 | 场景 | 通过 | 断言数 | 退出码 | 判定 |
| --- | --- | --- | --- | --- | --- | --- |
| `test_e2e_manual.dart` | M1 | 7 | **7/7** | 7 | 0 | ✅ PASS |
| `test_e2e_m2_manual.dart` | M2 | 11 | **11/11** | 44 | 0 | ✅ PASS |
| `test_e2e_m3_manual.dart` | M3 | 14 | **14/14** | 88 | 0 | ✅ PASS |
| `test_e2e_m35_manual.dart` | **M3.5（本次新写）** | 10 | **10/10** | 95 | 0 | ✅ PASS |
| **合计** | | **42** | **42/42** | **234** | | ✅ **PASS** |

- **契约偏差数：0**。四份脚本对 v1.4.0 冻结契约的每一处断言（状态码、业务码、字段键集合、
  可空性、枚举、错误谱）均命中，无一处需要"以实现为准"地放宽期望。
- **失败项：无**。M3.5 脚本首次运行即 10/10 通过（未出现需要调整断言或重试的场景）。
- 三份既有回归脚本**逐字未改**——回归价值恰在于脚本本身不动。

### 执行顺序与理由

依次串行 M1 → M2 → M3 → M3.5，不并行。M3 场景 10/11 对 Feed 做**全量翻页前后计数比对**
（`idsAfter.length == idsBefore.length - 1`），任何并发发帖都会污染该断言；M3.5 场景 10 也要发帖。
串行是这两个断言成立的前提。

---

## 2. M3.5 新增对外面逐项验证结果

任务列出的 8 项必覆盖点，逐项对照：

| # | 要求 | 覆盖场景 | 结果 | 关键证据 |
| --- | --- | --- | --- | --- |
| 1 | 注册 → `GET /me` 断言 nickname 为 null（未设）、avatarUrl 为 null | [1/10] | ✅ | 全新账号 `nickname=null avatarUrl=null`，两键**恒在**；同时断言 Me 形态在冻结的 6 字段内 |
| 2 | `PATCH /me` 设昵称 → 回读一致 | [3/10] | ✅ | PATCH 回显与 `GET /me` 回读**逐字段一致**（userId/username/phone/createdAt/avatarUrl 五字段逐一比对），证明两动词同一 `Me` 形态 |
| 3 | 三态：只带 nickname 不影响头像 / 显式 `null` 清空生效 / 空 patch 400 / 纯空白 400 | [5/10] | ✅ | 见 §2.1 展开 |
| 4 | 昵称边界：1 可、32 可、33 拒、**32 emoji 按码点计应通过** | [6/10] | ✅ | 见 §2.2 展开 |
| 5 | 用户头像两步上传(user_avatar) → 挂载 → avatarUrl 可下载且字节一致 → 响应**不含** avatarAssetId | [4/10] | ✅ | 见 §2.3 展开 |
| 6 | 宠物头像(pet_avatar) → 挂载 → 详情/列表 avatarUrl 可用；错 purpose 被拒 | [8/10] + [9/10] | ✅ | 见 §2.4 展开。**错 purpose 实测为 404/40405**（与契约一致，非 42203） |
| 7 | `GET /me/community-stats`：空 0/0 → 发帖 → 自赞 → 1/1 → 软删归零 | [10/10] | ✅ | 见 §2.5 展开 |
| 8 | purpose 白名单外（`id_card`）创建上传被拒 | [2/10] | ✅ | `400/40000`，message 回显白名单三值 |

`/internal` 侧按任务要求**未测**（内部端点不入公网契约）。

### 2.1 `PATCH /api/v1/me` 三态与错误谱（场景 5，13 条断言）

| 请求 | 期望 | 实测 | 说明 |
| --- | --- | --- | --- |
| `{nickname: "豆豆"}`（头像已在） | 200，头像不变 | 200，`avatarUrl` 仍非 null | **键缺省 = 不改**：只带昵称的 patch 不碰头像 |
| `{nickname: null}` | 200，昵称清空、头像留存 | 200，`nickname=null`、`avatarUrl` 非 null | **显式 null = 清空**，且只作用于携带的键；回读复核已持久化 |
| `{avatarAssetId: null}` | 200，`avatarUrl` 回落 null | 200，`avatarUrl=null` | 头像清除生效 |
| `{}` | 400/40000 | 400/40000 | message：`请至少提交一个可更新字段：nickname 或 avatarAssetId`——不静默 200 |
| `{nickname: "   "}` | 400/40000 | 400/40000 | **纯空白不隐式清空**，清空只留显式 null 一条路 |
| `{nickname: ""}` | 400/40000 | 400/40000 | 空串与纯空白同判 |
| `{bio: "…"}` | 400/40000 | 400/40000 | 只带未声明字段 = 空 patch（`bio` 列存在但 M3.5 未开放读写） |
| `{avatarAssetId: "not-a-uuid"}` | 400/40000 | 400/40000 | 参数错先于引用校验 |
| 坏 JSON（`{"nickname": `） | 400/40000 | 400/40000 | 非法 body |
| 无 token | 401/40101 | 401/40101 | 写入口同样强制鉴权 |
| 同 body 连发两次 | 两次 200 且状态一致 | 两次 200，nickname 与"有头像"布尔一致 | 无 `Idempotency-Key`，天然幂等 |

每一处 `PATCH` 成功响应都跑了 `assertMeShape`：**键集合不超出冻结 6 字段**，且**不含 `avatarAssetId`**。

### 2.2 昵称边界——码点计而非 UTF-16 长度（场景 6，7 条断言）

| 昵称 | 码点 | UTF-16 长度 | 期望 | 实测 |
| --- | --- | --- | --- | --- |
| `柴` | 1 | 1 | 200 | ✅ 200 |
| `猫`×32 | 32 | 32 | 200 | ✅ 200 |
| **`🐕`×32** | **32** | **64** | **200** | ✅ **200** |
| `猫`×33 | 33 | 33 | 400/40000 | ✅ 400/40000 |
| `🐕`×33 | 33 | 66 | 400/40000 | ✅ 400/40000 |
| `"  豆豆  "` | — | — | 200 且存为 `豆豆` | ✅ btrim 对齐 |

**32 emoji 昵称通过是这一格的核心**：若应用层按 `String.length()` 校验，UTF-16 长度 64 会被误拒，
而 PostgreSQL `char_length` 数的是码点、数据库本可存下。实测通过 + 回读逐字一致
（`runes.length == 32`，无截断），证明校验确实按码点。上边界对 CJK 与 emoji 两种字符集行为一致。

### 2.3 用户头像端到端（场景 4，9 条断言）

链路：`POST /media/uploads`(purpose=**user_avatar**) → 预签名 PUT 直传 MinIO →
`POST /complete`(→ready) → `PATCH /me {avatarAssetId}` → `GET <avatarUrl>`。

- `avatarUrl` 由 null 转为**现签预签名 GET**，携带 `X-Amz-Signature` SigV4 query 族。
- objectKey 前缀随 purpose：`patbond-media/user_avatar/2026/09/{assetId}`——证明 §4 的前缀规则生效。
- **预签名 GET 取回 344 字节，与上传逐字节一致**（`ListEquality` 全等比对）。
- `GET /me` 再取一次 `avatarUrl` 仍可下载 → **每次响应现签**（客户端不得持久化）。
- **同一对象去掉签名直访 → 403**：桶保持私有，头像不靠公开读。
- 挂头像时 `nickname` 未被改动（三态交叉验证）。
- 挂载/清空/初始三态的响应**均不含 `avatarAssetId`**。

### 2.4 宠物头像（场景 8 + 9，20 条断言）

| 断言 | 结果 |
| --- | --- |
| 建档响应 `avatarUrl` 键恒在且为 `null`；**不含** `avatarAssetId` | ✅ |
| `PATCH /pets/{id} {version, avatarAssetId}` 仅头像字段 → 200（WRITE 档） | ✅ |
| `version` 0→1（头像与资料共用同一把乐观锁） | ✅ |
| 只带 avatarAssetId 未动 `name`/`species` | ✅ |
| **详情** `GET /pets/{id}` 的 avatarUrl 可下载且字节一致 | ✅ |
| **列表** `GET /pets` 的 avatarUrl 可下载且字节一致（两处各自现签、均有效） | ✅ |
| 列表项同样不外露 `avatarAssetId` | ✅ |
| `{avatarAssetId: null}` 显式清除 → `avatarUrl=null`，回读复核 | ✅ |

asset 校验矩阵（场景 9）：

| 引用的 asset | 期望 | 实测 | message |
| --- | --- | --- | --- |
| 错用途 `user_avatar`（跨域头像不通用） | 404/40405 | ✅ | `该媒体资源的用途不是 pet_avatar，不能作为宠物头像` |
| 错用途 `post_image` | 404/40405 | ✅ | 同上 |
| 幽灵 assetId | 404/40405 | ✅ | `媒体资源不存在` |
| 他人（B）的 asset | 404/40405 | ✅ | `媒体资源不存在`（防枚举合并） |
| 本人 `pet_avatar` 但仍 `uploading` | 422/42203 | ✅ | `媒体尚未就绪` |
| 缺 `version`（只带 avatarAssetId） | 400/40000 | ✅ | `version 不能为空`——即便只改头像仍必填 |

**副作用复核**：以上 6 次失败的 PATCH 之后，宠物 `avatarUrl` 仍为 null 且 `version` 未 +1
——失败路径零副作用。

> **任务提出的"错 purpose 以实现为准（40405 或 42203）"已定论：实测 404/40405**，与
> `openapi.yaml` v1.4.0 的 `paths./api/v1/pets/{petId}.patch` 404 描述及 03 号报告 §2.6
> 完全一致。42203 只留给"用途相符但状态未就绪"。**契约与实现无偏差。**

用户侧同构矩阵（场景 7，6 条断言）：幽灵 / 他人(B) / 错用途 `post_image` / 错用途 `pet_avatar`
四路均 404/40405，且**幽灵 id 与他人 asset 的响应体逐字节一致**（不能据差异探出 id 是真的）；
本人 `user_avatar` 但 `uploading` → 422/42203（用**真未直传**的 asset，非 SQL 造数据）。
5 次失败后头像未被改动。

### 2.5 `GET /api/v1/me/community-stats`（场景 10，14 条断言）

| 步骤 | 期望 | 实测 |
| --- | --- | --- |
| 无 token | 401/40101（唯一错误谱） | ✅ `401/40101` |
| A 全新账号（无帖） | 200，`{0, 0}`，**永不 404** | ✅ `{"receivedLikeCount":0,"publishedPostCount":0}` |
| 形态 | 恰两字段，非 null | ✅ 无多余键 |
| 发布 1 帖 | `{0, 1}` | ✅ |
| **A 自赞该帖** | `{1, 1}`（自赞**计入**） | ✅ `{"receivedLikeCount":1,"publishedPostCount":1}` |
| 对账 | 帖详情 `likeCount` == `receivedLikeCount` | ✅ 两处均为 1，**口径对得上** |
| 再建 1 草稿 | `{1, 1}`（**草稿不计**） | ✅ 作品数仍 1 |
| 再发布 1 帖 | `{1, 2}`（多帖求和） | ✅ |
| B 发布并自赞一帖 | A 视角仍 `{1, 2}`（**他人帖不串号**） | ✅ 主体恒为 token 里的调用者 |
| **软删被赞的那帖** | `{0, 1}`（获赞**归零**） | ✅ `{"receivedLikeCount":0,"publishedPostCount":1}` |

超出任务要求补测的两格：**草稿不计** 与 **他人帖不串号**——前者是 §2.5 口径表最容易实现错的一格，
后者证明"路径上没有 userId"确实等价于主体隔离。

---

## 3. 契约偏差数：0

逐面核对 `patbond-doc/docs/api/openapi.yaml` v1.4.0，脚本断言与契约声明零分歧：

| 契约条目 | 声明 | 实测 |
| --- | --- | --- |
| `info.version` | 1.4.0 | — |
| 路径 / 操作 / schema 计数 | 32 / 45 / 75 | ✅ 与基线一致（机械计数复核） |
| `Me.required` | `[userId, username, nickname, avatarUrl, createdAt]` | ✅ 五键恒在；`phone` 可选可空 |
| `Me` 不含 `avatarAssetId` | 响应一律不外露 | ✅ 6 处响应（GET 初始/PATCH 回显/挂载后/清空后 等）逐一断言 |
| `Pet` 加 `avatarUrl` 进 required | 键恒在、值可空 | ✅ 创建/详情/列表三处 |
| `Pet` 不含 `avatarAssetId` | 只写不读 | ✅ 三处断言 |
| `UpdateMeRequest` 三态 | 缺省/null/给值 | ✅ 三态各一格 |
| `PATCH /me` 400 谱 | 空 patch、长度越界、纯空白/空串、非法 UUID、坏 JSON | ✅ 6 格全中 |
| `PATCH /me` 401/404/422 | 40101 / 40405 / 42203 | ✅ 全中 |
| `PATCH /pets/{petId}` 新增 404/40405、422/42203 | asset 四态 + 未就绪 | ✅ 6 格全中 |
| `CommunityStats` | 两 int64、required 非 nullable、空数据 0、永不 404 | ✅ 全中 |
| `CreateMediaUploadRequest.purpose` 枚举 | `[post_image, user_avatar, pet_avatar]`，外值 400/40000 | ✅ 三值放行 + `id_card` 被拒 |

---

## 4. 环境记录

| 项 | 值 |
| --- | --- |
| 日期 | 2026-09-14 |
| patbond-api | `dev@3cd8005`（工作树干净，零改动） |
| patbond-doc | `dev@38d9e97`（契约零改动；本报告为新增文件） |
| patbond-flutter | `dev@6945436` + 新增 `test_e2e_m35_manual.dart` |
| 契约 | `openapi.yaml` v1.4.0 — **32 路径 / 45 操作 / 75 schema**（机械计数复核一致） |
| Docker | 29.7.2；Docker Compose 5.5.1 |
| Dart SDK | 3.12.2 (stable) |
| Flutter | 3.44.6 (stable)，framework `ee80f08bbf` |
| JDK（打包） | `JAVA_HOME=/usr/lib/jvm/java-17-openjdk`（17.0.20.1） |

### 六容器实况

| 容器 | 镜像 | 状态 | 端口 |
| --- | --- | --- | --- |
| `patbond-postgres-1` | `postgres:18`（18.6） | Up (healthy) | 不发布（仅容器网） |
| `patbond-minio-1` | `minio/minio:RELEASE.2025-04-22T22-12-26Z` | Up (healthy) | 9000 |
| `patbond-auth-1` | `patbond-auth`（本地构建） | Up | 8081 |
| `patbond-user-1` | `patbond-user` | Up | 8082 |
| `patbond-pet-1` | `patbond-pet` | Up | 8083 |
| `patbond-community-1` | `patbond-community` | Up | 8084 |

MinIO 镜像 tag 与集成测试的 Testcontainer 钉同一版本（三环境零分叉，ADR-016）。

### 起停命令

```bash
cd <你的工作区>/patbond-api
JAVA_HOME=/usr/lib/jvm/java-17-openjdk ./mvnw -DskipTests package   # exit 0
docker compose up -d --build                                        # 等 postgres/minio healthy
# …跑四份脚本…
docker compose down
```

### 附带取证：M3.5 的"零 Flyway 迁移"在真实升级路径上成立

本次 compose 起在**已存在的 `pgdata` volume** 上（非全新库），user 服务（迁移唯一所有者）日志：

```
o.f.core.internal.command.DbValidate : Successfully validated 5 migrations
o.f.core.internal.command.DbMigrate  : Current version of schema "public": 5
o.f.core.internal.command.DbMigrate  : Schema "public" is up to date. No migration necessary.
```

即 M3.5 相对 M3 **未新增任何 Flyway 版本**（仍停在 V5，V6 留给后续真正建表的迭代），
ADR-022 的"零迁移"前提在**存量库升级**场景下得到实证，而不只是全新安装。
auth / pet / community 三服务不跑 Flyway（无迁移输出），与设计一致。

### 配置侧复核（03 号报告 §4 的部署警告）

03 号报告提醒：若环境的 `application.yml` 显式写了 `allowed-purposes: post_image`，头像上传会 400。
compose 挂载的是 `patbond-user/src/main/resources/application.yml.sample`，实测该文件第 59 行为
`allowed-purposes: post_image,user_avatar,pet_avatar` ✅；pet 服务已补齐
`PATBOND_MINIO_PUBLIC_ENDPOINT/ACCESS_KEY/SECRET_KEY`（compose 第 107 行），
故宠物侧 `avatarUrl` 才可能非 null——场景 8 的下载成功即其端到端证明。

---

## 5. 门禁三命令输出

```bash
cd <你的工作区>/patbond-flutter
```

### 5.1 `flutter analyze`

```
Analyzing patbond-flutter...
No issues found! (ran in 2.1s)
```
退出码 **0**。（新增的根目录脚本也在分析范围内——`flutter analyze` 覆盖整仓 `.dart`。）

### 5.2 `dart format --set-exit-if-changed lib test`

```
Formatted 161 files (0 changed) in 0.66 seconds.
```
退出码 **0**。

补充：该命令的范围是 `lib test`，**不覆盖仓库根目录的四份 E2E 脚本**。为免留下格式债，
另跑了一次显式检查，四份并列脚本均已 format-clean：

```
$ dart format --output=none --set-exit-if-changed \
    test_e2e_manual.dart test_e2e_m2_manual.dart \
    test_e2e_m3_manual.dart test_e2e_m35_manual.dart
Formatted 4 files (0 changed) in 0.06 seconds.
```
退出码 **0**。（新脚本首版曾 1 changed，已 `dart format` 归一；formatter 拆出的一处
无花括号 `if` 已补花括号，避免 `curly_braces_in_flow_control_structures` 风格债。
归一后**重跑脚本复核仍 10/10**，即上表证据出自最终提交的文件。）

### 5.3 `flutter test`

```
00:30 +597 ~2: All tests passed!
```
退出码 **0** — **597 passed**、2 skipped、0 failed，与基线 597 **逐格一致**（本次未新增单测：
E2E 脚本是独立可执行的手动脚本，不进 `flutter test` 反应堆）。

---

## 6. 失败项与判定

**无失败项。**

| 类别 | 数量 | 说明 |
| --- | --- | --- |
| 真实回归 | **0** | M1/M2/M3 三份既有脚本 32/32 场景全绿，M3.5 新增字段未破坏任何既有断言 |
| 契约偏差 | **0** | 见 §3 |
| 需放宽的断言 | **0** | 含任务预留的"错 purpose 以实现为准"一格——实测与契约一致（40405） |
| 环境/配置问题 | **0** | §4 两处部署风险点均实测已闭环 |

**判定：v0.4.0 发布 checklist 第 2 步 PASS。**

### 本次门禁未覆盖的范围（不构成 FAIL，按既定方案挂起）

- **真机四项**（`development/device-verification.md`）：弱网上传头像、预签名 URL 过期后重取、
  caregiver 账号改宠物头像、资料页获赞数与帖子详情点赞数对账。本脚本纯 `dart:io HttpClient`
  跑后端契约面，不驱动 Flutter UI，故这四项仍按 M3 起的方案 A 挂起。
  其中"获赞数对账"的**后端口径**已在场景 10 证明（详情 `likeCount` == `receivedLikeCount`），
  真机侧待验的只剩 UI 呈现。
- **caregiver 分档**（viewer 改头像 403 / caregiver 夹带混合 403）：需要第二账号建立
  `pet_owners` 照护关系，M2/M3 脚本均未铺该前置，本次亦未铺；后端已有
  `PetAvatarIntegrationTest` 三段断言覆盖（03 号报告 §2.4）。
- **并发** `PATCH /me` **列级 UPDATE**：由后端 `MeProfileIntegrationTest.concurrentDisjointPatchesBothSurvive`
  以 `CyclicBarrier` 覆盖，单线程脚本不复现，本次以"重放幂等"作为可观测替代。
- `/internal/**`：按任务要求不测（不入公网契约）。

---

## 7. 脚本落位与提交

| 项 | 值 |
| --- | --- |
| 新增文件 | `<你的工作区>/patbond-flutter/test_e2e_m35_manual.dart`（仓库**根目录**，与前三份并列，**不在 `test/`**） |
| 行数 | 1166 行，10 场景 / 95 断言 |
| 依赖 | 无（纯 `dart:io HttpClient` + `dart:convert`，不引 `collection` 包——`ListEquality` 内联，与 M3 脚本同先例） |
| 运行 | `cd <你的工作区>/patbond-flutter && dart run test_e2e_m35_manual.dart` |
| 提交 | `dev` 分支（`main` 受保护禁直推） |

### 脱敏纪律（与 M3 脚本一致）

- **token**：仅打印前 20 字符 + `...<REDACTED>`。
- **预签名 URL**：`redactSignedUrl()` 保留 scheme/host/port/path，**签名 query 整体替换为
  `<SIGNATURE_REDACTED>`**——objectKey 前缀（`user_avatar/2026/09/…`）仍可读，便于核对 purpose
  前缀规则，而签名族一字不落盘。
- **Idempotency-Key**：日志中以 `<KEY-1>` 占位，不打印真实 UUID。
- 超长昵称按"前 4 码点 + 码点数/UTF-16 长度"概述，不整条刷屏。

### 硬约束遵守情况

- `patbond-api`：`git status --porcelain` **空**，HEAD 仍 `3cd8005` — 代码/契约零改动，仅起 compose。
- `patbond-doc`：契约 `openapi.yaml` 零改动，HEAD 仍 `38d9e97`；本报告为新增文件，
  **只写不提交**（随后统一入档）；`mkdocs.yml` **未动**。
- `patbond-flutter`：仅新增 1 个文件，无既有文件改动。

---

## 8. 交接给发布 checklist 后续步骤

1. **第 2 步可勾**：42/42 场景、234 断言、契约偏差 0、门禁三命令全绿。
2. 本报告入档时需挂 `mkdocs.yml` 导航（本次按纪律未动）。
3. 建议把 `test_e2e_m35_manual.dart` 与前三份一同写进发布 checklist 的常设回归清单——
   下个迭代的发布门禁应跑**四份**而非三份。
4. 真机四项与 caregiver 分档仍挂起，见 §6；若 v0.4.0 定位为可发布版本，
   建议在 `device-verification.md` 明确登记"头像相关四项待真机补验"，避免遗忘。
5. 收尾已执行 `docker compose down`（volume 保留，未 `-v`）。