backend/generate/database/mongo/Doc/DATABASE_SCHEMA.md

MongoDB 資料庫結構文檔

本文檔描述所有 MongoDB 集合（Collection）的結構定義。

目錄

• Member 模組
  • account
  • account_uid_binding
  • user_info
  • count
• Permission 模組
  • permission
  • role
  • role_permission
  • user_role

---

Member 模組

account

集合名稱: account

說明: 用戶帳號認證資訊，儲存登入憑證、加密密碼和平台相關資料。

欄位定義

欄位名稱	類型	必填	說明
_id	ObjectID	是	MongoDB 自動生成的唯一識別碼
login_id	string	是	唯一登入識別碼（email、phone、username）
token	string	是	加密後的密碼或平台特定的 token
platform	int8	是	平台類型：1=credentials, 2=google, 3=line, 4=apple
create_at	int64	否	建立時間（Unix 時間戳，納秒）
update_at	int64	否	更新時間（Unix 時間戳，納秒）

索引

1. 複合唯一索引: {login_id: 1, platform: 1}
   • 確保同一平台下 login_id 唯一
2. 時間索引: {create_at: 1}
   • 用於按建立時間排序和查詢

Platform 枚舉值

• 1 = credentials (Digimon 平台)
• 2 = google
• 3 = line
• 4 = apple

AccountType 枚舉值

• 1 = phone (手機)
• 2 = email (信箱)
• 3 = platform (自定義帳號)

AlarmType 枚舉值

• 0 = uninitialized (未初始化)
• 1 = no_alert (未告警)
• 2 = system_alert (系統告警中)

---

account_uid_binding

集合名稱: account_uid_binding

說明: 帳號與 UID 的綁定關係，用於將多個帳號（不同平台）綁定到同一個用戶。

欄位定義

欄位名稱	類型	必填	說明
_id	ObjectID	是	MongoDB 自動生成的唯一識別碼
login_id	string	是	登入識別碼
uid	string	是	用戶唯一識別碼
type	int32	是	帳號類型：1=phone, 2=email, 3=platform
create_at	int64	否	建立時間（Unix 時間戳，納秒）
update_at	int64	否	更新時間（Unix 時間戳，納秒）

索引

1. 唯一索引: {login_id: 1}
   • 確保 login_id 唯一
2. 索引: {uid: 1}
   • 用於查詢某用戶的所有帳號綁定
3. 時間索引: {create_at: 1}
   • 用於按建立時間排序

---

user_info

集合名稱: user_info

說明: 用戶個人資料，包含詳細的用戶資訊，與認證憑證分離。

欄位定義

欄位名稱	類型	必填	說明
_id	ObjectID	是	MongoDB 自動生成的唯一識別碼
uid	string	是	用戶唯一識別碼
avatar_url	string	否	用戶頭像 URL
full_name	string	否	用戶全名
nickname	string	否	用戶暱稱
gender_code	int64	否	性別代碼
birthdate	int64	否	生日（格式：19930417）
address	string	否	用戶地址
alarm_category	int32	是	通知設定類型：0=未初始化, 1=未告警, 2=系統告警中
user_status	int32	是	用戶帳號狀態：0=未初始化, 1=未驗證, 2=啟用中, 3=停權中
preferred_language	string	是	偏好語言
currency	string	是	偏好貨幣
phone_number	string	否	電話號碼（驗證後顯示）
email	string	否	電子郵件（驗證後顯示）
create_at	int64	否	建立時間（Unix 時間戳，納秒）
update_at	int64	否	更新時間（Unix 時間戳，納秒）

索引

1. 唯一索引: {uid: 1}
   • 確保 uid 唯一
2. 時間索引: {create_at: 1}
   • 用於按建立時間排序

UserStatus 枚舉值

• 0 = uninitialized (未初始化)
• 1 = unverified (尚未驗證)
• 2 = active (啟用中)
• 3 = suspended (停權中)

---

count

集合名稱: count

說明: 自增 ID 計數器，用於生成唯一序號。

欄位定義

欄位名稱	類型	必填	說明
_id	ObjectID	是	MongoDB 自動生成的唯一識別碼
name	string	是	計數器名稱（唯一）
counter	uint64	是	當前計數值
create_at	int64	否	建立時間（Unix 時間戳，納秒）
update_at	int64	否	更新時間（Unix 時間戳，納秒）

索引

1. 唯一索引: {name: 1}
   • 確保計數器名稱唯一

---

Permission 模組

permission

集合名稱: permission

說明: 權限實體，定義系統中的各種權限，支援階層結構和 API 權限。

欄位定義

