daniel.w
/
backend
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
backend/generate/database/mongo/Doc/DATABASE_SCHEMA.md

458 lines
15 KiB
Markdown
Raw Normal View History

feat: update mongo doc
2025-11-12 08:17:23 +00:00
# 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