spec: 升级 openapi.provider.yaml 至 L2 契约等级 [AC-MCA-08][AC-MCA-12]

spec/ai-robot/openapi.provider.yaml

@@ -9,7 +9,7 @@ info:
     - 人工客服工作台 REST API
     - WebSocket 实时通信协议说明
   version: 1.0.0
-  x-contract-level: L0
+  x-contract-level: L2
   x-consumer: "frontend, wechat-server, douyin-server, jd-server"
   x-provider: "java-main-framework"
 
@@ -41,7 +41,10 @@ paths:
     get:
       operationId: verifyWecomUrl
       summary: 微信回调 URL 验证
-      description: 企业微信回调 URL 验证接口
+      description: |
+        企业微信回调 URL 验证接口。
+        
+        用于验证回调 URL 的有效性，企业微信在配置回调时会发送 GET 请求。
       tags:
         - Channel Callback
       parameters:
@@ -50,21 +53,31 @@ paths:
           required: true
           schema:
             type: string
+            minLength: 1
+            maxLength: 128
+          description: 消息签名，用于验证请求来源
         - name: timestamp
           in: query
           required: true
           schema:
             type: string
+            pattern: '^\d+$'
+          description: 时间戳（秒级），用于防重放攻击
         - name: nonce
           in: query
           required: true
           schema:
             type: string
+            minLength: 1
+            maxLength: 64
+          description: 随机字符串，用于防重放攻击
         - name: echostr
           in: query
           required: true
           schema:
             type: string
+            minLength: 1
+          description: 加密的随机字符串，验证成功后需解密返回
       responses:
         '200':
           description: 验证成功，返回解密后的 echostr
@@ -72,13 +85,31 @@ paths:
             text/plain:
               schema:
                 type: string
-        '500':
+                example: "1234567890"
-          description: 验证失败
+        '400':
+          description: 请求参数错误
           content:
             text/plain:
               schema:
                 type: string
-                example: error
+                enum:
+                  - error
+        '401':
+          description: 签名验证失败
+          content:
+            text/plain:
+              schema:
+                type: string
+                enum:
+                  - error
+        '500':
+          description: 服务器内部错误
+          content:
+            text/plain:
+              schema:
+                type: string
+                enum:
+                  - error
 
     post:
       operationId: handleWecomCallback
@@ -104,18 +135,21 @@ paths:
           required: false
           schema:
             type: string
+            maxLength: 128
           description: 消息签名（用于验签）
         - name: timestamp
           in: query
           required: false
           schema:
             type: string
+            pattern: '^\d+$'
           description: 时间戳（用于防重放）
         - name: nonce
           in: query
           required: false
           schema:
             type: string
+            maxLength: 64
           description: 随机数（用于防重放）
       requestBody:
         required: true
@@ -124,6 +158,7 @@ paths:
             schema:
               type: string
               description: 加密的 XML 消息
+            example: "<xml><Encrypt>...</Encrypt></xml>"
       responses:
         '200':
           description: 处理成功
@@ -131,7 +166,32 @@ paths:
             text/plain:
               schema:
                 type: string
-                example: success
+                enum:
+                  - success
+        '400':
+          description: 请求格式错误
+          content:
+            text/plain:
+              schema:
+                type: string
+                enum:
+                  - success
+        '401':
+          description: 签名验证失败
+          content:
+            text/plain:
+              schema:
+                type: string
+                enum:
+                  - success
+        '500':
+          description: 服务器内部错误（仍返回 success 以避免微信重试）
+          content:
+            text/plain:
+              schema:
+                type: string
+                enum:
+                  - success
 
   /channel/{channelType}/callback:
     post:
@@ -177,18 +237,21 @@ paths:
           required: false
           schema:
             type: string
+            maxLength: 256
           description: 消息签名（可选，具体由渠道决定）
         - name: X-Timestamp
           in: header
           required: false
           schema:
             type: string
+            pattern: '^\d+$'
           description: 时间戳（可选，用于防重放）
         - name: X-Nonce
           in: header
           required: false
           schema:
             type: string
+            maxLength: 64
           description: 随机数（可选，用于防重放）
       requestBody:
         required: true
@@ -204,6 +267,30 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/ApiResponse'
+        '400':
+          description: 请求格式错误
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiResponse'
+        '401':
+          description: 签名验证失败
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiResponse'
+        '404':
+          description: 不支持的渠道类型
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiResponse'
+        '500':
+          description: 服务器内部错误
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiResponse'
 
   /api/sessions:
     get:
