patbond-doc/docs/development/iterations/iteration-2/02-backend-technical-assessment.md

# Patbond 第二迭代后端技术评估（Dev）

- 日期：2026-09-07
- 评估范围：patbond-api 承接 M2「宠物健康档案」的改动面、建模与 API 草案、迁移规划、遗留项耦合
- 代码基线：patbond-api `0d81c38`（2026-09-04，工作区干净）
- 结论先行：**当前基线 82 个测试全绿（50.6s）**；建议 M2 在 patbond-user 内以独立包实现 pet_health 域，建模跟随 patbond-doc 目标模型（体重/疫苗强结构子表 + health_events 单表），共 7 项待拍板。

## 1. 现状盘点（实际读码结论）

### 1.1 模块与代码结构

Maven 三模块：`patbond-common`（错误码/响应契约/内部 DTO）、`patbond-auth`（8081，无库，Feign 调 user）、`patbond-user`（8082，唯一持库服务，Flyway 归属方）。

与 M2 直接相关的既有设施，全部可复用：

- **鉴权链路**：`patbond-user` 的 `BearerAuthFilter`（`patbond-user/src/main/java/com/patbond/patbond/user/security/BearerAuthFilter.java`）拦截 `/api/v1/*`，RS256 本地验签后把 userId 放进 request attribute `patbond.authenticatedUserId`，controller 用 `@RequestAttribute` 取。宠物接口直接挂在同一过滤器下，零新增鉴权代码。
- **异常/错误码契约**：`ErrorCode` 枚举（common）+ 每服务一个 `GlobalExceptionHandler`，`{code, message, data}` 信封 + 正确 HTTP 状态。扩展 = 往枚举追加值（不重编号）。
- **数据访问**：无 JPA，统一 `JdbcClient` + 手写 SQL（见 `UserRepository`），约束下沉数据库（CHECK/部分唯一索引），`updated_at` 由触发器维护。pet 域照此风格即可。
- **主键**：应用侧生成 UUIDv7（`patbond-user/src/main/java/com/patbond/patbond/user/support/UuidV7.java`）。
- **埋点挂接点**：`EventDictionary` 已预置 `health_record_action`（props 白名单 `recordType`/`actionType`），M2 后端无需改埋点代码，Flutter 侧触发即可。
- **测试设施**：Testcontainers（PostgreSQL 18）+ `TestcontainersConfiguration`，集成测试模式成熟，pet 域测试直接套用。

### 1.2 数据库现状

Flyway 链在 patbond-user：V1（identity/media/platform 基线）+ V2（platform.product_events）。**pet_health schema 尚未创建**（V1 只建了 platform/identity/media 三个 schema）。开发种子在 `db/dev/afterMigrate__dev_seed.sql`，默认不执行。

patbond-doc 目标模型（`patbond-doc/docs/database/patbond_postgresql.sql` 333-560 行）已给出完整的 pet_health 设计，共 8 张表：`breeds`、`pets`、`pet_owners`、`pet_weight_records`、`vaccine_catalog`、`pet_vaccinations`、`health_events`、`health_event_media`、`care_reminders`。该模型已经过评审，M2 建模应以它为正典裁剪，而不是另起炉灶。

### 1.3 缺口

- **media 上传流程未实现**：仓库中没有任何 media 相关代码（无 controller/service），`media.assets` 只有表。目标模型中宠物头像、疫苗证书、健康事件附件全部 FK 到 `media.assets`——附件能力被 media 上传流程阻塞（见待拍板 P3）。
- `marketplace` schema 未建：目标模型中 `pet_vaccinations.provider_id/booking_id`、`health_events.provider_id/booking_id` 本就未设 FK（预留列），M2 保留可空列即可，无阻塞。

## 2. 改动面评估

| 改动面 | 内容 | 量级 |
| --- | --- | --- |
| Flyway | V3 pet_health 结构基线（从目标模型裁剪）+ V4 字典种子（若拍板引入） | 中 |
| 新代码 | pet 域 controller/service/repository/DTO（约 5 组资源） | 大（M2 主体） |
| common | `ErrorCode` 追加 3~4 个值；若拍板新模块则需下沉 `UuidV7`/`BearerAuthFilter` | 小 |
| 契约 | openapi.yaml 冻结新增 pets 相关 path（实现前先冻结，本评估不动契约） | 中 |
| 既有代码 | 零改动（鉴权过滤器、异常处理、埋点均直接复用） | — |
| 依赖 | **无需新增任何依赖**（JdbcClient + Flyway + Testcontainers 足够，不引 JPA） | — |

## 3. 领域建模草案

### 3.1 模块归属【待拍板 P1】

