feat: chat integration, tenant admin spec, backend chat service, miniprogram updates, DEMO moved to tmp, XCX-TEST removed, migrations & docs

apps/backend/app/schemas/xcx_board.py

@@ -1,3 +1,8 @@
+# AI_CHANGELOG
+# - 2026-03-20 | Prompt: R3 项目类型筛选接口重建 | SkillFilterEnum 和 ProjectFilterEnum
+#   枚举值从 all/chinese/snooker/mahjong/karaoke 改为 ALL/BILLIARD/SNOOKER/MAHJONG/KTV，
+#   与 dws.cfg_area_category.category_code 一致，消除前后端映射层。
+
 """三看板接口 Pydantic Schema（BOARD-1/2/3 请求参数枚举 + 响应模型）。"""
 
 from __future__ import annotations
@@ -22,12 +27,14 @@ class CoachSortEnum(str, Enum):
 
 
 class SkillFilterEnum(str, Enum):
-    """BOARD-1 技能筛选。"""
-    all = "all"
-    chinese = "chinese"
-    snooker = "snooker"
-    mahjong = "mahjong"
-    karaoke = "karaoke"
+    """BOARD-1 技能筛选（值与 dws.cfg_area_category.category_code 一致）。"""
+    # CHANGE 2026-03-20 | R3 修复：枚举值从 chinese/snooker 等前端自定义值
+    # 改为数据库 category_code（BILLIARD/SNOOKER/MAHJONG/KTV），消除映射层。
+    ALL = "ALL"
+    BILLIARD = "BILLIARD"
+    SNOOKER = "SNOOKER"
+    MAHJONG = "MAHJONG"
+    KTV = "KTV"
 
 
 class BoardTimeEnum(str, Enum):
@@ -53,12 +60,14 @@ class CustomerDimensionEnum(str, Enum):
 
 
 class ProjectFilterEnum(str, Enum):
-    """BOARD-2 项目筛选。"""
-    all = "all"
-    chinese = "chinese"
-    snooker = "snooker"
-    mahjong = "mahjong"
-    karaoke = "karaoke"
+    """BOARD-2 项目筛选（值与 dws.cfg_area_category.category_code 一致）。"""
+    # CHANGE 2026-03-20 | R3 修复：枚举值从 chinese/snooker 等前端自定义值
+    # 改为数据库 category_code（BILLIARD/SNOOKER/MAHJONG/KTV），消除映射层。
+    ALL = "ALL"
+    BILLIARD = "BILLIARD"
+    SNOOKER = "SNOOKER"
+    MAHJONG = "MAHJONG"
+    KTV = "KTV"
 
 
 class FinanceTimeEnum(str, Enum):

apps/backend/app/schemas/xcx_chat.py

@@ -0,0 +1,106 @@
+"""
+小程序 CHAT 模块 Pydantic 模型。
+
+覆盖：对话历史列表、消息查看、发送消息、SSE 流式请求等场景。
+"""
+
+from __future__ import annotations
+
+from app.schemas.base import CamelModel
+
+
+# ---------------------------------------------------------------------------
+# 对话历史（CHAT-1）
+# ---------------------------------------------------------------------------
+
+
+class ChatHistoryItem(CamelModel):
+    """对话历史列表项。"""
+
+    id: int
+    title: str
+    customer_name: str | None = None
+    last_message: str | None = None
+    timestamp: str  # ISO 8601，最后消息时间
+    unread_count: int = 0
+
+
+class ChatHistoryResponse(CamelModel):
+    """CHAT-1 对话历史列表响应。"""
+
+    items: list[ChatHistoryItem]
+    total: int
+    page: int
+    page_size: int
+
+
+# ---------------------------------------------------------------------------
+# 消息查看（CHAT-2）
+# ---------------------------------------------------------------------------
+
+
+class ReferenceCard(CamelModel):
+    """引用卡片，附加在 AI 回复消息中的结构化上下文数据。"""
+
+    type: str  # 'customer' | 'record'
+    title: str
+    summary: str
+    data: dict[str, str]  # 键值对详情
+
+
+class ChatMessageItem(CamelModel):
+    """对话消息项。"""
+
+    id: int
+    role: str  # 'user' | 'assistant'
+    content: str
+    created_at: str  # ISO 8601（统一字段名）
+    reference_card: ReferenceCard | None = None
+
+
+class ChatMessagesResponse(CamelModel):
+    """CHAT-2 对话消息列表响应。"""
+
+    chat_id: int
+    items: list[ChatMessageItem]
+    total: int
+    page: int
+    page_size: int
+
+
+# ---------------------------------------------------------------------------
+# 发送消息（CHAT-3）
+# ---------------------------------------------------------------------------
+
+
+class MessageBrief(CamelModel):
+    """消息摘要（用于发送消息响应）。"""
+
+    id: int
+    content: str
+    created_at: str  # ISO 8601
+
+
+class SendMessageRequest(CamelModel):
+    """CHAT-3 发送消息请求体。"""
+
+    content: str
+
+
+class SendMessageResponse(CamelModel):
+    """CHAT-3 发送消息响应（含用户消息和 AI 回复）。"""
+
+    user_message: MessageBrief
+    ai_reply: MessageBrief
+
+
+# ---------------------------------------------------------------------------
+# SSE 流式（CHAT-4）
+# ---------------------------------------------------------------------------
+
+
+class ChatStreamRequest(CamelModel):
+    """CHAT-4 SSE 流式请求体。"""
+
+    chat_id: int
+    content: str

