fix(contracts): quality review fixes for p1a contracts

- status enum active|archived -> active|offline (align requirement docs) - UploadSessionState session-state semantics documented (no failed state) - maxLength: clientTaskId 128 / filename 255 / cursor 512 - PublicPhoto width/height required (layout placeholders) - reusable Unauthorized/InternalError responses (hybrid with inline op-specific codes) - PublicAlbum.translations -> translation (single resolved object) - contentType enum [jpeg/png/heic] (heic provisional pending G2) - minLength 1 on title/name; publicToken pattern ^[0-9a-z]{20,32}$ - CursorPageMeta hasMore/nextCursor invariant documented - public locale: silent fallback to defaultLocale (tech doc section 11) - plan: upload_sessions state comment aligned; P1b adds management photo list + account lookup endpoints Co-Authored-By: Claude Code <noreply@anthropic.com>
2026-09-17 18:06:54 +08:00
parent 1dae00eaef
commit f6448bd006
3 changed files with 152 additions and 581 deletions
@@ -75,11 +75,7 @@ paths:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
-          description: 服务器内部错误（INTERNAL_ERROR）。
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/Error'
+          $ref: '#/components/responses/InternalError'

  /auth/refresh:
    post:
@@ -103,17 +99,9 @@ paths:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
-          description: 令牌缺失、无效或已过期（AUTH_TOKEN_EXPIRED）。
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/Error'
+          $ref: '#/components/responses/Unauthorized'
        '500':
-          description: 服务器内部错误（INTERNAL_ERROR）。
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/Error'
+          $ref: '#/components/responses/InternalError'

  /auth/logout:
    post:
@@ -133,17 +121,9 @@ paths:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
-          description: 令牌缺失、无效或已过期（AUTH_TOKEN_EXPIRED）。
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/Error'
+          $ref: '#/components/responses/Unauthorized'
        '500':
-          description: 服务器内部错误（INTERNAL_ERROR）。
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/Error'
+          $ref: '#/components/responses/InternalError'

  # ─────────────────────────── albums ───────────────────────────

@@ -178,17 +158,9 @@ paths:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
-          description: 未认证（AUTH_TOKEN_EXPIRED）。
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/Error'
+          $ref: '#/components/responses/Unauthorized'
        '500':
-          description: 服务器内部错误（INTERNAL_ERROR）。
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/Error'
+          $ref: '#/components/responses/InternalError'

    get:
      operationId: listAlbums
@@ -221,17 +193,9 @@ paths:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
-          description: 未认证（AUTH_TOKEN_EXPIRED）。
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/Error'
+          $ref: '#/components/responses/Unauthorized'
        '500':
-          description: 服务器内部错误（INTERNAL_ERROR）。
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/Error'
+          $ref: '#/components/responses/InternalError'

  /albums/{albumId}:
    parameters:
@@ -251,11 +215,7 @@ paths:
              schema:
                $ref: '#/components/schemas/Album'
        '401':
-          description: 未认证（AUTH_TOKEN_EXPIRED）。
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/Error'
+          $ref: '#/components/responses/Unauthorized'
        '404':
          description: 相册不存在，或当前用户非成员不可见（ALBUM_NOT_FOUND，避免枚举）。
          content:
@@ -263,11 +223,7 @@ paths:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
-          description: 服务器内部错误（INTERNAL_ERROR）。
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/Error'
+          $ref: '#/components/responses/InternalError'

    patch:
      operationId: updateAlbum
@@ -298,11 +254,7 @@ paths:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
-          description: 未认证（AUTH_TOKEN_EXPIRED）。
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/Error'
+          $ref: '#/components/responses/Unauthorized'
        '403':
          description: 仅创建者或管理员可修改（AUTH_FORBIDDEN）。
          content:
@@ -316,11 +268,7 @@ paths:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
-          description: 服务器内部错误（INTERNAL_ERROR）。
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/Error'
+          $ref: '#/components/responses/InternalError'

  # ─────────────────────────── members ───────────────────────────

