1

src/shared/api/http.test.ts

@@ -66,6 +66,13 @@ describe('API error diagnostics', () => {
     }
   })
 
+  it('translates notification recipient error codes into actionable Chinese messages', () => {
+    expect(getApiErrorDetails(new ApiResponseError('NOTIFICATION_RECIPIENT_FORBIDDEN', 'A0400')).message)
+      .toBe('角色编码不存在或当前账号无权使用该角色，请检查后重试')
+    expect(getApiErrorDetails(new ApiResponseError('NOTIFICATION_RECIPIENT_EMPTY', 'A0400')).message)
+      .toBe('该角色下暂无可接收消息的有效用户，请先为角色分配启用中的成员')
+  })
+
   it('preserves a backend credential error for an explicit login request', () => {
     const error = new ApiResponseError(
       '用户名或密码错误',

src/shared/api/http.ts

@@ -53,6 +53,15 @@ let authRefreshHandler: AuthRefreshHandler | null = null
 let authSessionExpiredHandler: AuthSessionExpiredHandler | null = null
 let activeRefresh: Promise<string> | null = null
 
+const businessErrorMessages: Record<string, string> = {
+  NOTIFICATION_RECIPIENT_FORBIDDEN: '角色编码不存在或当前账号无权使用该角色，请检查后重试',
+  NOTIFICATION_RECIPIENT_EMPTY: '该角色下暂无可接收消息的有效用户，请先为角色分配启用中的成员',
+}
+
+function friendlyBusinessMessage(message?: string | null) {
+  return (message && businessErrorMessages[message]) || message || undefined
+}
+
 export function registerAuthRefreshHandler(handler: AuthRefreshHandler) {
   authRefreshHandler = handler
 }
@@ -134,7 +143,7 @@ export function getApiErrorDetails(
         ? '当前账号无权访问该数据，请联系管理员确认权限'
         : error.code.startsWith('S05')
           ? '服务暂时不可用，请稍后重试'
-          : error.message
+          : friendlyBusinessMessage(error.message) || '接口请求失败'
     return { message, code: error.code, requestId: error.requestId, traceId: error.traceId }
   }
   if (axios.isAxiosError(error)) {
@@ -156,7 +165,7 @@ export function getApiErrorDetails(
             ? '服务暂时不可用，请稍后重试'
             : undefined
     return {
-      message: statusMessage || response?.message || response?.error || fallback,
+      message: statusMessage || friendlyBusinessMessage(response?.message || response?.error) || fallback,
       code: response?.code || (error.response?.status ? `HTTP_${error.response.status}` : undefined),
       requestId: response?.requestId || undefined,
       traceId: response?.traceId || undefined,