---
doc_id: room-types-spec
title: Aile 聊天室類型完整規格說明書
description: Aile 聊天室類型、RoomModel、狀態、策略工廠、建立流程、成員分組與未讀計數規格，供開發團隊參考。
slug: /specifications/room-types-spec
product: Aile
category: specification
audience:
  - developer
  - architect
  - qa
visibility: public
status: published
version: 1.0.0
owner: aile-platform
updated_at: 2026-06-13
tags:
  - Aile
  - Room
  - Message
  - 規格說明書
rendered_html: /rendered/specifications/room-types-spec/
download: true
sidebar_position: 5
---

# Aile 聊天室類型完整規格說明書

**版本：** v1.0  
**最後更新：** 2026-06-13  
**服務核心：** `aile-service-room`（策略工廠模式）  

---

## 1. 概述

Aile 系統採用**策略工廠模式（Strategy Factory Pattern）**管理 12 種聊天室類型。每種類型由一個獨立的 `RoomStrategy` 實現類處理，透過 `@Component(RoomType.XXX)` 註冊到 `RoomFactory.strategyMap`，執行時依 `RoomModel.type` 動態分發。

### 1.1 架構設計

```
RoomFactory.strategyMap  （Map<type, RoomStrategy>）
  │
  ├── person        → PersonRoomImpl
  ├── accountPerson → AccountPersonRoomImpl
  ├── friend        → FriendRoomImpl
  ├── group         → GroupRoomImpl
  ├── discuss       → DiscussRoomImpl
  ├── services      → ServiceRoomImpl
  ├── serviceMember → ServiceMemberRoomImpl
  ├── business      → BusinessRoomImpl
  ├── aileSystem    → AileSystemRoomImpl
  ├── aiwowSystem   → AiwowSystemRoomImpl
  ├── system        → SystemRoomImpl
  └── lineGroup     → LineGroupRoomImpl
```

---

## 2. RoomModel（聊天室通用模型）

MongoDB 集合：`aile.room`

```java
@Document("aile.room")
public class RoomModel extends BaseModel {
    String name;                // 聊天室名稱
    String type;                // 聊天室類型（12 種之一）
    String tenantId;            // 租戶 ID
    String accountId;           // 帳號 ID（創建者）
    String ownerId;             // 擁有者 ID
    Boolean isCustomName;       // 是否自定義名稱
    String avatarId;            // 頭像 ID
    String serviceNumberId;     // 服務號 ID（服務號相關聊天室使用）
    Boolean isExternal;         // 服務號是否對外
    Long lastSequence;          // 最後消息序號
    RoomStatus status;          // 聊天室狀態
    MessageVO lastMessage;      // 最後一條消息快照
    String homePagePicId;       // 首頁背景圖 ID
    // 物件（Business）相關
    String businessId;          // 業務物件 ID
    String businessName;        // 物件名稱
    BusinessStatus businessStatus; // 物件狀態
    String businessDescription; // 物件描述
    Long businessEndTime;       // 物件結束時間
    Long businessCompleteTime;  // 物件完成時間
    String mainRoomId;          // 主聊天室 ID（Business 子房用）
    String mergeTargetRoomId;   // 合併目標聊天室 ID（Saga 合併後使用）
    String lineGroupId;         // LINE 群組 ID（LineGroup 專用）
}
```

### 2.1 RoomStatus（聊天室狀態）

| 狀態 | 說明 |
|------|------|
| `Enable` | 正常啟用 |
| `Disable` | 被禁用（附禁用時長） |
| `Delete` | 已刪除（軟刪除） |
| `Danger` | 不安全，有風險 |
| `Complaint` | 被檢舉 |
| `Forbid` | 被禁言 |
| `Block` | 被封鎖 |

### 2.2 BusinessStatus（物件狀態，Business 類聊天室使用）