@@ -354,11 +302,7 @@ paths:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
-          description: 未认证（AUTH_TOKEN_EXPIRED）。
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/Error'
+          $ref: '#/components/responses/Unauthorized'
        '403':
          description: 仅创建者或管理员可管理成员（AUTH_FORBIDDEN）。
          content:
@@ -378,11 +322,7 @@ paths:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
-          description: 服务器内部错误（INTERNAL_ERROR）。
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/Error'
+          $ref: '#/components/responses/InternalError'

    get:
      operationId: listAlbumMembers
@@ -415,11 +355,7 @@ paths:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
-          description: 未认证（AUTH_TOKEN_EXPIRED）。
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/Error'
+          $ref: '#/components/responses/Unauthorized'
        '404':
          description: 相册不存在，或当前用户不可见（ALBUM_NOT_FOUND）。
          content:
@@ -427,11 +363,7 @@ paths:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
-          description: 服务器内部错误（INTERNAL_ERROR）。
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/Error'
+          $ref: '#/components/responses/InternalError'

  /albums/{albumId}/members/{userId}:
    parameters:
@@ -450,11 +382,7 @@ paths:
        '204':
          description: 已移除，无响应体。
        '401':
-          description: 未认证（AUTH_TOKEN_EXPIRED）。
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/Error'
+          $ref: '#/components/responses/Unauthorized'
        '403':
          description: 无管理权限，或试图移除创建者（AUTH_FORBIDDEN）。
          content:
@@ -468,11 +396,7 @@ paths:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
-          description: 服务器内部错误（INTERNAL_ERROR）。
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/Error'
+          $ref: '#/components/responses/InternalError'

  # ─────────────────────────── categories ───────────────────────────

@@ -506,11 +430,7 @@ paths:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
-          description: 未认证（AUTH_TOKEN_EXPIRED）。
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/Error'
+          $ref: '#/components/responses/Unauthorized'
        '403':
          description: 仅创建者或管理员可管理分类（AUTH_FORBIDDEN）。
          content:
@@ -524,11 +444,7 @@ paths:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
-          description: 服务器内部错误（INTERNAL_ERROR）。
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/Error'
+          $ref: '#/components/responses/InternalError'

  /categories/{categoryId}:
    parameters:
@@ -560,11 +476,7 @@ paths:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
-          description: 未认证（AUTH_TOKEN_EXPIRED）。
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/Error'
+          $ref: '#/components/responses/Unauthorized'
        '403':
          description: 无所属相册的管理权限（AUTH_FORBIDDEN）。
          content:
@@ -578,11 +490,7 @@ paths:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
-          description: 服务器内部错误（INTERNAL_ERROR）。
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/Error'
+          $ref: '#/components/responses/InternalError'

    delete:
      operationId: deleteCategory
@@ -595,11 +503,7 @@ paths:
        '204':
          description: 已删除，无响应体。
        '401':
-          description: 未认证（AUTH_TOKEN_EXPIRED）。
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/Error'
+          $ref: '#/components/responses/Unauthorized'
        '403':
          description: 无所属相册的管理权限（AUTH_FORBIDDEN）。
          content:
@@ -613,11 +517,7 @@ paths:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
-          description: 服务器内部错误（INTERNAL_ERROR）。
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/Error'
+          $ref: '#/components/responses/InternalError'

  # ─────────────────────────── uploads ───────────────────────────

@@ -652,11 +552,7 @@ paths:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
-          description: 未认证（AUTH_TOKEN_EXPIRED）。
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/Error'
+          $ref: '#/components/responses/Unauthorized'
        '403':
          description: 无该相册的上传权限（AUTH_FORBIDDEN）。
          content:
@@ -672,11 +568,7 @@ paths:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
-          description: 服务器内部错误（INTERNAL_ERROR）。
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/Error'
+          $ref: '#/components/responses/InternalError'

    get:
      operationId: listUploads
@@ -709,17 +601,9 @@ paths:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
-          description: 未认证（AUTH_TOKEN_EXPIRED）。
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/Error'
+          $ref: '#/components/responses/Unauthorized'
        '500':
