458 lines
15 KiB
Markdown
458 lines
15 KiB
Markdown
# MongoDB 資料庫結構文檔
|
||
|
||
本文檔描述所有 MongoDB 集合（Collection）的結構定義。
|
||
|
||
## 目錄
|
||
|
||
- [Member 模組](#member-模組)
|
||
- [account](#account)
|
||
- [account_uid_binding](#account_uid_binding)
|
||
- [user_info](#user_info)
|
||
- [count](#count)
|
||
- [Permission 模組](#permission-模組)
|
||
- [permission](#permission)
|
||
- [role](#role)
|
||
- [role_permission](#role_permission)
|
||
- [user_role](#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
|
||
|