updates

app/routes/api.py

@@ -7,6 +7,7 @@ from app.services.message_service import (
     get_messages,
     send_and_save,
     save_messages,
+    WECHAT_ERROR_MAP,
 )
 from app.services.wechat_client import sync_msg, list_accounts
 from app.config import settings
@@ -57,7 +58,11 @@ async def send_message(
 ):
     """发送消息"""
     result = await send_and_save(db, req.external_userid, req.content, req.open_kfid)
-    return result
+    errcode = result.get("errcode", -1)
+    return {
+        **result,
+        "errmsg_cn": WECHAT_ERROR_MAP.get(errcode, result.get("errmsg", "")),
+    }
 
 
 @router.post("/sync")
@@ -72,10 +77,12 @@ async def sync_messages(
     saved = 0
     if msg_list:
         saved = await save_messages(db, msg_list)
+    errcode = result.get("errcode", -1)
     return {
         **result,
         "saved": saved,
         "total": len(msg_list),
+        "errmsg_cn": WECHAT_ERROR_MAP.get(errcode, result.get("errmsg", "")),
     }
 
 

app/services/message_service.py

@@ -134,6 +134,32 @@ async def send_and_save(db: AsyncSession, external_userid: str, content: str,
     return result
 
 
+# 微信客服 API 常见错误码 → 中文说明
+WECHAT_ERROR_MAP = {
+    95000: "客服账号 ID (open_kfid) 无效",
+    95001: "发送消息数量超限：客户未回复时，12 小时内最多主动发送 5 条消息",
+    95002: "客户会话已结束，无法发送消息",
+    95003: "客户不在当前客服账号的接待范围内",
+    95004: "接待人员未实名，无法发送消息",
+    95005: "接待人员未在企业微信客户端在线，无法发送消息",
+    48001: "API 接口无权限，请检查 Secret 对应的应用权限",
+    40001: "access_token 无效或已过期",
+    41001: "缺少 access_token 参数",
+    42001: "access_token 过期",
+    40003: "不合法的 OpenID",
+    40014: "不合法的 access_token",
+    45009: "API 调用频率超限",
+}
+
+
+def _wechat_errmsg(result: dict) -> str:
+    """将微信 API 错误码转为中文说明"""
+    code = result.get("errcode", 0)
+    if code == 0:
+        return "ok"
+    return WECHAT_ERROR_MAP.get(code, result.get("errmsg", f"未知错误(errcode={code})"))
+
+
 def _normalize_origin(origin) -> str:
     """将微信 API 返回的 origin 整数转为字符串"""
     if isinstance(origin, int):

app/static/app.js

@@ -150,7 +150,7 @@ async function sendMessage() {
             showToast("发送成功");
             await loadMessages(currentUser);
         } else {
-            showToast("发送失败: " + (result.errmsg || JSON.stringify(result)), "error");
+            showToast("发送失败: " + (result.errmsg_cn || result.errmsg || JSON.stringify(result)), "error");
         }
     } catch (e) {
         showToast("发送失败: " + e.message, "error");
@@ -176,7 +176,7 @@ async function syncMessages() {
             await loadConversations();
             if (currentUser) await loadMessages(currentUser);
         } else {
-            showToast("同步失败: " + (data.errmsg || JSON.stringify(data)), "error");
+            showToast("同步失败: " + (data.errmsg_cn || data.errmsg || JSON.stringify(data)), "error");
         }
     } catch (e) {
         showToast("同步失败: " + e.message, "error");