用戶(hù)認證API接口完整文檔

概述

本文檔詳細描述了用戶(hù)認證系統的所有API接口，包括登錄認證、用戶(hù)信息獲取、菜單權限管理等功能。所有接口都已在 src/api/PulsAuth.ts 中實(shí)現。

?? 核心認證接口

1. 用戶(hù)登錄

賬號密碼登錄

loginWithPassword(params: LoginParams): Promise<ApiResponse<Record<string, unknown>>>

請求參數：

interface LoginParams {
    account: string;    // 用戶(hù)賬號
    password: string;   // 用戶(hù)密碼（MD5加密）
    phone?: string;     // 手機號（可選）
    verifyCode?: string; // 驗證碼（可選）
}

手機號驗證碼登錄

loginWithPhone(params: LoginParams): Promise<ApiResponse<Record<string, unknown>>>

2. 獲取用戶(hù)認證信息

getUserInfo(): Promise<AuthApiResponse<UserAuthInfo>>

接口路徑： POST /api/auth/GetUserInfo
功能描述： 登錄后獲取用戶(hù)Token和基本認證信息
需要認證： ? 是

響應數據結構：

interface UserAuthInfo {
    token: string;                    // 主要JWT Token
    xiaoqi_token: string;            // 小七系統專(zhuān)用Token
    cachexiaoqi_token: string;       // 緩存Token
    email: string;                   // 用戶(hù)郵箱
    sub: string;                     // 用戶(hù)唯一標識
    exp: string;                     // Token過(guò)期時(shí)間戳
    xiaoqi_keyid: string;           // 小七系統用戶(hù)密鑰ID
    cachexiaoqi_keyid: string;      // 緩存密鑰ID
    xiaoqi_type: string;            // 小七系統類(lèi)型
    cachexiaoqi_type: string;       // 緩存類(lèi)型
    [key: string]: any;             // 其他JWT claims
}

3. 獲取用戶(hù)詳細信息

showUserInfos(): Promise<AuthApiResponse<UserDetailInfo>>

接口路徑： POST /api/auth/ShowUserInfos
功能描述： 獲取用戶(hù)完整的個(gè)人信息、企業(yè)信息和權限數據
需要認證： ? 是

響應數據結構：

interface UserDetailInfo {
    LoginUser: LoginUser;                    // 用戶(hù)基本信息
    name: string;                           // 用戶(hù)顯示名稱(chēng)
    LoginInfo: LoginInfo;                   // 登錄會(huì )話(huà)信息
    LoginType: number;                      // 登錄類(lèi)型
    LoginCompanies: LoginCompany[];         // 關(guān)聯(lián)企業(yè)列表
    LoginDepRoles: any[];                   // 部門(mén)角色信息
    LoginUserExtend: UserExtend[];          // 用戶(hù)擴展信息
    LoginCompaniesExtend: CompanyExtend[];  // 企業(yè)擴展信息
}

4. 獲取用戶(hù)菜單權限

showUserMenus(): Promise<AuthApiResponse<MenuItem[]>>

接口路徑： POST /api/auth/ShowUserMenus
功能描述： 根據用戶(hù)權限獲取可訪(fǎng)問(wèn)的菜單列表
需要認證： ? 是

響應數據結構：

interface MenuItem {
    id: string;                    // 菜單ID
    parentId?: string;            // 父菜單ID
    title: string;                // 菜單標題
    name: string;                 // 菜單名稱(chēng)
    path: string;                 // 路由路徑
    component?: string;           // 組件路徑
    icon?: string;                // 菜單圖標
    orderBy: number;              // 排序號
    isEnabled: number;            // 是否啟用
    isVisible: number;            // 是否可見(jiàn)
    menuType: number;             // 菜單類(lèi)型 0:目錄 1:菜單 2:按鈕
    permission?: string;          // 權限標識
    children?: MenuItem[];        // 子菜單
    meta?: {                      // 路由元信息
        title: string;
        icon?: string;
        hidden?: boolean;
        keepAlive?: boolean;
        requiresAuth?: boolean;
    };
}