@@ -235,6 +322,7 @@ paths:
           required: false
           schema:
             type: string
+            maxLength: 64
           description: 客服ID筛选
         - name: channelType
           in: query
@@ -253,11 +341,25 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/SessionListResponse'
+        '400':
+          description: 请求参数错误
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiResponse'
+        '500':
+          description: 服务器内部错误
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiResponse'
 
   /api/sessions/{sessionId}:
     get:
       operationId: getSession
       summary: 获取会话详情
+      description: |
+        获取指定会话的详细信息。
       tags:
         - Session Management
       parameters:
@@ -266,6 +368,9 @@ paths:
           required: true
           schema:
             type: string
+            minLength: 1
+            maxLength: 64
+          description: 会话ID
       responses:
         '200':
           description: 成功
@@ -273,17 +378,31 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/SessionResponse'
+        '400':
+          description: 请求参数错误
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiResponse'
         '404':
           description: 会话不存在
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/ApiResponse'
+        '500':
+          description: 服务器内部错误
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiResponse'
 
   /api/sessions/{sessionId}/history:
     get:
       operationId: getSessionHistory
       summary: 获取会话消息历史
+      description: |
+        获取指定会话的消息历史记录。
       tags:
         - Session Management
       parameters:
@@ -292,6 +411,9 @@ paths:
           required: true
           schema:
             type: string
+            minLength: 1
+            maxLength: 64
+          description: 会话ID
       responses:
         '200':
           description: 成功
@@ -299,12 +421,33 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/MessageListResponse'
+        '400':
+          description: 请求参数错误
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiResponse'
+        '404':
+          description: 会话不存在
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiResponse'
+        '500':
+          description: 服务器内部错误
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiResponse'
 
   /api/sessions/{sessionId}/accept:
     post:
       operationId: acceptSession
       summary: 接入会话
-      description: 客服接入待处理的会话
+      description: |
+        客服接入待处理的会话。
+        
+        仅状态为 `pending` 的会话可被接入。
       tags:
         - Session Management
       parameters:
@@ -313,6 +456,9 @@ paths:
           required: true
           schema:
             type: string
+            minLength: 1
+            maxLength: 64
+          description: 会话ID
       requestBody:
         required: true
         content:
@@ -324,7 +470,11 @@ paths:
               properties:
                 csId:
                   type: string
+                  minLength: 1
+                  maxLength: 64
                   description: 客服ID
+            example:
+              csId: "cs_001"
       responses:
         '200':
           description: 接入成功
@@ -333,23 +483,44 @@ paths:
               schema:
                 $ref: '#/components/schemas/ApiResponse'
         '400':
-          description: 会话状态不正确
+          description: 会话状态不正确或参数错误
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/ApiResponse'
+              examples:
+                invalid_status:
+                  value:
+                    code: 400
+                    message: "会话状态不正确"
+                missing_csId:
+                  value:
+                    code: 400
+                    message: "客服ID不能为空"
         '404':
           description: 会话不存在
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/ApiResponse'
+              example:
+                code: 404
+                message: "会话不存在"
+        '500':
+          description: 服务器内部错误
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiResponse'
 
   /api/sessions/{sessionId}/message:
     post:
       operationId: sendSessionMessage
       summary: 发送消息
-      description: 客服向会话发送消息
+      description: |
+        客服向会话发送消息。
+        
+        仅状态为 `manual` 的会话可发送消息。
       tags:
         - Session Management
       parameters:
@@ -358,6 +529,9 @@ paths:
           required: true
           schema:
             type: string
+            minLength: 1
+            maxLength: 64
+          description: 会话ID
       requestBody:
         required: true
         content:
@@ -369,11 +543,20 @@ paths:
               properties:
                 content:
                   type: string
+                  minLength: 1
+                  maxLength: 4096
                   description: 消息内容
                 msgType:
                   type: string
+                  enum:
+                    - text
+                    - image
+                    - file
                   default: text
                   description: 消息类型
+            example:
+              content: "您好，请问有什么可以帮助您的？"
+              msgType: "text"
       responses:
         '200':
           description: 发送成功
@@ -382,22 +565,39 @@ paths:
               schema:
                 $ref: '#/components/schemas/ApiResponse'
         '400':
