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'