GSS.Vital.BizForm.SDK 0.1.5

BizForm API .NET SDK

這是一個用於存取 VitalBizform 系統 API 的 .NET SDK，提供完整的 API 封裝，讓開發者能夠輕鬆地與 VitalBizform 系統進行互動。

目錄

• 系統需求
• 安裝方式
• 快速開始
• 功能特點
• 使用範例
• 錯誤處理
• 版本資訊
• API 功能說明

系統需求

• .NET 9.0 或更高版本
• Visual Studio 2022 或更高版本
• 有效的 API 金鑰（請參考 API Key 產生說明）

安裝方式

使用 .NET CLI：

dotnet add package GSS.Vital.BizForm.SDK

或使用 Visual Studio 的 Package Manager Console：

Install-Package GSS.Vital.BizForm.SDK

快速開始

1. 設定方式

SDK 提供多種設定方式，依優先順序如下：

環境變數（最高優先）

# 必要設定
BIZFORM_API_BASE_URL=https://bizform.vikosmos.com/Backend/
BIZFORM_API_LOGIN_URL=https://member.vikosmos.com/cas/login
BIZFORM_API_TOKEN_URL=https://bizform.vikosmos.com/Backend/api/account/token
BIZFORM_USERNAME=your-username
BIZFORM_PASSWORD=your-password

# 選用設定
BIZFORM_BEARER_TOKEN=your-bearer-token
BIZFORM_API_KEY=your-api-key
BIZFORM_DEPOT_ID=your-depot-id
BIZFORM_TOKEN_REFRESH_MINUTES=10
BIZFORM_REQUEST_TIMEOUT_SECONDS=30

程式碼設定

services.AddBizFormSDK(options =>
{
    options.BaseUrl = "https://bizform.vikosmos.com/Backend/";
    options.LoginUrl = "https://member.vikosmos.com/cas/login";
    options.TokenUrl = "https://bizform.vikosmos.com/Backend/api/account/token";
    options.ClientId = "your-username";
    options.ClientSecret = "your-password";
    options.TokenRefreshMinutes = 10;
    options.RequestTimeoutSeconds = 30;
});

功能特點

核心功能

表單管理

• 建立、讀取、更新、刪除表單
• 批次處理功能
• 表單狀態追蹤
• 自定義表單欄位

提交管理

• 表單提交
• 提交記錄查詢
• 提交狀態追蹤
• 批次提交處理

檔案管理

• 檔案上傳/下載
• 檔案版本控制
• 檔案預覽
• 檔案權限管理

使用者管理

• 使用者認證
• 權限控制
• 角色管理
• 使用者邀請

技術特性

• 模組化設計：支援依賴注入，易於整合
• 非同步支援：全面的非同步操作支援
• Token 管理：自動的 JWT Token 管理與更新
• 錯誤處理：統一的錯誤處理機制
• 日誌記錄：詳細的操作日誌
• 高度可測試：完整的單元測試支援

使用範例

表單管理

// 初始化服務
var bizFormService = serviceProvider.GetRequiredService<IBizFormService>();

// 取得表單列表
var forms = await bizFormService.GetFormsAsync(token);

使用者管理

// 取得使用者清單
var userListRequest = new UserListRequest 
{
    PageSize = 20,
    PageIndex = 0,
    Keyword = "john",
    OrderBy = "displayName",
    Enabled = true
};
var users = await bizFormService.GetUserListAsync(token, userListRequest);

// 邀請新使用者 (需要管理者權限)
bool success = await bizFormService.InviteUserAsync(
    token: "your-admin-token",
    email: "newuser@example.com"
);

錯誤處理

異常類型

• ArgumentException：參數驗證失敗（如：電子郵件格式不正確）
• HttpRequestException：API 請求失敗，包含詳細的錯誤訊息
• InvalidOperationException：操作無效（如：API 回傳空值）
• UnauthorizedAccessException：認證失敗或權限不足

錯誤處理範例

try
{
    // 呼叫 SDK 方法
    var users = await bizFormService.GetUserListAsync(token, request);
}
catch (ArgumentException ex)
{
    // 處理參數錯誤
    logger.LogError("參數錯誤: {Message}", ex.Message);
}
catch (HttpRequestException ex)
{
    // 處理 API 請求錯誤
    logger.LogError("API 請求失敗: {Message}", ex.Message);
}
catch (UnauthorizedAccessException ex)
{
    // 處理認證或權限錯誤
    logger.LogError("認證失敗: {Message}", ex.Message);
}
catch (Exception ex)
{
    // 處理其他未預期的錯誤
    logger.LogError("未預期的錯誤: {Message}", ex.Message);
}

API 功能說明

使用者管理 API

GetTokenAsync

Task<string> GetTokenAsync()

取得認證 Token。此 Token 用於後續 API 呼叫的身份驗證。

• 回傳：JWT Token 字串
• 錯誤：認證失敗時拋出異常

GetUserListAsync

Task<IEnumerable<User>> GetUserListAsync(string token)

取得系統中所有使用者清單。

• 參數：
  • token：認證 Token
• 回傳：使用者清單
• 錯誤：權限不足或 Token 無效時拋出異常

GetUserAsync

Task<User> GetUserAsync(string token, string email)

取得單一使用者的詳細資訊。

• 參數：
  • token：認證 Token
  • email：要查詢的使用者電子郵件
• 回傳：
  • User 物件：查詢成功時返回使用者資訊
  • null：使用者不存在
• 錯誤：
  • 電子郵件格式錯誤
  • Token 無效

// 使用範例
var user = await bizFormService.GetUserAsync(token, "user@example.com");
if (user != null)
{
    Console.WriteLine($"使用者名稱: {user.DisplayName}");
    Console.WriteLine($"是否為管理者: {user.IsManager}");
    Console.WriteLine($"帳號狀態: {(user.Disabled ? "已停用" : "啟用中")}");
}

InviteUserAsync

Task<bool> InviteUserAsync(string token, string email)

邀請新使用者加入系統（需要管理者權限）。

• 參數：
  • token：認證 Token
  • email：被邀請者的電子郵件
• 回傳：
  • true：邀請成功
  • false：邀請失敗
• 錯誤：
  • 電子郵件格式錯誤
  • 權限不足
  • Token 無效

DisableUserAsync

Task<bool> DisableUserAsync(string token, string email)

停用指定使用者的帳號（需要管理者權限）。

• 參數：
  • token：認證 Token
  • email：要停用的使用者電子郵件
• 回傳：
  • true：停用成功
  • false：使用者不存在
• 錯誤：
  • 電子郵件格式錯誤
  • 權限不足
  • Token 無效

使用範例

// 取得 Token
var token = await bizFormService.GetTokenAsync();

// 取得使用者清單
var users = await bizFormService.GetUserListAsync(token);

// 邀請新使用者
var invited = await bizFormService.InviteUserAsync(token, "newuser@example.com");

// 停用使用者
var disabled = await bizFormService.DisableUserAsync(token, "user@example.com");

版本資訊

當前版本

• 版本號：0.0.2
• 發布日期：2024-12-24
• 支援的 .NET 版本：.NET 8.0+

更新記錄

• 1.0.1 (2024-12-13)
  • 修正 Form 模型中的 Privileges 屬性型別
  • 優化 JSON 反序列化處理
  • 新增使用者管理功能
• 1.0.0 (2024-12-01)
  • 初始版本發布
  • 完整支援表單管理 API
  • 整合 JWT 認證機制