- **方案 A：新建 `patbond-pet` Maven 模块（独立服务）**。符合开发计划 4.1「按迭代增加模块，边界与 schema 对齐」的字面方向。代价：新端口/compose 服务/CI 矩阵；`BearerAuthFilter`、`JwtVerifier`、`GlobalExceptionHandler`、`UuidV7` 需下沉 common 或复制；Flyway 单链归属要拆（共库单 `flyway_schema_history`，需为新模块配独立 history 表），部署与联调面翻倍。
- **方案 B（推荐）：在 patbond-user 内新增独立顶层包 `com.patbond.patbond.user.pethealth`**。零基础设施成本，Flyway 链自然延续（V3+），鉴权/异常/UUIDv7 直接复用。约束：包内不 import user 域内部类（只经 service 接口），SQL 只碰 `pet_health` schema（读 `identity.users` 仅限权限校验 join），保证未来抽成独立模块时是「搬包 + 拆迁移」而非重写。
- 推荐 B：MVP 单实例共库阶段，「模块边界与 schema 对齐」用包边界 + schema 读写纪律即可兑现，把工程成本留给业务代码。

### 3.2 表结构草案（Flyway V3，从目标模型裁剪）

按目标模型原样建（列、CHECK、部分唯一索引、`set_updated_at` 触发器全保留），仅做以下裁剪调整：

| 表 | M2 处置 | 调整点 |
| --- | --- | --- |
| `pets` | 建 | 主键去掉 `DEFAULT gen_random_uuid()`，应用侧 UUIDv7（与 users 做法对齐）；`avatar_asset_id` 保留可空列（media 未实现，暂不写入） |
| `pet_owners` | 建 | 目标模型原样；创建宠物时自动写入 `(pet_id, creator, 'owner', is_primary=true)` |
| `pet_weight_records` | 建 | 原样 |
| `breeds` + `vaccine_catalog` | 建（P2 拍板） | 若引入：结构进 V3、种子进 V4 正式迁移（字典是生产数据，不放 db/dev）；若不引入：pets 全走 `custom_breed_name`（`ck_pets_breed` 约束允许），疫苗表需把 `vaccine_id` 放宽为自由文本——**偏离目标模型，后续迁移代价大** |
| `pet_vaccinations` | 建 | `provider_id`/`booking_id`/`certificate_asset_id` 保留可空预留列，M2 不写入 |
| `health_events` | 建 | `event_type` 枚举沿用目标模型 6 值（medical/feeding/deworming/grooming/measurement/note） |
| `health_event_media` | **不建，推迟** | 依赖 media 上传流程（P3）；纯增量表，后续 V5+ 补零成本 |
| `care_reminders` | 建（P6 拍板） | 纯 CRUD，无推送 |

与 user/auth 的关系：`pet_owners.user_id -> identity.users(id)` 与 `health_events.created_by_user_id -> identity.users(id)` 两个跨 schema FK，共库阶段保留（与 V1 中 `media.assets.owner_user_id` 先例一致）。鉴权只用 JWT 里的 userId，不新增 auth 侧改动、不新增 `/internal` 接口。

### 3.3 健康记录类型建模：单表 + type vs 每类型子表【已由目标模型定调，确认即可】

- 纯单表（所有记录一张表 + type + jsonb）：查询简单，但体重/疫苗的强约束（剂次唯一、状态-日期一致性、数值范围）全丢给应用层。
- 纯子表（每类型一张表）：表爆炸，时间线聚合要 UNION 多表。
- **推荐（= 目标模型的混合方案）**：`pet_weight_records`、`pet_vaccinations` 独立强结构子表（各自的 CHECK 与部分唯一索引是业务规则本体，如「同系列同剂次未取消唯一」）；其余低结构记录统一进 `health_events` + `event_type` 枚举。时间线视图由 health_events 承载，体重/疫苗页各查各表。

## 4. API 资源设计草案（供契约冻结参考，本评估不改 openapi.yaml）

路径与开发计划 6.2 对齐，全部挂 `BearerAuthFilter` 强制鉴权：

| 接口 | 说明 |
| --- | --- |
| `GET /api/v1/pets` | 当前用户可见宠物列表（经 pet_owners join）；量小，建议一次性返回不分页（契约冻结时定） |
| `POST /api/v1/pets` | 创建，创建者自动 primary owner，返回 201 |
| `GET /api/v1/pets/{petId}` | 详情（含调用者自己的 role） |
| `PATCH /api/v1/pets/{petId}` | 更新，请求体带 `version` 乐观锁，冲突返回 409/40902 |
| `DELETE /api/v1/pets/{petId}` | 软删（status=deleted），仅 owner；是否进 M2 契约冻结时定 |
| `GET/POST /api/v1/pets/{petId}/weights` | 体重记录（GET 按 measured_at 倒序，cursor 分页） |
| `GET/POST /api/v1/pets/{petId}/vaccinations`、`PATCH .../vaccinations/{id}` | 疫苗记录（PATCH 带 version；状态迁移 scheduled→completed/cancelled） |
| `GET/POST /api/v1/pets/{petId}/health-events` | 健康时间线（cursor 分页：`(occurred_at, id)` 复合游标，与既有索引对齐） |
| `GET/POST/PATCH /api/v1/pets/{petId}/reminders` | 提醒 CRUD（P6） |
| `GET /api/v1/pets/{petId}/health-summary` | 服务端聚合：最新体重与趋势、疫苗进度、下次接种、当月花费（P5） |
| `GET /api/v1/breeds`、`GET /api/v1/vaccines` | 字典只读接口（若 P2 拍板引入；query 参数 species） |

