feat: integrate client and server sharing workflows

docs/openapi.yaml

@@ -75,6 +75,7 @@ paths:
     delete:
       tags: [channel]
       summary: 删除整个频道及全部密文(所有者)
+      description: 有效的 owner 凭据即可调用,不要求 owner 终端占用席位。
       security: [{ bearer: [] }]
       parameters:
         - { $ref: '#/components/parameters/RoleOwner' }
@@ -90,7 +91,7 @@ paths:
       summary: 修改设置(所有者)
       description: |
         字段均可选,只修改提供的字段。`ttl_seconds` 的变更从现在起算。
-        成功后向订阅者推送 `{"t":"settings"}`。
+        成功后向订阅者推送 `{"t":"settings"}`。有效的 owner 凭据即可调用,不要求 owner 终端占用席位。
       security: [{ bearer: [] }]
       parameters:
         - { $ref: '#/components/parameters/ChannelId' }
@@ -118,7 +119,7 @@ paths:
       description: |
         幂等:同一终端重复调用返回同一席位,不重复占用。
         席位已满返回 403 `seats_full`。
-        除本接口和「读取频道信息」外,其余频道接口都要求终端已入席,否则 403 `not_joined`。
+        读取频道信息和 owner 管理接口不占席位;频道内容、席位信息/设备名等其余操作要求终端已入席,否则 403 `not_joined`。
       security: [{ bearer: [] }]
       parameters:
         - { $ref: '#/components/parameters/Role' }
@@ -135,6 +136,7 @@ paths:
     get:
       tags: [seat]
       summary: 查看席位列表(所有者)
+      description: 有效的 owner 凭据即可调用,不要求 owner 终端占用席位。
       security: [{ bearer: [] }]
       parameters:
         - { $ref: '#/components/parameters/RoleOwner' }
@@ -172,7 +174,7 @@ paths:
     delete:
       tags: [seat]
       summary: 释放席位(所有者)
-      description: 被释放的终端后续请求返回 `not_joined`。向订阅者推送 `{"t":"seats"}`。
+      description: 有效的 owner 凭据即可调用,不要求 owner 终端占用席位。被释放终端后续请求返回 `not_joined`;向订阅者推送 `{"t":"seats"}`。
       security: [{ bearer: [] }]
       parameters:
         - { $ref: '#/components/parameters/ChannelId' }
@@ -343,7 +345,7 @@ paths:
       summary: 拉取条目的帧(GATED 条目的取数方式)
       description: |
         返回封装拼接,每帧自带 `payload_len`,可流式解析。条目尚未 FINAL 时响应持续输出直到 FINAL。
-        `from=0` 计一次下载;`from>0` 视为续传,不计数。
+        `from=0` 计一次下载;`from>0` 只有同一终端此前对同一条目成功启动过 `from=0` 才能续传,否则返回 410 `gone`。
         达到下载上限后返回 410 `gone`,5 分钟宽限期后删除密文,宽限期内已开始的拉取可继续续传。
       security: [{ bearer: [] }]
       parameters:
@@ -558,7 +560,7 @@ paths:
     get:
       tags: [share]
       summary: 下载封存分享中的文件帧
-      description: from=0 计一次下载;from>0 为续传。首次成功读取会登记访客终端。
+      description: from=0 计一次下载;from>0 只有同一 X-WD-Endpoint 此前对同一文件成功启动过 from=0 才能续传,否则返回 410 gone 且不登记访客。首次成功读取会登记访客终端。
       security: [{ bearer: [] }]
       parameters:
         - { $ref: '#/components/parameters/ShareId' }
@@ -689,9 +691,10 @@ components:
 
     ServerInfo:
       type: object
-      required: [protocol, limits, captcha, transports]
-      properties:
-        protocol: { type: integer, const: 1 }
+        required: [protocol, contract_version, limits, captcha, transports]
+        properties:
+          protocol: { type: integer, const: 1 }
+          contract_version: { type: string, example: 1.0.0, description: API 契约的 SemVer。破坏性变更递增主版本。 }
         captcha:
           type: object
           required: [provider, enabled]