diff --git a/internal/transport/http/docs/openapi.yaml b/internal/transport/http/docs/openapi.yaml
index 131cda1..28587de 100644
--- a/internal/transport/http/docs/openapi.yaml
+++ b/internal/transport/http/docs/openapi.yaml
@@ -1278,6 +1278,114 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/Envelope"
+  /v1/follows/{uid}:
+    get:
+      tags: [friends]
+      summary: 查看关注状态
+      description: |
+        当前用户是否关注对方。无请求体。`data` 含 `uid`、`following`、`followed_by`、`mutual`、`friend`。
+        这是关注关系，不是新的消息接口。
+      operationId: getFollow
+      parameters:
+        - $ref: "#/components/parameters/FriendUID"
+      responses:
+        "200":
+          description: 统一 envelope
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Envelope"
+    put:
+      tags: [friends]
+      summary: 关注
+      description: |
+        无请求体。只增加一条单向关注。只有一方关注时 `mutual` 与 `friend` 都为 false，不会成为好友。
+        若对方已经关注自己，这次关注使双方互相关注，则自动写入已有双向好友边（来源 `4`），并沿用成为好友的系统消息。已经是好友时不重复写这条系统消息。
+      operationId: followUser
+      parameters:
+        - $ref: "#/components/parameters/FriendUID"
+      responses:
+        "200":
+          description: |
+            统一 envelope。`data.following` 为 true。仅一方关注时 `mutual=false`、`friend=false`。互关成功时 `mutual=true`、`friend=true`。
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Envelope"
+    delete:
+      tags: [friends]
+      summary: 取消关注
+      description: |
+        只删除自己这一条关注。若因此不再互相关注，删除双方好友边。不删除历史消息。
+        只有一方关注时取消关注，不改动已经存在的好友关系。
+      operationId: unfollowUser
+      parameters:
+        - $ref: "#/components/parameters/FriendUID"
+      responses:
+        "200":
+          description: 统一 envelope。`data.following` 为 false。不再互关时 `friend` 为 false。
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Envelope"
+  /v1/follows/{uid}:
+    get:
+      tags: [friends]
+      summary: 查看是否关注
+      description: |
+        返回关注状态，不是新的好友模型。
+        只有一方关注时 `friend` 为 false。
+        双方互相关注时自动建立双向好友，`friend` 为 true。
+        已经互关之后，任何一方取消关注都会删除双方好友边，不删除历史消息。
+      operationId: getFollow
+      parameters:
+        - $ref: "#/components/parameters/FriendUID"
+      responses:
+        "200":
+          description: |
+            data：`uid`、`following`、`followed_by`、`mutual`、`friend`。
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Envelope"
+    put:
+      tags: [friends]
+      summary: 关注
+      description: |
+        无请求体。只写入一条 `user_id` → `target_id` 的关注。
+        只有一方关注时不成为好友。
+        双方互相关注时，复用现有好友边自动建立双向好友（来源为互关），并写入已有的成为好友系统消息。
+      operationId: followUser
+      parameters:
+        - $ref: "#/components/parameters/FriendUID"
+      responses:
+        "200":
+          description: |
+            data：`uid`、`following`、`followed_by`、`mutual`、`friend`。
+            单关时 `following=true`、`mutual=false`、`friend=false`。
+            补上对方已有的关注后 `mutual=true`、`friend=true`。
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Envelope"
+    delete:
+      tags: [friends]
+      summary: 取消关注
+      description: |
+        只删除自己这一条关注。
+        若取消前双方已互关，则删除双方好友边，不是只删一方。历史消息保留。
+        若本来只有一方关注，不改已有的好友申请关系。
+      operationId: unfollowUser
+      parameters:
+        - $ref: "#/components/parameters/FriendUID"
+      responses:
+        "200":
+          description: |
+            data 字段与关注相同。互关后取关：`friend=false`，双方好友边都没有了。
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Envelope"
   /v1/groups:
     get:
       tags: [groups]
@@ -3488,8 +3596,8 @@ components:
       description: friend_requests.status，申请结果 status 同此。1待处理 2已同意 3已拒绝
     FriendSource:
       type: integer
-      enum: [0, 1, 2, 3]
-      description: 好友添加来源。0未知 1二维码 2邮箱 3spark_id
+      enum: [0, 1, 2, 3, 4]
+      description: 好友添加来源。0未知 1二维码 2邮箱 3spark_id 4互关
     ReportReason:
       type: integer
       enum: [1, 2, 3, 4]