欄位名稱	類型	必填	說明
_id	ObjectID	是	MongoDB 自動生成的唯一識別碼
parent_id	ObjectID	否	父權限 ID（用於階層結構）
name	string	是	權限名稱（唯一）
http_method	string	否	HTTP 方法（GET、POST、PUT、DELETE 等）
http_path	string	否	HTTP 路徑（API 端點）
status	int8	是	權限狀態：0=停用, 1=啟用, 2=已刪除
type	int8	是	權限類型：1=後台權限, 2=前台權限
create_time	int64	是	建立時間（Unix 時間戳，秒）
update_time	int64	是	更新時間（Unix 時間戳，秒）

索引

1. 唯一索引: {name: 1}
   • 確保權限名稱唯一
2. 複合唯一稀疏索引: {http_path: 1, http_method: 1} (sparse: true)
   • 確保 API 權限的路徑和方法組合唯一（只索引存在這些欄位的文檔）
3. 查詢索引: {status: 1}
   • 用於查詢啟用/停用的權限
4. 查詢索引: {parent_id: 1}
   • 用於查詢子權限
5. 複合索引: {type: 1, status: 1}
   • 用於按類型和狀態組合查詢
6. 時間戳索引: {create_time: 1}
   • 用於排序和時間範圍查詢

RecordState 枚舉值

• 0 = inactive (停用)
• 1 = active (啟用)
• 2 = deleted (已刪除)

Type 枚舉值

• 1 = backend (後台權限)
• 2 = frontend (前台權限)

---

role

集合名稱: role

說明: 角色實體，定義系統中的角色，每個角色可以擁有多個權限。

欄位定義

欄位名稱	類型	必填	說明
_id	ObjectID	是	MongoDB 自動生成的唯一識別碼
client_id	int	是	客戶端 ID
uid	string	是	角色唯一識別碼（唯一）
name	string	是	角色名稱
status	int8	是	角色狀態：0=停用, 1=啟用, 2=已刪除
create_time	int64	是	建立時間（Unix 時間戳，秒）
update_time	int64	是	更新時間（Unix 時間戳，秒）

索引

1. 唯一索引: {uid: 1}
   • 確保角色 UID 唯一
2. 複合唯一索引: {client_id: 1, name: 1}
   • 確保同一客戶端下角色名稱唯一
3. 查詢索引: {client_id: 1}
   • 用於按客戶端查詢
4. 查詢索引: {status: 1}
   • 用於按狀態查詢
5. 複合索引: {client_id: 1, status: 1}
   • 用於按客戶端和狀態組合查詢
6. 時間戳索引: {create_time: 1}
   • 用於排序和時間範圍查詢
7. 時間戳索引: {update_time: -1} (降序)
   • 用於按更新時間排序

預設角色數據

系統會自動插入以下初始角色：

• ADMIN - 管理員
• OPERATOR - 操作員
• USER - 一般使用者
• PLAYER - 陪玩專員

---

role_permission

集合名稱: role_permission

說明: 角色權限關聯表，建立角色與權限的多對多關係。

欄位定義

欄位名稱	類型	必填	說明
_id	ObjectID	是	MongoDB 自動生成的唯一識別碼
role_id	ObjectID	是	角色 ID
permission_id	ObjectID	是	權限 ID
create_time	int64	是	建立時間（Unix 時間戳，秒）
update_time	int64	是	更新時間（Unix 時間戳，秒）

索引

1. 複合唯一索引: {role_id: 1, permission_id: 1}
   • 確保角色和權限的組合唯一（避免重複關聯）
2. 查詢索引: {role_id: 1}
   • 用於查詢某角色的所有權限
3. 查詢索引: {permission_id: 1}
   • 用於查詢擁有某權限的所有角色
4. 複合索引: {permission_id: 1, status: 1}
   • 用於按權限和狀態組合查詢
5. 時間戳索引: {create_time: 1}
   • 用於排序和時間範圍查詢

---

user_role

集合名稱: user_role

說明: 用戶角色關聯表，建立用戶與角色的關係（一個用戶只能有一個角色）。

欄位定義

欄位名稱	類型	必填	說明
_id	ObjectID	是	MongoDB 自動生成的唯一識別碼
brand	string	是	品牌識別碼
uid	string	是	用戶唯一識別碼（唯一）
role_id	string	是	角色 ID（角色 UID）
status	int8	是	狀態：0=停用, 1=啟用, 2=已刪除
create_time	int64	是	建立時間（Unix 時間戳，秒）
update_time	int64	是	更新時間（Unix 時間戳，秒）

索引

1. 唯一索引: {uid: 1}
   • 確保一個用戶只能有一個角色
2. 查詢索引: {role_id: 1}
   • 用於查詢某角色的所有用戶
3. 查詢索引: {brand: 1}
   • 用於按品牌查詢
4. 查詢索引: {status: 1}
   • 用於按狀態查詢
5. 複合索引: {brand: 1, role_id: 1}
   • 用於按品牌和角色組合查詢
6. 複合索引: {brand: 1, status: 1}
   • 用於按品牌和狀態組合查詢
7. 時間戳索引: {create_time: 1}
   • 用於排序和時間範圍查詢