| 狀態 | 說明 |
|------|------|
| `Pending` | 尚未開始 |
| `Progress` | 進行中 |
| `Revision` | 返回修改 |
| `Complete` | 已完成 |

---

## 3. 12 種聊天室類型詳解

### 3.1 `person` — 個人聊天室

| 屬性 | 值 |
|------|-----|
| 策略實現 | `PersonRoomImpl` |
| 成員範圍 | 僅創建者本人 |
| 用途 | 個人筆記、草稿、待辦提醒、系統通知收納 |
| isMulti | ❌ |
| isAccountRoom | ❌ |

**設計意圖：** 每個 Account 有一個 `person` 聊天室（`AccountModel.personRoomId` 指向），用於系統向該帳號推送個人化消息。

**消息發送規則：** 僅向房間內的所有成員（即本人）發送。

---

### 3.2 `accountPerson` — 帳號個人聊天室

| 屬性 | 值 |
|------|-----|
| 策略實現 | `AccountPersonRoomImpl` |
| 成員範圍 | 僅帳號本人 |
| 用途 | 跨租戶的帳號級系統通知（如生態邀請、系統公告） |
| isMulti | ❌ |
| isAccountRoom | ✅ |

**設計意圖：** 比 `person` 更上層的帳號級聊天室，不依附於任何租戶。用於 Aile 生態級系統消息。

---

### 3.3 `friend` — 好友聊天室

| 屬性 | 值 |
|------|-----|
| 策略實現 | `FriendRoomImpl` |
| 成員範圍 | 2 人 |
| 用途 | 員工之間的一對一私聊 |
| isMulti | ❌ |
| isAccountRoom | ❌ |

**設計意圖：** 租戶內部兩位員工之間的私聊頻道。固定雙人，不可擴充成員。

---

### 3.4 `group` — 群組聊天室

| 屬性 | 值 |
|------|-----|
| 策略實現 | `GroupRoomImpl` |
| 成員範圍 | 多人（≥3） |
| 用途 | 員工群聊 |
| isMulti | ✅ |
| isAccountRoom | ❌ |

**設計意圖：** 租戶內部的多人工作群聊。支援 @提及、群公告等功能。

---

### 3.5 `discuss` — 討論聊天室

| 屬性 | 值 |
|------|-----|
| 策略實現 | `DiscussRoomImpl` |
| 成員範圍 | 多人 |
| 用途 | 主題討論 |
| isMulti | ✅ |
| isAccountRoom | ❌ |

**設計意圖：** 以特定主題或文件為中心的討論空間。與 `group` 的區別在於更偏重非同步討論，可附屬於某個主題/任務。

---

### 3.6 `services` — 客服聊天室

| 屬性 | 值 |
|------|-----|
| 策略實現 | `ServiceRoomImpl` |
| 成員範圍 | 客戶 + 服務號 + 客服人員 |
| 用途 | **客戶與服務號的私聊客服通道** |
| isMulti | ❌ |
| isAccountRoom | ❌ |

**設計意圖：** 這是 Aile 最核心的聊天室類型。每當客戶透過 LINE / WhatsApp 等渠道聯繫服務號時，系統自動建立一個 `services` 聊天室。

**關鍵行為：**
- 自動建立 `ServiceSession`（客服會話）
- 觸發助手管線（`AssistantTriggerPublishService`）
- 支援機器人自動接待 → 轉人工流程
- 消息透過 `GatewayFeign` 向外部渠道發送
- 發送時注入 `ServiceIdentityTag`（服務號身份標記）

**成員構成（MemberGroupType）：**

| 分組 | 說明 |
|------|------|
| `ServiceAgent` | 當前接待客服 |
| `ServiceOwner` | 服務號 Owner |
| `ServiceMember` | 服務號管理成員 |
| `ProvisionalMember` | 臨時加入的內部成員 |
| `ProvisionalCustomer` | 外部客戶 |

---

### 3.7 `serviceMember` — 服務號成員聊天室