apps/backend/app/schemas/xcx_coaches.py

@@ -1,3 +1,7 @@
+# AI_CHANGELOG
+# - 2026-03-20 | Prompt: M4 emoji 注释修复 | heart_emoji 注释从旧 3 级（❤️/💛/🤍）
+#   改为 P6 权威定义的 4 级（💖/🧡/💛/💙），与 compute_heart_icon() 实际逻辑对齐。
+
 from __future__ import annotations
 
 from app.schemas.base import CamelModel
@@ -43,7 +47,9 @@ class TopCustomer(CamelModel):
     name: str
     initial: str
     avatar_gradient: str
-    heart_emoji: str    # ❤️ / 💛 / 🤍
+    # CHANGE 2026-03-20 | M4 修复: emoji 注释与 P6 权威定义对齐（4 级映射）
+    # intent: 注释应反映 compute_heart_icon() 的实际 4 级映射（💖🧡💛💙）
+    heart_emoji: str    # 💖 / 🧡 / 💛 / 💙
     score: str
     score_color: str
     service_count: int

apps/backend/app/schemas/xcx_config.py

@@ -1,4 +1,8 @@
-"""CONFIG-1 技能类型响应 Schema。"""
+# AI_CHANGELOG
+# - 2026-03-20 | Prompt: R3 项目类型筛选接口重建 | SkillTypeItem.key 注释从
+#   chinese/snooker 改为 BILLIARD/SNOOKER，label 说明改为从 display_name 读取。
+
+"""CONFIG-1 项目类型筛选器响应 Schema。"""
 
 from __future__ import annotations
 
@@ -6,7 +10,14 @@ from app.schemas.base import CamelModel
 
 
 class SkillTypeItem(CamelModel):
-    key: str    # chinese/snooker/mahjong/karaoke
-    label: str  # 中文标签
-    emoji: str  # 表情符号
-    cls: str    # 前端样式类
+    """项目类型筛选器选项。
+
+    key 值与 dws.cfg_area_category.category_code 一致
+    （BILLIARD/SNOOKER/MAHJONG/KTV），"不限"选项 key="ALL"。
+    """
+    # CHANGE 2026-03-20 | R3 修复：key 从 chinese/snooker 改为 BILLIARD/SNOOKER，
+    # label 从 display_name 读取（含 emoji），cls 保留但后端不再填充。
+    key: str    # BILLIARD/SNOOKER/MAHJONG/KTV/ALL
+    label: str  # display_name（含 emoji，如 "🎱 中式/追分"）
+    emoji: str  # short_name（单 emoji，如 "🎱"）
+    cls: str    # 前端样式类（预留，当前为空字符串）

apps/backend/app/schemas/xcx_customers.py

@@ -1,3 +1,7 @@
+# AI_CHANGELOG
+# - 2026-03-20 | Prompt: M4 emoji 注释修复 | FavoriteCoach.emoji 注释从旧 2 级（💖/💛）
+#   改为 P6 权威定义的 4 级（💖/🧡/💛/💙），与 compute_heart_icon() 实际逻辑对齐。
+
 from __future__ import annotations
 
 from app.schemas.base import CamelModel
@@ -28,7 +32,9 @@ class CoachTask(CamelModel):
     metrics: list[MetricItem] = []
 
 class FavoriteCoach(CamelModel):
-    emoji: str          # 💖 / 💛
+    # CHANGE 2026-03-20 | M4 修复: emoji 注释与 P6 权威定义对齐（4 级映射）
+    # intent: 注释应反映 compute_heart_icon() 的实际 4 级映射（💖🧡💛💙）
+    emoji: str          # 💖 / 🧡 / 💛 / 💙
     name: str
     relation_index: str
     index_color: str