权限规则：owner 全权；caregiver 可读写记录、不可改宠物档案与成员；viewer 只读。M2 只实现 owner 路径（P4），但 repository 层权限查询按三档写好。

错误码扩展（追加进 `ErrorCode`，延续现有编号段）：

| code | HTTP | 语义 |
| --- | --- | --- |
| 40300 `PET_ACCESS_DENIED` | 403 | 对可见宠物无相应操作权限（如 viewer 尝试写） |
| 40401 `PET_NOT_FOUND` | 404 | 宠物不存在**或调用者不可见**（防 ID 枚举，见 P7） |
| 40402 `RECORD_NOT_FOUND` | 404 | 宠物下的记录不存在 |
| 40902 `VERSION_CONFLICT` | 409 | 乐观锁版本冲突（对应验收标准「并发更新返回明确冲突」） |

幂等：开发计划 6.1 的 `Idempotency-Key` 强制名单（帖子/生成任务/预约）不含 pets，M2 写接口不强制幂等键；客户端重试语义靠乐观锁 + 唯一约束兜底。

## 5. 待拍板清单

| # | 事项 | 选项 | 推荐 |
| --- | --- | --- | --- |
| P1 | 模块归属 | 新建 patbond-pet 模块 vs patbond-user 内独立包 | user 内独立包（3.1） |
| P2 | 品种/疫苗字典 | 引入 breeds + vaccine_catalog（V3 结构 + V4 种子）vs 自由文本 | 引入字典，种子最小集（犬猫核心疫苗），避免偏离目标模型 |
| P3 | 附件/图片 | 进 M2（需先实现 media 上传流程）vs 推迟 | **推迟出 M2**；media 上传是独立工作量，不该给健康档案当前置；表列已预留 |
| P4 | 共同照护人 | 邀请/成员管理 API 进 M2 vs 只做 owner 自动归属 | 只做 owner，权限校验按三档 role 实现好，邀请 API 下迭代 |
| P5 | 健康汇总聚合 | 服务端 `health-summary` 接口 vs 客户端自聚合 | 服务端聚合（计划 M2 验收提到「从事实表聚合生成」，且跨设备一致） |
| P6 | 提醒 | care_reminders CRUD 进 M2（无推送）vs 推迟 | 进 M2 做纯 CRUD（计划 M2 范围明确包含），推送依赖通知基础设施、明确不做 |
| P7 | 无权限读取语义 | 403 vs 404 | 不可见宠物一律 404/40401（防枚举）；可见但越权操作 403/40300 |

## 6. 遗留中低优先项与 M2 的耦合评估

- **access token 黑名单**：与 M2 **弱耦合，建议不进本迭代**。宠物权限每次请求实时查 `pet_owners`，撤销照护关系立即生效，不依赖 token 吊销；access token 15 分钟 TTL（ADR-003）对健康档案的敏感级别足够。黑名单需求真正的触发点是「改密/封号即时踢出」，属身份域主题，与 pet 域实现无交集。
- **/internal 改 mTLS**：与 M2 **无耦合，建议不进本迭代**。M2 不新增任何 `/internal` 接口（按 P1 推荐方案，pet 域与 user 同进程，连内部调用都没有）；即使 P1 拍板为独立模块，也应沿用现有静态 service token 方案，mTLS 留给微服务化阶段（与 ADR-002 的节奏一致）。

## 7. 构建与测试基线（2026-09-07 实测）

命令：`JAVA_HOME=/usr/lib/jvm/java-17-openjdk ./mvnw test`（系统默认 JDK 26 不可用于构建，须显式指定）。

| 模块 | 测试数 | 结果 |
| --- | --- | --- |
| patbond-common | 3 | 通过 |
| patbond-user | 48 | 通过（含 Testcontainers 集成测试） |
| patbond-auth | 31 | 通过 |
| **合计** | **82** | **全绿，BUILD SUCCESS，总耗时 50.6s** |

与第一迭代收官基线（82 测试）一致，无回归。此为 M2 开工基线：M2 结束时测试数只增不减，且该命令保持一次通过。