# 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