?? Token管理接口

1. 刷新Token

refreshUserToken(refreshToken?: string): Promise<AuthApiResponse<UserAuthInfo>>

接口路徑： POST /api/auth/RefreshToken
功能描述： 當Token即將過(guò)期時(shí)調用此接口刷新Token
需要認證： ? 是

2. 驗證Token有效性

validateToken(): Promise<AuthApiResponse<{valid: boolean, exp: number}>>

接口路徑： POST /api/auth/ValidateToken
功能描述： 驗證當前Token是否有效
需要認證： ? 是

3. 用戶(hù)登出

logout(): Promise<AuthApiResponse<any>>

接口路徑： POST /api/auth/Logout
功能描述： 注銷(xiāo)當前用戶(hù)會(huì )話(huà)，清除服務(wù)端Token
需要認證： ? 是

??? 權限管理接口

1. 獲取用戶(hù)權限列表

getUserPermissions(): Promise<AuthApiResponse<string[]>>

接口路徑： POST /api/auth/GetUserPermissions
功能描述： 獲取當前用戶(hù)的詳細權限信息
需要認證： ? 是

2. 切換用戶(hù)企業(yè)

switchCompany(companyId: string): Promise<AuthApiResponse<UserDetailInfo>>

接口路徑： POST /api/auth/SwitchCompany
功能描述： 多企業(yè)用戶(hù)切換當前工作企業(yè)
需要認證： ? 是

?? 數據類(lèi)型定義

用戶(hù)基本信息

interface LoginUser {
    Uuid: string;                 // 用戶(hù)唯一標識
    Fluuid?: string;             // 父級UUID
    Qyuuid: string;              // 企業(yè)UUID
    Username: string;            // 用戶(hù)名
    Email: string;               // 郵箱
    PhoneNumber: string;         // 手機號
    AuthType: string;            // 認證類(lèi)型
    Grade: string;               // 用戶(hù)等級
    Nickname: string;            // 昵稱(chēng)
    Synopsis: string;            // 個(gè)人簡(jiǎn)介
    IsEnabled: number;           // 是否啟用
    IsActive: number;            // 是否激活
    CreateTime: string;          // 創(chuàng  )建時(shí)間
}

企業(yè)信息

interface LoginCompany {
    CompanyId: string;           // 企業(yè)ID
    ParentId: string;            // 父企業(yè)ID
    GroupId: string;             // 集團ID
    BelongName: string;          // 所屬名稱(chēng)
    AreaName: string;            // 區域名稱(chēng)
    Name: string;                // 企業(yè)名稱(chēng)
    Code: string;                // 企業(yè)代碼
    Description: string;         // 企業(yè)描述
    Nsrmc: string;               // 納稅人名稱(chēng)
    Shxydm: string;              // 社會(huì )信用代碼
    IsEnabled: number;           // 是否啟用
}

用戶(hù)擴展信息

interface UserExtend {
    Uuid: string;                // 擴展信息ID
    Fluuid: string;              // 關(guān)聯(lián)用戶(hù)ID
    UserKey: string;             // 擴展鍵名 (如: 'avator', 'slogan')
    UserValues: string;          // 擴展值
}

?? 使用示例

1. 完整登錄流程

import { 
    loginWithPassword, 
    getUserInfo, 
    showUserInfos, 
    showUserMenus 
} from '@/api/PulsAuth';
import { useUserStore } from '@/store/modules/user';

