From 2fdc91a54cf0c0c27eec425a1c3292fefc659f65 Mon Sep 17 00:00:00 2001
From: MerCry <jiong1114>
Date: Tue, 24 Feb 2026 12:43:57 +0800
Subject: [PATCH] docs: add ai-service provider openapi [AC-AISVC-01]

---
 java/openapi.deps.yaml                | 188 +++++++++++++++++++
 spec/ai-service/openapi.provider.yaml | 248 ++++++++++++++++++++++++++
 2 files changed, 436 insertions(+)
 create mode 100644 java/openapi.deps.yaml
 create mode 100644 spec/ai-service/openapi.provider.yaml

diff --git a/java/openapi.deps.yaml b/java/openapi.deps.yaml
new file mode 100644
index 0000000..d9ec669
--- /dev/null
+++ b/java/openapi.deps.yaml
@@ -0,0 +1,188 @@
+openapi: 3.0.3
+info:
+  title: AI Service API
+  description: |
+    Python AI 服务接口契约。
+    
+    本文件定义主框架对 AI 服务的接口需求（Consumer-First）。
+    由主框架作为调用方，Python AI 服务作为提供方实现。
+  version: 1.0.0
+  x-contract-level: L0
+  x-consumer: "java-main-framework"
+  x-provider: "python-ai-service"
+
+servers:
+  - url: http://ai-service:8080
+    description: AI 服务地址
+
+paths:
+  /ai/chat:
+    post:
+      operationId: generateReply
+      summary: 生成 AI 回复
+      description: |
+        根据用户消息和会话历史生成 AI 回复。
+        
+        覆盖验收标准：
+        - AC-MCA-04: 主框架通过 HTTP POST 调用 AI 服务
+        - AC-MCA-05: 响应包含 reply、confidence、shouldTransfer 字段
+        - AC-MCA-06: AI 服务不可用时的降级处理（主框架侧实现）
+        - AC-MCA-07: 超时处理（主框架侧实现）
+      tags:
+        - AI Chat
+      x-requirements:
+        - AC-MCA-04
+        - AC-MCA-04-REQ
+        - AC-MCA-04-OPT
+        - AC-MCA-05
+        - AC-MCA-06
+        - AC-MCA-07
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/ChatRequest'
+            example:
+              sessionId: "kf_001_wx123456_1708765432000"
+              currentMessage: "我想了解产品价格"
+              channelType: "wechat"
+      responses:
+        '200':
+          description: 成功生成回复
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ChatResponse'
+              example:
+                reply: "您好，我们的产品价格根据套餐不同有所差异。"
+                confidence: 0.92
+                shouldTransfer: false
+        '400':
+          description: 请求参数错误
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '500':
+          description: 服务内部错误
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '503':
+          description: 服务不可用
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+
+  /ai/health:
+    get:
+      operationId: healthCheck
+      summary: 健康检查
+      description: 检查 AI 服务是否正常运行
+      tags:
+        - Health
+      responses:
+        '200':
+          description: 服务正常
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  status:
+                    type: string
+        '503':
+          description: 服务不健康
+
+components:
+  schemas:
+    ChatRequest:
+      type: object
+      required:
+        - sessionId
+        - currentMessage
+        - channelType
+      properties:
+        sessionId:
+          type: string
+          description: 会话ID（AC-MCA-04-REQ 必填）
+        currentMessage:
+          type: string
+          description: 当前用户消息（AC-MCA-04-REQ 必填）
+        channelType:
+          type: string
+          description: 渠道类型（AC-MCA-04-REQ 必填）
+          enum:
+            - wechat
+            - douyin
+            - jd
+        history:
+          type: array
+          description: 历史消息列表（AC-MCA-04-OPT 可选）
+          items:
+            $ref: '#/components/schemas/ChatMessage'
+        metadata:
+          type: object
+          description: 扩展元数据（AC-MCA-04-OPT 可选）
+          additionalProperties: true
+
+    ChatMessage:
+      type: object
+      required:
+        - role
+        - content
+      properties:
+        role:
+          type: string
+          enum:
+            - user
+            - assistant
+        content:
+          type: string
+
+    ChatResponse:
+      type: object
+      required:
+        - reply
+        - confidence
+        - shouldTransfer
+      properties:
+        reply:
+          type: string
+          description: AI 回复内容（AC-MCA-05 必填）
+        confidence:
+          type: number
+          format: double
+          description: 置信度评分 0.0-1.0（AC-MCA-05 必填）
+        shouldTransfer:
+          type: boolean
+          description: 是否建议转人工（AC-MCA-05 必填）
+        transferReason:
+          type: string
+          description: 转人工原因（可选）
+        metadata:
+          type: object
+          description: 响应元数据（可选）
+          additionalProperties: true
+
+    ErrorResponse:
+      type: object
+      required:
+        - code
+        - message
+      properties:
+        code:
+          type: string
+          description: 错误代码
+        message:
+          type: string
+          description: 错误消息
+        details:
+          type: array
+          description: 详细错误信息（可选）
+          items:
+            type: object
+            additionalProperties: true
diff --git a/spec/ai-service/openapi.provider.yaml b/spec/ai-service/openapi.provider.yaml
new file mode 100644
index 0000000..4688a85
--- /dev/null
+++ b/spec/ai-service/openapi.provider.yaml
@@ -0,0 +1,248 @@
+openapi: 3.0.3
+info:
+  title: AI Service API
+  description: |
+    Python AI 服务对外提供的接口契约（Provider）。
+
+    目标：100% 覆盖并对齐 Java 端 Consumer-First 依赖契约 `java/openapi.deps.yaml`。
+    - 路径与方法必须一致
+    - non-streaming JSON 响应 schema 必须一致（reply/confidence/shouldTransfer 等）
+
+    额外扩展：支持 SSE 流式输出（Accept: text/event-stream）。
+  version: 1.0.0
+  x-contract-level: L0
+  x-provider: "python-ai-service"
+  x-consumer: "java-main-framework"
+
+servers:
+  - url: http://ai-service:8080
+    description: AI 服务地址
+
+tags:
+  - name: AI Chat
+    description: 对话生成
+  - name: Health
+    description: 健康检查
+
+paths:
+  /ai/chat:
+    post:
+      operationId: generateReply
+      summary: 生成 AI 回复
+      description: |
+        根据用户消息和会话历史生成 AI 回复。
+
+        non-streaming：返回 application/json（ChatResponse）。
+        streaming：当请求头包含 `Accept: text/event-stream` 时，以 SSE 推送事件流。
+
+        覆盖验收标准（来自 Java 侧契约描述）：
+        - AC-MCA-04: 主框架通过 HTTP POST 调用 AI 服务
+        - AC-MCA-05: 响应包含 reply、confidence、shouldTransfer 字段
+        - AC-MCA-06: AI 服务不可用时的降级处理（主框架侧实现）
+        - AC-MCA-07: 超时处理（主框架侧实现）
+      tags:
+        - AI Chat
+      x-requirements:
+        - AC-MCA-04
+        - AC-MCA-04-REQ
+        - AC-MCA-04-OPT
+        - AC-MCA-05
+        - AC-MCA-06
+        - AC-MCA-07
+      parameters:
+        - name: X-Tenant-Id
+          in: header
+          required: true
+          description: 租户ID（多租户隔离必填，便于网关/拦截器统一处理）
+          schema:
+            type: string
+        - name: Accept
+          in: header
+          required: false
+          description: |
+            内容协商。
+            - 设置为 text/event-stream 时返回 SSE 事件流
+            - 其他情况返回 application/json
+          schema:
+            type: string
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/ChatRequest'
+            example:
+              sessionId: "kf_001_wx123456_1708765432000"
+              currentMessage: "我想了解产品价格"
+              channelType: "wechat"
+              metadata:
+                channelUserId: "wx123456"
+                extra: "..."
+      responses:
+        '200':
+          description: |
+            成功生成回复。
+
+            注意：
+            - non-streaming：响应 Content-Type 为 application/json
+            - streaming：当请求头 Accept: text/event-stream 时，服务端可返回 text/event-stream（见下方 200 的第二种 content 描述）
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ChatResponse'
+              example:
+                reply: "您好，我们的产品价格根据套餐不同有所差异。"
+                confidence: 0.92
+                shouldTransfer: false
+            text/event-stream:
+              schema:
+                type: string
+                description: |
+                  SSE 事件流（按行文本）。事件模型：
+
+                  1) event: message
+                     - data: {"delta": "..."}
+                     - 返回时机：模型生成过程中多次发送，用于增量渲染。
+
+                  2) event: final
+                     - data: ChatResponse（完整结构化结果，字段至少包含 reply/confidence/shouldTransfer）
+                     - 返回时机：生成结束时发送一次，随后关闭连接。
+
+                  3) event: error
+                     - data: ErrorResponse（结构化错误，至少 code/message，可含 details）
+                     - 返回时机：发生错误时发送一次，随后关闭连接。
+
+                  示例（片段）：
+                  event: message\n
+data: {"delta":"您好，"}\n
+
+                  event: final\n
+data: {"reply":"...","confidence":0.9,"shouldTransfer":false}\n
+        '400':
+          description: 请求参数错误
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '500':
+          description: 服务内部错误
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '503':
+          description: 服务不可用
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+
+  /ai/health:
+    get:
+      operationId: healthCheck
+      summary: 健康检查
+      description: 检查 AI 服务是否正常运行
+      tags:
+        - Health
+      responses:
+        '200':
+          description: 服务正常
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  status:
+                    type: string
+        '503':
+          description: 服务不健康
+
+components:
+  schemas:
+    ChatRequest:
+      type: object
+      required:
+        - sessionId
+        - currentMessage
+        - channelType
+      properties:
+        sessionId:
+          type: string
+          description: 会话ID（AC-MCA-04-REQ 必填）
+        currentMessage:
+          type: string
+          description: 当前用户消息（AC-MCA-04-REQ 必填）
+        channelType:
+          type: string
+          description: 渠道类型（AC-MCA-04-REQ 必填）
+          enum:
+            - wechat
+            - douyin
+            - jd
+        history:
+          type: array
+          description: 历史消息列表（AC-MCA-04-OPT 可选）
+          items:
+            $ref: '#/components/schemas/ChatMessage'
+        metadata:
+          type: object
+          description: 扩展元数据（AC-MCA-04-OPT 可选）
+          additionalProperties: true
+
+    ChatMessage:
+      type: object
+      required:
+        - role
+        - content
+      properties:
+        role:
+          type: string
+          enum:
+            - user
+            - assistant
+        content:
+          type: string
+
+    ChatResponse:
+      type: object
+      required:
+        - reply
+        - confidence
+        - shouldTransfer
+      properties:
+        reply:
+          type: string
+          description: AI 回复内容（AC-MCA-05 必填）
+        confidence:
+          type: number
+          format: double
+          description: 置信度评分 0.0-1.0（AC-MCA-05 必填）
+        shouldTransfer:
+          type: boolean
+          description: 是否建议转人工（AC-MCA-05 必填）
+        transferReason:
+          type: string
+          description: 转人工原因（可选）
+        metadata:
+          type: object
+          description: 响应元数据（可选）
+          additionalProperties: true
+
+    ErrorResponse:
+      type: object
+      required:
+        - code
+        - message
+      properties:
+        code:
+          type: string
+          description: 错误代码
+        message:
+          type: string
+          description: 错误消息
+        details:
+          type: array
+          description: 详细错误信息（可选）
+          items:
+            type: object
+            additionalProperties: true