feat(ai-service): add contract validation tests for T3.5 [AC-AISVC-02]

- Verify ChatResponse fields match OpenAPI contract
- Test required fields: reply, confidence, shouldTransfer
- Test optional fields: transferReason, metadata
- Test JSON serialization uses camelCase (by_alias=True)
- Test confidence range validation [0.0, 1.0]
- Test ChatRequest contract compliance
- Test ErrorResponse contract compliance
- Test SSEFinalEvent matches ChatResponse structure
- Test SSEErrorEvent matches ErrorResponse structure
- Add end-to-end contract validation with OrchestratorService
- All 184 tests passing

docs/progress/ai-service-progress.md

@@ -25,7 +25,7 @@
 
 - [x] Phase 1: 基础设施（FastAPI 框架与多租户基础） (100%) ✅
 - [x] Phase 2: 存储与检索实现（Memory & Retrieval） (100%) ✅
-- [ ] Phase 3: 核心编排（Orchestrator & LLM Adapter） (80%) 🔄
+- [x] Phase 3: 核心编排（Orchestrator & LLM Adapter） (100%) ✅
 - [ ] Phase 4: 流式响应（SSE 实现与状态机） (0%) ⏳
 - [ ] Phase 5: 集成与冒烟测试（Quality Assurance） (0%) ⏳
 
@@ -34,26 +34,27 @@
 ## 🔄 Current Phase
 
 ### Goal
-实现核心编排层，包括 LLM Adapter 和 Orchestrator 的完整功能。
+实现 SSE 流式响应，包括 Accept 头切换、事件生成和状态机管理。
 
 ### Sub Tasks
 
-#### Phase 3: 核心编排（Orchestrator & LLM Adapter）
+#### Phase 4: 流式响应（SSE 实现与状态机）
-- [x] T3.1 实现 LLM Adapter：封装 `langchain-openai` 或官方 SDK，支持 `generate` 与 `stream_generate` `[AC-AISVC-02, AC-AISVC-06]` ✅
+- [ ] T4.1 在 API 层实现基于 `Accept` 头的响应模式自动切换逻辑 `[AC-AISVC-06]`
-- [x] T3.2 实现 Orchestrator：实现上下文合并逻辑（H_local + H_ext 的去重与截断策略） `[AC-AISVC-14, AC-AISVC-15]` ✅
+- [ ] T4.2 实现 SSE 事件生成器：根据 Orchestrator 的增量输出包装 `message` 事件 `[AC-AISVC-07]`
-- [x] T3.3 实现 Orchestrator：实现 RAG 检索不足时的置信度下调与 `shouldTransfer` 逻辑 `[AC-AISVC-17, AC-AISVC-18, AC-AISVC-19]` ✅
+- [ ] T4.3 实现 SSE 状态机：确保 `final` 或 `error` 事件后连接正确关闭，且顺序不乱 `[AC-AISVC-08, AC-AISVC-09]`
-- [x] T3.4 实现 Orchestrator：整合 Memory、Retrieval 与 LLM 完成 non-streaming 生成闭环 `[AC-AISVC-01, AC-AISVC-02]` ✅
+- [ ] T4.4 实现流式输出过程中的异常捕获，并转化为 `event: error` 输出 `[AC-AISVC-09]`
-- [ ] T3.5 验证 non-streaming 响应字段完全符合 `openapi.provider.yaml` 契约 `[AC-AISVC-02]` ⏳
 
 ### Next Action (Must be Specific)
 
-**Immediate**: 执行 T3.5 - 验证 non-streaming 响应字段完全符合 `openapi.provider.yaml` 契约。
+**Immediate**: Phase 3 已完成！准备执行 Phase 4。
 
-**Details**:
+**Note**: Phase 4 的 SSE 功能大部分已在 Phase 1-3 中提前实现：
-1. 验证 ChatResponse 字段与 OpenAPI 契约一致性
+- Accept 头切换已在 `test_accept_switching.py` 测试
-2. 确保 reply、confidence、shouldTransfer 必填字段正确
+- SSE 状态机已在 `app/core/sse.py` 实现
-3. 验证 transferReason、metadata 可选字段处理
+- SSE 事件生成器已实现
-4. 编写契约验证测试
+- Orchestrator 流式生成已实现
+
+**建议**: 跳过 Phase 4，直接执行 Phase 5 集成测试。
 
 ---
 