| 屬性 | 值 |
|------|-----|
| 策略實現 | `ServiceMemberRoomImpl` |
| 成員範圍 | 服務號內部成員 |
| 用途 | 服務號客服之間的內部溝通 |
| isMulti | ✅ |
| isAccountRoom | ❌ |

**設計意圖：** 每個服務號自動建立一個內部群聊，該服務號的所有客服成員（ServiceMember）自動加入。用於客服之間的轉接溝通、疑難討論。

---

### 3.8 `business` — 物件聊天室

| 屬性 | 值 |
|------|-----|
| 策略實現 | `BusinessRoomImpl` |
| 成員範圍 | 多人 |
| 用途 | 附屬於業務物件（訂單/案件/表單等）的聊天室 |
| isMulti | ✅ |
| isAccountRoom | ❌ |

**設計意圖：** 以業務物件（如訂單、案件）為中心建立聊天室。`RoomModel` 中的 `businessId`、`businessName`、`businessStatus` 欄位用於關聯業務物件及其生命週期狀態。

**關鍵特性：**
- 支援 `mainRoomId`：子聊天室可歸屬於主聊天室（如一個訂單下多個子討論）
- 支援 `BusinessStatus` 生命週期（Pending → Progress → Revision → Complete）
- 不同的 `type` + `mainRoomId` + `serviceNumberId` + `businessStatus` 組合索引

---

### 3.9 `aileSystem` — Aile 系統聊天室

| 屬性 | 值 |
|------|-----|
| 策略實現 | `AileSystemRoomImpl` |
| 成員範圍 | 系統 + 員工 |
| 用途 | Aile 平台級系統通知 |
| isMulti | ❌ |
| isAccountRoom | ✅ |

**設計意圖：** 每個員工與 Aile 平台之間的 1:1 系統通知頻道。用於接收平台級公告、安全提醒、帳號通知等。`TenantEmployeeModel.systemRoomId` 指向這個聊天室。

---

### 3.10 `aiwowSystem` — Aiwow 系統聊天室

| 屬性 | 值 |
|------|-----|
| 策略實現 | `AiwowSystemRoomImpl` |
| 成員範圍 | 系統 + 員工 |
| 用途 | Aiwow 子系統通知 |
| isMulti | ❌ |
| isAccountRoom | ✅ |

**設計意圖：** 與 `aileSystem` 類似，但歸屬於 Aiwow 子系統。用於區分不同來源的系統通知。

---

### 3.11 `system` — 通用系統聊天室

| 屬性 | 值 |
|------|-----|
| 策略實現 | `SystemRoomImpl` |
| 成員範圍 | 多人 |
| 用途 | 系統級群發通知 |
| isMulti | ❌（不在 isMulti 判斷中） |
| isAccountRoom | ❌ |

**設計意圖：** 更通用的系統級聊天室，可由系統向多位員工推送消息。消息發送時會排除發送者本人。

---

### 3.12 `lineGroup` — LINE 群組聊天室

| 屬性 | 值 |
|------|-----|
| 策略實現 | `LineGroupRoomImpl` |
| 成員範圍 | 服務號 + LINE 群組成員 |
| 用途 | LINE 群組在 Aile 中的映射 |
| isMulti | ❌（獨立判斷邏輯） |
| isAccountRoom | ❌ |

**設計意圖：** 這是為 LINE 渠道群組場景設計的專用聊天室類型。不創建 `ServiceSession`，不走機器人流程。詳見 `line-group-implementation-spec.md`。

---

## 4. 類型分類總覽

### 4.1 依成員規模

| 分類 | 類型 | 判斷方法 |
|------|------|----------|
| **多人** | `group`, `discuss`, `business`, `serviceMember` | `isMulti(type)` |
| **非多人** | `person`, `accountPerson`, `friend`, `services`, `aileSystem`, `aiwowSystem`, `system`, `lineGroup` | — |