-          description: 会话状态不正确
+          description: 会话状态不正确或参数错误
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/ApiResponse'
+              examples:
+                invalid_status:
+                  value:
+                    code: 400
+                    message: "会话状态不正确"
+                missing_content:
+                  value:
+                    code: 400
+                    message: "消息内容不能为空"
         '404':
           description: 会话不存在
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/ApiResponse'
+        '500':
+          description: 服务器内部错误或消息发送失败
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiResponse'
 
   /api/sessions/{sessionId}/close:
     post:
       operationId: closeSession
       summary: 关闭会话
+      description: |
+        关闭指定的会话。
       tags:
         - Session Management
       parameters:
@@ -406,6 +606,9 @@ paths:
           required: true
           schema:
             type: string
+            minLength: 1
+            maxLength: 64
+          description: 会话ID
       responses:
         '200':
           description: 关闭成功
@@ -413,12 +616,24 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/ApiResponse'
+        '400':
+          description: 请求参数错误
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiResponse'
         '404':
           description: 会话不存在
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/ApiResponse'
+        '500':
+          description: 服务器内部错误
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiResponse'
 
 components:
   schemas:
@@ -431,42 +646,89 @@ components:
         code:
           type: integer
           description: 响应码（0=成功，非0=失败）
+          enum:
+            - 0
+            - 400
+            - 404
+            - 500
         message:
           type: string
+          minLength: 1
+          maxLength: 256
           description: 响应消息
         data:
           type: object
           description: 响应数据（可选）
+      example:
+        code: 0
+        message: "success"
 
     SessionListResponse:
       allOf:
         - $ref: '#/components/schemas/ApiResponse'
         - type: object
+          required:
+            - code
+            - message
+            - data
           properties:
+            code:
+              type: integer
+              enum:
+                - 0
+            message:
+              type: string
             data:
               type: array
               items:
                 $ref: '#/components/schemas/SessionInfo'
+      example:
+        code: 0
+        message: "success"
+        data:
+          - sessionId: "session_001"
+            customerId: "customer_001"
+            status: "manual"
+            channelType: "wechat"
 
     SessionResponse:
       allOf:
         - $ref: '#/components/schemas/ApiResponse'
         - type: object
+          required:
+            - code
+            - message
+            - data
           properties:
+            code:
+              type: integer
+              enum:
+                - 0
+            message:
+              type: string
             data:
               $ref: '#/components/schemas/SessionInfo'
 
     SessionInfo:
       type: object
+      required:
+        - sessionId
+        - customerId
+        - status
       properties:
         sessionId:
           type: string
+          minLength: 1
+          maxLength: 64
           description: 会话ID
         customerId:
           type: string
+          minLength: 1
+          maxLength: 64
           description: 客户ID
         kfId:
           type: string
+          maxLength: 64
           description: 客服账号ID
         channelType:
           type: string
@@ -485,9 +747,11 @@ components:
             - closed
         manualCsId:
           type: string
+          maxLength: 64
           description: 接待客服ID
         lastMessage:
           type: string
+          maxLength: 4096
           description: 最后一条消息
         lastMessageTime:
           type: string
@@ -495,19 +759,35 @@ components:
           description: 最后消息时间
         messageCount:
           type: integer
+          minimum: 0
           description: 消息数量
         createdAt:
           type: string
           format: date-time
+          description: 创建时间
         updatedAt:
           type: string
           format: date-time
+          description: 更新时间
+        metadata:
+          type: object
+          description: 扩展元数据
 
     MessageListResponse:
       allOf:
         - $ref: '#/components/schemas/ApiResponse'
         - type: object
+          required:
+            - code
+            - message
+            - data
           properties:
+            code:
+              type: integer
+              enum:
+                - 0
+            message:
+              type: string
             data:
               type: array
               items:
@@ -515,12 +795,21 @@ components:
 
     MessageInfo:
       type: object
+      required:
+        - msgId
+        - sessionId
+        - senderType
+        - content
       properties:
         msgId:
           type: string
+          minLength: 1
+          maxLength: 128
           description: 消息ID
         sessionId:
           type: string
+          minLength: 1
+          maxLength: 64
           description: 会话ID
         senderType:
           type: string
@@ -531,16 +820,25 @@ components:
             - manual
         senderId:
           type: string
+          maxLength: 64
           description: 发送者ID
         content:
           type: string
+          minLength: 1
+          maxLength: 4096
           description: 消息内容
         msgType:
           type: string
           description: 消息类型
+          enum:
+            - text
+            - image
+            - file
+            - event
         createdAt:
           type: string
           format: date-time
+          description: 创建时间
 
 x-websocket:
   path: /ws/cs/{csId}