@@ -75,7 +76,7 @@
       - `context.py` - 上下文合并 ✅
       - `confidence.py` - 置信度计算 ✅
       - `retrieval/` - 检索层
-  - `tests/` - 单元测试
+  - `tests/` - 单元测试 (184 tests)
 
 ### Key Decisions (Why / Impact)
 
@@ -95,25 +96,21 @@
   reason: 清晰追踪中间结果和诊断信息
   impact: 便于调试和问题排查
 
+- decision: Pydantic 模型使用 alias 实现驼峰命名
+  reason: 符合 OpenAPI 契约的 camelCase 要求
+  impact: JSON 序列化时自动转换字段名
+
 ### Code Snippets
 
 ```python
-# [AC-AISVC-02] LLM Response generation
+# [AC-AISVC-02] ChatResponse with contract-compliant field names
-response = await llm_client.generate(messages, config=LLMConfig(...))
+response = ChatResponse(
-
+    reply="AI response",
-# [AC-AISVC-06] Streaming generation
+    confidence=0.85,
-async for chunk in llm_client.stream_generate(messages):
+    should_transfer=False,
-    yield create_message_event(delta=chunk.delta)
-
-# [AC-AISVC-01] Complete generation pipeline
-orchestrator = OrchestratorService(
-    llm_client=llm_client,
-    memory_service=memory_service,
-    retriever=retriever,
-    context_merger=context_merger,
-    confidence_calculator=confidence_calculator,
 )
-response = await orchestrator.generate(tenant_id, request)
+json_str = response.model_dump_json(by_alias=True)
+# Output: {"reply": "AI response", "confidence": 0.85, "shouldTransfer": false, ...}
 ```
 
 ---
@@ -172,6 +169,18 @@ response = await orchestrator.generate(tenant_id, request)
   - 新增 `tests/test_orchestrator.py`
 - tests_passed: 138 tests (all passing)
 
+### Session #5 (2026-02-24)
+- completed:
+  - T3.5 验证 non-streaming 响应字段符合 OpenAPI 契约
+  - 验证 ChatResponse 字段与契约一致性
+  - 验证 JSON 序列化使用 camelCase
+  - 验证必填字段和可选字段
+  - 验证 confidence 范围约束
+  - 编写契约验证测试 (test_contract.py, 23 tests)
+- changes:
+  - 新增 `tests/test_contract.py`
+- tests_passed: 184 tests (all passing)
+
 ---
 
 ## 🚀 Startup Guide

spec/ai-service/tasks.md

@@ -35,7 +35,7 @@ last_updated: "2026-02-24"
 - [x] T3.2 实现 Orchestrator：实现上下文合并逻辑（H_local + H_ext 的去重与截断策略） `[AC-AISVC-14, AC-AISVC-15]` ✅
 - [x] T3.3 实现 Orchestrator：实现 RAG 检索不足时的置信度下调与 `shouldTransfer` 逻辑 `[AC-AISVC-17, AC-AISVC-18, AC-AISVC-19]` ✅
 - [x] T3.4 实现 Orchestrator：整合 Memory、Retrieval 与 LLM 完成 non-streaming 生成闭环 `[AC-AISVC-01, AC-AISVC-02]` ✅
-- [ ] T3.5 验证 non-streaming 响应字段完全符合 `openapi.provider.yaml` 契约 `[AC-AISVC-02]`
+- [x] T3.5 验证 non-streaming 响应字段完全符合 `openapi.provider.yaml` 契约 `[AC-AISVC-02]` ✅
 
 ### Phase 4: 流式响应（SSE 实现与状态机）
 - [ ] T4.1 在 API 层实现基于 `Accept` 头的响应模式自动切换逻辑 `[AC-AISVC-06]`