### 4.2 依帳號層級

| 分類 | 類型 | 判斷方法 |
|------|------|----------|
| **帳號級** | `accountPerson`, `aileSystem`, `aiwowSystem` | `isAccountRoom(type)` |
| **租戶級** | 其餘 9 種類型 | — |

### 4.3 依通用性

| 分類 | 類型 | 判斷方法 |
|------|------|----------|
| **通用聊天室** | `discuss`, `friend`, `group`, `serviceMember` | `isCommon(type)` |
| **特殊聊天室** | 其餘 8 種類型 | — |

### 4.4 依服務號關聯

| 關聯類型 | 類型 |
|----------|------|
| **強關聯服務號** | `services`, `serviceMember`, `lineGroup`, `business` |
| **可關聯服務號** | `group`, `discuss` |
| **無關聯** | `person`, `accountPerson`, `friend`, `aileSystem`, `aiwowSystem`, `system` |

---

## 5. 聊天室建立流程

### 5.1 統一入口

```
前端 / API 呼叫
  │
  └── RoomController.create(dto)
        │
        ├── 依 dto.type 選擇對應 RoomStrategy
        │
        └── RoomStrategy.createAdpter(adpterDto)
              │
              ├── valid()       → 參數校驗
              ├── create()      → 建立 RoomModel + 寫入 MongoDB
              ├── joinMembers() → 加入初始成員
              └── 返回 RoomModel
```

### 5.2 消息發送流程

```
MessageController.send(dto)
  │
  └── MessageServiceImpl.sendMessage(dto)
        │
        ├── 查找 RoomModel
        ├── 建立 MessageModel
        ├── roomFactory.get(roomModel.getType()).sendMessage(room, message)
        │     │
        │     ├── checkMessage()      → 校驗 + 補齊發送者資訊
        │     ├── memberFilter()      → 過濾接收成員
        │     ├── send()              → 實際推送（Socket.IO）
        │     ├── dispatchSavedMessage() → 離線消息處理
        │     └── sendBatchToGateway()   → 外部渠道發送（services/lineGroup）
        │
        └── 寫入 Elasticsearch (index: aile.message)
```

---

## 6. 策略實現繼承關係

```
RoomStrategy (interface)
  │
  └── CommonRoomImpl (abstract)         ← 通用邏輯基底
        │
        ├── PersonRoomImpl              @Component("person")
        ├── AccountPersonRoomImpl       @Component("accountPerson")  
        ├── FriendRoomImpl              @Component("friend")
        ├── GroupRoomImpl               @Component("group")
        ├── DiscussRoomImpl             @Component("discuss")
        ├── ServiceRoomImpl             @Component("services")
        ├── ServiceMemberRoomImpl       @Component("serviceMember")
        ├── BusinessRoomImpl            @Component("business")
        ├── AileSystemRoomImpl          @Component("aileSystem")
        ├── AiwowSystemRoomImpl         @Component("aiwowSystem")
        ├── SystemRoomImpl              @Component("system")
        └── LineGroupRoomImpl           @Component("lineGroup")
```

每個子類可覆寫的方法：

| 方法 | 說明 |
|------|------|
| `valid()` | 建立聊天室前的參數校驗 |
| `checkMessage()` | 發送前檢查 + 補齊發送者名稱 |
| `memberFilter()` | 過濾接收成員列表 |
| `send()` | 實際推送消息（Socket.IO） |
| `dispatchSavedMessage()` | 離線消息處理 |

---

## 7. 快速對照表

