使用說明文件 - UserManagement 類

LWCJacky 2025/1/10 手冊自製網頁模板授權元件

# 使用說明文件 - `UserManagement` 類

English (opens new window)

# 簡介

UserManagement 類提供了一套完整的用戶管理系統，支援新增用戶、分配角色、檢查權限等功能。此類使用了 SQLite 資料庫來保存和管理用戶數據，並將其角色和權限資料結合到一個簡單的架構中。

# 資料表結構

在資料庫中，共有三個主要的資料表：

users 表
- 保存用戶基本資料，如用戶唯一識別碼（sub）、名稱、電子郵件、頭像等。
permissions 表
- 定義所有可用的權限名稱與其優先順序。
roles 表
- 保存用戶與其分配的權限間的關聯。每位用戶可以有多個角色，每個角色對應特定的權限。

# 資料表架構

# users 表

欄位名稱	類型	說明
`id`	INTEGER	用戶自增 ID，主鍵
`sub`	TEXT	用戶唯一識別碼，需唯一
`name`	TEXT	用戶名稱
`picture`	TEXT	用戶頭像
`email`	TEXT	用戶電子郵件
`created_at`	DATETIME	用戶建立時間
`updated_at`	DATETIME	用戶更新時間

# permissions 表

欄位名稱	類型	說明
`id`	INTEGER	權限自增 ID，主鍵
`role`	TEXT	權限名稱，需唯一
`priority`	INTEGER	權限優先順序
`created_at`	DATETIME	權限建立時間
`updated_at`	DATETIME	權限更新時間

# roles 表

欄位名稱	類型	說明
`id`	INTEGER	角色自增 ID，主鍵
`sub`	TEXT	用戶唯一識別碼，來自 `users`
`role`	TEXT	權限名稱，來自 `permissions`
`created_at`	DATETIME	角色建立時間
`updated_at`	DATETIME	角色更新時間

# 方法介紹

# `init(db_file)`

初始化方法，接收資料庫檔案的路徑，並自動建立資料表（如果尚未存在）。

# `get_connection()`

建立並返回一個新的資料庫連線。

# `create_tables()`

創建 users, permissions, roles 三個資料表（如果不存在）。

# `add_permission(role, priority)`

新增權限，接收權限名稱 role 及其優先順序 priority。

範例：

user_mgmt.add_permission('admin', 1)

# `assign_role(sub, role)`

將權限分配給用戶。sub 是用戶唯一識別碼，role 是欲分配的權限名稱。

範例：

user_mgmt.assign_role("U1234567890abcdef1234567890abcdef", "admin")

# `validate_user_permission(sub, required_role)`

驗證用戶是否具備所需的權限。sub 是用戶唯一識別碼，required_role 是所需的權限名稱。

範例：

if user_mgmt.validate_user_permission("U6185c50e69a8c1433abfcaf8b947f1f0", "admin"):
    print("使用者具備管理員權限")

# `insert_user(sub, name, email, picture=None)`

插入或更新用戶基本資訊。sub 是用戶唯一識別碼，name 是用戶名稱，email 是用戶的電子郵件，picture 是頭像的 URL。

範例：

user_mgmt.insert_user(
    sub="U1234567890abcdef1234567890abcdef",
    name="John Doe",
    email="john@example.com",
    picture="https://example.com/picture.jpg"
)

# `get_user_by_id(user_id)`

根據用戶 ID 獲取用戶資訊。

範例：

user = user_mgmt.get_user_by_id("U6185c50e69a8c1433abfcaf8b947f1f0")
print(user)

# `get_user_roles(user_id)`

根據用戶 ID 獲取用戶的所有角色。

範例：

roles = user_mgmt.get_user_roles("U6185c50e69a8c1433abfcaf8b947f1f0")
print(roles)

# `check_email_exists(email)`

檢查電子郵件是否已存在於資料庫中。

範例：

if user_mgmt.check_email_exists("john@example.com"):
    print("Email 已存在")

# `fetch_users()`

獲取所有用戶的基本資訊。

範例：

users = user_mgmt.fetch_users()
print(users)

# `get_fetch_users()`

以字典形式獲取所有用戶資訊。

範例：

users = user_mgmt.get_fetch_users()
print(json.dumps(users, indent=4, ensure_ascii=False))

# `get_fetch_available_roles()`

獲取所有可用的角色及其優先順序。

範例：

roles = user_mgmt.get_fetch_available_roles()
print(roles)

# `get_fetch_roles_for_user(sub)`

根據用戶唯一識別碼（sub）獲取該用戶的所有角色。

範例：

roles = user_mgmt.get_fetch_roles_for_user("U6185c50e69a8c1433abfcaf8b947f1f0")
print(roles)

# `remove_role(user_id, role)`

刪除用戶的指定角色。

範例：

user_mgmt.remove_role("U6185c50e69a8c1433abfcaf8b947f1f0", "admin")

# 使用範例

if __name__ == "__main__":
    user_mgmt = UserManagement('../user_management.db')

    # 添加權限
    user_mgmt.add_permission('admin', 1)
    user_mgmt.add_permission('user', 10)

    # 檢查 email 是否已存在
    email = "taro@example.com"
    if user_mgmt.check_email_exists(email):
        print(f"Email {email} 已存在。")
    else:
        print(f"Email {email} 可用。")

    # 插入用戶
    user_mgmt.insert_user(
        sub="U1234567890abcdef1234567890abcdef",
        name="Taro",
        email=email,
        picture="https://profile.example.com/pic.jpg"
    )

    # 分配角色
    user_mgmt.assign_role("U1234567890abcdef1234567890abcdef", "admin")
    
    # 驗證用戶權限
    try:
        permission = user_mgmt.validate_user_permission("U1234567890abcdef1234567890abcdef", "admin")
        print(f"權限驗證結果: {permission}")
    except PermissionError as e:
        print(e)

    # 獲取用戶列表
    print(json.dumps(user_mgmt.get_fetch_users(), indent=4, ensure_ascii=False))

# 結語

UserManagement 類提供了靈活且功能強大的用戶管理解決方案，適合需要管理多用戶、角色和權限的應用。此類透過使用 SQLite 資料庫，便於在小型和中型應用中實作完整的用戶管理功能。

LWCJacky