// 用戶(hù)登錄流程
const handleLogin = async (loginForm: LoginParams) => {
    try {
        // 1. 用戶(hù)登錄
        const loginRes = await loginWithPassword(loginForm);
        if (loginRes.Result === 1) {
            const userStore = useUserStore();
            userStore.token = JSON.stringify(loginRes.DataValue);
            
            // 2. 獲取用戶(hù)認證信息
            const authRes = await getUserInfo();
            if (authRes.Result === 1) {
                userStore.setAuthInfo(authRes.DataValue);
            }
            
            // 3. 獲取用戶(hù)詳細信息
            const userRes = await showUserInfos();
            if (userRes.Result === 1) {
                userStore.setUserDetails(userRes.DataValue);
            }
            
            // 4. 獲取用戶(hù)菜單權限
            const menuRes = await showUserMenus();
            if (menuRes.Result === 1) {
                // 處理菜單數據，更新路由
                console.log('用戶(hù)菜單:', menuRes.DataValue);
            }
            
            console.log('登錄成功');
        }
    } catch (error) {
        console.error('登錄失敗:', error);
    }
};

2. Token管理

// Token刷新
const refreshToken = async () => {
    try {
        const res = await refreshUserToken();
        if (res.Result === 1) {
            const userStore = useUserStore();
            userStore.setAuthInfo(res.DataValue);
            return true;
        }
    } catch (error) {
        console.error('Token刷新失敗:', error);
        return false;
    }
};

// Token驗證
const checkTokenValid = async () => {
    try {
        const res = await validateToken();
        return res.Result === 1 && res.DataValue.valid;
    } catch (error) {
        return false;
    }
};

3. 權限檢查

// 獲取用戶(hù)權限
const checkUserPermissions = async () => {
    try {
        const res = await getUserPermissions();
        if (res.Result === 1) {
            const permissions = res.DataValue;
            console.log('用戶(hù)權限:', permissions);
            return permissions;
        }
    } catch (error) {
        console.error('獲取權限失敗:', error);
        return [];
    }
};

4. 企業(yè)切換

// 切換企業(yè)
const handleSwitchCompany = async (companyId: string) => {
    try {
        const res = await switchCompany(companyId);
        if (res.Result === 1) {
            const userStore = useUserStore();
            userStore.setUserDetails(res.DataValue);
            console.log('企業(yè)切換成功');
        }
    } catch (error) {
        console.error('企業(yè)切換失敗:', error);
    }
};

?? 配置說(shuō)明

請求配置

所有認證相關(guān)接口都配置了以下選項：

• withToken: true - 自動(dòng)攜帶認證Token
• isTransformResponse: false - 保持原始響應格式
• 自動(dòng)處理Token過(guò)期和刷新

錯誤處理

// 統一錯誤處理
const handleApiError = (error: any) => {
    if (error.response?.status === 401) {
        // Token過(guò)期，跳轉登錄
        router.push('/login');
    } else if (error.response?.status === 403) {
        // 權限不足
        console.error('權限不足');
    } else {
        console.error('API調用失敗:', error.message);
    }
};

?? 響應格式

所有接口統一使用以下響應格式：

interface AuthApiResponse<T = any> {
    Result: number;              // 結果狀態(tài) 1:成功 0:失敗
    DataValue: T;               // 響應數據
    MessageCode: string;        // 消息代碼
    Message: string;            // 消息描述
    ContentEncoding?: string;   // 內容編碼
    ContentType?: string;       // 內容類(lèi)型
    JsonRequestBehavior?: number;
    MaxJsonLength?: number;
    RecursionLimit?: number;
}

??? 安全注意事項

1. Token安全：所有Token都應安全存儲，避免XSS攻擊
2. 權限驗證：前端權限驗證僅用于UI展示，真正的權限控制在后端
3. 敏感操作：重要操作需要重新驗證身份
4. 數據加密：密碼等敏感信息需要加密傳輸
5. 會(huì )話(huà)管理：及時(shí)清理過(guò)期會(huì )話(huà)和Token

更新日志

• 2025-10-03：
  • 完善所有用戶(hù)認證相關(guān)接口
  • 添加完整的TypeScript類(lèi)型定義
  • 實(shí)現Token管理和權限控制接口
  • 提供詳細的使用示例和文檔