---

資料類型說明

時間戳記

• Member 模組: 使用 int64 類型，單位為納秒（nanoseconds），欄位名為 create_at、update_at
• Permission 模組: 使用 int64 類型，單位為秒（seconds），欄位名為 create_time、update_time

枚舉類型

Platform (平台類型)

• 1 = credentials (Digimon 平台)
• 2 = google
• 3 = line
• 4 = apple

Status (帳號狀態)

• 0 = uninitialized (未初始化)
• 1 = unverified (尚未驗證)
• 2 = active (啟用中)
• 3 = suspended (停權中)

RecordState (記錄狀態)

• 0 = inactive (停用)
• 1 = active (啟用)
• 2 = deleted (已刪除)

Type (權限類型)

• 1 = backend (後台權限)
• 2 = frontend (前台權限)

AccountType (帳號類型)

• 1 = phone (手機)
• 2 = email (信箱)
• 3 = platform (自定義帳號)

AlarmType (通知類型)

• 0 = uninitialized (未初始化)
• 1 = no_alert (未告警)
• 2 = system_alert (系統告警中)

---

索引總覽

Member 模組索引

集合	索引類型	索引欄位	唯一	說明
account	複合唯一	login_id, platform	✅	確保同一平台下 login_id 唯一
account	單一	create_at	❌	時間排序
account_uid_binding	唯一	login_id	✅	確保 login_id 唯一
account_uid_binding	單一	uid	❌	查詢用戶的所有帳號
account_uid_binding	單一	create_at	❌	時間排序
user_info	唯一	uid	✅	確保 uid 唯一
user_info	單一	create_at	❌	時間排序
count	唯一	name	✅	確保計數器名稱唯一

Permission 模組索引

集合	索引類型	索引欄位	唯一	稀疏	說明
permission	唯一	name	✅	❌	權限名稱唯一
permission	複合唯一稀疏	http_path, http_method	✅	✅	API 權限唯一
permission	單一	status	❌	❌	狀態查詢
permission	單一	parent_id	❌	❌	子權限查詢
permission	複合	type, status	❌	❌	類型和狀態組合查詢
permission	單一	create_time	❌	❌	時間排序
role	唯一	uid	✅	❌	角色 UID 唯一
role	複合唯一	client_id, name	✅	❌	同客戶端下角色名稱唯一
role	單一	client_id	❌	❌	客戶端查詢
role	單一	status	❌	❌	狀態查詢
role	複合	client_id, status	❌	❌	客戶端和狀態組合查詢
role	單一	create_time	❌	❌	時間排序
role	單一	update_time	❌	❌	更新時間排序（降序）
role_permission	複合唯一	role_id, permission_id	✅	❌	避免重複關聯
role_permission	單一	role_id	❌	❌	角色權限查詢
role_permission	單一	permission_id	❌	❌	權限角色查詢
role_permission	複合	permission_id, status	❌	❌	權限和狀態組合查詢
role_permission	單一	create_time	❌	❌	時間排序
user_role	唯一	uid	✅	❌	一個用戶一個角色
user_role	單一	role_id	❌	❌	角色用戶查詢
user_role	單一	brand	❌	❌	品牌查詢
user_role	單一	status	❌	❌	狀態查詢
user_role	複合	brand, role_id	❌	❌	品牌和角色組合查詢
user_role	複合	brand, status	❌	❌	品牌和狀態組合查詢
user_role	單一	create_time	❌	❌	時間排序

---

關聯關係

Member 模組

account (1) ──< (N) account_uid_binding (N) >── (1) user_info

• 一個 account 可以對應一個 account_uid_binding
• 一個 user_info 可以對應多個 account_uid_binding（多個帳號綁定到同一用戶）

Permission 模組

role (N) <──> (N) permission (透過 role_permission)
user_role (N) >── (1) role

• 角色和權限是多對多關係（透過 role_permission）
• 用戶和角色是一對一關係（透過 user_role，一個用戶只能有一個角色）

---

注意事項

1. 時間戳記差異：

   • Member 模組使用納秒級時間戳（create_at、update_at）
   • Permission 模組使用秒級時間戳（create_time、update_time）

2. 唯一性約束：

   • account: login_id + platform 組合必須唯一
   • account_uid_binding: login_id 必須唯一
   • user_info: uid 必須唯一
   • permission: name 必須唯一，http_path + http_method 組合必須唯一（稀疏索引）
   • role: uid 必須唯一，client_id + name 組合必須唯一
   • role_permission: role_id + permission_id 組合必須唯一
   • user_role: uid 必須唯一（一個用戶只能有一個角色）

3. 稀疏索引：

   • permission 集合的 http_path + http_method 索引是稀疏索引，只索引存在這些欄位的文檔

4. 預設數據：

   • role 集合會自動插入 4 個預設角色：ADMIN、OPERATOR、USER、PLAYER