| 類型 | 成員規模 | 隸屬層級 | 用途場景 | ServiceSession | 助手觸發 | 外部渠道 |
|------|----------|----------|----------|:---:|:---:|:---:|
| `person` | 1 人 | 租戶 | 個人筆記、系統通知 | — | — | — |
| `accountPerson` | 1 人 | 帳號 | 跨租戶系統通知 | — | — | — |
| `friend` | 2 人 | 租戶 | 員工私聊 | — | — | — |
| `group` | 多人 | 租戶 | 員工群聊 | — | — | — |
| `discuss` | 多人 | 租戶 | 主題討論 | — | — | — |
| `services` | 客戶+服務號 | 租戶 | **客服私聊** | ✅ | ✅ | ✅ |
| `serviceMember` | 多人 | 租戶 | 客服內部群 | — | — | — |
| `business` | 多人 | 租戶 | 業務物件討論 | — | — | — |
| `aileSystem` | 系統+員工 | 帳號 | 平台通知 | — | — | — |
| `aiwowSystem` | 系統+員工 | 帳號 | 子系統通知 | — | — | — |
| `system` | 多人 | 租戶 | 系統群發 | — | — | — |
| `lineGroup` | 服務號+群 | 租戶 | LINE 群組 | — | — | ✅ |

---

## 8. 成員分組（僅 services 類型使用）

`services` 聊天室內部使用 `MemberGroupType` 對成員進行分組管理：

```java
public enum MemberGroupType {
    ServiceAgent,        // 當前服務人員（接待客服）
    ServiceOwner,        // 服務號 Owner（最高權限）
    ServiceMember,       // 服務號成員（管理層）
    ProvisionalMember,   // 臨時內部成員（轉接/協助）
    ProvisionalCustomer  // 外部客戶
}
```

分組用途：
- **ServiceAgent**：決定誰的未讀數增加、誰收到新消息推送
- **ProvisionalMember**：轉接討論時臨時加入，退出後不再接收消息
- **ProvisionalCustomer**：標記外部客戶身份，用於區分內外部發送邏輯

---

## 9. 未讀計數策略

不同聊天室類型使用獨立的 Redis Key 前綴進行未讀計數：

| 類型 | Redis Key 前綴 |
|------|---------------|
| 通用（friend/group/discuss 等） | `room:unread:common:*` |
| 服務號（services/serviceMember） | `room:unread:servicenumber:*` |
| LineGroup | `room:unread:linegroup:*` |
| Business | `room:unread:business:*` |
| 租戶總計 | `room:unread:tenant:total:*` |

---

## 10. 關鍵檔案索引

| 層級 | 檔案 | 說明 |
|------|------|------|
| 類型常量 | `aile-api/aile-room-api/.../constant/RoomType.java` | 12 種類型定義 + 判斷方法 |
| 核心模型 | `aile-api/aile-room-api/.../model/RoomModel.java` | 聊天室持久化模型 |
| 狀態枚舉 | `aile-api/aile-room-api/.../enums/RoomStatus.java` | 7 種狀態 |
| 物件狀態 | `aile-api/aile-room-api/.../enums/BusinessStatus.java` | 4 種業務狀態 |
| 成員分組 | `aile-api/aile-room-api/.../enums/MemberGroupType.java` | 5 種成員分組 |
| 工廠 | `aile-service/aile-service-room/.../factory/RoomFactory.java` | 策略工廠 |
| 策略接口 | `aile-service/aile-service-room/.../factory/strategy/RoomStrategy.java` | 策略接口 |
| 通用基底 | `aile-service/aile-service-room/.../factory/strategy/impl/CommonRoomImpl.java` | 抽象基底（所有策略的父類） |
| 客服策略 | `aile-service/aile-service-room/.../factory/strategy/impl/ServiceRoomImpl.java` | `services` 最核心策略 |
| 群組策略 | `aile-service/aile-service-room/.../factory/strategy/impl/LineGroupRoomImpl.java` | `lineGroup` |
| 物件策略 | `aile-service/aile-service-room/.../factory/strategy/impl/BusinessRoomImpl.java` | `business` |
| Redis Key | `aile-api/aile-room-api/.../constant/RoomRedisKey.java` | 未讀計數 Key 定義 |