From 3cd80055779db2d52cf8cc1af425d06131f7e41d Mon Sep 17 00:00:00 2001 From: Lixi20 Date: Fri, 11 Sep 2026 10:33:19 +0800 Subject: [PATCH] =?UTF-8?q?test(contract):=20v1.4.0=20=E5=BF=AB=E7=85=A7?= =?UTF-8?q?=E5=9B=9B=E6=A8=A1=E5=9D=97=E5=90=8C=E6=AD=A5=20+=20=E7=94=A8?= =?UTF-8?q?=E6=88=B7=E8=B5=84=E6=96=99=E4=B8=8E=E5=A4=B4=E5=83=8F=E7=9F=A9?= =?UTF-8?q?=E9=98=B5=E5=85=A5=E5=9C=BA=EF=BC=88T3.5-07=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit doc 仓正典 main@5f02909 冻结 v1.4.0 后的 api 侧收尾：字节级同步快照、守卫 升版、新增/变更操作入契约一致性矩阵。**零生产代码改动**（只改契约快照与测试）。 快照同步（字节级，md5 与正典逐一比对一致 a7081fb84f1207eef579ab94025f5801）： - 四模块 openapi-v1.3.0.yaml → openapi-v1.4.0.yaml，删旧文件（守卫只认一份， 保留旧快照是死重；历史版本由 git 与 doc 仓承载，沿 T3-19 先例） - 四份守卫期望升版：1.3.0/31/43/72 → 1.4.0/32/45/75 矩阵扩展（173 → 181 格，豁免仍为 1 格）： - patbond-auth +5 格：PATCH /api/v1/me 全响应矩阵（200 设值 / 200 显式 null 清空 / 400 空 patch / 401 / 404 双码 40400+40405 / 422 42203），并让 GET /api/v1/me 在 nickname 非空分支再走一遍严格校验。注意 /api/v1/me 的守卫与 矩阵都在 auth 模块（实现在 user，契约测试跨服务发请求），扩契约易漏 - patbond-pet +1 格：PATCH /api/v1/pets/{petId} 新增 422/42203；404 单元格 补 40405 第二种业务码（幽灵 asset 与用途不符 asset 合并同答），并补一格 挂 ready 头像的 200 - patbond-community +2 格：GET /api/v1/me/community-stats 200（空数据零值与 有数据 1 赞/2 作品两分支）+ 401（由全操作循环覆盖） - patbond-user media 域 2 操作 8 格不变（v1.4.0 未触碰其冻结面） T3.5-04/05/06 遗留的 11 格契约守卫红（auth 2 + pet 9，根因为新增字段未冻结） 全部转绿。测试 379 → 381（+2 个新增矩阵方法），根反应堆 clean test 全绿， check-secrets.sh --all exit 0。 mutation 自证（三处定向注毒均红、还原即绿）：CommunityStats.required 注入 fakeStatsField → GET /me/community-stats 200 报漂移；Me.required 注入 fakeMeField → GET+PATCH /me 200 报漂移；Pet.required 注入 fakePetAvatarField → POST /pets 201 等 9 格报漂移。 Co-Authored-By: Claude Opus 5 (1M context) --- .../contract/AuthContractConformanceTest.java | 106 +++++- .../auth/contract/OpenApiContract.java | 6 +- ...penapi-v1.3.0.yaml => openapi-v1.4.0.yaml} | 342 ++++++++++++++++-- .../CommunityContractConformanceTest.java | 67 +++- .../community/contract/OpenApiContract.java | 6 +- ...penapi-v1.3.0.yaml => openapi-v1.4.0.yaml} | 342 ++++++++++++++++-- .../pet/contract/ContractConformanceTest.java | 67 +++- .../patbond/pet/contract/OpenApiContract.java | 6 +- ...penapi-v1.3.0.yaml => openapi-v1.4.0.yaml} | 342 ++++++++++++++++-- .../MediaContractConformanceTest.java | 14 +- .../user/contract/OpenApiContract.java | 6 +- ...penapi-v1.3.0.yaml => openapi-v1.4.0.yaml} | 342 ++++++++++++++++-- 12 files changed, 1486 insertions(+), 160 deletions(-) rename patbond-auth/src/test/resources/contract/{openapi-v1.3.0.yaml => openapi-v1.4.0.yaml} (87%) rename patbond-community/src/test/resources/contract/{openapi-v1.3.0.yaml => openapi-v1.4.0.yaml} (87%) rename patbond-pet/src/test/resources/contract/{openapi-v1.3.0.yaml => openapi-v1.4.0.yaml} (87%) rename patbond-user/src/test/resources/contract/{openapi-v1.3.0.yaml => openapi-v1.4.0.yaml} (87%) diff --git a/patbond-auth/src/test/java/com/patbond/patbond/auth/contract/AuthContractConformanceTest.java b/patbond-auth/src/test/java/com/patbond/patbond/auth/contract/AuthContractConformanceTest.java index e33d29e..7e65135 100644 --- a/patbond-auth/src/test/java/com/patbond/patbond/auth/contract/AuthContractConformanceTest.java +++ b/patbond-auth/src/test/java/com/patbond/patbond/auth/contract/AuthContractConformanceTest.java @@ -20,6 +20,7 @@ import org.springframework.http.HttpHeaders; import org.springframework.http.HttpMethod; import org.springframework.http.MediaType; import org.springframework.http.ResponseEntity; +import org.springframework.jdbc.core.simple.JdbcClient; import org.springframework.test.context.DynamicPropertyRegistry; import org.springframework.test.context.DynamicPropertySource; import org.testcontainers.containers.PostgreSQLContainer; @@ -38,16 +39,24 @@ import java.util.concurrent.ConcurrentHashMap; import static org.assertj.core.api.Assertions.assertThat; /** - * T3-19（D3-8）：auth 域 6 个 M1 操作补进契约一致性保障，机制与 - * patbond-pet 的 ContractConformanceTest 同构——对冻结契约 v1.3.0（快照 - * {@code src/test/resources/contract/openapi-v1.3.0.yaml}，正典在 doc 仓 + * T3-19（D3-8）：auth 域 M1 操作补进契约一致性保障，机制与 + * patbond-pet 的 ContractConformanceTest 同构——对冻结契约 v1.4.0（快照 + * {@code src/test/resources/contract/openapi-v1.4.0.yaml}，正典在 doc 仓 * {@code docs/api/openapi.yaml}）逐操作真实发请求，用 {@link ContractValidator} * 严格校验响应结构，最后以全响应矩阵门禁兜底。 * *

与 pet 侧的差别只在运行方式：register/login/refresh/logout 走真实 HTTP * 打到 auth 服务（本测试的 Spring 上下文），me/trackEvents 打到同 JVM 内 * 启动的真实 user 服务（复用 AuthE2eIntegrationTest 的编排先例）， - * 因此这 6 个操作是跨服务的真实纵切，不是 MockMvc 短路。 + * 因此这些操作是跨服务的真实纵切，不是 MockMvc 短路。 + * + *

T3.5-07：v1.4.0 把 {@code PATCH /api/v1/me} 与 {@code GET} 的 + * nickname/avatarUrl 纳入冻结面，故本类的操作面自 6 增至 7。注意 + * {@code /api/v1/me} 的守卫与矩阵都在 **auth 模块**（实现在 patbond-user， + * 但契约测试在这里跨服务发请求），扩契约时容易漏。本类不配置对象存储， + * 故 {@code avatarUrl} 恒为 null——正是「存储未配置时资料读取整体降级」的 + * nullable 实证；真实签名 URL 的全链路在 patbond-user 的 + * MeAvatarSigningIntegrationTest（真实 MinIO）覆盖。 */ @TestMethodOrder(MethodOrderer.OrderAnnotation.class) @SpringBootTest( @@ -63,13 +72,14 @@ class AuthContractConformanceTest { /** 已被真实响应校验过的 (操作, 状态码) 单元格。 */ private static final Set COVERED = ConcurrentHashMap.newKeySet(); - /** auth 域 6 个操作（= 契约中 tags ∈ {auth, user, analytics}）。 */ + /** auth 域 7 个操作（= 契约中 tags ∈ {auth, user, analytics}）。 */ private static final List AUTH_OPERATIONS = List.of( "POST /api/v1/auth/register", "POST /api/v1/auth/login", "POST /api/v1/auth/refresh", "POST /api/v1/auth/logout", "GET /api/v1/me", + "PATCH /api/v1/me", "POST /api/v1/events"); private static final PostgreSQLContainer POSTGRES = new PostgreSQLContainer<>("postgres:18"); @@ -305,6 +315,80 @@ class AuthContractConformanceTest { null, 423, 42300); } + // ---- PATCH /api/v1/me（v1.4.0 新增操作，T3.5-07）-------------------- + + /** + * `PATCH /api/v1/me` 的全响应矩阵（200/400/401/404/422）与三态语义的形态 + * 实证，外加 GET 在 nickname 非空分支上再走一遍严格校验。 + * + *

422/42203 需要一枚「本人所有、用途 user_avatar、状态 uploading」的 + * asset：本上下文未配置对象存储（创建上传会 500），故按 MeProfileIntegrationTest + * 的先例直接写 media.assets 行——测试数据造法，不触碰实现。 + */ + @Test + @Order(7) + void meProfileWriteShapes() { + String registered = register("contract_auth_frank", "+8613800000608"); + String accessToken = JsonPath.read(registered, "$.data.accessToken"); + UUID userId = UUID.fromString(JsonPath.read(registered, "$.data.userId")); + + // 200：三态「给值」——设昵称；avatarUrl 为 null（存储未配置时的降级实证） + String patched = verified(HttpMethod.PATCH, userBaseUrl + "/api/v1/me", "/api/v1/me", + "{\"nickname\":\"契约昵称\"}", accessToken, 200); + assertThat((String) JsonPath.read(patched, "$.data.nickname")).isEqualTo("契约昵称"); + assertThat((Object) JsonPath.read(patched, "$.data.avatarUrl")).isNull(); + + // GET 回读：nickname 非空分支同样过严格校验（PATCH 与 GET 同一 Me 形态） + String reread = verified(HttpMethod.GET, userBaseUrl + "/api/v1/me", "/api/v1/me", + null, accessToken, 200); + assertThat((String) JsonPath.read(reread, "$.data.nickname")).isEqualTo("契约昵称"); + + // 200：三态「显式 null = 清空」 + String cleared = verified(HttpMethod.PATCH, userBaseUrl + "/api/v1/me", "/api/v1/me", + "{\"nickname\":null}", accessToken, 200); + assertThat((Object) JsonPath.read(cleared, "$.data.nickname")).isNull(); + + // 400/40000：空 patch（不静默 200） + verifiedError(HttpMethod.PATCH, userBaseUrl + "/api/v1/me", "/api/v1/me", + "{}", accessToken, 400, 40000); + + // 401/40101：无 token + verifiedError(HttpMethod.PATCH, userBaseUrl + "/api/v1/me", "/api/v1/me", + "{\"nickname\":\"无票\"}", null, 401, 40101); + + // 404：同一单元格的两种业务码——用户已注销 40400 / asset 不可引用 40405 + String ghostToken = signToken(TestJwtKeys.KEY_PAIR.getPrivate(), + UUID.randomUUID().toString(), Duration.ofMinutes(15)); + verifiedError(HttpMethod.PATCH, userBaseUrl + "/api/v1/me", "/api/v1/me", + "{\"nickname\":\"幽灵\"}", ghostToken, 404, 40400); + verifiedError(HttpMethod.PATCH, userBaseUrl + "/api/v1/me", "/api/v1/me", + "{\"avatarAssetId\":\"%s\"}".formatted(UUID.randomUUID()), + accessToken, 404, 40405); + + // 422/42203：本人的 user_avatar asset 仍在 uploading + UUID uploading = insertUserAvatarAsset(userId, "uploading"); + verifiedError(HttpMethod.PATCH, userBaseUrl + "/api/v1/me", "/api/v1/me", + "{\"avatarAssetId\":\"%s\"}".formatted(uploading), accessToken, 422, 42203); + } + + /** 一枚本人所有的 user_avatar asset 行（模拟 T3-03 两步上传的中间产物）。 */ + private UUID insertUserAvatarAsset(UUID ownerUserId, String status) { + UUID id = UUID.randomUUID(); + userApp.getBean(JdbcClient.class).sql(""" + INSERT INTO media.assets + (id, owner_user_id, kind, purpose, storage_type, bucket, object_key, + mime_type, byte_size, status) + VALUES (:id, :owner, 'image', 'user_avatar', 'object', 'patbond-media', + :objectKey, 'image/jpeg', 2048, :status) + """) + .param("id", id) + .param("owner", ownerUserId) + .param("objectKey", "user_avatar/2026/09/" + id) + .param("status", status) + .update(); + return id; + } + // ---- 快照与覆盖门禁 ------------------------------------------------- /** @@ -314,17 +398,17 @@ class AuthContractConformanceTest { @Test @Order(98) void frozenSnapshotIsTheExpectedContractVersion() { - assertThat(CONTRACT.version()).isEqualTo("1.3.0"); - assertThat(CONTRACT.paths()).hasSize(31); - assertThat(CONTRACT.operations()).hasSize(43); - assertThat(CONTRACT.schemas()).hasSize(72); + assertThat(CONTRACT.version()).isEqualTo("1.4.0"); + assertThat(CONTRACT.paths()).hasSize(32); + assertThat(CONTRACT.operations()).hasSize(45); + assertThat(CONTRACT.schemas()).hasSize(75); assertThat(CONTRACT.operationsTagged(Set.of("auth", "user", "analytics"))) .containsExactlyInAnyOrderElementsOf(AUTH_OPERATIONS); } /** - * 全矩阵覆盖门禁：auth 域 6 个操作声明的每个 (操作, 状态码) 都必须被 - * 前面的测试真实触发并通过契约校验（19 个单元格，无豁免）。 + * 全矩阵覆盖门禁：auth 域 7 个操作声明的每个 (操作, 状态码) 都必须被 + * 前面的测试真实触发并通过契约校验（24 个单元格，无豁免）。 */ @Test @Order(99) diff --git a/patbond-auth/src/test/java/com/patbond/patbond/auth/contract/OpenApiContract.java b/patbond-auth/src/test/java/com/patbond/patbond/auth/contract/OpenApiContract.java index a86ba66..14f0ab0 100644 --- a/patbond-auth/src/test/java/com/patbond/patbond/auth/contract/OpenApiContract.java +++ b/patbond-auth/src/test/java/com/patbond/patbond/auth/contract/OpenApiContract.java @@ -13,8 +13,8 @@ import java.util.Objects; import java.util.Set; /** - * The frozen v1.3.0 OpenAPI contract, loaded from the test-resource snapshot - * {@code /contract/openapi-v1.3.0.yaml}. + * The frozen v1.4.0 OpenAPI contract, loaded from the test-resource snapshot + * {@code /contract/openapi-v1.4.0.yaml}. * *

Sync discipline (T2-09, extended by T3-19): the canonical * contract lives in the doc repo at {@code docs/api/openapi.yaml}; this @@ -36,7 +36,7 @@ import java.util.Set; */ final class OpenApiContract { - static final String RESOURCE = "/contract/openapi-v1.3.0.yaml"; + static final String RESOURCE = "/contract/openapi-v1.4.0.yaml"; private static final Set HTTP_METHODS = Set.of("get", "put", "post", "delete", "options", "head", "patch", "trace"); diff --git a/patbond-auth/src/test/resources/contract/openapi-v1.3.0.yaml b/patbond-auth/src/test/resources/contract/openapi-v1.4.0.yaml similarity index 87% rename from patbond-auth/src/test/resources/contract/openapi-v1.3.0.yaml rename to patbond-auth/src/test/resources/contract/openapi-v1.4.0.yaml index c9d3072..d669f33 100644 --- a/patbond-auth/src/test/resources/contract/openapi-v1.3.0.yaml +++ b/patbond-auth/src/test/resources/contract/openapi-v1.4.0.yaml @@ -1,7 +1,7 @@ openapi: 3.0.3 info: title: Patbond API — Auth / Me / Events / Pets / Community / Media（公开契约） - version: 1.3.0 + version: 1.4.0 description: | Patbond 第一迭代「真实登录纵切」公开契约（冻结稿的正式化，字段与草案零偏差）， 1.1.0 追加埋点上报端点 `POST /api/v1/events`（M2 第一波契约补录，以实现实测行为为准）。 @@ -11,6 +11,14 @@ info: **1.3.0 M3 契约冻结：community/media 域 13 路径**（媒体两步上传、帖子生命周期、 公共 Feed、单层评论、点赞/收藏/关注最小接口）按第二波已定型实现合入 （iteration-3 报告 13/15/16/17 定型表；冻结报告见 iteration-3/18）。 + **1.4.0 M3.5 契约冻结：用户资料与头像**——`GET /api/v1/me` 补 `nickname`/`avatarUrl`， + 新增 `PATCH /api/v1/me`（昵称与头像读写，三态部分更新），`Pet` 补 `avatarUrl` 且 + `PATCH /api/v1/pets/{petId}` 收 `avatarAssetId`，新增 `GET /api/v1/me/community-stats` + （获赞总数与作品数），媒体 `purpose` 白名单追加 `user_avatar`/`pet_avatar` + （iteration-3.5 报告 03 定型表；冻结报告见 iteration-3.5/04）。 + **1.4.0 相对 1.3.0 纯增量**：无字段删改、无类型变更、无必填收紧，仅新增操作、 + 新增响应字段（键恒在、值可空）、新增可选请求字段、新增响应格与枚举追加， + v1.3.0 客户端无需改动即可继续工作。 ## 通用约定（development-plan 第 6 节） - 公开接口统一前缀 `/api/v1`；JSON 字段一律 `camelCase`；资源 ID 为 UUID 字符串。 @@ -29,14 +37,14 @@ info: | 40100 | 401 | 用户名或密码错误 | | 40101 | 401 | access token 无效或过期（缺失、伪造、篡改、过期） | | 40102 | 401 | refresh token 已失效或被重用（未知、过期、已轮换、已退出、家族已撤销） | - | 40300 | 403 | PET_ACCESS_DENIED：对可见宠物无相应操作权限（viewer 写记录、caregiver 改宠物档案） | + | 40300 | 403 | PET_ACCESS_DENIED：对可见宠物无相应操作权限（viewer 写记录或改头像、caregiver 改宠物档案——头像除外，见 M3.5 分档） | | 40301 | 403 | POST_ACCESS_DENIED：对可见帖子/评论无相应操作权限（改删他人已发布帖、删他人可见评论——含帖主）；仅发给对资源「可见」的调用者 | | 40400 | 404 | 资源不存在 | | 40401 | 404 | PET_NOT_FOUND：宠物不存在、已软删除或调用者与宠物无关系（防枚举，三种情况响应完全一致） | | 40402 | 404 | RECORD_NOT_FOUND：顶层记录路径下记录不存在或所属宠物对调用者不可见（记录级防枚举，两种情况响应完全一致） | | 40403 | 404 | POST_NOT_FOUND：帖子不存在、已软删、hidden/archived（作者同样）或他人 draft（防枚举，全部情况响应完全一致）；评论与互动路径上含作者本人草稿 | | 40404 | 404 | COMMENT_NOT_FOUND：评论不存在、已删或所属帖子不可见（防枚举合并） | - | 40405 | 404 | MEDIA_NOT_FOUND：asset 不存在、非本人所有或已删（防枚举合并） | + | 40405 | 404 | MEDIA_NOT_FOUND：asset 不存在、非本人所有、已删，或**用途与引用场景不符**（帖图当头像、user_avatar 当宠物头像等）；防枚举合并，同码各情形响应一致（用途不符分支只对调用者自己的 asset 可达，故 message 可具体） | | 40406 | 404 | USER_NOT_FOUND：目标用户不存在或已注销（关注端点与评论 replyToUserId；不复用 40400——该码已承担「路由级资源不存在」兜底语义，复用会使二者不可区分） | | 40900 | 409 | 用户名已存在（大小写不敏感） | | 40901 | 409 | 手机号已被使用 | @@ -46,7 +54,7 @@ info: | 40905 | 409 | IDEMPOTENCY_PAYLOAD_MISMATCH：同 Idempotency-Key 不同 payload（规范化 request_hash 不符，community 域创建型写入） | | 42201 | 422 | VACCINATION_RULE_VIOLATION：疫苗状态机非法迁移或状态-日期规则违反 | | 42202 | 422 | REMINDER_RULE_VIOLATION：提醒状态机非法迁移或 completed-completedAt 一致性违反 | - | 42203 | 422 | MEDIA_NOT_READY：引用了本人所有但非 ready（uploading/failed）状态的 asset | + | 42203 | 422 | MEDIA_NOT_READY：引用了本人所有、用途相符但非 ready（uploading/failed）状态的 asset（帖图与用户/宠物头像同构） | | 42204 | 422 | FOLLOW_RULE_VIOLATION：自关注（仅 PUT；自取关为 200 幂等 no-op） | | 42205 | 422 | MEDIA_UPLOAD_STATE_INVALID：complete 时 asset 非 uploading——对象未上传保持可重试、大小/类型不符置 failed 终态、failed 态再确认；已 ready 幂等 200 除外 | | 42300 | 423 | 登录失败次数过多，账号已临时锁定（见下） | @@ -68,7 +76,10 @@ info: - **权限模型（ADR-015：owner/caregiver/viewer 三角色，pet_owners 表）**，操作分三档： - `READ`——三角色皆可：宠物详情/列表、各记录列表、档案摘要； - `WRITE`——owner + caregiver：体重/疫苗/健康事件/提醒的 POST 与 PATCH； - - `MANAGE`——仅 owner：宠物档案 PATCH（含状态流转）。 + **M3.5 起还含宠物头像字段 `avatarAssetId`**（ADR-022：头像属日常照护信息）。 + - `MANAGE`——仅 owner：宠物档案 PATCH 的资料字段（含状态流转）。 + **同一端点按「本次请求触及哪些字段」定档**（不是端点级降档）：仅改头像走 WRITE， + 触及任一资料字段走 MANAGE，混合请求取更严的一半。 权限每请求实时查库、无缓存：撤销照护关系立即生效。 - **防枚举语义**：宠物不存在、已软删除、调用者与宠物无 pet_owners 关系三种情况 响应完全一致（404/40401），GET 与写操作一致适用；顶层记录路径下「记录不存在」与 @@ -126,6 +137,41 @@ info: 整体不出现，后续按新增可选字段/端点纯增量补入。`/internal/**` 服务间接口 （如作者公开资料批量接口）不属于本公开契约。 + ## 用户资料与头像域约定（M3.5 冻结，iteration-3.5 报告 03 定型；ADR-022） + - **三态部分更新（仅本域，pets 域 M2 两态语义不回改）**：`PATCH /api/v1/me` 的 + `nickname`/`avatarAssetId` 与 `PATCH /api/v1/pets/{petId}` 的 `avatarAssetId` + 按三态解释——**键缺省 = 不改；键出现且为 `null` = 清空；键出现且有值 = 设置**。 + 昵称与头像天生可选，「删掉我设的那个」是一等公民操作，只有两态无法表达。 + 同一请求体内的其余 pets 字段仍是 M2 的「缺省或 null 皆为不改」。 + - **空 PATCH 与纯空白昵称一律 400/40000**，不静默 200、不隐式清空：清空只留 + 显式 `null` 一条路，否则「误提交空格」与「想删昵称」无法区分。 + - **昵称**：btrim 后 1~32 **码点**（非 UTF-16 长度）；**不设唯一约束**（ADR-022， + 允许重名，靠 userId 区分）；注册不收昵称。`/api/v1/me` 返回 **DB 原值**， + 未设置即 `null`，**不做 username 回退**——`/me` 是本人编辑态，回退会把展示约定 + 固化成真实数据；他人视角的展示回退在 `/internal/users/profiles`（SQL COALESCE）， + 本人视角的展示回退由客户端做 `nickname ?? username`。 + - **头像读取一律 `avatarUrl`（时效性预签名 GET，与帖图同一纪律）**：每次响应现签， + **会过期、客户端不得持久化**，过期即重取；无头像、asset 非 ready、对象存储未配置 + 三种情况均为 `null`（降级而非报错——签一个必然 404 的 URL 比给 null 更糟）。 + 指针不隐式清理：asset 事后退出 ready 时 `avatarUrl` 转 null 而引用保留。 + - **`avatarAssetId` 只写不读**：请求体收，响应**一律不外露**（`Me` 与 `Pet` 皆无该字段）； + 「是否有头像」等价于 `avatarUrl != null`。 + - **两种头像用途互不通用**：`user_avatar` 不能当宠物头像、`pet_avatar` 不能当用户头像、 + `post_image` 不能当任何头像——引用侧按 `purpose` 校验，不符者 404/40405 + （四态校验：不存在/非本人/已删/用途不符 → 404/40405；本人且用途相符但 + uploading/failed → 422/42203）。 + - **宠物头像的权限档按「本次请求碰了哪些字段」定档**（ADR-022 头像为 WRITE 档）： + 仅改 `avatarAssetId` 时 owner + caregiver 皆可（viewer 403/40300）；触及任一资料 + 字段时仍是 MANAGE（仅 owner）；**混合请求取更严的一半**，堵住把改名夹带进头像 + 请求绕过 MANAGE 的路径。头像与资料共用同一把乐观锁 `version`（仍必填）。 + - **`/api/v1/me` 无乐观锁、无幂等键**：只有一个合法写者（账号本人），暴露 `version` + 只是给客户端加负担；丢失更新由**列级选择性 UPDATE** 排除（SET 列表只含本次请求 + 真正携带的列），并发改不同字段两者皆存活；同 body 重放天然幂等。 + - **`GET /api/v1/me/community-stats` 为独立端点**（ADR-022 决策 A，不并入 + `/users/{userId}/follow-stats`——后者主体是「某用户的关注数」，混入「我的获赞」 + 会让一个载荷有两个主体）。路径上**没有 userId**：「查不到别人的获赞」不靠权限 + 判断，而是入口本身不存在，故**永不 404**，任何已认证用户都有 stats。 + servers: - url: http://127.0.0.1:8081 description: patbond-auth（本地开发，/api/v1/auth/**） @@ -140,7 +186,7 @@ tags: - name: auth description: 注册 / 登录 / 刷新 / 退出（patbond-auth） - name: user - description: 当前用户（patbond-user） + description: 当前用户资料：读取与昵称/头像更新（patbond-user） - name: analytics description: 产品事件批量上报（patbond-user） - name: pets @@ -152,7 +198,9 @@ tags: - name: media description: 媒体上传两步流程（patbond-user，ADR-016 预签名直传） - name: posts - description: 帖子生命周期：草稿/编辑/发布/删除/详情/我的帖子（patbond-community） + description: | + 帖子生命周期：草稿/编辑/发布/删除/详情/我的帖子；含由帖子派生的「我的社区数字」 + 聚合（patbond-community） - name: feed description: 公共 Feed 游标分页（patbond-community） - name: comments @@ -301,7 +349,15 @@ paths: get: tags: [user] summary: 当前用户资料 - description: 由 patbond-user 提供；access token 以 RS256 公钥本地验签，无需经过 auth 服务。 + description: | + 由 patbond-user 提供；access token 以 RS256 公钥本地验签，无需经过 auth 服务。 + + - `nickname` 为 **DB 原值**，未设置即 `null`（**不做 username 回退**，见 info + 「用户资料与头像域约定」）；本人视角的展示回退由客户端做 `nickname ?? username`。 + - `avatarUrl` 为**每次响应现签的时效性预签名 GET**：**会过期、客户端不得持久化**， + 过期即重取；无头像、asset 非 ready、对象存储未配置均为 `null`。 + - 响应**不含** `avatarAssetId`：客户端只写不读它，「是否有头像」等价于 + `avatarUrl != null`。 operationId: me security: - bearerAuth: [] @@ -320,6 +376,66 @@ paths: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' + patch: + tags: [user] + summary: 更新当前用户资料（昵称 / 头像，三态部分更新） + description: | + 本人资料的唯一写入口（主体恒为 token 里的调用者，无「他人」情形）。 + + - **三态语义**：键缺省 = 不改；键出现且为 `null` = 清空；键出现且有值 = 设置。 + - **空 patch 400/40000**（两字段都未出现，含只带未声明字段）：不静默 200， + 空 PATCH 几乎总是客户端 bug。纯空白/空串昵称同为 400/40000，不隐式清空。 + - `avatarAssetId` 须为**调用者本人、用途为 `user_avatar`、状态 `ready`** 的 asset： + 不存在/非本人/已删/用途不符 404/40405；本人且用途相符但 uploading/failed + 422/42203。 + - **无 `version` 乐观锁、无 `Idempotency-Key`**：只有一个合法写者；丢失更新由 + 列级选择性 UPDATE 排除（并发改不同字段两者皆存活），同 body 重放天然幂等。 + - 成功返回**与 GET 完全相同的 `Me` 全量形态**（回显更新后资料，`avatarUrl` 现签）。 + operationId: updateMe + security: + - bearerAuth: [] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateMeRequest' + responses: + '200': + description: 更新成功，返回更新后的完整 Me + content: + application/json: + schema: + $ref: '#/components/schemas/MeEnvelope' + '400': + description: | + 参数校验失败（code 40000）：空 patch、昵称 btrim 后长度不在 1~32 码点、 + 昵称纯空白或空串、`avatarAssetId` 非法 UUID、body 非法 JSON + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorEnvelope' + examples: + emptyPatch: + value: { code: 40000, message: 请求未包含任何可更新字段, data: null } + '401': + $ref: '#/components/responses/AccessTokenInvalid' + '404': + description: | + 用户不存在或已注销（code 40400，token 仍有效但账号已注销）；或 + `avatarAssetId` 引用的 asset 不存在/非本人/已删/用途不是 `user_avatar` + （code 40405，防枚举合并） + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorEnvelope' + examples: + userNotFound: + value: { code: 40400, message: 用户不存在, data: null } + mediaNotFound: + value: { code: 40405, message: 媒体资源不存在, data: null } + '422': + $ref: '#/components/responses/MediaNotReady' /api/v1/events: post: @@ -468,18 +584,32 @@ paths: $ref: '#/components/responses/PetNotFound' patch: tags: [pets] - summary: 更新宠物档案 + summary: 更新宠物档案（含头像） description: | - 权限档：MANAGE（**仅 owner**）；caregiver/viewer 更新得 403/40300。 + 权限档**按本次请求触及的字段定档**（M3.5 起，ADR-022）： - - 部分更新：缺席字段不变；**不支持将可选字段清空回 null**。 + | 请求体触及 | 所需档位 | caregiver | viewer | + | --- | --- | --- | --- | + | 仅 `avatarAssetId`（+ `version`） | WRITE | ✅ | ✗ 403/40300 | + | 任一资料字段（name/sex/status/…） | MANAGE（仅 owner） | ✗ 403/40300 | ✗ 403/40300 | + | 资料字段 + `avatarAssetId` 混合 | MANAGE（**取更严的一半**） | ✗ 403/40300 | ✗ 403/40300 | + + 混合请求取更严，是为了堵住「夹带」——否则 caregiver 可把改名塞进头像请求绕过 MANAGE。 + + - 部分更新：缺席字段不变；资料字段**不支持清空回 null**（M2 语义不回改）。 + - **例外：`avatarAssetId` 是本端点唯一的三态字段**（M3.5）——键缺省 = 不改； + 键出现且为 `null` = **清除头像**；键出现且有值 = 设置。差异刻意限定在有清空 + 需求的字段上。 - 例外：品种对（`breedId`/`customBreedName`）**整体替换**——提交任一侧即替换 整对，互斥校验同创建。 - `species` 不可改（创建即定，避免与品种配对失效，请求体不含该字段）。 - `status` 可迁移至 active/lost/deceased/archived；**`deleted` 不可经 PATCH 设置**（400/40000，软删除留待专用端点，M2 契约不含）。 - - `version` 必填（缺失 400/40000），比对通过才写入并 +1；过期 409/40902。 + - `version` **必填**（缺失 400/40000），即便只改头像；比对通过才写入并 +1； + 过期 409/40902。头像与资料共用同一把乐观锁——头像变更也应让并发编辑者感知行已变。 - 芯片号改为已被登记的值：409/40903。 + - `avatarAssetId` 须为**调用者本人、用途为 `pet_avatar`、状态 `ready`** 的 asset： + 不存在/非本人/已删/用途不符 404/40405；本人且用途相符但 uploading/failed 422/42203。 operationId: updatePet security: - bearerAuth: [] @@ -505,7 +635,19 @@ paths: '403': $ref: '#/components/responses/PetWriteDenied' '404': - $ref: '#/components/responses/PetNotFound' + description: | + 宠物不存在、已软删除或调用者与宠物无关系（code 40401，防枚举合并）；或 + `avatarAssetId` 引用的 asset 不存在/非本人/已删/用途不是 `pet_avatar` + （code 40405，防枚举合并） + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorEnvelope' + examples: + petNotFound: + value: { code: 40401, message: 宠物不存在, data: null } + mediaNotFound: + value: { code: 40405, message: 媒体资源不存在, data: null } '409': description: 版本冲突（code 40902）或芯片号已被登记（code 40903） content: @@ -517,6 +659,8 @@ paths: value: { code: 40902, message: 数据已被修改，请刷新后重试, data: null } microchipExists: value: { code: 40903, message: 芯片号已被登记, data: null } + '422': + $ref: '#/components/responses/MediaNotReady' /api/v1/breeds: get: @@ -1201,7 +1345,7 @@ paths: petNotFound: value: { code: 40401, message: 宠物不存在, data: null } mediaNotFound: - value: { code: 40405, message: 媒体不存在, data: null } + value: { code: 40405, message: 媒体资源不存在, data: null } '409': $ref: '#/components/responses/IdempotencyPayloadMismatch' '422': @@ -1284,7 +1428,7 @@ paths: petNotFound: value: { code: 40401, message: 宠物不存在, data: null } mediaNotFound: - value: { code: 40405, message: 媒体不存在, data: null } + value: { code: 40405, message: 媒体资源不存在, data: null } '409': $ref: '#/components/responses/VersionConflict' '422': @@ -1348,6 +1492,35 @@ paths: '401': $ref: '#/components/responses/AccessTokenInvalid' + /api/v1/me/community-stats: + get: + tags: [posts] + summary: 我的社区数字（获赞总数 / 作品数） + description: | + 主体恒为 token 里的调用者：无查询参数、无路径参数，**路径上没有 userId**—— + 「查不到别人的获赞」不靠权限判断，而是入口本身不存在。 + + - **统计集合 = 本人的、`status='published'` 的、`deleted_at IS NULL` 的帖**。 + 草稿不计（尚非作品，且未发布不可被赞）；软删不计（删帖即撤回其数字，与 + `/me/posts`、Feed 的可见性一致）；运营态 hidden/archived 不计（对所有人不可见， + 含作者本人）；他人帖自然不计。 + - **自己赞自己计入**——与帖子详情页的 `likeCount` 保持同一口径，两处数字必须能对上。 + - `receivedLikeCount` = 该集合的 `like_count` 之和（读侧实时聚合，读的是写侧同事务 + 维护的帖级冗余列，故为精确值而非估算；ADR-022 不引入按人累计的冗余列）。 + - **空数据返回 `0` 而非 null**，且**永不 404**：任何已认证用户都有 stats。 + operationId: getMyCommunityStats + security: + - bearerAuth: [] + responses: + '200': + description: 我的获赞总数与作品数 + content: + application/json: + schema: + $ref: '#/components/schemas/CommunityStatsEnvelope' + '401': + $ref: '#/components/responses/AccessTokenInvalid' + /api/v1/feed: get: tags: [feed] @@ -1812,8 +1985,9 @@ components: value: { code: 40402, message: 记录不存在, data: null } PetWriteDenied: description: | - 对可见宠物无相应操作权限（code 40300）：viewer 写记录、caregiver/viewer 改 - 宠物档案。仅发给对宠物「可见」的调用者，不泄露新信息。 + 对可见宠物无相应操作权限（code 40300）：viewer 写记录或改头像、caregiver/viewer + 改宠物档案的资料字段（caregiver 仅改 `avatarAssetId` 时允许，M3.5 按字段分档）。 + 仅发给对宠物「可见」的调用者，不泄露新信息。 content: application/json: schema: @@ -1854,14 +2028,16 @@ components: commentNotFound: value: { code: 40404, message: 评论不存在, data: null } MediaNotFound: - description: asset 不存在、非本人所有或已删（code 40405，防枚举合并） + description: | + asset 不存在、非本人所有、已删，或**用途与引用场景不符**（code 40405，防枚举合并）。 + 用途不符即「从头像域看，一张帖子配图不是头像」；两种头像用途亦互不通用。 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: mediaNotFound: - value: { code: 40405, message: 媒体不存在, data: null } + value: { code: 40405, message: 媒体资源不存在, data: null } UserNotFound: description: 目标用户不存在或已注销（code 40406，合并不泄露成因） content: @@ -2001,8 +2177,10 @@ components: Me: type: object - description: 当前用户资料（冻结契约，恰好这 4 个字段） - required: [userId, username, createdAt] + description: | + 本人资料（`GET` 与 `PATCH /api/v1/me` 的统一响应形态，冻结契约恰好这 6 个字段）。 + **不含** `avatarAssetId`：客户端只写不读它，「是否有头像」等价于 `avatarUrl != null`。 + required: [userId, username, nickname, avatarUrl, createdAt] properties: userId: type: string @@ -2011,16 +2189,65 @@ components: username: type: string example: demo_user + nickname: + type: string + nullable: true + minLength: 1 + maxLength: 32 + description: | + 昵称，**DB 原值**；未设置为 null（键恒在）。长度按**码点**计 1~32（btrim 后）。 + **本端点不做 username 回退**——`/me` 是本人编辑态，回退会把展示约定固化成 + 真实数据；本人视角的展示回退由客户端做 `nickname ?? username`，他人视角的 + 回退在 `/internal/users/profiles`（SQL COALESCE，不属本公开契约）。 + 不设唯一约束（ADR-022，允许重名）。 + example: 小柴 phone: type: string nullable: true description: E.164；未绑定时为 null example: '+8613800138000' + avatarUrl: + type: string + nullable: true + description: | + 头像访问 URL——时效性预签名 GET（TTL 默认 1 小时，配置项），每次响应现签， + **客户端不得持久化、过期即重取**；桶保持私有，无签名直访被拒。 + 无头像、asset 非 ready、对象存储未配置三种情况均为 null（键恒在）。 + example: https://minio.example.com/patbond-media/user_avatar/2026/09/019212aa…?X-Amz-Signature=… createdAt: type: string format: date-time example: '2026-09-04T04:05:06.789Z' + UpdateMeRequest: + type: object + description: | + 本人资料部分更新（**三态语义**，与 pets 域 M2 的两态刻意不同）： + **键缺省 = 不改；键出现且为 `null` = 清空；键出现且有值 = 设置**。 + 两字段都未出现（含只带未声明字段）为**空 patch**，答 400/40000 而非静默 200。 + 无必填字段、无 `version` 乐观锁、无 `Idempotency-Key`（同 body 重放天然幂等）。 + properties: + nickname: + type: string + nullable: true + minLength: 1 + maxLength: 32 + description: | + 昵称；btrim 后长度按**码点**计须在 1~32，否则 400/40000。 + 显式 `null` = **清空昵称**；纯空白或空串是 400/40000，**不是隐式清空** + （清空只留显式 null 一条路，否则「误提交空格」与「想删昵称」无法区分）。 + example: 小柴 + avatarAssetId: + type: string + format: uuid + nullable: true + description: | + 头像 asset ID（两步上传的产物，`purpose` 须为 `user_avatar`）。 + 显式 `null` = **清除头像**。校验：不存在/非本人/已删/用途不符 404/40405； + 本人且用途相符但 uploading/failed 422/42203；非法 UUID 400/40000。 + **响应不回显该字段**（只写不读）。 + example: 019212bb-0000-7000-8000-000000000009 + AuthTokenEnvelope: type: object required: [code, message] @@ -2226,7 +2453,8 @@ components: `breedId` 与 `customBreedName` 恰有其一非空（ck_pets_breed）； `breedDisplayName` 由品种字典解出，随 breedId 存在。 软删除态（deleted）的宠物在全部端点表现为 404/40401，本 schema 的 - status 永不出现 deleted。`avatarAssetId` 不出现在 M2 契约（ADR-010）。 + status 永不出现 deleted。头像以 `avatarUrl` 的现签形式返回， + **`avatarAssetId` 不外露**（只写不读，写入口为 `PATCH /api/v1/pets/{petId}`）。 required: - id - name @@ -2234,6 +2462,7 @@ components: - sex - birthDateEstimated - status + - avatarUrl - myRole - createdAt - updatedAt @@ -2294,6 +2523,15 @@ components: type: string enum: [active, lost, deceased, archived] description: 状态（deleted 为内部软删态，接口永不返回；软删宠物一律 404/40401） + avatarUrl: + type: string + nullable: true + description: | + 宠物头像访问 URL——时效性预签名 GET（TTL 默认 1 小时，配置项），每次响应现签， + **客户端不得持久化、过期即重取**；桶保持私有，无签名直访被拒。 + 无头像、asset 非 ready、对象存储未配置三种情况均为 null（键恒在）。 + asset 事后退出 ready 时转 null 而引用保留（读请求不做写副作用）。 + example: https://minio.example.com/patbond-media/pet_avatar/2026/09/019212cc…?X-Amz-Signature=… myRole: type: string enum: [owner, caregiver, viewer] @@ -2351,14 +2589,18 @@ components: UpdatePetRequest: type: object description: | - 部分更新：缺席字段不变；不支持清空回 null。例外：品种对 + 部分更新：缺席字段不变；资料字段不支持清空回 null。例外：品种对 （breedId/customBreedName）整体替换——提交任一侧即替换整对，互斥校验同创建。 species 不可改（不在请求体）。 + **`avatarAssetId` 是本 schema 唯一的三态字段**（M3.5）：键缺省 = 不改； + 键出现且为 `null` = 清除头像；键出现且有值 = 设置。其余字段保持 M2 两态语义。 + 权限档按本次触及的字段决定（仅头像 → WRITE；触及资料字段 → MANAGE；混合取更严）， + 见端点描述。 required: [version] properties: version: type: integer - description: 当前持有的版本号（乐观锁，必填；缺失 400/40000，过期 409/40902） + description: 当前持有的版本号（乐观锁，必填；缺失 400/40000，过期 409/40902）；即便只改头像也必带 name: type: string minLength: 1 @@ -2393,6 +2635,16 @@ components: type: string enum: [active, lost, deceased, archived] description: 状态流转；deleted 不可经 PATCH 设置（400/40000） + avatarAssetId: + type: string + format: uuid + nullable: true + description: | + 宠物头像 asset ID（两步上传的产物，`purpose` 须为 `pet_avatar`）。 + **三态**：缺省 = 不改；显式 `null` = 清除头像；给值 = 设置。校验：不存在/ + 非本人/已删/用途不符 404/40405；本人且用途相符但 uploading/failed 422/42203； + 非法 UUID 400/40000。**响应不回显该字段**（只写不读，读取见 `Pet.avatarUrl`）。 + example: 019212cc-0000-7000-8000-00000000000a PetEnvelope: type: object @@ -3205,10 +3457,13 @@ components: description: M3 仅 image（ADR-018 视频后置；video/document 为向后新增枚举预留） purpose: type: string - enum: [post_image] + enum: [post_image, user_avatar, pet_avatar] description: | - 用途白名单（M3 定型仅 post_image，决定 objectKey 前缀）；P6 扩 - user_avatar/pet_avatar 时为向后兼容的枚举追加（服务端纯配置扩展） + 用途白名单（服务端配置项 `patbond.media.allowed-purposes`，决定 objectKey 前缀 + `/yyyy/MM/{assetId}`）。M3.5 起为三值：`post_image`（帖子配图）、 + `user_avatar`（用户头像）、`pet_avatar`（宠物头像）——相对 M3 的纯枚举追加。 + **用途即引用侧的类型检查**：引用时校验 `purpose` 相符，故帖图不能当头像、 + 两种头像也互不通用（不符者 404/40405）。白名单外的取值 400/40000。 mimeType: type: string enum: [image/jpeg, image/png, image/webp] @@ -3857,3 +4112,36 @@ components: example: success data: $ref: '#/components/schemas/FollowStats' + + CommunityStats: + type: object + description: | + 调用者本人的社区数字（M3.5）。两数同一集合：本人的、`status='published'` 的、 + 未软删的帖（草稿 / 软删 / hidden / archived 均不计）。读侧实时聚合，无冗余计数列。 + required: [receivedLikeCount, publishedPostCount] + properties: + receivedLikeCount: + type: integer + format: int64 + description: | + 获赞总数 = 该集合的 `like_count` 之和（写侧同事务维护的帖级冗余列，精确值）。 + **自己赞自己计入**，与帖子详情的 `likeCount` 同一口径。空数据为 0，非 null。 + example: 128 + publishedPostCount: + type: integer + format: int64 + description: 作品数 = 该集合的帖子数。空数据为 0，非 null。 + example: 12 + + CommunityStatsEnvelope: + type: object + required: [code, message, data] + properties: + code: + type: integer + enum: [0] + message: + type: string + example: success + data: + $ref: '#/components/schemas/CommunityStats' diff --git a/patbond-community/src/test/java/com/patbond/patbond/community/contract/CommunityContractConformanceTest.java b/patbond-community/src/test/java/com/patbond/patbond/community/contract/CommunityContractConformanceTest.java index 565e1e5..ba37284 100644 --- a/patbond-community/src/test/java/com/patbond/patbond/community/contract/CommunityContractConformanceTest.java +++ b/patbond-community/src/test/java/com/patbond/patbond/community/contract/CommunityContractConformanceTest.java @@ -28,20 +28,21 @@ import static org.springframework.test.web.servlet.request.MockMvcRequestBuilder import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.request; /** - * T3-20（M3 第二波收尾）：community 域 17 个操作补进契约一致性保障，机制与 - * patbond-pet 的 ContractConformanceTest 同构——对冻结契约 v1.3.0（快照 - * {@code src/test/resources/contract/openapi-v1.3.0.yaml}，正典在 doc 仓 + * T3-20（M3 第二波收尾）：community 域 18 个操作补进契约一致性保障，机制与 + * patbond-pet 的 ContractConformanceTest 同构——对冻结契约 v1.4.0（快照 + * {@code src/test/resources/contract/openapi-v1.4.0.yaml}，正典在 doc 仓 * {@code docs/api/openapi.yaml}）逐操作真实起服务发请求，用 * {@link ContractValidator} 严格校验响应结构：路径/方法/状态码已声明、字段名 * 与类型、必填与 nullable、枚举与格式、信封结构、错误码值。 * *

覆盖目标是**全响应矩阵**：最后的 {@link #everyDeclaredResponseCellIsExercised()} - * 断言契约为这 17 个操作声明的每一个 (操作, 状态码) 单元格（共 64 格）都被 + * 断言契约为这 18 个操作声明的每一个 (操作, 状态码) 单元格（共 66 格）都被 * 至少一次真实响应校验过，**无豁免**——community 域的 409 均为幂等键/乐观锁 * 冲突、422 均为业务规则拒绝，单线程即可确定性触发。 * *

media 域 2 个操作属 patbond-user 模块，由该模块的 - * MediaContractConformanceTest 覆盖（快照同一份）。 + * MediaContractConformanceTest 覆盖；auth/user 域 7 操作在 patbond-auth + * （含 v1.4.0 新增的 PATCH /api/v1/me）。快照四模块同一份。 */ @TestMethodOrder(MethodOrderer.OrderAnnotation.class) class CommunityContractConformanceTest extends PostApiTestBase { @@ -52,7 +53,7 @@ class CommunityContractConformanceTest extends PostApiTestBase { /** 已被真实响应校验过的 (操作, 状态码) 单元格，如 "GET /api/v1/feed 200"。 */ private static final Set COVERED = ConcurrentHashMap.newKeySet(); - /** community 域 17 个操作（= 契约中 tags ∈ {posts, feed, comments, interactions, follows}）。 */ + /** community 域 18 个操作（= 契约中 tags ∈ {posts, feed, comments, interactions, follows}）。 */ private static final List COMMUNITY_OPERATIONS = List.of( "POST /api/v1/posts", "GET /api/v1/posts/{postId}", @@ -70,7 +71,8 @@ class CommunityContractConformanceTest extends PostApiTestBase { "GET /api/v1/me/bookmarks", "PUT /api/v1/users/{userId}/follow", "DELETE /api/v1/users/{userId}/follow", - "GET /api/v1/users/{userId}/follow-stats"); + "GET /api/v1/users/{userId}/follow-stats", + "GET /api/v1/me/community-stats"); private static final String IDEMPOTENCY_KEY = "Idempotency-Key"; @@ -127,7 +129,7 @@ class CommunityContractConformanceTest extends PostApiTestBase { return JsonPath.read(created, "$.data.id"); } - // ---- 成功路径：17 操作全覆盖 --------------------------------------- + // ---- 成功路径：18 操作全覆盖 --------------------------------------- @Test @Order(1) @@ -299,6 +301,43 @@ class CommunityContractConformanceTest extends PostApiTestBase { assertThat((Boolean) JsonPath.read(unfollowedAgain, "$.data.following")).isFalse(); } + /** + * `GET /api/v1/me/community-stats`（v1.4.0 新增操作，T3.5-07）：空数据零值 + * 与有数据两个分支都过严格校验。**永不 404**，故本操作只有 200/401 两格 + * （401 由 {@link #unauthenticatedRequestsAnswer40101OnAllOperations()} 的 + * 全操作循环覆盖）。 + */ + @Test + @Order(51) + void myCommunityStatsSuccessShapes() throws Exception { + UUID fresh = newUser(); + + // 空数据：两数为 0 而非 null，且不是 404 + String zeros = verified(get("/api/v1/me/community-stats") + .header("Authorization", "Bearer " + token(fresh)), + "GET", "/api/v1/me/community-stats", 200); + assertThat(((Number) JsonPath.read(zeros, "$.data.receivedLikeCount")).longValue()) + .isZero(); + assertThat(((Number) JsonPath.read(zeros, "$.data.publishedPostCount")).longValue()) + .isZero(); + + // 有数据：两篇已发布帖，其中一篇被他人赞一次 → 1 赞 / 2 作品 + UUID author = newUser(); + UUID fan = newUser(); + String postA = newPublishedPost(author, "契约统计帖甲"); + newPublishedPost(author, "契约统计帖乙"); + verified(authed(put("/api/v1/posts/{postId}/like", postA), fan), + "PUT", "/api/v1/posts/{postId}/like", 200); + + String counted = verified(get("/api/v1/me/community-stats") + .header("Authorization", "Bearer " + token(author)), + "GET", "/api/v1/me/community-stats", 200); + assertThat(((Number) JsonPath.read(counted, "$.data.receivedLikeCount")).longValue()) + .isEqualTo(1L); + assertThat(((Number) JsonPath.read(counted, "$.data.publishedPostCount")).longValue()) + .isEqualTo(2L); + } + // ---- 错误信封 ------------------------------------------------------ @Test @@ -482,18 +521,18 @@ class CommunityContractConformanceTest extends PostApiTestBase { @Test @Order(98) void frozenSnapshotIsTheExpectedContractVersion() { - assertThat(CONTRACT.version()).isEqualTo("1.3.0"); - assertThat(CONTRACT.paths()).hasSize(31); - assertThat(CONTRACT.operations()).hasSize(43); - assertThat(CONTRACT.schemas()).hasSize(72); + assertThat(CONTRACT.version()).isEqualTo("1.4.0"); + assertThat(CONTRACT.paths()).hasSize(32); + assertThat(CONTRACT.operations()).hasSize(45); + assertThat(CONTRACT.schemas()).hasSize(75); assertThat(CONTRACT.operationsTagged( Set.of("posts", "feed", "comments", "interactions", "follows"))) .containsExactlyInAnyOrderElementsOf(COMMUNITY_OPERATIONS); } /** - * 全矩阵覆盖门禁：community 域 17 个操作声明的每个 (操作, 状态码) 都必须被 - * 前面的测试真实触发并通过契约校验（64 个单元格，无豁免）。 + * 全矩阵覆盖门禁：community 域 18 个操作声明的每个 (操作, 状态码) 都必须被 + * 前面的测试真实触发并通过契约校验（66 个单元格，无豁免）。 */ @Test @Order(99) diff --git a/patbond-community/src/test/java/com/patbond/patbond/community/contract/OpenApiContract.java b/patbond-community/src/test/java/com/patbond/patbond/community/contract/OpenApiContract.java index 7e6a966..dd78440 100644 --- a/patbond-community/src/test/java/com/patbond/patbond/community/contract/OpenApiContract.java +++ b/patbond-community/src/test/java/com/patbond/patbond/community/contract/OpenApiContract.java @@ -13,8 +13,8 @@ import java.util.Objects; import java.util.Set; /** - * The frozen v1.3.0 OpenAPI contract, loaded from the test-resource snapshot - * {@code /contract/openapi-v1.3.0.yaml}. + * The frozen v1.4.0 OpenAPI contract, loaded from the test-resource snapshot + * {@code /contract/openapi-v1.4.0.yaml}. * *

Sync discipline (T2-09, extended by T3-19): the canonical * contract lives in the doc repo at {@code docs/api/openapi.yaml}; this @@ -36,7 +36,7 @@ import java.util.Set; */ final class OpenApiContract { - static final String RESOURCE = "/contract/openapi-v1.3.0.yaml"; + static final String RESOURCE = "/contract/openapi-v1.4.0.yaml"; private static final Set HTTP_METHODS = Set.of("get", "put", "post", "delete", "options", "head", "patch", "trace"); diff --git a/patbond-community/src/test/resources/contract/openapi-v1.3.0.yaml b/patbond-community/src/test/resources/contract/openapi-v1.4.0.yaml similarity index 87% rename from patbond-community/src/test/resources/contract/openapi-v1.3.0.yaml rename to patbond-community/src/test/resources/contract/openapi-v1.4.0.yaml index c9d3072..d669f33 100644 --- a/patbond-community/src/test/resources/contract/openapi-v1.3.0.yaml +++ b/patbond-community/src/test/resources/contract/openapi-v1.4.0.yaml @@ -1,7 +1,7 @@ openapi: 3.0.3 info: title: Patbond API — Auth / Me / Events / Pets / Community / Media（公开契约） - version: 1.3.0 + version: 1.4.0 description: | Patbond 第一迭代「真实登录纵切」公开契约（冻结稿的正式化，字段与草案零偏差）， 1.1.0 追加埋点上报端点 `POST /api/v1/events`（M2 第一波契约补录，以实现实测行为为准）。 @@ -11,6 +11,14 @@ info: **1.3.0 M3 契约冻结：community/media 域 13 路径**（媒体两步上传、帖子生命周期、 公共 Feed、单层评论、点赞/收藏/关注最小接口）按第二波已定型实现合入 （iteration-3 报告 13/15/16/17 定型表；冻结报告见 iteration-3/18）。 + **1.4.0 M3.5 契约冻结：用户资料与头像**——`GET /api/v1/me` 补 `nickname`/`avatarUrl`， + 新增 `PATCH /api/v1/me`（昵称与头像读写，三态部分更新），`Pet` 补 `avatarUrl` 且 + `PATCH /api/v1/pets/{petId}` 收 `avatarAssetId`，新增 `GET /api/v1/me/community-stats` + （获赞总数与作品数），媒体 `purpose` 白名单追加 `user_avatar`/`pet_avatar` + （iteration-3.5 报告 03 定型表；冻结报告见 iteration-3.5/04）。 + **1.4.0 相对 1.3.0 纯增量**：无字段删改、无类型变更、无必填收紧，仅新增操作、 + 新增响应字段（键恒在、值可空）、新增可选请求字段、新增响应格与枚举追加， + v1.3.0 客户端无需改动即可继续工作。 ## 通用约定（development-plan 第 6 节） - 公开接口统一前缀 `/api/v1`；JSON 字段一律 `camelCase`；资源 ID 为 UUID 字符串。 @@ -29,14 +37,14 @@ info: | 40100 | 401 | 用户名或密码错误 | | 40101 | 401 | access token 无效或过期（缺失、伪造、篡改、过期） | | 40102 | 401 | refresh token 已失效或被重用（未知、过期、已轮换、已退出、家族已撤销） | - | 40300 | 403 | PET_ACCESS_DENIED：对可见宠物无相应操作权限（viewer 写记录、caregiver 改宠物档案） | + | 40300 | 403 | PET_ACCESS_DENIED：对可见宠物无相应操作权限（viewer 写记录或改头像、caregiver 改宠物档案——头像除外，见 M3.5 分档） | | 40301 | 403 | POST_ACCESS_DENIED：对可见帖子/评论无相应操作权限（改删他人已发布帖、删他人可见评论——含帖主）；仅发给对资源「可见」的调用者 | | 40400 | 404 | 资源不存在 | | 40401 | 404 | PET_NOT_FOUND：宠物不存在、已软删除或调用者与宠物无关系（防枚举，三种情况响应完全一致） | | 40402 | 404 | RECORD_NOT_FOUND：顶层记录路径下记录不存在或所属宠物对调用者不可见（记录级防枚举，两种情况响应完全一致） | | 40403 | 404 | POST_NOT_FOUND：帖子不存在、已软删、hidden/archived（作者同样）或他人 draft（防枚举，全部情况响应完全一致）；评论与互动路径上含作者本人草稿 | | 40404 | 404 | COMMENT_NOT_FOUND：评论不存在、已删或所属帖子不可见（防枚举合并） | - | 40405 | 404 | MEDIA_NOT_FOUND：asset 不存在、非本人所有或已删（防枚举合并） | + | 40405 | 404 | MEDIA_NOT_FOUND：asset 不存在、非本人所有、已删，或**用途与引用场景不符**（帖图当头像、user_avatar 当宠物头像等）；防枚举合并，同码各情形响应一致（用途不符分支只对调用者自己的 asset 可达，故 message 可具体） | | 40406 | 404 | USER_NOT_FOUND：目标用户不存在或已注销（关注端点与评论 replyToUserId；不复用 40400——该码已承担「路由级资源不存在」兜底语义，复用会使二者不可区分） | | 40900 | 409 | 用户名已存在（大小写不敏感） | | 40901 | 409 | 手机号已被使用 | @@ -46,7 +54,7 @@ info: | 40905 | 409 | IDEMPOTENCY_PAYLOAD_MISMATCH：同 Idempotency-Key 不同 payload（规范化 request_hash 不符，community 域创建型写入） | | 42201 | 422 | VACCINATION_RULE_VIOLATION：疫苗状态机非法迁移或状态-日期规则违反 | | 42202 | 422 | REMINDER_RULE_VIOLATION：提醒状态机非法迁移或 completed-completedAt 一致性违反 | - | 42203 | 422 | MEDIA_NOT_READY：引用了本人所有但非 ready（uploading/failed）状态的 asset | + | 42203 | 422 | MEDIA_NOT_READY：引用了本人所有、用途相符但非 ready（uploading/failed）状态的 asset（帖图与用户/宠物头像同构） | | 42204 | 422 | FOLLOW_RULE_VIOLATION：自关注（仅 PUT；自取关为 200 幂等 no-op） | | 42205 | 422 | MEDIA_UPLOAD_STATE_INVALID：complete 时 asset 非 uploading——对象未上传保持可重试、大小/类型不符置 failed 终态、failed 态再确认；已 ready 幂等 200 除外 | | 42300 | 423 | 登录失败次数过多，账号已临时锁定（见下） | @@ -68,7 +76,10 @@ info: - **权限模型（ADR-015：owner/caregiver/viewer 三角色，pet_owners 表）**，操作分三档： - `READ`——三角色皆可：宠物详情/列表、各记录列表、档案摘要； - `WRITE`——owner + caregiver：体重/疫苗/健康事件/提醒的 POST 与 PATCH； - - `MANAGE`——仅 owner：宠物档案 PATCH（含状态流转）。 + **M3.5 起还含宠物头像字段 `avatarAssetId`**（ADR-022：头像属日常照护信息）。 + - `MANAGE`——仅 owner：宠物档案 PATCH 的资料字段（含状态流转）。 + **同一端点按「本次请求触及哪些字段」定档**（不是端点级降档）：仅改头像走 WRITE， + 触及任一资料字段走 MANAGE，混合请求取更严的一半。 权限每请求实时查库、无缓存：撤销照护关系立即生效。 - **防枚举语义**：宠物不存在、已软删除、调用者与宠物无 pet_owners 关系三种情况 响应完全一致（404/40401），GET 与写操作一致适用；顶层记录路径下「记录不存在」与 @@ -126,6 +137,41 @@ info: 整体不出现，后续按新增可选字段/端点纯增量补入。`/internal/**` 服务间接口 （如作者公开资料批量接口）不属于本公开契约。 + ## 用户资料与头像域约定（M3.5 冻结，iteration-3.5 报告 03 定型；ADR-022） + - **三态部分更新（仅本域，pets 域 M2 两态语义不回改）**：`PATCH /api/v1/me` 的 + `nickname`/`avatarAssetId` 与 `PATCH /api/v1/pets/{petId}` 的 `avatarAssetId` + 按三态解释——**键缺省 = 不改；键出现且为 `null` = 清空；键出现且有值 = 设置**。 + 昵称与头像天生可选，「删掉我设的那个」是一等公民操作，只有两态无法表达。 + 同一请求体内的其余 pets 字段仍是 M2 的「缺省或 null 皆为不改」。 + - **空 PATCH 与纯空白昵称一律 400/40000**，不静默 200、不隐式清空：清空只留 + 显式 `null` 一条路，否则「误提交空格」与「想删昵称」无法区分。 + - **昵称**：btrim 后 1~32 **码点**（非 UTF-16 长度）；**不设唯一约束**（ADR-022， + 允许重名，靠 userId 区分）；注册不收昵称。`/api/v1/me` 返回 **DB 原值**， + 未设置即 `null`，**不做 username 回退**——`/me` 是本人编辑态，回退会把展示约定 + 固化成真实数据；他人视角的展示回退在 `/internal/users/profiles`（SQL COALESCE）， + 本人视角的展示回退由客户端做 `nickname ?? username`。 + - **头像读取一律 `avatarUrl`（时效性预签名 GET，与帖图同一纪律）**：每次响应现签， + **会过期、客户端不得持久化**，过期即重取；无头像、asset 非 ready、对象存储未配置 + 三种情况均为 `null`（降级而非报错——签一个必然 404 的 URL 比给 null 更糟）。 + 指针不隐式清理：asset 事后退出 ready 时 `avatarUrl` 转 null 而引用保留。 + - **`avatarAssetId` 只写不读**：请求体收，响应**一律不外露**（`Me` 与 `Pet` 皆无该字段）； + 「是否有头像」等价于 `avatarUrl != null`。 + - **两种头像用途互不通用**：`user_avatar` 不能当宠物头像、`pet_avatar` 不能当用户头像、 + `post_image` 不能当任何头像——引用侧按 `purpose` 校验，不符者 404/40405 + （四态校验：不存在/非本人/已删/用途不符 → 404/40405；本人且用途相符但 + uploading/failed → 422/42203）。 + - **宠物头像的权限档按「本次请求碰了哪些字段」定档**（ADR-022 头像为 WRITE 档）： + 仅改 `avatarAssetId` 时 owner + caregiver 皆可（viewer 403/40300）；触及任一资料 + 字段时仍是 MANAGE（仅 owner）；**混合请求取更严的一半**，堵住把改名夹带进头像 + 请求绕过 MANAGE 的路径。头像与资料共用同一把乐观锁 `version`（仍必填）。 + - **`/api/v1/me` 无乐观锁、无幂等键**：只有一个合法写者（账号本人），暴露 `version` + 只是给客户端加负担；丢失更新由**列级选择性 UPDATE** 排除（SET 列表只含本次请求 + 真正携带的列），并发改不同字段两者皆存活；同 body 重放天然幂等。 + - **`GET /api/v1/me/community-stats` 为独立端点**（ADR-022 决策 A，不并入 + `/users/{userId}/follow-stats`——后者主体是「某用户的关注数」，混入「我的获赞」 + 会让一个载荷有两个主体）。路径上**没有 userId**：「查不到别人的获赞」不靠权限 + 判断，而是入口本身不存在，故**永不 404**，任何已认证用户都有 stats。 + servers: - url: http://127.0.0.1:8081 description: patbond-auth（本地开发，/api/v1/auth/**） @@ -140,7 +186,7 @@ tags: - name: auth description: 注册 / 登录 / 刷新 / 退出（patbond-auth） - name: user - description: 当前用户（patbond-user） + description: 当前用户资料：读取与昵称/头像更新（patbond-user） - name: analytics description: 产品事件批量上报（patbond-user） - name: pets @@ -152,7 +198,9 @@ tags: - name: media description: 媒体上传两步流程（patbond-user，ADR-016 预签名直传） - name: posts - description: 帖子生命周期：草稿/编辑/发布/删除/详情/我的帖子（patbond-community） + description: | + 帖子生命周期：草稿/编辑/发布/删除/详情/我的帖子；含由帖子派生的「我的社区数字」 + 聚合（patbond-community） - name: feed description: 公共 Feed 游标分页（patbond-community） - name: comments @@ -301,7 +349,15 @@ paths: get: tags: [user] summary: 当前用户资料 - description: 由 patbond-user 提供；access token 以 RS256 公钥本地验签，无需经过 auth 服务。 + description: | + 由 patbond-user 提供；access token 以 RS256 公钥本地验签，无需经过 auth 服务。 + + - `nickname` 为 **DB 原值**，未设置即 `null`（**不做 username 回退**，见 info + 「用户资料与头像域约定」）；本人视角的展示回退由客户端做 `nickname ?? username`。 + - `avatarUrl` 为**每次响应现签的时效性预签名 GET**：**会过期、客户端不得持久化**， + 过期即重取；无头像、asset 非 ready、对象存储未配置均为 `null`。 + - 响应**不含** `avatarAssetId`：客户端只写不读它，「是否有头像」等价于 + `avatarUrl != null`。 operationId: me security: - bearerAuth: [] @@ -320,6 +376,66 @@ paths: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' + patch: + tags: [user] + summary: 更新当前用户资料（昵称 / 头像，三态部分更新） + description: | + 本人资料的唯一写入口（主体恒为 token 里的调用者，无「他人」情形）。 + + - **三态语义**：键缺省 = 不改；键出现且为 `null` = 清空；键出现且有值 = 设置。 + - **空 patch 400/40000**（两字段都未出现，含只带未声明字段）：不静默 200， + 空 PATCH 几乎总是客户端 bug。纯空白/空串昵称同为 400/40000，不隐式清空。 + - `avatarAssetId` 须为**调用者本人、用途为 `user_avatar`、状态 `ready`** 的 asset： + 不存在/非本人/已删/用途不符 404/40405；本人且用途相符但 uploading/failed + 422/42203。 + - **无 `version` 乐观锁、无 `Idempotency-Key`**：只有一个合法写者；丢失更新由 + 列级选择性 UPDATE 排除（并发改不同字段两者皆存活），同 body 重放天然幂等。 + - 成功返回**与 GET 完全相同的 `Me` 全量形态**（回显更新后资料，`avatarUrl` 现签）。 + operationId: updateMe + security: + - bearerAuth: [] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateMeRequest' + responses: + '200': + description: 更新成功，返回更新后的完整 Me + content: + application/json: + schema: + $ref: '#/components/schemas/MeEnvelope' + '400': + description: | + 参数校验失败（code 40000）：空 patch、昵称 btrim 后长度不在 1~32 码点、 + 昵称纯空白或空串、`avatarAssetId` 非法 UUID、body 非法 JSON + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorEnvelope' + examples: + emptyPatch: + value: { code: 40000, message: 请求未包含任何可更新字段, data: null } + '401': + $ref: '#/components/responses/AccessTokenInvalid' + '404': + description: | + 用户不存在或已注销（code 40400，token 仍有效但账号已注销）；或 + `avatarAssetId` 引用的 asset 不存在/非本人/已删/用途不是 `user_avatar` + （code 40405，防枚举合并） + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorEnvelope' + examples: + userNotFound: + value: { code: 40400, message: 用户不存在, data: null } + mediaNotFound: + value: { code: 40405, message: 媒体资源不存在, data: null } + '422': + $ref: '#/components/responses/MediaNotReady' /api/v1/events: post: @@ -468,18 +584,32 @@ paths: $ref: '#/components/responses/PetNotFound' patch: tags: [pets] - summary: 更新宠物档案 + summary: 更新宠物档案（含头像） description: | - 权限档：MANAGE（**仅 owner**）；caregiver/viewer 更新得 403/40300。 + 权限档**按本次请求触及的字段定档**（M3.5 起，ADR-022）： - - 部分更新：缺席字段不变；**不支持将可选字段清空回 null**。 + | 请求体触及 | 所需档位 | caregiver | viewer | + | --- | --- | --- | --- | + | 仅 `avatarAssetId`（+ `version`） | WRITE | ✅ | ✗ 403/40300 | + | 任一资料字段（name/sex/status/…） | MANAGE（仅 owner） | ✗ 403/40300 | ✗ 403/40300 | + | 资料字段 + `avatarAssetId` 混合 | MANAGE（**取更严的一半**） | ✗ 403/40300 | ✗ 403/40300 | + + 混合请求取更严，是为了堵住「夹带」——否则 caregiver 可把改名塞进头像请求绕过 MANAGE。 + + - 部分更新：缺席字段不变；资料字段**不支持清空回 null**（M2 语义不回改）。 + - **例外：`avatarAssetId` 是本端点唯一的三态字段**（M3.5）——键缺省 = 不改； + 键出现且为 `null` = **清除头像**；键出现且有值 = 设置。差异刻意限定在有清空 + 需求的字段上。 - 例外：品种对（`breedId`/`customBreedName`）**整体替换**——提交任一侧即替换 整对，互斥校验同创建。 - `species` 不可改（创建即定，避免与品种配对失效，请求体不含该字段）。 - `status` 可迁移至 active/lost/deceased/archived；**`deleted` 不可经 PATCH 设置**（400/40000，软删除留待专用端点，M2 契约不含）。 - - `version` 必填（缺失 400/40000），比对通过才写入并 +1；过期 409/40902。 + - `version` **必填**（缺失 400/40000），即便只改头像；比对通过才写入并 +1； + 过期 409/40902。头像与资料共用同一把乐观锁——头像变更也应让并发编辑者感知行已变。 - 芯片号改为已被登记的值：409/40903。 + - `avatarAssetId` 须为**调用者本人、用途为 `pet_avatar`、状态 `ready`** 的 asset： + 不存在/非本人/已删/用途不符 404/40405；本人且用途相符但 uploading/failed 422/42203。 operationId: updatePet security: - bearerAuth: [] @@ -505,7 +635,19 @@ paths: '403': $ref: '#/components/responses/PetWriteDenied' '404': - $ref: '#/components/responses/PetNotFound' + description: | + 宠物不存在、已软删除或调用者与宠物无关系（code 40401，防枚举合并）；或 + `avatarAssetId` 引用的 asset 不存在/非本人/已删/用途不是 `pet_avatar` + （code 40405，防枚举合并） + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorEnvelope' + examples: + petNotFound: + value: { code: 40401, message: 宠物不存在, data: null } + mediaNotFound: + value: { code: 40405, message: 媒体资源不存在, data: null } '409': description: 版本冲突（code 40902）或芯片号已被登记（code 40903） content: @@ -517,6 +659,8 @@ paths: value: { code: 40902, message: 数据已被修改，请刷新后重试, data: null } microchipExists: value: { code: 40903, message: 芯片号已被登记, data: null } + '422': + $ref: '#/components/responses/MediaNotReady' /api/v1/breeds: get: @@ -1201,7 +1345,7 @@ paths: petNotFound: value: { code: 40401, message: 宠物不存在, data: null } mediaNotFound: - value: { code: 40405, message: 媒体不存在, data: null } + value: { code: 40405, message: 媒体资源不存在, data: null } '409': $ref: '#/components/responses/IdempotencyPayloadMismatch' '422': @@ -1284,7 +1428,7 @@ paths: petNotFound: value: { code: 40401, message: 宠物不存在, data: null } mediaNotFound: - value: { code: 40405, message: 媒体不存在, data: null } + value: { code: 40405, message: 媒体资源不存在, data: null } '409': $ref: '#/components/responses/VersionConflict' '422': @@ -1348,6 +1492,35 @@ paths: '401': $ref: '#/components/responses/AccessTokenInvalid' + /api/v1/me/community-stats: + get: + tags: [posts] + summary: 我的社区数字（获赞总数 / 作品数） + description: | + 主体恒为 token 里的调用者：无查询参数、无路径参数，**路径上没有 userId**—— + 「查不到别人的获赞」不靠权限判断，而是入口本身不存在。 + + - **统计集合 = 本人的、`status='published'` 的、`deleted_at IS NULL` 的帖**。 + 草稿不计（尚非作品，且未发布不可被赞）；软删不计（删帖即撤回其数字，与 + `/me/posts`、Feed 的可见性一致）；运营态 hidden/archived 不计（对所有人不可见， + 含作者本人）；他人帖自然不计。 + - **自己赞自己计入**——与帖子详情页的 `likeCount` 保持同一口径，两处数字必须能对上。 + - `receivedLikeCount` = 该集合的 `like_count` 之和（读侧实时聚合，读的是写侧同事务 + 维护的帖级冗余列，故为精确值而非估算；ADR-022 不引入按人累计的冗余列）。 + - **空数据返回 `0` 而非 null**，且**永不 404**：任何已认证用户都有 stats。 + operationId: getMyCommunityStats + security: + - bearerAuth: [] + responses: + '200': + description: 我的获赞总数与作品数 + content: + application/json: + schema: + $ref: '#/components/schemas/CommunityStatsEnvelope' + '401': + $ref: '#/components/responses/AccessTokenInvalid' + /api/v1/feed: get: tags: [feed] @@ -1812,8 +1985,9 @@ components: value: { code: 40402, message: 记录不存在, data: null } PetWriteDenied: description: | - 对可见宠物无相应操作权限（code 40300）：viewer 写记录、caregiver/viewer 改 - 宠物档案。仅发给对宠物「可见」的调用者，不泄露新信息。 + 对可见宠物无相应操作权限（code 40300）：viewer 写记录或改头像、caregiver/viewer + 改宠物档案的资料字段（caregiver 仅改 `avatarAssetId` 时允许，M3.5 按字段分档）。 + 仅发给对宠物「可见」的调用者，不泄露新信息。 content: application/json: schema: @@ -1854,14 +2028,16 @@ components: commentNotFound: value: { code: 40404, message: 评论不存在, data: null } MediaNotFound: - description: asset 不存在、非本人所有或已删（code 40405，防枚举合并） + description: | + asset 不存在、非本人所有、已删，或**用途与引用场景不符**（code 40405，防枚举合并）。 + 用途不符即「从头像域看，一张帖子配图不是头像」；两种头像用途亦互不通用。 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: mediaNotFound: - value: { code: 40405, message: 媒体不存在, data: null } + value: { code: 40405, message: 媒体资源不存在, data: null } UserNotFound: description: 目标用户不存在或已注销（code 40406，合并不泄露成因） content: @@ -2001,8 +2177,10 @@ components: Me: type: object - description: 当前用户资料（冻结契约，恰好这 4 个字段） - required: [userId, username, createdAt] + description: | + 本人资料（`GET` 与 `PATCH /api/v1/me` 的统一响应形态，冻结契约恰好这 6 个字段）。 + **不含** `avatarAssetId`：客户端只写不读它，「是否有头像」等价于 `avatarUrl != null`。 + required: [userId, username, nickname, avatarUrl, createdAt] properties: userId: type: string @@ -2011,16 +2189,65 @@ components: username: type: string example: demo_user + nickname: + type: string + nullable: true + minLength: 1 + maxLength: 32 + description: | + 昵称，**DB 原值**；未设置为 null（键恒在）。长度按**码点**计 1~32（btrim 后）。 + **本端点不做 username 回退**——`/me` 是本人编辑态，回退会把展示约定固化成 + 真实数据；本人视角的展示回退由客户端做 `nickname ?? username`，他人视角的 + 回退在 `/internal/users/profiles`（SQL COALESCE，不属本公开契约）。 + 不设唯一约束（ADR-022，允许重名）。 + example: 小柴 phone: type: string nullable: true description: E.164；未绑定时为 null example: '+8613800138000' + avatarUrl: + type: string + nullable: true + description: | + 头像访问 URL——时效性预签名 GET（TTL 默认 1 小时，配置项），每次响应现签， + **客户端不得持久化、过期即重取**；桶保持私有，无签名直访被拒。 + 无头像、asset 非 ready、对象存储未配置三种情况均为 null（键恒在）。 + example: https://minio.example.com/patbond-media/user_avatar/2026/09/019212aa…?X-Amz-Signature=… createdAt: type: string format: date-time example: '2026-09-04T04:05:06.789Z' + UpdateMeRequest: + type: object + description: | + 本人资料部分更新（**三态语义**，与 pets 域 M2 的两态刻意不同）： + **键缺省 = 不改；键出现且为 `null` = 清空；键出现且有值 = 设置**。 + 两字段都未出现（含只带未声明字段）为**空 patch**，答 400/40000 而非静默 200。 + 无必填字段、无 `version` 乐观锁、无 `Idempotency-Key`（同 body 重放天然幂等）。 + properties: + nickname: + type: string + nullable: true + minLength: 1 + maxLength: 32 + description: | + 昵称；btrim 后长度按**码点**计须在 1~32，否则 400/40000。 + 显式 `null` = **清空昵称**；纯空白或空串是 400/40000，**不是隐式清空** + （清空只留显式 null 一条路，否则「误提交空格」与「想删昵称」无法区分）。 + example: 小柴 + avatarAssetId: + type: string + format: uuid + nullable: true + description: | + 头像 asset ID（两步上传的产物，`purpose` 须为 `user_avatar`）。 + 显式 `null` = **清除头像**。校验：不存在/非本人/已删/用途不符 404/40405； + 本人且用途相符但 uploading/failed 422/42203；非法 UUID 400/40000。 + **响应不回显该字段**（只写不读）。 + example: 019212bb-0000-7000-8000-000000000009 + AuthTokenEnvelope: type: object required: [code, message] @@ -2226,7 +2453,8 @@ components: `breedId` 与 `customBreedName` 恰有其一非空（ck_pets_breed）； `breedDisplayName` 由品种字典解出，随 breedId 存在。 软删除态（deleted）的宠物在全部端点表现为 404/40401，本 schema 的 - status 永不出现 deleted。`avatarAssetId` 不出现在 M2 契约（ADR-010）。 + status 永不出现 deleted。头像以 `avatarUrl` 的现签形式返回， + **`avatarAssetId` 不外露**（只写不读，写入口为 `PATCH /api/v1/pets/{petId}`）。 required: - id - name @@ -2234,6 +2462,7 @@ components: - sex - birthDateEstimated - status + - avatarUrl - myRole - createdAt - updatedAt @@ -2294,6 +2523,15 @@ components: type: string enum: [active, lost, deceased, archived] description: 状态（deleted 为内部软删态，接口永不返回；软删宠物一律 404/40401） + avatarUrl: + type: string + nullable: true + description: | + 宠物头像访问 URL——时效性预签名 GET（TTL 默认 1 小时，配置项），每次响应现签， + **客户端不得持久化、过期即重取**；桶保持私有，无签名直访被拒。 + 无头像、asset 非 ready、对象存储未配置三种情况均为 null（键恒在）。 + asset 事后退出 ready 时转 null 而引用保留（读请求不做写副作用）。 + example: https://minio.example.com/patbond-media/pet_avatar/2026/09/019212cc…?X-Amz-Signature=… myRole: type: string enum: [owner, caregiver, viewer] @@ -2351,14 +2589,18 @@ components: UpdatePetRequest: type: object description: | - 部分更新：缺席字段不变；不支持清空回 null。例外：品种对 + 部分更新：缺席字段不变；资料字段不支持清空回 null。例外：品种对 （breedId/customBreedName）整体替换——提交任一侧即替换整对，互斥校验同创建。 species 不可改（不在请求体）。 + **`avatarAssetId` 是本 schema 唯一的三态字段**（M3.5）：键缺省 = 不改； + 键出现且为 `null` = 清除头像；键出现且有值 = 设置。其余字段保持 M2 两态语义。 + 权限档按本次触及的字段决定（仅头像 → WRITE；触及资料字段 → MANAGE；混合取更严）， + 见端点描述。 required: [version] properties: version: type: integer - description: 当前持有的版本号（乐观锁，必填；缺失 400/40000，过期 409/40902） + description: 当前持有的版本号（乐观锁，必填；缺失 400/40000，过期 409/40902）；即便只改头像也必带 name: type: string minLength: 1 @@ -2393,6 +2635,16 @@ components: type: string enum: [active, lost, deceased, archived] description: 状态流转；deleted 不可经 PATCH 设置（400/40000） + avatarAssetId: + type: string + format: uuid + nullable: true + description: | + 宠物头像 asset ID（两步上传的产物，`purpose` 须为 `pet_avatar`）。 + **三态**：缺省 = 不改；显式 `null` = 清除头像；给值 = 设置。校验：不存在/ + 非本人/已删/用途不符 404/40405；本人且用途相符但 uploading/failed 422/42203； + 非法 UUID 400/40000。**响应不回显该字段**（只写不读，读取见 `Pet.avatarUrl`）。 + example: 019212cc-0000-7000-8000-00000000000a PetEnvelope: type: object @@ -3205,10 +3457,13 @@ components: description: M3 仅 image（ADR-018 视频后置；video/document 为向后新增枚举预留） purpose: type: string - enum: [post_image] + enum: [post_image, user_avatar, pet_avatar] description: | - 用途白名单（M3 定型仅 post_image，决定 objectKey 前缀）；P6 扩 - user_avatar/pet_avatar 时为向后兼容的枚举追加（服务端纯配置扩展） + 用途白名单（服务端配置项 `patbond.media.allowed-purposes`，决定 objectKey 前缀 + `/yyyy/MM/{assetId}`）。M3.5 起为三值：`post_image`（帖子配图）、 + `user_avatar`（用户头像）、`pet_avatar`（宠物头像）——相对 M3 的纯枚举追加。 + **用途即引用侧的类型检查**：引用时校验 `purpose` 相符，故帖图不能当头像、 + 两种头像也互不通用（不符者 404/40405）。白名单外的取值 400/40000。 mimeType: type: string enum: [image/jpeg, image/png, image/webp] @@ -3857,3 +4112,36 @@ components: example: success data: $ref: '#/components/schemas/FollowStats' + + CommunityStats: + type: object + description: | + 调用者本人的社区数字（M3.5）。两数同一集合：本人的、`status='published'` 的、 + 未软删的帖（草稿 / 软删 / hidden / archived 均不计）。读侧实时聚合，无冗余计数列。 + required: [receivedLikeCount, publishedPostCount] + properties: + receivedLikeCount: + type: integer + format: int64 + description: | + 获赞总数 = 该集合的 `like_count` 之和（写侧同事务维护的帖级冗余列，精确值）。 + **自己赞自己计入**，与帖子详情的 `likeCount` 同一口径。空数据为 0，非 null。 + example: 128 + publishedPostCount: + type: integer + format: int64 + description: 作品数 = 该集合的帖子数。空数据为 0，非 null。 + example: 12 + + CommunityStatsEnvelope: + type: object + required: [code, message, data] + properties: + code: + type: integer + enum: [0] + message: + type: string + example: success + data: + $ref: '#/components/schemas/CommunityStats' diff --git a/patbond-pet/src/test/java/com/patbond/patbond/pet/contract/ContractConformanceTest.java b/patbond-pet/src/test/java/com/patbond/patbond/pet/contract/ContractConformanceTest.java index 45d5c41..6caf6dd 100644 --- a/patbond-pet/src/test/java/com/patbond/patbond/pet/contract/ContractConformanceTest.java +++ b/patbond-pet/src/test/java/com/patbond/patbond/pet/contract/ContractConformanceTest.java @@ -14,6 +14,7 @@ import org.springframework.test.web.servlet.MvcResult; import org.springframework.test.web.servlet.request.MockHttpServletRequestBuilder; import java.nio.charset.StandardCharsets; +import java.time.OffsetDateTime; import java.util.ArrayList; import java.util.List; import java.util.Set; @@ -27,8 +28,8 @@ import static org.springframework.test.web.servlet.request.MockMvcRequestBuilder import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.request; /** - * T2-09 契约一致性保障：对冻结契约 v1.3.0（快照 - * {@code src/test/resources/contract/openapi-v1.3.0.yaml}，正典在 doc 仓 + * T2-09 契约一致性保障：对冻结契约 v1.4.0（快照 + * {@code src/test/resources/contract/openapi-v1.4.0.yaml}，正典在 doc 仓 * {@code docs/api/openapi.yaml}）的 pets 域 18 个操作逐一真实起服务发请求， * 用 {@link ContractValidator} 严格校验响应结构：路径/方法/状态码已声明、 * 字段名与类型、必填与 nullable、枚举与格式、信封结构、错误码值。 @@ -38,8 +39,8 @@ import static org.springframework.test.web.servlet.request.MockMvcRequestBuilder * 校验过（唯一豁免：照护提醒 PATCH 的 409——并发条件更新守卫落空，单线程 * MockMvc 无法确定性触发）。契约新增操作或状态码时，本测试立即变红。 * - *

auth 域 6 个既有操作（register/login/refresh/logout/me/trackEvents） - * 不在本单范围（M1 交付无契约测试，补齐另立工单）。 + *

auth/user 域 7 个操作（register/login/refresh/logout/me 读写/trackEvents） + * 的契约测试在 patbond-auth（T3-19 补齐）；快照同一份。 */ @TestMethodOrder(MethodOrderer.OrderAnnotation.class) class ContractConformanceTest extends PetIntegrationTestSupport { @@ -122,6 +123,29 @@ class ContractConformanceTest extends PetIntegrationTestSupport { return JsonPath.read(body, "$.data.id"); } + /** + * 一枚 media.assets 行，用途/状态/归属可控（T3.5-07：头像引用侧的四态校验 + * 需要，造法与 PetAvatarIntegrationTest 同构——测试数据，不触碰实现）。 + */ + private UUID insertAsset(UUID ownerUserId, String purpose, String status) { + UUID id = UUID.randomUUID(); + jdbcClient.sql(""" + INSERT INTO media.assets + (id, owner_user_id, kind, purpose, storage_type, bucket, object_key, + mime_type, byte_size, status, ready_at) + VALUES (:id, :owner, 'image', :purpose, 'object', 'patbond-media', + :objectKey, 'image/jpeg', 2048, :status, :readyAt) + """) + .param("id", id) + .param("owner", ownerUserId) + .param("purpose", purpose) + .param("objectKey", purpose + "/2026/09/" + id) + .param("status", status) + .param("readyAt", "ready".equals(status) ? OffsetDateTime.now() : null) + .update(); + return id; + } + // ---- 成功路径：18 操作全覆盖 --------------------------------------- @Test @@ -594,6 +618,33 @@ class ContractConformanceTest extends PetIntegrationTestSupport { .content("{\"version\":0,\"personality\":\"皮\"}"), "PATCH", "/api/v1/pets/{petId}", 409, 40902); + // -- 宠物头像（v1.4.0 新增两格，T3.5-07）-- + // 404/40405：与 40401 同一单元格的第二种业务码——幽灵 asset 与用途不符 + // 的 asset 合并同答（防枚举） + verifiedError(patch("/api/v1/pets/{id}", petId).header(AUTH, bearer(owner)) + .contentType(MediaType.APPLICATION_JSON) + .content("{\"version\":1,\"avatarAssetId\":\"%s\"}" + .formatted(UUID.randomUUID())), + "PATCH", "/api/v1/pets/{petId}", 404, 40405); + verifiedError(patch("/api/v1/pets/{id}", petId).header(AUTH, bearer(owner)) + .contentType(MediaType.APPLICATION_JSON) + .content("{\"version\":1,\"avatarAssetId\":\"%s\"}" + .formatted(insertAsset(owner, "post_image", "ready"))), + "PATCH", "/api/v1/pets/{petId}", 404, 40405); + // 422/42203：本人的 pet_avatar asset 仍在 uploading（新增状态码单元格） + verifiedError(patch("/api/v1/pets/{id}", petId).header(AUTH, bearer(owner)) + .contentType(MediaType.APPLICATION_JSON) + .content("{\"version\":1,\"avatarAssetId\":\"%s\"}" + .formatted(insertAsset(owner, "pet_avatar", "uploading"))), + "PATCH", "/api/v1/pets/{petId}", 422, 42203); + // 200：挂上 ready 头像（avatarUrl 的非 null 分支不在本模块——未配置对象 + // 存储时恒 null，真实签名 URL 由 PetAvatarIntegrationTest 覆盖） + verified(patch("/api/v1/pets/{id}", petId).header(AUTH, bearer(owner)) + .contentType(MediaType.APPLICATION_JSON) + .content("{\"version\":1,\"avatarAssetId\":\"%s\"}" + .formatted(insertAsset(owner, "pet_avatar", "ready"))), + "PATCH", "/api/v1/pets/{petId}", 200); + // -- 疫苗：40904 重复剂次、42201 状态-日期规则、PATCH 400/409/422 -- verified(post("/api/v1/pets/{id}/vaccinations", petId).header(AUTH, bearer(owner)) .contentType(MediaType.APPLICATION_JSON) @@ -703,10 +754,10 @@ class ContractConformanceTest extends PetIntegrationTestSupport { @Test @Order(98) void frozenSnapshotIsTheExpectedContractVersion() { - assertThat(CONTRACT.version()).isEqualTo("1.3.0"); - assertThat(CONTRACT.paths()).hasSize(31); - assertThat(CONTRACT.operations()).hasSize(43); - assertThat(CONTRACT.schemas()).hasSize(72); + assertThat(CONTRACT.version()).isEqualTo("1.4.0"); + assertThat(CONTRACT.paths()).hasSize(32); + assertThat(CONTRACT.operations()).hasSize(45); + assertThat(CONTRACT.schemas()).hasSize(75); assertThat(CONTRACT.operationsTagged(Set.of("pets", "dictionaries", "health-records"))) .containsExactlyInAnyOrderElementsOf(PETS_OPERATIONS); } diff --git a/patbond-pet/src/test/java/com/patbond/patbond/pet/contract/OpenApiContract.java b/patbond-pet/src/test/java/com/patbond/patbond/pet/contract/OpenApiContract.java index ca302d4..cd05b0b 100644 --- a/patbond-pet/src/test/java/com/patbond/patbond/pet/contract/OpenApiContract.java +++ b/patbond-pet/src/test/java/com/patbond/patbond/pet/contract/OpenApiContract.java @@ -13,8 +13,8 @@ import java.util.Objects; import java.util.Set; /** - * The frozen v1.3.0 OpenAPI contract, loaded from the test-resource snapshot - * {@code /contract/openapi-v1.3.0.yaml}. + * The frozen v1.4.0 OpenAPI contract, loaded from the test-resource snapshot + * {@code /contract/openapi-v1.4.0.yaml}. * *

Sync discipline (T2-09): the canonical contract lives in the doc * repo at {@code docs/api/openapi.yaml}; this snapshot is a byte-identical @@ -32,7 +32,7 @@ import java.util.Set; */ final class OpenApiContract { - static final String RESOURCE = "/contract/openapi-v1.3.0.yaml"; + static final String RESOURCE = "/contract/openapi-v1.4.0.yaml"; private static final Set HTTP_METHODS = Set.of("get", "put", "post", "delete", "options", "head", "patch", "trace"); diff --git a/patbond-pet/src/test/resources/contract/openapi-v1.3.0.yaml b/patbond-pet/src/test/resources/contract/openapi-v1.4.0.yaml similarity index 87% rename from patbond-pet/src/test/resources/contract/openapi-v1.3.0.yaml rename to patbond-pet/src/test/resources/contract/openapi-v1.4.0.yaml index c9d3072..d669f33 100644 --- a/patbond-pet/src/test/resources/contract/openapi-v1.3.0.yaml +++ b/patbond-pet/src/test/resources/contract/openapi-v1.4.0.yaml @@ -1,7 +1,7 @@ openapi: 3.0.3 info: title: Patbond API — Auth / Me / Events / Pets / Community / Media（公开契约） - version: 1.3.0 + version: 1.4.0 description: | Patbond 第一迭代「真实登录纵切」公开契约（冻结稿的正式化，字段与草案零偏差）， 1.1.0 追加埋点上报端点 `POST /api/v1/events`（M2 第一波契约补录，以实现实测行为为准）。 @@ -11,6 +11,14 @@ info: **1.3.0 M3 契约冻结：community/media 域 13 路径**（媒体两步上传、帖子生命周期、 公共 Feed、单层评论、点赞/收藏/关注最小接口）按第二波已定型实现合入 （iteration-3 报告 13/15/16/17 定型表；冻结报告见 iteration-3/18）。 + **1.4.0 M3.5 契约冻结：用户资料与头像**——`GET /api/v1/me` 补 `nickname`/`avatarUrl`， + 新增 `PATCH /api/v1/me`（昵称与头像读写，三态部分更新），`Pet` 补 `avatarUrl` 且 + `PATCH /api/v1/pets/{petId}` 收 `avatarAssetId`，新增 `GET /api/v1/me/community-stats` + （获赞总数与作品数），媒体 `purpose` 白名单追加 `user_avatar`/`pet_avatar` + （iteration-3.5 报告 03 定型表；冻结报告见 iteration-3.5/04）。 + **1.4.0 相对 1.3.0 纯增量**：无字段删改、无类型变更、无必填收紧，仅新增操作、 + 新增响应字段（键恒在、值可空）、新增可选请求字段、新增响应格与枚举追加， + v1.3.0 客户端无需改动即可继续工作。 ## 通用约定（development-plan 第 6 节） - 公开接口统一前缀 `/api/v1`；JSON 字段一律 `camelCase`；资源 ID 为 UUID 字符串。 @@ -29,14 +37,14 @@ info: | 40100 | 401 | 用户名或密码错误 | | 40101 | 401 | access token 无效或过期（缺失、伪造、篡改、过期） | | 40102 | 401 | refresh token 已失效或被重用（未知、过期、已轮换、已退出、家族已撤销） | - | 40300 | 403 | PET_ACCESS_DENIED：对可见宠物无相应操作权限（viewer 写记录、caregiver 改宠物档案） | + | 40300 | 403 | PET_ACCESS_DENIED：对可见宠物无相应操作权限（viewer 写记录或改头像、caregiver 改宠物档案——头像除外，见 M3.5 分档） | | 40301 | 403 | POST_ACCESS_DENIED：对可见帖子/评论无相应操作权限（改删他人已发布帖、删他人可见评论——含帖主）；仅发给对资源「可见」的调用者 | | 40400 | 404 | 资源不存在 | | 40401 | 404 | PET_NOT_FOUND：宠物不存在、已软删除或调用者与宠物无关系（防枚举，三种情况响应完全一致） | | 40402 | 404 | RECORD_NOT_FOUND：顶层记录路径下记录不存在或所属宠物对调用者不可见（记录级防枚举，两种情况响应完全一致） | | 40403 | 404 | POST_NOT_FOUND：帖子不存在、已软删、hidden/archived（作者同样）或他人 draft（防枚举，全部情况响应完全一致）；评论与互动路径上含作者本人草稿 | | 40404 | 404 | COMMENT_NOT_FOUND：评论不存在、已删或所属帖子不可见（防枚举合并） | - | 40405 | 404 | MEDIA_NOT_FOUND：asset 不存在、非本人所有或已删（防枚举合并） | + | 40405 | 404 | MEDIA_NOT_FOUND：asset 不存在、非本人所有、已删，或**用途与引用场景不符**（帖图当头像、user_avatar 当宠物头像等）；防枚举合并，同码各情形响应一致（用途不符分支只对调用者自己的 asset 可达，故 message 可具体） | | 40406 | 404 | USER_NOT_FOUND：目标用户不存在或已注销（关注端点与评论 replyToUserId；不复用 40400——该码已承担「路由级资源不存在」兜底语义，复用会使二者不可区分） | | 40900 | 409 | 用户名已存在（大小写不敏感） | | 40901 | 409 | 手机号已被使用 | @@ -46,7 +54,7 @@ info: | 40905 | 409 | IDEMPOTENCY_PAYLOAD_MISMATCH：同 Idempotency-Key 不同 payload（规范化 request_hash 不符，community 域创建型写入） | | 42201 | 422 | VACCINATION_RULE_VIOLATION：疫苗状态机非法迁移或状态-日期规则违反 | | 42202 | 422 | REMINDER_RULE_VIOLATION：提醒状态机非法迁移或 completed-completedAt 一致性违反 | - | 42203 | 422 | MEDIA_NOT_READY：引用了本人所有但非 ready（uploading/failed）状态的 asset | + | 42203 | 422 | MEDIA_NOT_READY：引用了本人所有、用途相符但非 ready（uploading/failed）状态的 asset（帖图与用户/宠物头像同构） | | 42204 | 422 | FOLLOW_RULE_VIOLATION：自关注（仅 PUT；自取关为 200 幂等 no-op） | | 42205 | 422 | MEDIA_UPLOAD_STATE_INVALID：complete 时 asset 非 uploading——对象未上传保持可重试、大小/类型不符置 failed 终态、failed 态再确认；已 ready 幂等 200 除外 | | 42300 | 423 | 登录失败次数过多，账号已临时锁定（见下） | @@ -68,7 +76,10 @@ info: - **权限模型（ADR-015：owner/caregiver/viewer 三角色，pet_owners 表）**，操作分三档： - `READ`——三角色皆可：宠物详情/列表、各记录列表、档案摘要； - `WRITE`——owner + caregiver：体重/疫苗/健康事件/提醒的 POST 与 PATCH； - - `MANAGE`——仅 owner：宠物档案 PATCH（含状态流转）。 + **M3.5 起还含宠物头像字段 `avatarAssetId`**（ADR-022：头像属日常照护信息）。 + - `MANAGE`——仅 owner：宠物档案 PATCH 的资料字段（含状态流转）。 + **同一端点按「本次请求触及哪些字段」定档**（不是端点级降档）：仅改头像走 WRITE， + 触及任一资料字段走 MANAGE，混合请求取更严的一半。 权限每请求实时查库、无缓存：撤销照护关系立即生效。 - **防枚举语义**：宠物不存在、已软删除、调用者与宠物无 pet_owners 关系三种情况 响应完全一致（404/40401），GET 与写操作一致适用；顶层记录路径下「记录不存在」与 @@ -126,6 +137,41 @@ info: 整体不出现，后续按新增可选字段/端点纯增量补入。`/internal/**` 服务间接口 （如作者公开资料批量接口）不属于本公开契约。 + ## 用户资料与头像域约定（M3.5 冻结，iteration-3.5 报告 03 定型；ADR-022） + - **三态部分更新（仅本域，pets 域 M2 两态语义不回改）**：`PATCH /api/v1/me` 的 + `nickname`/`avatarAssetId` 与 `PATCH /api/v1/pets/{petId}` 的 `avatarAssetId` + 按三态解释——**键缺省 = 不改；键出现且为 `null` = 清空；键出现且有值 = 设置**。 + 昵称与头像天生可选，「删掉我设的那个」是一等公民操作，只有两态无法表达。 + 同一请求体内的其余 pets 字段仍是 M2 的「缺省或 null 皆为不改」。 + - **空 PATCH 与纯空白昵称一律 400/40000**，不静默 200、不隐式清空：清空只留 + 显式 `null` 一条路，否则「误提交空格」与「想删昵称」无法区分。 + - **昵称**：btrim 后 1~32 **码点**（非 UTF-16 长度）；**不设唯一约束**（ADR-022， + 允许重名，靠 userId 区分）；注册不收昵称。`/api/v1/me` 返回 **DB 原值**， + 未设置即 `null`，**不做 username 回退**——`/me` 是本人编辑态，回退会把展示约定 + 固化成真实数据；他人视角的展示回退在 `/internal/users/profiles`（SQL COALESCE）， + 本人视角的展示回退由客户端做 `nickname ?? username`。 + - **头像读取一律 `avatarUrl`（时效性预签名 GET，与帖图同一纪律）**：每次响应现签， + **会过期、客户端不得持久化**，过期即重取；无头像、asset 非 ready、对象存储未配置 + 三种情况均为 `null`（降级而非报错——签一个必然 404 的 URL 比给 null 更糟）。 + 指针不隐式清理：asset 事后退出 ready 时 `avatarUrl` 转 null 而引用保留。 + - **`avatarAssetId` 只写不读**：请求体收，响应**一律不外露**（`Me` 与 `Pet` 皆无该字段）； + 「是否有头像」等价于 `avatarUrl != null`。 + - **两种头像用途互不通用**：`user_avatar` 不能当宠物头像、`pet_avatar` 不能当用户头像、 + `post_image` 不能当任何头像——引用侧按 `purpose` 校验，不符者 404/40405 + （四态校验：不存在/非本人/已删/用途不符 → 404/40405；本人且用途相符但 + uploading/failed → 422/42203）。 + - **宠物头像的权限档按「本次请求碰了哪些字段」定档**（ADR-022 头像为 WRITE 档）： + 仅改 `avatarAssetId` 时 owner + caregiver 皆可（viewer 403/40300）；触及任一资料 + 字段时仍是 MANAGE（仅 owner）；**混合请求取更严的一半**，堵住把改名夹带进头像 + 请求绕过 MANAGE 的路径。头像与资料共用同一把乐观锁 `version`（仍必填）。 + - **`/api/v1/me` 无乐观锁、无幂等键**：只有一个合法写者（账号本人），暴露 `version` + 只是给客户端加负担；丢失更新由**列级选择性 UPDATE** 排除（SET 列表只含本次请求 + 真正携带的列），并发改不同字段两者皆存活；同 body 重放天然幂等。 + - **`GET /api/v1/me/community-stats` 为独立端点**（ADR-022 决策 A，不并入 + `/users/{userId}/follow-stats`——后者主体是「某用户的关注数」，混入「我的获赞」 + 会让一个载荷有两个主体）。路径上**没有 userId**：「查不到别人的获赞」不靠权限 + 判断，而是入口本身不存在，故**永不 404**，任何已认证用户都有 stats。 + servers: - url: http://127.0.0.1:8081 description: patbond-auth（本地开发，/api/v1/auth/**） @@ -140,7 +186,7 @@ tags: - name: auth description: 注册 / 登录 / 刷新 / 退出（patbond-auth） - name: user - description: 当前用户（patbond-user） + description: 当前用户资料：读取与昵称/头像更新（patbond-user） - name: analytics description: 产品事件批量上报（patbond-user） - name: pets @@ -152,7 +198,9 @@ tags: - name: media description: 媒体上传两步流程（patbond-user，ADR-016 预签名直传） - name: posts - description: 帖子生命周期：草稿/编辑/发布/删除/详情/我的帖子（patbond-community） + description: | + 帖子生命周期：草稿/编辑/发布/删除/详情/我的帖子；含由帖子派生的「我的社区数字」 + 聚合（patbond-community） - name: feed description: 公共 Feed 游标分页（patbond-community） - name: comments @@ -301,7 +349,15 @@ paths: get: tags: [user] summary: 当前用户资料 - description: 由 patbond-user 提供；access token 以 RS256 公钥本地验签，无需经过 auth 服务。 + description: | + 由 patbond-user 提供；access token 以 RS256 公钥本地验签，无需经过 auth 服务。 + + - `nickname` 为 **DB 原值**，未设置即 `null`（**不做 username 回退**，见 info + 「用户资料与头像域约定」）；本人视角的展示回退由客户端做 `nickname ?? username`。 + - `avatarUrl` 为**每次响应现签的时效性预签名 GET**：**会过期、客户端不得持久化**， + 过期即重取；无头像、asset 非 ready、对象存储未配置均为 `null`。 + - 响应**不含** `avatarAssetId`：客户端只写不读它，「是否有头像」等价于 + `avatarUrl != null`。 operationId: me security: - bearerAuth: [] @@ -320,6 +376,66 @@ paths: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' + patch: + tags: [user] + summary: 更新当前用户资料（昵称 / 头像，三态部分更新） + description: | + 本人资料的唯一写入口（主体恒为 token 里的调用者，无「他人」情形）。 + + - **三态语义**：键缺省 = 不改；键出现且为 `null` = 清空；键出现且有值 = 设置。 + - **空 patch 400/40000**（两字段都未出现，含只带未声明字段）：不静默 200， + 空 PATCH 几乎总是客户端 bug。纯空白/空串昵称同为 400/40000，不隐式清空。 + - `avatarAssetId` 须为**调用者本人、用途为 `user_avatar`、状态 `ready`** 的 asset： + 不存在/非本人/已删/用途不符 404/40405；本人且用途相符但 uploading/failed + 422/42203。 + - **无 `version` 乐观锁、无 `Idempotency-Key`**：只有一个合法写者；丢失更新由 + 列级选择性 UPDATE 排除（并发改不同字段两者皆存活），同 body 重放天然幂等。 + - 成功返回**与 GET 完全相同的 `Me` 全量形态**（回显更新后资料，`avatarUrl` 现签）。 + operationId: updateMe + security: + - bearerAuth: [] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateMeRequest' + responses: + '200': + description: 更新成功，返回更新后的完整 Me + content: + application/json: + schema: + $ref: '#/components/schemas/MeEnvelope' + '400': + description: | + 参数校验失败（code 40000）：空 patch、昵称 btrim 后长度不在 1~32 码点、 + 昵称纯空白或空串、`avatarAssetId` 非法 UUID、body 非法 JSON + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorEnvelope' + examples: + emptyPatch: + value: { code: 40000, message: 请求未包含任何可更新字段, data: null } + '401': + $ref: '#/components/responses/AccessTokenInvalid' + '404': + description: | + 用户不存在或已注销（code 40400，token 仍有效但账号已注销）；或 + `avatarAssetId` 引用的 asset 不存在/非本人/已删/用途不是 `user_avatar` + （code 40405，防枚举合并） + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorEnvelope' + examples: + userNotFound: + value: { code: 40400, message: 用户不存在, data: null } + mediaNotFound: + value: { code: 40405, message: 媒体资源不存在, data: null } + '422': + $ref: '#/components/responses/MediaNotReady' /api/v1/events: post: @@ -468,18 +584,32 @@ paths: $ref: '#/components/responses/PetNotFound' patch: tags: [pets] - summary: 更新宠物档案 + summary: 更新宠物档案（含头像） description: | - 权限档：MANAGE（**仅 owner**）；caregiver/viewer 更新得 403/40300。 + 权限档**按本次请求触及的字段定档**（M3.5 起，ADR-022）： - - 部分更新：缺席字段不变；**不支持将可选字段清空回 null**。 + | 请求体触及 | 所需档位 | caregiver | viewer | + | --- | --- | --- | --- | + | 仅 `avatarAssetId`（+ `version`） | WRITE | ✅ | ✗ 403/40300 | + | 任一资料字段（name/sex/status/…） | MANAGE（仅 owner） | ✗ 403/40300 | ✗ 403/40300 | + | 资料字段 + `avatarAssetId` 混合 | MANAGE（**取更严的一半**） | ✗ 403/40300 | ✗ 403/40300 | + + 混合请求取更严，是为了堵住「夹带」——否则 caregiver 可把改名塞进头像请求绕过 MANAGE。 + + - 部分更新：缺席字段不变；资料字段**不支持清空回 null**（M2 语义不回改）。 + - **例外：`avatarAssetId` 是本端点唯一的三态字段**（M3.5）——键缺省 = 不改； + 键出现且为 `null` = **清除头像**；键出现且有值 = 设置。差异刻意限定在有清空 + 需求的字段上。 - 例外：品种对（`breedId`/`customBreedName`）**整体替换**——提交任一侧即替换 整对，互斥校验同创建。 - `species` 不可改（创建即定，避免与品种配对失效，请求体不含该字段）。 - `status` 可迁移至 active/lost/deceased/archived；**`deleted` 不可经 PATCH 设置**（400/40000，软删除留待专用端点，M2 契约不含）。 - - `version` 必填（缺失 400/40000），比对通过才写入并 +1；过期 409/40902。 + - `version` **必填**（缺失 400/40000），即便只改头像；比对通过才写入并 +1； + 过期 409/40902。头像与资料共用同一把乐观锁——头像变更也应让并发编辑者感知行已变。 - 芯片号改为已被登记的值：409/40903。 + - `avatarAssetId` 须为**调用者本人、用途为 `pet_avatar`、状态 `ready`** 的 asset： + 不存在/非本人/已删/用途不符 404/40405；本人且用途相符但 uploading/failed 422/42203。 operationId: updatePet security: - bearerAuth: [] @@ -505,7 +635,19 @@ paths: '403': $ref: '#/components/responses/PetWriteDenied' '404': - $ref: '#/components/responses/PetNotFound' + description: | + 宠物不存在、已软删除或调用者与宠物无关系（code 40401，防枚举合并）；或 + `avatarAssetId` 引用的 asset 不存在/非本人/已删/用途不是 `pet_avatar` + （code 40405，防枚举合并） + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorEnvelope' + examples: + petNotFound: + value: { code: 40401, message: 宠物不存在, data: null } + mediaNotFound: + value: { code: 40405, message: 媒体资源不存在, data: null } '409': description: 版本冲突（code 40902）或芯片号已被登记（code 40903） content: @@ -517,6 +659,8 @@ paths: value: { code: 40902, message: 数据已被修改，请刷新后重试, data: null } microchipExists: value: { code: 40903, message: 芯片号已被登记, data: null } + '422': + $ref: '#/components/responses/MediaNotReady' /api/v1/breeds: get: @@ -1201,7 +1345,7 @@ paths: petNotFound: value: { code: 40401, message: 宠物不存在, data: null } mediaNotFound: - value: { code: 40405, message: 媒体不存在, data: null } + value: { code: 40405, message: 媒体资源不存在, data: null } '409': $ref: '#/components/responses/IdempotencyPayloadMismatch' '422': @@ -1284,7 +1428,7 @@ paths: petNotFound: value: { code: 40401, message: 宠物不存在, data: null } mediaNotFound: - value: { code: 40405, message: 媒体不存在, data: null } + value: { code: 40405, message: 媒体资源不存在, data: null } '409': $ref: '#/components/responses/VersionConflict' '422': @@ -1348,6 +1492,35 @@ paths: '401': $ref: '#/components/responses/AccessTokenInvalid' + /api/v1/me/community-stats: + get: + tags: [posts] + summary: 我的社区数字（获赞总数 / 作品数） + description: | + 主体恒为 token 里的调用者：无查询参数、无路径参数，**路径上没有 userId**—— + 「查不到别人的获赞」不靠权限判断，而是入口本身不存在。 + + - **统计集合 = 本人的、`status='published'` 的、`deleted_at IS NULL` 的帖**。 + 草稿不计（尚非作品，且未发布不可被赞）；软删不计（删帖即撤回其数字，与 + `/me/posts`、Feed 的可见性一致）；运营态 hidden/archived 不计（对所有人不可见， + 含作者本人）；他人帖自然不计。 + - **自己赞自己计入**——与帖子详情页的 `likeCount` 保持同一口径，两处数字必须能对上。 + - `receivedLikeCount` = 该集合的 `like_count` 之和（读侧实时聚合，读的是写侧同事务 + 维护的帖级冗余列，故为精确值而非估算；ADR-022 不引入按人累计的冗余列）。 + - **空数据返回 `0` 而非 null**，且**永不 404**：任何已认证用户都有 stats。 + operationId: getMyCommunityStats + security: + - bearerAuth: [] + responses: + '200': + description: 我的获赞总数与作品数 + content: + application/json: + schema: + $ref: '#/components/schemas/CommunityStatsEnvelope' + '401': + $ref: '#/components/responses/AccessTokenInvalid' + /api/v1/feed: get: tags: [feed] @@ -1812,8 +1985,9 @@ components: value: { code: 40402, message: 记录不存在, data: null } PetWriteDenied: description: | - 对可见宠物无相应操作权限（code 40300）：viewer 写记录、caregiver/viewer 改 - 宠物档案。仅发给对宠物「可见」的调用者，不泄露新信息。 + 对可见宠物无相应操作权限（code 40300）：viewer 写记录或改头像、caregiver/viewer + 改宠物档案的资料字段（caregiver 仅改 `avatarAssetId` 时允许，M3.5 按字段分档）。 + 仅发给对宠物「可见」的调用者，不泄露新信息。 content: application/json: schema: @@ -1854,14 +2028,16 @@ components: commentNotFound: value: { code: 40404, message: 评论不存在, data: null } MediaNotFound: - description: asset 不存在、非本人所有或已删（code 40405，防枚举合并） + description: | + asset 不存在、非本人所有、已删，或**用途与引用场景不符**（code 40405，防枚举合并）。 + 用途不符即「从头像域看，一张帖子配图不是头像」；两种头像用途亦互不通用。 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: mediaNotFound: - value: { code: 40405, message: 媒体不存在, data: null } + value: { code: 40405, message: 媒体资源不存在, data: null } UserNotFound: description: 目标用户不存在或已注销（code 40406，合并不泄露成因） content: @@ -2001,8 +2177,10 @@ components: Me: type: object - description: 当前用户资料（冻结契约，恰好这 4 个字段） - required: [userId, username, createdAt] + description: | + 本人资料（`GET` 与 `PATCH /api/v1/me` 的统一响应形态，冻结契约恰好这 6 个字段）。 + **不含** `avatarAssetId`：客户端只写不读它，「是否有头像」等价于 `avatarUrl != null`。 + required: [userId, username, nickname, avatarUrl, createdAt] properties: userId: type: string @@ -2011,16 +2189,65 @@ components: username: type: string example: demo_user + nickname: + type: string + nullable: true + minLength: 1 + maxLength: 32 + description: | + 昵称，**DB 原值**；未设置为 null（键恒在）。长度按**码点**计 1~32（btrim 后）。 + **本端点不做 username 回退**——`/me` 是本人编辑态，回退会把展示约定固化成 + 真实数据；本人视角的展示回退由客户端做 `nickname ?? username`，他人视角的 + 回退在 `/internal/users/profiles`（SQL COALESCE，不属本公开契约）。 + 不设唯一约束（ADR-022，允许重名）。 + example: 小柴 phone: type: string nullable: true description: E.164；未绑定时为 null example: '+8613800138000' + avatarUrl: + type: string + nullable: true + description: | + 头像访问 URL——时效性预签名 GET（TTL 默认 1 小时，配置项），每次响应现签， + **客户端不得持久化、过期即重取**；桶保持私有，无签名直访被拒。 + 无头像、asset 非 ready、对象存储未配置三种情况均为 null（键恒在）。 + example: https://minio.example.com/patbond-media/user_avatar/2026/09/019212aa…?X-Amz-Signature=… createdAt: type: string format: date-time example: '2026-09-04T04:05:06.789Z' + UpdateMeRequest: + type: object + description: | + 本人资料部分更新（**三态语义**，与 pets 域 M2 的两态刻意不同）： + **键缺省 = 不改；键出现且为 `null` = 清空；键出现且有值 = 设置**。 + 两字段都未出现（含只带未声明字段）为**空 patch**，答 400/40000 而非静默 200。 + 无必填字段、无 `version` 乐观锁、无 `Idempotency-Key`（同 body 重放天然幂等）。 + properties: + nickname: + type: string + nullable: true + minLength: 1 + maxLength: 32 + description: | + 昵称；btrim 后长度按**码点**计须在 1~32，否则 400/40000。 + 显式 `null` = **清空昵称**；纯空白或空串是 400/40000，**不是隐式清空** + （清空只留显式 null 一条路，否则「误提交空格」与「想删昵称」无法区分）。 + example: 小柴 + avatarAssetId: + type: string + format: uuid + nullable: true + description: | + 头像 asset ID（两步上传的产物，`purpose` 须为 `user_avatar`）。 + 显式 `null` = **清除头像**。校验：不存在/非本人/已删/用途不符 404/40405； + 本人且用途相符但 uploading/failed 422/42203；非法 UUID 400/40000。 + **响应不回显该字段**（只写不读）。 + example: 019212bb-0000-7000-8000-000000000009 + AuthTokenEnvelope: type: object required: [code, message] @@ -2226,7 +2453,8 @@ components: `breedId` 与 `customBreedName` 恰有其一非空（ck_pets_breed）； `breedDisplayName` 由品种字典解出，随 breedId 存在。 软删除态（deleted）的宠物在全部端点表现为 404/40401，本 schema 的 - status 永不出现 deleted。`avatarAssetId` 不出现在 M2 契约（ADR-010）。 + status 永不出现 deleted。头像以 `avatarUrl` 的现签形式返回， + **`avatarAssetId` 不外露**（只写不读，写入口为 `PATCH /api/v1/pets/{petId}`）。 required: - id - name @@ -2234,6 +2462,7 @@ components: - sex - birthDateEstimated - status + - avatarUrl - myRole - createdAt - updatedAt @@ -2294,6 +2523,15 @@ components: type: string enum: [active, lost, deceased, archived] description: 状态（deleted 为内部软删态，接口永不返回；软删宠物一律 404/40401） + avatarUrl: + type: string + nullable: true + description: | + 宠物头像访问 URL——时效性预签名 GET（TTL 默认 1 小时，配置项），每次响应现签， + **客户端不得持久化、过期即重取**；桶保持私有，无签名直访被拒。 + 无头像、asset 非 ready、对象存储未配置三种情况均为 null（键恒在）。 + asset 事后退出 ready 时转 null 而引用保留（读请求不做写副作用）。 + example: https://minio.example.com/patbond-media/pet_avatar/2026/09/019212cc…?X-Amz-Signature=… myRole: type: string enum: [owner, caregiver, viewer] @@ -2351,14 +2589,18 @@ components: UpdatePetRequest: type: object description: | - 部分更新：缺席字段不变；不支持清空回 null。例外：品种对 + 部分更新：缺席字段不变；资料字段不支持清空回 null。例外：品种对 （breedId/customBreedName）整体替换——提交任一侧即替换整对，互斥校验同创建。 species 不可改（不在请求体）。 + **`avatarAssetId` 是本 schema 唯一的三态字段**（M3.5）：键缺省 = 不改； + 键出现且为 `null` = 清除头像；键出现且有值 = 设置。其余字段保持 M2 两态语义。 + 权限档按本次触及的字段决定（仅头像 → WRITE；触及资料字段 → MANAGE；混合取更严）， + 见端点描述。 required: [version] properties: version: type: integer - description: 当前持有的版本号（乐观锁，必填；缺失 400/40000，过期 409/40902） + description: 当前持有的版本号（乐观锁，必填；缺失 400/40000，过期 409/40902）；即便只改头像也必带 name: type: string minLength: 1 @@ -2393,6 +2635,16 @@ components: type: string enum: [active, lost, deceased, archived] description: 状态流转；deleted 不可经 PATCH 设置（400/40000） + avatarAssetId: + type: string + format: uuid + nullable: true + description: | + 宠物头像 asset ID（两步上传的产物，`purpose` 须为 `pet_avatar`）。 + **三态**：缺省 = 不改；显式 `null` = 清除头像；给值 = 设置。校验：不存在/ + 非本人/已删/用途不符 404/40405；本人且用途相符但 uploading/failed 422/42203； + 非法 UUID 400/40000。**响应不回显该字段**（只写不读，读取见 `Pet.avatarUrl`）。 + example: 019212cc-0000-7000-8000-00000000000a PetEnvelope: type: object @@ -3205,10 +3457,13 @@ components: description: M3 仅 image（ADR-018 视频后置；video/document 为向后新增枚举预留） purpose: type: string - enum: [post_image] + enum: [post_image, user_avatar, pet_avatar] description: | - 用途白名单（M3 定型仅 post_image，决定 objectKey 前缀）；P6 扩 - user_avatar/pet_avatar 时为向后兼容的枚举追加（服务端纯配置扩展） + 用途白名单（服务端配置项 `patbond.media.allowed-purposes`，决定 objectKey 前缀 + `/yyyy/MM/{assetId}`）。M3.5 起为三值：`post_image`（帖子配图）、 + `user_avatar`（用户头像）、`pet_avatar`（宠物头像）——相对 M3 的纯枚举追加。 + **用途即引用侧的类型检查**：引用时校验 `purpose` 相符，故帖图不能当头像、 + 两种头像也互不通用（不符者 404/40405）。白名单外的取值 400/40000。 mimeType: type: string enum: [image/jpeg, image/png, image/webp] @@ -3857,3 +4112,36 @@ components: example: success data: $ref: '#/components/schemas/FollowStats' + + CommunityStats: + type: object + description: | + 调用者本人的社区数字（M3.5）。两数同一集合：本人的、`status='published'` 的、 + 未软删的帖（草稿 / 软删 / hidden / archived 均不计）。读侧实时聚合，无冗余计数列。 + required: [receivedLikeCount, publishedPostCount] + properties: + receivedLikeCount: + type: integer + format: int64 + description: | + 获赞总数 = 该集合的 `like_count` 之和（写侧同事务维护的帖级冗余列，精确值）。 + **自己赞自己计入**，与帖子详情的 `likeCount` 同一口径。空数据为 0，非 null。 + example: 128 + publishedPostCount: + type: integer + format: int64 + description: 作品数 = 该集合的帖子数。空数据为 0，非 null。 + example: 12 + + CommunityStatsEnvelope: + type: object + required: [code, message, data] + properties: + code: + type: integer + enum: [0] + message: + type: string + example: success + data: + $ref: '#/components/schemas/CommunityStats' diff --git a/patbond-user/src/test/java/com/patbond/patbond/user/contract/MediaContractConformanceTest.java b/patbond-user/src/test/java/com/patbond/patbond/user/contract/MediaContractConformanceTest.java index 04f88d2..a74f2ce 100644 --- a/patbond-user/src/test/java/com/patbond/patbond/user/contract/MediaContractConformanceTest.java +++ b/patbond-user/src/test/java/com/patbond/patbond/user/contract/MediaContractConformanceTest.java @@ -40,13 +40,13 @@ import static org.springframework.test.web.servlet.request.MockMvcRequestBuilder /** * T3-20（M3 第二波收尾）：media 域 2 个操作（两步上传，属 user 模块）补进契约 * 一致性保障，机制与 patbond-pet 的 ContractConformanceTest 同构——对冻结契约 - * v1.3.0（快照 {@code src/test/resources/contract/openapi-v1.3.0.yaml}，正典在 + * v1.4.0（快照 {@code src/test/resources/contract/openapi-v1.4.0.yaml}，正典在 * doc 仓 {@code docs/api/openapi.yaml}）逐操作真实起服务发请求（真实 MinIO * Testcontainer，直传走真实 HTTP PUT），用 {@link ContractValidator} 严格校验 * 响应结构，最后以全响应矩阵门禁兜底（8 个单元格，无豁免）。 * - *

auth 域 6 操作在 patbond-auth、pets 域 18 操作在 patbond-pet、community 域 - * 17 操作在 patbond-community 的同构测试内（快照同一份）。 + *

auth/user 域 7 操作在 patbond-auth、pets 域 18 操作在 patbond-pet、community 域 + * 18 操作在 patbond-community 的同构测试内（快照同一份）。 */ @TestMethodOrder(MethodOrderer.OrderAnnotation.class) @SpringBootTest @@ -245,10 +245,10 @@ class MediaContractConformanceTest { @Test @Order(98) void frozenSnapshotIsTheExpectedContractVersion() { - assertThat(CONTRACT.version()).isEqualTo("1.3.0"); - assertThat(CONTRACT.paths()).hasSize(31); - assertThat(CONTRACT.operations()).hasSize(43); - assertThat(CONTRACT.schemas()).hasSize(72); + assertThat(CONTRACT.version()).isEqualTo("1.4.0"); + assertThat(CONTRACT.paths()).hasSize(32); + assertThat(CONTRACT.operations()).hasSize(45); + assertThat(CONTRACT.schemas()).hasSize(75); assertThat(CONTRACT.operationsTagged(Set.of("media"))) .containsExactlyInAnyOrderElementsOf(MEDIA_OPERATIONS); } diff --git a/patbond-user/src/test/java/com/patbond/patbond/user/contract/OpenApiContract.java b/patbond-user/src/test/java/com/patbond/patbond/user/contract/OpenApiContract.java index 0ea219a..79fe84e 100644 --- a/patbond-user/src/test/java/com/patbond/patbond/user/contract/OpenApiContract.java +++ b/patbond-user/src/test/java/com/patbond/patbond/user/contract/OpenApiContract.java @@ -13,8 +13,8 @@ import java.util.Objects; import java.util.Set; /** - * The frozen v1.3.0 OpenAPI contract, loaded from the test-resource snapshot - * {@code /contract/openapi-v1.3.0.yaml}. + * The frozen v1.4.0 OpenAPI contract, loaded from the test-resource snapshot + * {@code /contract/openapi-v1.4.0.yaml}. * *

Sync discipline (T2-09, extended by T3-19): the canonical * contract lives in the doc repo at {@code docs/api/openapi.yaml}; this @@ -36,7 +36,7 @@ import java.util.Set; */ final class OpenApiContract { - static final String RESOURCE = "/contract/openapi-v1.3.0.yaml"; + static final String RESOURCE = "/contract/openapi-v1.4.0.yaml"; private static final Set HTTP_METHODS = Set.of("get", "put", "post", "delete", "options", "head", "patch", "trace"); diff --git a/patbond-user/src/test/resources/contract/openapi-v1.3.0.yaml b/patbond-user/src/test/resources/contract/openapi-v1.4.0.yaml similarity index 87% rename from patbond-user/src/test/resources/contract/openapi-v1.3.0.yaml rename to patbond-user/src/test/resources/contract/openapi-v1.4.0.yaml index c9d3072..d669f33 100644 --- a/patbond-user/src/test/resources/contract/openapi-v1.3.0.yaml +++ b/patbond-user/src/test/resources/contract/openapi-v1.4.0.yaml @@ -1,7 +1,7 @@ openapi: 3.0.3 info: title: Patbond API — Auth / Me / Events / Pets / Community / Media（公开契约） - version: 1.3.0 + version: 1.4.0 description: | Patbond 第一迭代「真实登录纵切」公开契约（冻结稿的正式化，字段与草案零偏差）， 1.1.0 追加埋点上报端点 `POST /api/v1/events`（M2 第一波契约补录，以实现实测行为为准）。 @@ -11,6 +11,14 @@ info: **1.3.0 M3 契约冻结：community/media 域 13 路径**（媒体两步上传、帖子生命周期、 公共 Feed、单层评论、点赞/收藏/关注最小接口）按第二波已定型实现合入 （iteration-3 报告 13/15/16/17 定型表；冻结报告见 iteration-3/18）。 + **1.4.0 M3.5 契约冻结：用户资料与头像**——`GET /api/v1/me` 补 `nickname`/`avatarUrl`， + 新增 `PATCH /api/v1/me`（昵称与头像读写，三态部分更新），`Pet` 补 `avatarUrl` 且 + `PATCH /api/v1/pets/{petId}` 收 `avatarAssetId`，新增 `GET /api/v1/me/community-stats` + （获赞总数与作品数），媒体 `purpose` 白名单追加 `user_avatar`/`pet_avatar` + （iteration-3.5 报告 03 定型表；冻结报告见 iteration-3.5/04）。 + **1.4.0 相对 1.3.0 纯增量**：无字段删改、无类型变更、无必填收紧，仅新增操作、 + 新增响应字段（键恒在、值可空）、新增可选请求字段、新增响应格与枚举追加， + v1.3.0 客户端无需改动即可继续工作。 ## 通用约定（development-plan 第 6 节） - 公开接口统一前缀 `/api/v1`；JSON 字段一律 `camelCase`；资源 ID 为 UUID 字符串。 @@ -29,14 +37,14 @@ info: | 40100 | 401 | 用户名或密码错误 | | 40101 | 401 | access token 无效或过期（缺失、伪造、篡改、过期） | | 40102 | 401 | refresh token 已失效或被重用（未知、过期、已轮换、已退出、家族已撤销） | - | 40300 | 403 | PET_ACCESS_DENIED：对可见宠物无相应操作权限（viewer 写记录、caregiver 改宠物档案） | + | 40300 | 403 | PET_ACCESS_DENIED：对可见宠物无相应操作权限（viewer 写记录或改头像、caregiver 改宠物档案——头像除外，见 M3.5 分档） | | 40301 | 403 | POST_ACCESS_DENIED：对可见帖子/评论无相应操作权限（改删他人已发布帖、删他人可见评论——含帖主）；仅发给对资源「可见」的调用者 | | 40400 | 404 | 资源不存在 | | 40401 | 404 | PET_NOT_FOUND：宠物不存在、已软删除或调用者与宠物无关系（防枚举，三种情况响应完全一致） | | 40402 | 404 | RECORD_NOT_FOUND：顶层记录路径下记录不存在或所属宠物对调用者不可见（记录级防枚举，两种情况响应完全一致） | | 40403 | 404 | POST_NOT_FOUND：帖子不存在、已软删、hidden/archived（作者同样）或他人 draft（防枚举，全部情况响应完全一致）；评论与互动路径上含作者本人草稿 | | 40404 | 404 | COMMENT_NOT_FOUND：评论不存在、已删或所属帖子不可见（防枚举合并） | - | 40405 | 404 | MEDIA_NOT_FOUND：asset 不存在、非本人所有或已删（防枚举合并） | + | 40405 | 404 | MEDIA_NOT_FOUND：asset 不存在、非本人所有、已删，或**用途与引用场景不符**（帖图当头像、user_avatar 当宠物头像等）；防枚举合并，同码各情形响应一致（用途不符分支只对调用者自己的 asset 可达，故 message 可具体） | | 40406 | 404 | USER_NOT_FOUND：目标用户不存在或已注销（关注端点与评论 replyToUserId；不复用 40400——该码已承担「路由级资源不存在」兜底语义，复用会使二者不可区分） | | 40900 | 409 | 用户名已存在（大小写不敏感） | | 40901 | 409 | 手机号已被使用 | @@ -46,7 +54,7 @@ info: | 40905 | 409 | IDEMPOTENCY_PAYLOAD_MISMATCH：同 Idempotency-Key 不同 payload（规范化 request_hash 不符，community 域创建型写入） | | 42201 | 422 | VACCINATION_RULE_VIOLATION：疫苗状态机非法迁移或状态-日期规则违反 | | 42202 | 422 | REMINDER_RULE_VIOLATION：提醒状态机非法迁移或 completed-completedAt 一致性违反 | - | 42203 | 422 | MEDIA_NOT_READY：引用了本人所有但非 ready（uploading/failed）状态的 asset | + | 42203 | 422 | MEDIA_NOT_READY：引用了本人所有、用途相符但非 ready（uploading/failed）状态的 asset（帖图与用户/宠物头像同构） | | 42204 | 422 | FOLLOW_RULE_VIOLATION：自关注（仅 PUT；自取关为 200 幂等 no-op） | | 42205 | 422 | MEDIA_UPLOAD_STATE_INVALID：complete 时 asset 非 uploading——对象未上传保持可重试、大小/类型不符置 failed 终态、failed 态再确认；已 ready 幂等 200 除外 | | 42300 | 423 | 登录失败次数过多，账号已临时锁定（见下） | @@ -68,7 +76,10 @@ info: - **权限模型（ADR-015：owner/caregiver/viewer 三角色，pet_owners 表）**，操作分三档： - `READ`——三角色皆可：宠物详情/列表、各记录列表、档案摘要； - `WRITE`——owner + caregiver：体重/疫苗/健康事件/提醒的 POST 与 PATCH； - - `MANAGE`——仅 owner：宠物档案 PATCH（含状态流转）。 + **M3.5 起还含宠物头像字段 `avatarAssetId`**（ADR-022：头像属日常照护信息）。 + - `MANAGE`——仅 owner：宠物档案 PATCH 的资料字段（含状态流转）。 + **同一端点按「本次请求触及哪些字段」定档**（不是端点级降档）：仅改头像走 WRITE， + 触及任一资料字段走 MANAGE，混合请求取更严的一半。 权限每请求实时查库、无缓存：撤销照护关系立即生效。 - **防枚举语义**：宠物不存在、已软删除、调用者与宠物无 pet_owners 关系三种情况 响应完全一致（404/40401），GET 与写操作一致适用；顶层记录路径下「记录不存在」与 @@ -126,6 +137,41 @@ info: 整体不出现，后续按新增可选字段/端点纯增量补入。`/internal/**` 服务间接口 （如作者公开资料批量接口）不属于本公开契约。 + ## 用户资料与头像域约定（M3.5 冻结，iteration-3.5 报告 03 定型；ADR-022） + - **三态部分更新（仅本域，pets 域 M2 两态语义不回改）**：`PATCH /api/v1/me` 的 + `nickname`/`avatarAssetId` 与 `PATCH /api/v1/pets/{petId}` 的 `avatarAssetId` + 按三态解释——**键缺省 = 不改；键出现且为 `null` = 清空；键出现且有值 = 设置**。 + 昵称与头像天生可选，「删掉我设的那个」是一等公民操作，只有两态无法表达。 + 同一请求体内的其余 pets 字段仍是 M2 的「缺省或 null 皆为不改」。 + - **空 PATCH 与纯空白昵称一律 400/40000**，不静默 200、不隐式清空：清空只留 + 显式 `null` 一条路，否则「误提交空格」与「想删昵称」无法区分。 + - **昵称**：btrim 后 1~32 **码点**（非 UTF-16 长度）；**不设唯一约束**（ADR-022， + 允许重名，靠 userId 区分）；注册不收昵称。`/api/v1/me` 返回 **DB 原值**， + 未设置即 `null`，**不做 username 回退**——`/me` 是本人编辑态，回退会把展示约定 + 固化成真实数据；他人视角的展示回退在 `/internal/users/profiles`（SQL COALESCE）， + 本人视角的展示回退由客户端做 `nickname ?? username`。 + - **头像读取一律 `avatarUrl`（时效性预签名 GET，与帖图同一纪律）**：每次响应现签， + **会过期、客户端不得持久化**，过期即重取；无头像、asset 非 ready、对象存储未配置 + 三种情况均为 `null`（降级而非报错——签一个必然 404 的 URL 比给 null 更糟）。 + 指针不隐式清理：asset 事后退出 ready 时 `avatarUrl` 转 null 而引用保留。 + - **`avatarAssetId` 只写不读**：请求体收，响应**一律不外露**（`Me` 与 `Pet` 皆无该字段）； + 「是否有头像」等价于 `avatarUrl != null`。 + - **两种头像用途互不通用**：`user_avatar` 不能当宠物头像、`pet_avatar` 不能当用户头像、 + `post_image` 不能当任何头像——引用侧按 `purpose` 校验，不符者 404/40405 + （四态校验：不存在/非本人/已删/用途不符 → 404/40405；本人且用途相符但 + uploading/failed → 422/42203）。 + - **宠物头像的权限档按「本次请求碰了哪些字段」定档**（ADR-022 头像为 WRITE 档）： + 仅改 `avatarAssetId` 时 owner + caregiver 皆可（viewer 403/40300）；触及任一资料 + 字段时仍是 MANAGE（仅 owner）；**混合请求取更严的一半**，堵住把改名夹带进头像 + 请求绕过 MANAGE 的路径。头像与资料共用同一把乐观锁 `version`（仍必填）。 + - **`/api/v1/me` 无乐观锁、无幂等键**：只有一个合法写者（账号本人），暴露 `version` + 只是给客户端加负担；丢失更新由**列级选择性 UPDATE** 排除（SET 列表只含本次请求 + 真正携带的列），并发改不同字段两者皆存活；同 body 重放天然幂等。 + - **`GET /api/v1/me/community-stats` 为独立端点**（ADR-022 决策 A，不并入 + `/users/{userId}/follow-stats`——后者主体是「某用户的关注数」，混入「我的获赞」 + 会让一个载荷有两个主体）。路径上**没有 userId**：「查不到别人的获赞」不靠权限 + 判断，而是入口本身不存在，故**永不 404**，任何已认证用户都有 stats。 + servers: - url: http://127.0.0.1:8081 description: patbond-auth（本地开发，/api/v1/auth/**） @@ -140,7 +186,7 @@ tags: - name: auth description: 注册 / 登录 / 刷新 / 退出（patbond-auth） - name: user - description: 当前用户（patbond-user） + description: 当前用户资料：读取与昵称/头像更新（patbond-user） - name: analytics description: 产品事件批量上报（patbond-user） - name: pets @@ -152,7 +198,9 @@ tags: - name: media description: 媒体上传两步流程（patbond-user，ADR-016 预签名直传） - name: posts - description: 帖子生命周期：草稿/编辑/发布/删除/详情/我的帖子（patbond-community） + description: | + 帖子生命周期：草稿/编辑/发布/删除/详情/我的帖子；含由帖子派生的「我的社区数字」 + 聚合（patbond-community） - name: feed description: 公共 Feed 游标分页（patbond-community） - name: comments @@ -301,7 +349,15 @@ paths: get: tags: [user] summary: 当前用户资料 - description: 由 patbond-user 提供；access token 以 RS256 公钥本地验签，无需经过 auth 服务。 + description: | + 由 patbond-user 提供；access token 以 RS256 公钥本地验签，无需经过 auth 服务。 + + - `nickname` 为 **DB 原值**，未设置即 `null`（**不做 username 回退**，见 info + 「用户资料与头像域约定」）；本人视角的展示回退由客户端做 `nickname ?? username`。 + - `avatarUrl` 为**每次响应现签的时效性预签名 GET**：**会过期、客户端不得持久化**， + 过期即重取；无头像、asset 非 ready、对象存储未配置均为 `null`。 + - 响应**不含** `avatarAssetId`：客户端只写不读它，「是否有头像」等价于 + `avatarUrl != null`。 operationId: me security: - bearerAuth: [] @@ -320,6 +376,66 @@ paths: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' + patch: + tags: [user] + summary: 更新当前用户资料（昵称 / 头像，三态部分更新） + description: | + 本人资料的唯一写入口（主体恒为 token 里的调用者，无「他人」情形）。 + + - **三态语义**：键缺省 = 不改；键出现且为 `null` = 清空；键出现且有值 = 设置。 + - **空 patch 400/40000**（两字段都未出现，含只带未声明字段）：不静默 200， + 空 PATCH 几乎总是客户端 bug。纯空白/空串昵称同为 400/40000，不隐式清空。 + - `avatarAssetId` 须为**调用者本人、用途为 `user_avatar`、状态 `ready`** 的 asset： + 不存在/非本人/已删/用途不符 404/40405；本人且用途相符但 uploading/failed + 422/42203。 + - **无 `version` 乐观锁、无 `Idempotency-Key`**：只有一个合法写者；丢失更新由 + 列级选择性 UPDATE 排除（并发改不同字段两者皆存活），同 body 重放天然幂等。 + - 成功返回**与 GET 完全相同的 `Me` 全量形态**（回显更新后资料，`avatarUrl` 现签）。 + operationId: updateMe + security: + - bearerAuth: [] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateMeRequest' + responses: + '200': + description: 更新成功，返回更新后的完整 Me + content: + application/json: + schema: + $ref: '#/components/schemas/MeEnvelope' + '400': + description: | + 参数校验失败（code 40000）：空 patch、昵称 btrim 后长度不在 1~32 码点、 + 昵称纯空白或空串、`avatarAssetId` 非法 UUID、body 非法 JSON + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorEnvelope' + examples: + emptyPatch: + value: { code: 40000, message: 请求未包含任何可更新字段, data: null } + '401': + $ref: '#/components/responses/AccessTokenInvalid' + '404': + description: | + 用户不存在或已注销（code 40400，token 仍有效但账号已注销）；或 + `avatarAssetId` 引用的 asset 不存在/非本人/已删/用途不是 `user_avatar` + （code 40405，防枚举合并） + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorEnvelope' + examples: + userNotFound: + value: { code: 40400, message: 用户不存在, data: null } + mediaNotFound: + value: { code: 40405, message: 媒体资源不存在, data: null } + '422': + $ref: '#/components/responses/MediaNotReady' /api/v1/events: post: @@ -468,18 +584,32 @@ paths: $ref: '#/components/responses/PetNotFound' patch: tags: [pets] - summary: 更新宠物档案 + summary: 更新宠物档案（含头像） description: | - 权限档：MANAGE（**仅 owner**）；caregiver/viewer 更新得 403/40300。 + 权限档**按本次请求触及的字段定档**（M3.5 起，ADR-022）： - - 部分更新：缺席字段不变；**不支持将可选字段清空回 null**。 + | 请求体触及 | 所需档位 | caregiver | viewer | + | --- | --- | --- | --- | + | 仅 `avatarAssetId`（+ `version`） | WRITE | ✅ | ✗ 403/40300 | + | 任一资料字段（name/sex/status/…） | MANAGE（仅 owner） | ✗ 403/40300 | ✗ 403/40300 | + | 资料字段 + `avatarAssetId` 混合 | MANAGE（**取更严的一半**） | ✗ 403/40300 | ✗ 403/40300 | + + 混合请求取更严，是为了堵住「夹带」——否则 caregiver 可把改名塞进头像请求绕过 MANAGE。 + + - 部分更新：缺席字段不变；资料字段**不支持清空回 null**（M2 语义不回改）。 + - **例外：`avatarAssetId` 是本端点唯一的三态字段**（M3.5）——键缺省 = 不改； + 键出现且为 `null` = **清除头像**；键出现且有值 = 设置。差异刻意限定在有清空 + 需求的字段上。 - 例外：品种对（`breedId`/`customBreedName`）**整体替换**——提交任一侧即替换 整对，互斥校验同创建。 - `species` 不可改（创建即定，避免与品种配对失效，请求体不含该字段）。 - `status` 可迁移至 active/lost/deceased/archived；**`deleted` 不可经 PATCH 设置**（400/40000，软删除留待专用端点，M2 契约不含）。 - - `version` 必填（缺失 400/40000），比对通过才写入并 +1；过期 409/40902。 + - `version` **必填**（缺失 400/40000），即便只改头像；比对通过才写入并 +1； + 过期 409/40902。头像与资料共用同一把乐观锁——头像变更也应让并发编辑者感知行已变。 - 芯片号改为已被登记的值：409/40903。 + - `avatarAssetId` 须为**调用者本人、用途为 `pet_avatar`、状态 `ready`** 的 asset： + 不存在/非本人/已删/用途不符 404/40405；本人且用途相符但 uploading/failed 422/42203。 operationId: updatePet security: - bearerAuth: [] @@ -505,7 +635,19 @@ paths: '403': $ref: '#/components/responses/PetWriteDenied' '404': - $ref: '#/components/responses/PetNotFound' + description: | + 宠物不存在、已软删除或调用者与宠物无关系（code 40401，防枚举合并）；或 + `avatarAssetId` 引用的 asset 不存在/非本人/已删/用途不是 `pet_avatar` + （code 40405，防枚举合并） + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorEnvelope' + examples: + petNotFound: + value: { code: 40401, message: 宠物不存在, data: null } + mediaNotFound: + value: { code: 40405, message: 媒体资源不存在, data: null } '409': description: 版本冲突（code 40902）或芯片号已被登记（code 40903） content: @@ -517,6 +659,8 @@ paths: value: { code: 40902, message: 数据已被修改，请刷新后重试, data: null } microchipExists: value: { code: 40903, message: 芯片号已被登记, data: null } + '422': + $ref: '#/components/responses/MediaNotReady' /api/v1/breeds: get: @@ -1201,7 +1345,7 @@ paths: petNotFound: value: { code: 40401, message: 宠物不存在, data: null } mediaNotFound: - value: { code: 40405, message: 媒体不存在, data: null } + value: { code: 40405, message: 媒体资源不存在, data: null } '409': $ref: '#/components/responses/IdempotencyPayloadMismatch' '422': @@ -1284,7 +1428,7 @@ paths: petNotFound: value: { code: 40401, message: 宠物不存在, data: null } mediaNotFound: - value: { code: 40405, message: 媒体不存在, data: null } + value: { code: 40405, message: 媒体资源不存在, data: null } '409': $ref: '#/components/responses/VersionConflict' '422': @@ -1348,6 +1492,35 @@ paths: '401': $ref: '#/components/responses/AccessTokenInvalid' + /api/v1/me/community-stats: + get: + tags: [posts] + summary: 我的社区数字（获赞总数 / 作品数） + description: | + 主体恒为 token 里的调用者：无查询参数、无路径参数，**路径上没有 userId**—— + 「查不到别人的获赞」不靠权限判断，而是入口本身不存在。 + + - **统计集合 = 本人的、`status='published'` 的、`deleted_at IS NULL` 的帖**。 + 草稿不计（尚非作品，且未发布不可被赞）；软删不计（删帖即撤回其数字，与 + `/me/posts`、Feed 的可见性一致）；运营态 hidden/archived 不计（对所有人不可见， + 含作者本人）；他人帖自然不计。 + - **自己赞自己计入**——与帖子详情页的 `likeCount` 保持同一口径，两处数字必须能对上。 + - `receivedLikeCount` = 该集合的 `like_count` 之和（读侧实时聚合，读的是写侧同事务 + 维护的帖级冗余列，故为精确值而非估算；ADR-022 不引入按人累计的冗余列）。 + - **空数据返回 `0` 而非 null**，且**永不 404**：任何已认证用户都有 stats。 + operationId: getMyCommunityStats + security: + - bearerAuth: [] + responses: + '200': + description: 我的获赞总数与作品数 + content: + application/json: + schema: + $ref: '#/components/schemas/CommunityStatsEnvelope' + '401': + $ref: '#/components/responses/AccessTokenInvalid' + /api/v1/feed: get: tags: [feed] @@ -1812,8 +1985,9 @@ components: value: { code: 40402, message: 记录不存在, data: null } PetWriteDenied: description: | - 对可见宠物无相应操作权限（code 40300）：viewer 写记录、caregiver/viewer 改 - 宠物档案。仅发给对宠物「可见」的调用者，不泄露新信息。 + 对可见宠物无相应操作权限（code 40300）：viewer 写记录或改头像、caregiver/viewer + 改宠物档案的资料字段（caregiver 仅改 `avatarAssetId` 时允许，M3.5 按字段分档）。 + 仅发给对宠物「可见」的调用者，不泄露新信息。 content: application/json: schema: @@ -1854,14 +2028,16 @@ components: commentNotFound: value: { code: 40404, message: 评论不存在, data: null } MediaNotFound: - description: asset 不存在、非本人所有或已删（code 40405，防枚举合并） + description: | + asset 不存在、非本人所有、已删，或**用途与引用场景不符**（code 40405，防枚举合并）。 + 用途不符即「从头像域看，一张帖子配图不是头像」；两种头像用途亦互不通用。 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: mediaNotFound: - value: { code: 40405, message: 媒体不存在, data: null } + value: { code: 40405, message: 媒体资源不存在, data: null } UserNotFound: description: 目标用户不存在或已注销（code 40406，合并不泄露成因） content: @@ -2001,8 +2177,10 @@ components: Me: type: object - description: 当前用户资料（冻结契约，恰好这 4 个字段） - required: [userId, username, createdAt] + description: | + 本人资料（`GET` 与 `PATCH /api/v1/me` 的统一响应形态，冻结契约恰好这 6 个字段）。 + **不含** `avatarAssetId`：客户端只写不读它，「是否有头像」等价于 `avatarUrl != null`。 + required: [userId, username, nickname, avatarUrl, createdAt] properties: userId: type: string @@ -2011,16 +2189,65 @@ components: username: type: string example: demo_user + nickname: + type: string + nullable: true + minLength: 1 + maxLength: 32 + description: | + 昵称，**DB 原值**；未设置为 null（键恒在）。长度按**码点**计 1~32（btrim 后）。 + **本端点不做 username 回退**——`/me` 是本人编辑态，回退会把展示约定固化成 + 真实数据；本人视角的展示回退由客户端做 `nickname ?? username`，他人视角的 + 回退在 `/internal/users/profiles`（SQL COALESCE，不属本公开契约）。 + 不设唯一约束（ADR-022，允许重名）。 + example: 小柴 phone: type: string nullable: true description: E.164；未绑定时为 null example: '+8613800138000' + avatarUrl: + type: string + nullable: true + description: | + 头像访问 URL——时效性预签名 GET（TTL 默认 1 小时，配置项），每次响应现签， + **客户端不得持久化、过期即重取**；桶保持私有，无签名直访被拒。 + 无头像、asset 非 ready、对象存储未配置三种情况均为 null（键恒在）。 + example: https://minio.example.com/patbond-media/user_avatar/2026/09/019212aa…?X-Amz-Signature=… createdAt: type: string format: date-time example: '2026-09-04T04:05:06.789Z' + UpdateMeRequest: + type: object + description: | + 本人资料部分更新（**三态语义**，与 pets 域 M2 的两态刻意不同）： + **键缺省 = 不改；键出现且为 `null` = 清空；键出现且有值 = 设置**。 + 两字段都未出现（含只带未声明字段）为**空 patch**，答 400/40000 而非静默 200。 + 无必填字段、无 `version` 乐观锁、无 `Idempotency-Key`（同 body 重放天然幂等）。 + properties: + nickname: + type: string + nullable: true + minLength: 1 + maxLength: 32 + description: | + 昵称；btrim 后长度按**码点**计须在 1~32，否则 400/40000。 + 显式 `null` = **清空昵称**；纯空白或空串是 400/40000，**不是隐式清空** + （清空只留显式 null 一条路，否则「误提交空格」与「想删昵称」无法区分）。 + example: 小柴 + avatarAssetId: + type: string + format: uuid + nullable: true + description: | + 头像 asset ID（两步上传的产物，`purpose` 须为 `user_avatar`）。 + 显式 `null` = **清除头像**。校验：不存在/非本人/已删/用途不符 404/40405； + 本人且用途相符但 uploading/failed 422/42203；非法 UUID 400/40000。 + **响应不回显该字段**（只写不读）。 + example: 019212bb-0000-7000-8000-000000000009 + AuthTokenEnvelope: type: object required: [code, message] @@ -2226,7 +2453,8 @@ components: `breedId` 与 `customBreedName` 恰有其一非空（ck_pets_breed）； `breedDisplayName` 由品种字典解出，随 breedId 存在。 软删除态（deleted）的宠物在全部端点表现为 404/40401，本 schema 的 - status 永不出现 deleted。`avatarAssetId` 不出现在 M2 契约（ADR-010）。 + status 永不出现 deleted。头像以 `avatarUrl` 的现签形式返回， + **`avatarAssetId` 不外露**（只写不读，写入口为 `PATCH /api/v1/pets/{petId}`）。 required: - id - name @@ -2234,6 +2462,7 @@ components: - sex - birthDateEstimated - status + - avatarUrl - myRole - createdAt - updatedAt @@ -2294,6 +2523,15 @@ components: type: string enum: [active, lost, deceased, archived] description: 状态（deleted 为内部软删态，接口永不返回；软删宠物一律 404/40401） + avatarUrl: + type: string + nullable: true + description: | + 宠物头像访问 URL——时效性预签名 GET（TTL 默认 1 小时，配置项），每次响应现签， + **客户端不得持久化、过期即重取**；桶保持私有，无签名直访被拒。 + 无头像、asset 非 ready、对象存储未配置三种情况均为 null（键恒在）。 + asset 事后退出 ready 时转 null 而引用保留（读请求不做写副作用）。 + example: https://minio.example.com/patbond-media/pet_avatar/2026/09/019212cc…?X-Amz-Signature=… myRole: type: string enum: [owner, caregiver, viewer] @@ -2351,14 +2589,18 @@ components: UpdatePetRequest: type: object description: | - 部分更新：缺席字段不变；不支持清空回 null。例外：品种对 + 部分更新：缺席字段不变；资料字段不支持清空回 null。例外：品种对 （breedId/customBreedName）整体替换——提交任一侧即替换整对，互斥校验同创建。 species 不可改（不在请求体）。 + **`avatarAssetId` 是本 schema 唯一的三态字段**（M3.5）：键缺省 = 不改； + 键出现且为 `null` = 清除头像；键出现且有值 = 设置。其余字段保持 M2 两态语义。 + 权限档按本次触及的字段决定（仅头像 → WRITE；触及资料字段 → MANAGE；混合取更严）， + 见端点描述。 required: [version] properties: version: type: integer - description: 当前持有的版本号（乐观锁，必填；缺失 400/40000，过期 409/40902） + description: 当前持有的版本号（乐观锁，必填；缺失 400/40000，过期 409/40902）；即便只改头像也必带 name: type: string minLength: 1 @@ -2393,6 +2635,16 @@ components: type: string enum: [active, lost, deceased, archived] description: 状态流转；deleted 不可经 PATCH 设置（400/40000） + avatarAssetId: + type: string + format: uuid + nullable: true + description: | + 宠物头像 asset ID（两步上传的产物，`purpose` 须为 `pet_avatar`）。 + **三态**：缺省 = 不改；显式 `null` = 清除头像；给值 = 设置。校验：不存在/ + 非本人/已删/用途不符 404/40405；本人且用途相符但 uploading/failed 422/42203； + 非法 UUID 400/40000。**响应不回显该字段**（只写不读，读取见 `Pet.avatarUrl`）。 + example: 019212cc-0000-7000-8000-00000000000a PetEnvelope: type: object @@ -3205,10 +3457,13 @@ components: description: M3 仅 image（ADR-018 视频后置；video/document 为向后新增枚举预留） purpose: type: string - enum: [post_image] + enum: [post_image, user_avatar, pet_avatar] description: | - 用途白名单（M3 定型仅 post_image，决定 objectKey 前缀）；P6 扩 - user_avatar/pet_avatar 时为向后兼容的枚举追加（服务端纯配置扩展） + 用途白名单（服务端配置项 `patbond.media.allowed-purposes`，决定 objectKey 前缀 + `/yyyy/MM/{assetId}`）。M3.5 起为三值：`post_image`（帖子配图）、 + `user_avatar`（用户头像）、`pet_avatar`（宠物头像）——相对 M3 的纯枚举追加。 + **用途即引用侧的类型检查**：引用时校验 `purpose` 相符，故帖图不能当头像、 + 两种头像也互不通用（不符者 404/40405）。白名单外的取值 400/40000。 mimeType: type: string enum: [image/jpeg, image/png, image/webp] @@ -3857,3 +4112,36 @@ components: example: success data: $ref: '#/components/schemas/FollowStats' + + CommunityStats: + type: object + description: | + 调用者本人的社区数字（M3.5）。两数同一集合：本人的、`status='published'` 的、 + 未软删的帖（草稿 / 软删 / hidden / archived 均不计）。读侧实时聚合，无冗余计数列。 + required: [receivedLikeCount, publishedPostCount] + properties: + receivedLikeCount: + type: integer + format: int64 + description: | + 获赞总数 = 该集合的 `like_count` 之和（写侧同事务维护的帖级冗余列，精确值）。 + **自己赞自己计入**，与帖子详情的 `likeCount` 同一口径。空数据为 0，非 null。 + example: 128 + publishedPostCount: + type: integer + format: int64 + description: 作品数 = 该集合的帖子数。空数据为 0，非 null。 + example: 12 + + CommunityStatsEnvelope: + type: object + required: [code, message, data] + properties: + code: + type: integer + enum: [0] + message: + type: string + example: success + data: + $ref: '#/components/schemas/CommunityStats'