-          description: 服务器内部错误（INTERNAL_ERROR）。
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/Error'
+          $ref: '#/components/responses/InternalError'

  /uploads/{uploadId}/renew:
    parameters:
@@ -739,11 +623,7 @@ paths:
              schema:
                $ref: '#/components/schemas/UploadInitResponse'
        '401':
-          description: 未认证（AUTH_TOKEN_EXPIRED）。
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/Error'
+          $ref: '#/components/responses/Unauthorized'
        '403':
          description: 无权操作该会话或会话不存在（AUTH_FORBIDDEN，不区分以避免枚举）。
          content:
@@ -759,11 +639,7 @@ paths:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
-          description: 服务器内部错误（INTERNAL_ERROR）。
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/Error'
+          $ref: '#/components/responses/InternalError'

  /uploads/{uploadId}/complete:
    parameters:
@@ -793,11 +669,7 @@ paths:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
-          description: 未认证（AUTH_TOKEN_EXPIRED）。
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/Error'
+          $ref: '#/components/responses/Unauthorized'
        '403':
          description: 无权操作该会话或会话不存在（AUTH_FORBIDDEN，不区分以避免枚举）。
          content:
@@ -811,11 +683,7 @@ paths:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
-          description: 服务器内部错误（INTERNAL_ERROR）。
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/Error'
+          $ref: '#/components/responses/InternalError'

  # ─────────────────────────── photos ───────────────────────────

@@ -849,11 +717,7 @@ paths:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
-          description: 未认证（AUTH_TOKEN_EXPIRED）。
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/Error'
+          $ref: '#/components/responses/Unauthorized'
        '403':
          description: 无该照片的管理权限（AUTH_FORBIDDEN）。
          content:
@@ -867,11 +731,7 @@ paths:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
-          description: 服务器内部错误（INTERNAL_ERROR）。
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/Error'
+          $ref: '#/components/responses/InternalError'

    delete:
      operationId: deletePhoto
@@ -884,11 +744,7 @@ paths:
        '204':
          description: 已软删除，无响应体。
        '401':
-          description: 未认证（AUTH_TOKEN_EXPIRED）。
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/Error'
+          $ref: '#/components/responses/Unauthorized'
        '403':
          description: 无该照片的管理权限（AUTH_FORBIDDEN）。
          content:
@@ -902,11 +758,7 @@ paths:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
-          description: 服务器内部错误（INTERNAL_ERROR）。
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/Error'
+          $ref: '#/components/responses/InternalError'

  # ─────────────────────────── public ───────────────────────────

@@ -943,11 +795,7 @@ paths:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
-          description: 服务器内部错误（INTERNAL_ERROR）。
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/Error'
+          $ref: '#/components/responses/InternalError'

  /public/albums/{token}/photos:
    parameters:
@@ -996,11 +844,7 @@ paths:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
-          description: 服务器内部错误（INTERNAL_ERROR）。
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/Error'
+          $ref: '#/components/responses/InternalError'

  /public/albums/{token}/photos/{photoId}:
    parameters:
@@ -1030,11 +874,7 @@ paths:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
-          description: 服务器内部错误（INTERNAL_ERROR）。
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/Error'
+          $ref: '#/components/responses/InternalError'

 components:
  securitySchemes:
@@ -1091,6 +931,7 @@ components:
      description: 分页游标（上一页响应的 nextCursor）。
      schema:
        type: string
+        maxLength: 512
    LocaleQuery:
      name: locale
      in: query
@@ -1098,6 +939,20 @@ components:
      schema:
        $ref: '#/components/schemas/Locale'

+  responses:
+    Unauthorized:
+      description: 未认证：令牌缺失、无效或已过期（AUTH_TOKEN_EXPIRED）。
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+    InternalError:
+      description: 服务器内部错误（INTERNAL_ERROR）。
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+
  schemas:
    # ── 通用 ──

@@ -1135,7 +990,7 @@ components:
    CursorPageMeta:
      type: object
      required: [nextCursor, hasMore]
