聊天 API

聊天接口负责会话管理、消息发送、历史读取和安全指南。主消息接口是普通 JSON 响应，不是稳定 SSE 流式接口。

Endpoint 索引

Method	Path	鉴权	用途
GET	/api/chat/history	Bearer JWT	读取指定会话或默认会话历史。
POST	/api/chat/message	Bearer JWT	发送用户消息并返回 AI 回复。
POST	/api/chat/clear-history	Bearer JWT	清空进程内临时历史。
POST	/api/chat/session	Bearer JWT	创建新会话。
GET	/api/chat/sessions	Bearer JWT	读取当前用户会话列表。
DELETE	/api/chat/session/{session_id}	Bearer JWT	软删除当前用户会话。
GET	/api/chat/safety-guidelines	无	读取通用安全指南。

Endpoint 契约

GET /api/chat/history

项	内容
Request	query page、limit、sessionId
Response	messages、total、page、limit
Errors	400 分页非法；401；404 会话不存在或无权限；500
Consumer	ChatApiClient.getHistory
Handler	chat.get_chat_history
DB Touchpoints	读 chat_sessions 归属；读 dialogue_logs
Tests	tests/services/test_dialogue_repository_phase1.py

POST /api/chat/message

项	内容
Request	message、input_type、user_context、provider、sessionId、idempotencyKey
Response	id、content、ragContext、confidence、sessionId、safety_check
Errors	401；404 会话不存在或无权限；500
Consumer	ChatApiClient.sendMessage、ChatBloc
Handler	chat.send_message -> SendChatMessageUseCase
DB Touchpoints	读写 chat_sessions、dialogue_logs；RAG 读 knowledge_chunks
Tests	tests/use_cases/test_send_chat_message_use_case.py、tests/api/test_chat_idempotency_phase3.py

POST /api/chat/clear-history

项	内容
Request	无
Response	message
Errors	401；500
Consumer	旧清空历史入口
Handler	chat.clear_chat_history
DB Touchpoints	当前不删除数据库记录；仅清空进程内临时历史
Tests	source inspection

POST /api/chat/session

项	内容
Request	当前 handler 不读取 body
Response	id、session_id、user_id、name、时间字段
Errors	401；500
Consumer	ChatApiClient.createSession
Handler	chat.create_new_session
DB Touchpoints	写 chat_sessions
Tests	tests/presenters/test_chat_session_presenter.py

GET /api/chat/sessions

项	内容
Request	query skip、limit
Response	sessions、total、skip、limit
Errors	401；500
Consumer	ChatApiClient.getSessions
Handler	chat.get_sessions
DB Touchpoints	读 chat_sessions
Tests	tests/presenters/test_chat_session_presenter.py

DELETE /api/chat/session/{session_id}

项	内容
Request	path session_id
Response	success、message
Errors	401；404 会话不存在或已删除；500
Consumer	ChatApiClient.deleteSession
Handler	chat.delete_session
DB Touchpoints	软删除本人 chat_sessions.is_deleted
Tests	tests/services/test_dialogue_repository_phase1.py

GET /api/chat/safety-guidelines

项	内容
Request	无
Response	general、emergency_contacts
Errors	500
Consumer	运维 smoke / 安全说明入口
Handler	chat.get_safety_guidelines
DB Touchpoints	不读写 DB
Tests	运维手册 smoke 路径

POST /api/chat/message 请求

Field	Type	Required	Description
message	string	yes	用户输入内容。
input_type	string	no	默认 text。
user_context	object	no	前端附加上下文。
provider	string	no	可指定 LLM provider；默认由后端配置决定。
sessionId	string	no	传入时后端校验会话归属。
idempotencyKey	string	no	客户端重试复用键；后端用同用户同 key 重放已落库响应。

POST /api/chat/message 响应

{
  "id": "<message-id>",
  "content": "AI response text",
  "ragContext": ["source summary"],
  "confidence": 0.86,
  "sessionId": "<session-id>",
  "timestamp": "2026-05-08T10:00:00Z",
  "safety_check": {
    "is_safe": true,
    "risk_level": "safe",
    "flags": [],
    "warnings": []
  },
  "requires_acknowledgment": false
}

主链路

1. get_current_user 校验 JWT 与用户存在性。
2. 如传 sessionId，DialogueRepository.get_session_by_id 校验当前用户归属。
3. 使用 idempotencyKey 查询 dialogue_logs.message_hash，命中时重放响应。
4. SendChatMessageUseCase 编排 safety filter、RAG、LLM manager 和对话持久化。
5. 用户消息、AI 回复、RAG context、safety metadata 写入 dialogue_logs，会话时间和标题更新到 chat_sessions。

来源锚点

• Router: apps/backend_service/app/api/chat.py
• Use case: apps/backend_service/app/use_cases/chat/send_message.py
• Repository: apps/backend_service/app/repositories/dialogue_repository.py
• Flutter: apps/flutter_app/lib/api/chat_api_client.dart
• Tests: apps/backend_service/tests/use_cases/test_send_chat_message_use_case.py、apps/backend_service/tests/api/test_chat_idempotency_phase3.py