-      description: 游标分页元信息；各列表响应以 allOf 内嵌本结构（条目 schema 在业务端点中定义）。
+      description: 游标分页元信息；各列表响应以 allOf 内嵌本结构（条目 schema 在业务端点中定义）。不变式：hasMore=true 当且仅当 nextCursor≠null，两者必须成对填充。
      properties:
        nextCursor:
          type: [string, 'null']
@@ -1199,6 +1054,7 @@ components:
          $ref: '#/components/schemas/Locale'
        title:
          type: string
+          minLength: 1
          description: 相册标题。
        description:
          type: [string, 'null']
@@ -1310,6 +1166,7 @@ components:
        publicToken:
          type: string
          readOnly: true
+          pattern: '^[0-9a-z]{20,32}$'
          description: 公开访问令牌（不可枚举）。
        ownerId:
          type: string
@@ -1319,10 +1176,10 @@ components:
          type: string
          readOnly: true
          default: active
-          description: 相册状态。
+          description: 相册状态；offline 表示下线（停止公开访问与新授权签发）。
          enum:
            - active
-            - archived
+            - offline
        defaultLocale:
          $ref: '#/components/schemas/Locale'
        timezone:
@@ -1460,6 +1317,7 @@ components:
          $ref: '#/components/schemas/Locale'
        name:
          type: string
+          minLength: 1
          description: 分类名称。

    CategoryCreateRequest:
@@ -1517,7 +1375,11 @@ components:

    UploadSessionState:
      type: string
-      description: 上传会话状态（服务端视角；本地任务状态见技术实施方案 §5.5）。
+      description: |
+        上传会话状态（服务端视角；本地任务状态见技术实施方案 §5.5）。
+        会话没有 failed 状态：完成核验失败属于单次请求错误（UPLOAD_VERIFY_FAILED），
+        会话保持 pending 可重试；cancelled 为用户主动取消；
+        expired 为超过 expiresAt 未完成（核验时推导或由补偿扫描落定）。
      enum:
        - pending
        - confirmed
@@ -1555,9 +1417,11 @@ components:
          description: 目标分类 ID；缺省为相册默认分类。
        clientTaskId:
          type: string
+          maxLength: 128
          description: 客户端任务幂等键；同一任务的重试必须复用（会话与照片 ID 均复用）。
        filename:
          type: string
+          maxLength: 255
          description: 原始文件名（仅元数据，不作对象唯一标识）。
        bytes:
          type: integer
@@ -1566,7 +1430,8 @@ components:
          description: 申明文件字节数；完成核验时逐一比对。
        contentType:
          type: string
-          description: MIME 类型；仅接受图片类型（JPEG/PNG/HEIC）。
+          enum: [image/jpeg, image/png, image/heic]
+          description: MIME 类型白名单；image/heic 为暂定项，解码能力待 G2 真机验证后确认。

    UploadCredential:
      type: object
@@ -1850,7 +1715,7 @@ components:
        - timezone
        - startAt
        - endAt
-        - translations
+        - translation
        - categories
        - banner
        - viewCount
@@ -1858,6 +1723,7 @@ components:
        publicToken:
          type: string
          readOnly: true
+          pattern: '^[0-9a-z]{20,32}$'
          description: 相册公开令牌。
        resolvedLocale:
          $ref: '#/components/schemas/Locale'
@@ -1877,7 +1743,7 @@ components:
          format: date-time
          readOnly: true
          description: 活动结束时间；未定为 null。
-        translations:
+        translation:
          $ref: '#/components/schemas/PublicAlbumTranslation'
        categories:
          type: array
@@ -1896,8 +1762,8 @@ components:

    PublicPhoto:
      type: object
-      description: 公开照片条目（仅 published 照片；URL 为短期签名，需在过期前刷新）。
-      required: [photoId, thumb, browse, likeCount, publishedAt]
+      description: 公开照片条目（仅 published 照片，处理完成即有宽高；URL 为短期签名，需在过期前刷新）。
+      required: [photoId, width, height, thumb, browse, likeCount, publishedAt]
      properties:
        photoId:
          type: string