a620906209/CFDivePlatform
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(openspec): archive realtime-booking-chat，同步主 specs

Browse Source 
- archive openspec/changes/realtime-booking-chat → archive/2026-05-29-realtime-booking-chat
- 新增 openspec/specs/booking-chat/spec.md（即時訊息完整規格）
- 新增 openspec/specs/user-presence/spec.md（Presence Channel 規格）
- 更新 openspec/specs/booking-lifecycle/spec.md（補訊息頻道語義與封存 Scenario）

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Hank
2026-05-29 01:14:52 +08:00
parent 5ba598c78f
commit 83e0e599a0
10 changed files with 519 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
openspec/changes/archive/2026-05-29-realtime-booking-chat/.openspec.yaml
+2
View File
@@ -0,0 +1,2 @@
schema: spec-driven
created: 2026-05-26
openspec/changes/archive/2026-05-29-realtime-booking-chat/design.md
View File
openspec/changes/archive/2026-05-29-realtime-booking-chat/proposal.md
+36
View File
@@ -0,0 +1,36 @@
## Why
預約成立後，會員與教練之間沒有直接溝通管道，只能透過平台外的通訊工具協調集合地點、裝備確認等細節，造成使用流程斷裂。加入即時訊息功能可以將溝通閉環留在平台內，提升黏著度與信任感。
## What Changes
- 新增 `booking_messages` 資料表，儲存文字與圖片訊息，與 `bookings` 一對多關聯
- 新增站內通知系統：發送訊息時同步寫入 `notifications` 資料表（`NewBookingMessageNotification`，database channel only），並廣播 `NotificationCreated` event 至 `private-App.Models.User.{receiverId}` 頻道，前端即時更新 Bell Icon 未讀計數（**實作中追加，超出原始 scope**）
- 新增瀏覽器 Web Notification：分頁在背景時收到對方訊息，透過 Notifications API 推送原生通知（`tag: booking-chat-{id}` 防疊加）（**實作中追加**）
- 引入 **Laravel Reverb** 作為自架 WebSocket 伺服器（docker-compose 新增 `reverb` service）
- 每個 confirmed 預約建立一條 **Presence Channel**（`presence-booking.{id}`），同時承載訊息推播與在線狀態
- 已讀回執：對方在頻道內且讀取訊息時觸發 `MessageRead` event
- 圖片訊息：透過 HTTP POST 上傳至 Laravel Storage，WebSocket 廣播包含圖片 URL
- 訊息視窗隨預約狀態開關：`confirmed` → 可讀寫；`completed` → 封存唯讀；其餘狀態不開放
- 新增 DNS subdomain `ws.hank-space.com`，透過 Nginx Proxy Manager 獨立 Proxy Host 接入（B 方案）
- 前端（Vue 3）新增訊息面板，嵌入 Member 的預約詳情頁與 Coach 的預約管理頁
## Capabilities
### New Capabilities
- `booking-chat`: 預約確認後的即時文字與圖片訊息，含訊息歷史、在線狀態、已讀回執，課程結束後封存
- `user-presence`: 基於 Presence Channel 的每預約在線狀態追蹤（誰在線、加入/離開事件）
### Modified Capabilities
- `booking-lifecycle`: 預約狀態機新增「訊息視窗開關」語義——`confirmed` 開啟可讀寫頻道，`completed` 切換為封存唯讀，其餘終態（rejected、expired、cancelled）無訊息頻道
## Impact
- **新增套件**：`laravel/reverb`（PHP）、`intervention/image`（PHP）、`laravel-echo`、`pusher-js`（npm）
- **新增 Docker service**：`reverb`（連接 `cfdive-network` 與 `proxy_net`，port 8080 僅內網）
- **新增 API 端點**：訊息列表（`GET /api/bookings/{id}/messages`）、發送文字/圖片（`POST /api/bookings/{id}/messages`）、標記已讀（`POST /api/bookings/{id}/messages/read`）、批次未讀計數（`GET /api/bookings/messages/unread-counts`）
- **修改**：`docker-compose.yml`、`config/broadcasting.php`（connection 改為 `reverb`）
- **Infrastructure**：NPM 新增 `ws.hank-space.com` Proxy Host（WebSocket 啟用）、DNS A Record
- **不影響**：現有預約 API、評價系統、所有已完成模組
openspec/changes/archive/2026-05-29-realtime-booking-chat/specs/booking-chat/spec.md
+134
View File
@@ -0,0 +1,134 @@
## ADDED Requirements
### Requirement: 發送文字訊息
Member 與 Provider SHALL 能在 `confirmed` 狀態的預約中透過 `POST /api/bookings/{id}/messages` 發送文字訊息。訊息儲存後系統 SHALL 廣播 `MessageSent` event 至 `presence-booking.{id}` 頻道。
#### Scenario: 成功發送文字訊息
- **WHEN** 已認證的 Member 或 Provider 對自己參與的 `confirmed` 預約送出 `POST /api/bookings/{id}/messages`，body 為 `{ type: 'text', content: '...' }`
- **THEN** 系統建立 `BookingMessage` 記錄，回傳 201，並透過 WebSocket 廣播 `MessageSent` event（含 `id`、`sender_id`、`sender_type`、`type`、`content`、`created_at`）
#### Scenario: 預約非 confirmed 狀態時不可發送
- **WHEN** 預約 status 不為 `confirmed`
- **THEN** 系統回傳 403，告知訊息功能僅在預約確認期間開放
#### Scenario: 非參與方不可發送
- **WHEN** 非該預約的 Member 或對應 Provider 嘗試發送訊息
- **THEN** 系統回傳 403 Forbidden
#### Scenario: 訊息內容不可為空
- **WHEN** `content` 為空字串或未提供
- **THEN** 系統回傳 422，`errors.content` 說明必填
### Requirement: 發送圖片訊息
Member 與 Provider SHALL 能在 `confirmed` 預約中上傳圖片作為訊息。圖片透過 HTTP multipart POST 上傳至 Laravel Storage，系統建立 `type: image` 的 `BookingMessage` 並廣播圖片 URL。
#### Scenario: 成功上傳並發送圖片
- **WHEN** 已認證使用者對 `confirmed` 預約送出 `POST /api/bookings/{id}/messages`，`Content-Type: multipart/form-data`，`type: image`，`file` 為有效圖片（jpg/png/gif/webp，≤ 10MB）
- **THEN** 系統儲存圖片至 Storage，建立 `BookingMessage`（`content` 存圖片 URL），廣播 `MessageSent` event，回傳 201
#### Scenario: 不支援的檔案類型被拒絕
- **WHEN** 上傳的 `file` 非 jpg/png/gif/webp
- **THEN** 系統回傳 422，`errors.file` 說明僅支援圖片格式
#### Scenario: 超過大小限制被拒絕
- **WHEN** 圖片檔案大小超過 10MB
- **THEN** 系統回傳 422，`errors.file` 說明大小限制
### Requirement: 讀取訊息歷史
Member 與 Provider SHALL 能透過 `GET /api/bookings/{id}/messages` 取得該預約的完整訊息歷史，按 `created_at` 升序排列。
#### Scenario: 成功取得訊息歷史
- **WHEN** 已認證的參與方送出 `GET /api/bookings/{id}/messages`
- **THEN** 系統回傳訊息陣列，每筆包含 `id`、`sender_id`、`sender_type`、`type`、`content`、`read_at`、`created_at`
#### Scenario: 非參與方無法讀取歷史
- **WHEN** 非該預約參與方嘗試讀取訊息
- **THEN** 系統回傳 403 Forbidden
#### Scenario: 預約完成後仍可讀取歷史
- **WHEN** 預約 status 為 `completed`，參與方送出 `GET /api/bookings/{id}/messages`
- **THEN** 系統回傳完整歷史訊息（唯讀，不可繼續發送）
### Requirement: 訊息封存
預約狀態轉換為 `completed` 時，系統 SHALL 自動關閉對應 Presence Channel，訊息歷史轉為唯讀。終態（rejected、expired、member_cancelled、provider_cancelled）的預約 SHALL 不具備訊息功能。
#### Scenario: completed 後不可發送新訊息
- **WHEN** 預約 status 為 `completed`，任一方嘗試 `POST /api/bookings/{id}/messages`
- **THEN** 系統回傳 403，告知預約已結束，訊息已封存
#### Scenario: 終態預約無訊息記錄也無法發送
- **WHEN** 預約 status 為 `rejected`、`expired`、`member_cancelled` 或 `provider_cancelled`
- **THEN** `GET /api/bookings/{id}/messages` 回傳空陣列；`POST` 回傳 403
### Requirement: 標記訊息已讀
接收方讀取訊息時，系統 SHALL 更新 `read_at`，並廣播 `MessageRead` event 至頻道。
#### Scenario: 成功標記已讀
- **WHEN** 已認證使用者送出 `POST /api/bookings/{id}/messages/read`（含 `last_read_message_id`）
- **THEN** 系統將該訊息及之前所有訊息（自己未讀的）的 `read_at` 更新為當前時間，廣播 `MessageRead` event（含 `reader_type`、`last_read_message_id`）
#### Scenario: 不可標記自己的訊息
- **WHEN** 發送方嘗試標記自己發出的訊息為已讀
- **THEN** 系統忽略（不更新、不廣播），回傳 200
### Requirement: 未讀訊息計數 Endpoint
系統 SHALL 提供 `GET /api/bookings/messages/unread-counts` endpoint，一次回傳當前使用者所有相關預約的未讀訊息數，避免前端逐筆呼叫造成 N+1 請求。
#### Scenario: 取得未讀計數
- **WHEN** 已認證的 Member 或 Provider 送出 `GET /api/bookings/messages/unread-counts`
- **THEN** 系統回傳 `{ status: true, data: { "{bookingId}": count, ... } }`，僅包含未讀數 > 0 的 booking；無未讀則回傳空物件 `{}`
- **AND** 計算邏輯為：對方發送（`sender_type` 為對方角色）且 `read_at IS NULL` 的訊息數量
#### Scenario: 路由優先順序正確
- **WHEN** 路由檔案定義 `/bookings/messages/unread-counts`
- **THEN** 該路由必須在 `/bookings/{booking}/messages` 之前註冊，以防 Route Model Binding 將 `messages` 誤判為 `{booking}` 參數
### Requirement: 預約列表未讀角標
前端 SHALL 在預約列表（Member 的 `MyBookingsView`、Coach 的 `BookingManagerView`）的每筆預約卡片上，以紅色角標顯示未讀訊息數。
#### Scenario: 有未讀訊息時顯示角標
- **WHEN** `GET /api/bookings/messages/unread-counts` 回傳某 booking 的 count > 0
- **THEN** 對應預約卡片上顯示紅色角標（數字）
#### Scenario: 開啟聊天視窗後角標即時清零
- **WHEN** 使用者展開某預約的 `BookingChat` 元件，元件 mount 時呼叫 `markRead`
- **THEN** `BookingChat` emit `read` 事件，父層呼叫 `clearCount(bookingId)` 即時清零角標，無需等下一輪 60s 輪詢
### Requirement: 站內通知（Bell Icon）即時更新
當使用者收到新的聊天訊息時，系統 SHALL 即時更新其 Bell Icon 的未讀通知計數，延遲不超過廣播傳輸時間（毫秒級），不依賴輪詢。
#### Scenario: 發送訊息觸發接收方 Bell 更新
- **WHEN** 使用者 A 透過 `POST /api/bookings/{id}/messages` 成功發送訊息
- **THEN** 系統同步（非 queue）寫入 `notifications` 資料表（`NewBookingMessageNotification`，database channel only）
- **AND** 系統 broadcast `NotificationCreated` event 至接收方的 `private-App.Models.User.{receiverId}` 頻道
- **AND** 接收方前端收到 `.notification.created` 事件後立即重新 fetch `/notifications/unread-count`
#### Scenario: 通知 title 包含寄件方姓名
- **WHEN** 通知寫入 DB
- **THEN** `title` 欄位格式為 `"{senderLabel} 傳來新訊息"`，其中 Provider 的 senderLabel 加上「教練 」前綴（例：「教練 王小明 傳來新訊息」），Member 直接使用姓名
#### Scenario: 不寄送 Email 通知
- **WHEN** 新訊息通知寫入
- **THEN** `via()` 僅回傳 `['database']`，不透過 mail channel 發送 Email
### Requirement: 瀏覽器 Web Notification（背景通知）
當使用者的瀏覽器分頁處於背景（`document.hidden === true`）時，系統 SHALL 觸發瀏覽器原生通知，告知有新的聊天訊息。
#### Scenario: 分頁在背景時收到訊息顯示通知
- **WHEN** `BookingChat` 收到對方的 `MessageSent` event
- **AND** `document.hidden === true`
- **AND** `Notification.permission === 'granted'`
- **THEN** 系統建立一則 `Notification`，`tag: 'booking-chat-{bookingId}'`（防止同預約疊加多則）
#### Scenario: 分頁在前景時不顯示通知
- **WHEN** `BookingChat` 收到對方的 `MessageSent` event
- **AND** `document.hidden === false`（使用者正在看畫面）
- **THEN** 系統不推送 Web Notification（避免干擾）
#### Scenario: 元件 mount 時請求通知權限
- **WHEN** `BookingChat` 元件 mount
- **THEN** 呼叫 `Notification.requestPermission()`，取得使用者授權後方可推送通知
#### Scenario: 自己的訊息不觸發通知
- **WHEN** `MessageSent` event 的 `sender_type` 與當前使用者角色相同
- **THEN** 不推送 Web Notification（只對「對方」的訊息觸發）
openspec/changes/archive/2026-05-29-realtime-booking-chat/specs/booking-lifecycle/spec.md
+24
View File
@@ -0,0 +1,24 @@
## MODIFIED Requirements
### Requirement: 預約狀態機
系統 SHALL 維護七個合法狀態，且只允許以下轉換：
- `pending` → `confirmed`（Provider 確認）
- `pending` → `rejected`（Provider 拒絕）
- `pending` → `member_cancelled`（Member 取消）
- `pending` → `expired`（Scheduler 超時）
- `confirmed` → `completed`（Scheduler 課程後自動）
- `confirmed` → `member_cancelled`（Member 取消）
- `confirmed` → `provider_cancelled`（Provider 取消）
各狀態對應訊息頻道語義：
- `confirmed`：`presence-booking.{id}` 頻道開放，可讀寫訊息
- `completed`：頻道關閉，訊息歷史封存唯讀
- 其餘狀態（`pending`、`rejected`、`expired`、`member_cancelled`、`provider_cancelled`）：無訊息頻道
#### Scenario: 非法狀態轉換被拒絕
- **WHEN** 任何角色嘗試執行上述以外的狀態轉換
- **THEN** 系統回傳 422，說明當前狀態不允許此操作
#### Scenario: confirmed 轉 completed 時封存訊息頻道
- **WHEN** Scheduler 將 `confirmed` 預約轉為 `completed`
- **THEN** 對應 `presence-booking.{id}` 頻道不再授權新連線；現有訊息歷史保留，後續 POST 訊息回傳 403
openspec/changes/archive/2026-05-29-realtime-booking-chat/specs/user-presence/spec.md
+53
View File
@@ -0,0 +1,53 @@
## ADDED Requirements
### Requirement: 訂閱預約 Presence Channel
已認證的 Member 與 Provider SHALL 能透過 Laravel Echo 訂閱 `presence-booking.{booking_id}` 頻道，訂閱時系統 SHALL 驗證使用者確為該預約的參與方。
#### Scenario: 合法參與方成功訂閱
- **WHEN** 已認證使用者帶有效 Bearer token 連線至 `wss://ws.hank-space.com`，並訂閱 `presence-booking.{id}`
- **THEN** `broadcasting/auth` 端點回傳授權成功，使用者加入頻道，頻道廣播 `joining` event（含 `user_id`、`user_type`、`name`）
#### Scenario: 非參與方訂閱被拒絕
- **WHEN** 非該預約參與方嘗試訂閱頻道
- **THEN** `broadcasting/auth` 回傳 403，連線不建立
#### Scenario: 預約非 confirmed 狀態時頻道不授權
- **WHEN** 預約 status 不為 `confirmed`，任何使用者嘗試訂閱
- **THEN** `broadcasting/auth` 回傳 403
### Requirement: 在線狀態感知
訂閱 Presence Channel 後，系統 SHALL 回傳目前在線成員清單。任一方加入或離開時 SHALL 廣播對應事件。
#### Scenario: 取得目前在線清單
- **WHEN** 使用者成功加入 `presence-booking.{id}` 頻道
- **THEN** Echo `.here()` callback 收到目前在線的使用者清單（含 `user_id`、`user_type`、`name`）
#### Scenario: 對方加入頻道
- **WHEN** 對方（Member 或 Provider）開啟訊息視窗並成功訂閱頻道
- **THEN** 已在頻道中的使用者收到 `.joining()` event，可顯示「對方已上線」
#### Scenario: 對方離開頻道
- **WHEN** 對方關閉訊息視窗或斷線
- **THEN** 仍在頻道中的使用者收到 `.leaving()` event，可顯示「對方已離線」
### Requirement: 已讀回執顯示
前端 SHALL 依據 `MessageRead` event 更新訊息的已讀狀態，顯示「已讀」標記。
#### Scenario: 己方訊息被對方讀取後顯示已讀
- **WHEN** 頻道收到 `MessageRead` event，`reader_type` 為對方，`last_read_message_id` >= 某訊息 id
- **THEN** 前端將該訊息及之前的己方訊息顯示「已讀」標記
#### Scenario: 對方不在頻道時訊息顯示未讀
- **WHEN** 對方未訂閱頻道（離線）
- **THEN** 新發送的訊息 `read_at` 為 null，顯示「未讀」狀態
### Requirement: 未讀訊息計數
系統 SHALL 在預約列表頁顯示每個預約的未讀訊息數量角標。
#### Scenario: 有未讀訊息時顯示角標
- **WHEN** Member 或 Provider 進入預約列表，某預約有 `read_at IS NULL` 且 `sender_type` 為對方的訊息
- **THEN** 對應預約卡片顯示未讀數量角標（數字或紅點）
#### Scenario: 進入訊息視窗後角標清除
- **WHEN** 使用者進入該預約的訊息視窗，送出 `POST /api/bookings/{id}/messages/read`
- **THEN** 未讀角標消失
openspec/changes/archive/2026-05-29-realtime-booking-chat/tasks.md
+78
View File
@@ -0,0 +1,78 @@
## 1. 基礎建設與套件安裝
- [x] 1.1 [後端] 安裝 `laravel/reverb`：`composer require laravel/reverb`，執行 `php artisan reverb:install` 生成 `config/reverb.php`
- [x] 1.2 [後端] 安裝 `intervention/image`：`composer require intervention/image`；用途：上傳圖片時移除 EXIF（含 GPS 座標）、強制重新編碼為 jpg/png 以防格式偽裝、限制最大尺寸（長邊 2048px）
- [x] 1.3 [前端] 安裝 `laravel-echo` 與 `pusher-js`：`npm install laravel-echo pusher-js`
- [x] 1.4 [後端] 更新 `.env`：設定 `BROADCAST_CONNECTION=reverb`、`REVERB_APP_ID=cfdive`、`REVERB_APP_KEY`（32 字元隨機）、`REVERB_APP_SECRET`（32 字元隨機）、`REVERB_HOST=reverb`（Docker service DNS，非 bind address）、`REVERB_PORT=8080`；另補 Vite 前端用的 `VITE_REVERB_APP_KEY`、`VITE_REVERB_HOST=ws.hank-space.com`、`VITE_REVERB_PORT=443`、`VITE_REVERB_SCHEME=https`
- [x] 1.5 [後端] 在 `config/broadcasting.php` 確認 `reverb` driver 設定正確（`host`、`port` 從 env 讀取）
- [x] 1.6 [後端] 在 `bootstrap/app.php` 啟用 broadcasting：確認 `->withBroadcasting()` 已加入，或在 `routes/api.php` 明確呼叫 `Broadcast::routes(['middleware' => ['auth:sanctum']])` 以確保 `/broadcasting/auth` endpoint 存在並受 Sanctum 保護
## 2. Docker 與 Infrastructure 設定
- [x] 2.1 [後端] 在 `docker-compose.yml` 新增 `reverb` service：複用 `cfdive-platform` image，`command: php artisan reverb:start --host=0.0.0.0 --port=8080 --debug`，連接 `cfdive-network` 與 `proxy_net`，`restart: unless-stopped`，`depends_on: app`
- [x] 2.2 [Infrastructure] 在 DNS 新增 A Record：`ws.hank-space.com` → VPS IP
- [x] 2.3 [Infrastructure] 在 Nginx Proxy Manager 新增 Proxy Host：Domain `ws.hank-space.com`，Forward 至 `reverb:8080`，啟用 WebSocket support，申請 SSL 憑證
- [x] 2.4 [後端] 執行 `docker-compose up --build reverb` 驗證 Reverb 容器啟動正常
## 3. 資料庫
- [x] 3.1 [後端] 建立 migration `create_booking_messages_table`：欄位 `id`、`booking_id`（FK）、`sender_id`（FK users）、`sender_type`（enum: member/provider）、`type`（enum: text/image）、`content`（text）、`read_at`（timestamp nullable）、`timestamps`；加 index `(booking_id, created_at)`
- [x] 3.2 [後端] 執行 `php artisan migrate` 並確認資料表建立
## 4. 後端 Model、Channel 與 Event
- [x] 4.1 [後端] 建立 `app/Models/BookingMessage.php`：定義 `$fillable`、`booking()` belongsTo、`sender()` morphTo 或一般 belongsTo（依 sender_type 切換）
- [x] 4.2 [後端] 建立 `app/Broadcasting/BookingPresenceChannel.php`：實作 `join()` 方法，eager load `schedule`；Member 驗證 `booking->member_id === $user->id`，Provider 驗證 `booking->schedule->provider_id === $user->id`；`confirmed` 以外狀態返回 `false`；授權成功回傳 `['user_id', 'user_type', 'name']`
- [x] 4.3 [後端] 在 `routes/channels.php` 註冊 `Broadcast::channel('presence-booking.{bookingId}', BookingPresenceChannel::class)`
- [x] 4.4 [後端] 建立 `app/Events/MessageSent.php`：implements `ShouldBroadcastNow`（同步廣播，MVP 不走 queue），`broadcastOn()` 返回 `new PresenceChannel("presence-booking.{$this->message->booking_id}")`，`broadcastWith()` 回傳 `id`、`sender_id`、`sender_type`、`type`、`content`、`created_at`
- [x] 4.5 [後端] 建立 `app/Events/MessageRead.php`：implements `ShouldBroadcastNow`，廣播 `reader_type`、`last_read_message_id`
## 5. 後端 API
- [x] 5.1 [後端] 建立 `app/Http/Controllers/BookingMessageController.php`，方法：`index`（取得歷史）、`store`（發送文字/圖片）、`markRead`（標記已讀）
- [x] 5.2 [後端] `index` 方法：驗證使用者為參與方，回傳 `booking.messages()->orderBy('created_at')->get()`，`confirmed` 與 `completed` 均可讀取
- [x] 5.3 [後端] `store` 方法：驗證 booking status 為 `confirmed`（其他狀態回傳 403）；text 訊息驗證 `content` 非空；image 訊息驗證 `file`（mimes: jpg,png,gif,webp，max: 10240KB），存至 `Storage::disk('public')`，路徑 `booking-images/{uuid}.{ext}`，`content` 存完整 URL（`Storage::url(...)`）；建立 `BookingMessage`；dispatch `MessageSent` event（ShouldBroadcastNow）
- [x] 5.4 [後端] `markRead` 方法：更新「對方發送」且「id ≤ last_read_message_id」且「read_at IS NULL」的訊息之 `read_at`；booking status 為 `confirmed` 時 dispatch `MessageRead` event；`completed` 時只更新 DB，不 broadcast（頻道已關閉）
- [x] 5.5 [後端] 在 `routes/api.php` 新增路由（member 與 provider 各自的 auth middleware group）：`GET /api/bookings/{booking}/messages`、`POST /api/bookings/{booking}/messages`、`POST /api/bookings/{booking}/messages/read`
## 6. 前端 Echo 初始化
- [x] 6.1 [前端] 在 `frontend/src/plugins/echo.js`（新建）初始化 `Laravel Echo`：`broadcaster: 'reverb'`，`wsHost: ws.hank-space.com`，`wsPort: 443`，`wssPort: 443`，`forceTLS: true`，`enabledTransports: ['ws', 'wss']`
- [x] 6.2 [前端] 在 `frontend/src/plugins/echo.js` 支援雙 token：Member 用 `localStorage.getItem('token')`，Coach 用 `localStorage.getItem('coach_token')`，依當前角色動態設定 Authorization header；`authEndpoint` 使用完整 URL：`${import.meta.env.VITE_API_URL}/broadcasting/auth`（跨 domain 不可使用相對路徑）
- [x] 6.3 [前端] 在 `main.js` 掛載 Echo plugin
## 7. 前端訊息元件
- [x] 7.1 [前端] 建立 `frontend/src/components/BookingChat.vue`：props 接收 `bookingId`、`bookingStatus`、`currentUserType`
- [x] 7.2 [前端] `BookingChat.vue` 訂閱 `presence-booking.{bookingId}`，處理 `.here()`（顯示在線狀態）、`.joining()`、`.leaving()`
- [x] 7.3 [前端] `BookingChat.vue` 監聽 `MessageSent` event，新訊息即時 append 到訊息列表
- [x] 7.4 [前端] `BookingChat.vue` 監聽 `MessageRead` event，更新訊息「已讀」標記
- [x] 7.5 [前端] `BookingChat.vue` 實作文字輸入框與送出按鈕，call `POST /api/bookings/{id}/messages`
- [x] 7.6 [前端] `BookingChat.vue` 實作圖片上傳按鈕（`<input type="file" accept="image/*">`），以 `FormData` 送出
- [x] 7.7 [前端] `BookingChat.vue` 在 `confirmed` 狀態顯示輸入區；`completed` 狀態顯示「對話已封存」提示；其他狀態不渲染元件
- [x] 7.8 [前端] 元件 mount 時呼叫 `GET /api/bookings/{id}/messages` 載入歷史訊息，並送出 `markRead`
## 8. 前端嵌入預約詳情頁
- [x] 8.1 [前端] 在 Member 的預約詳情頁（`src/views/MyBookingsView.vue` 展開區塊）嵌入 `<BookingChat>` 元件
- [x] 8.2 [前端] 在 Coach 的預約管理頁（`src/views/coach/BookingManagerView.vue`）嵌入 `<BookingChat>` 元件，點擊「訊息」按鈕展開
- [x] 8.3 [前端] 在預約列表卡片顯示未讀訊息角標：實作 `GET /api/bookings/messages/unread-counts`（一次回傳所有 booking 的未讀數，非逐筆呼叫）；建立 `useBookingUnreadCounts` composable（60s 輪詢）；`BookingChat` 加 `emit('read')` 讓父層即時清零角標
## 8.5 訊息通知系統（實作中追加，超出原始 scope）
- [x] 8.5.1 [後端] 建立 `NewBookingMessageNotification`：`database` channel only（不寄信）；`title` 含寄件方姓名（provider 加「教練」前綴）；**不走 Queue**（同步寫入，確保廣播前 DB 已有資料）
- [x] 8.5.2 [後端] 建立 `NotificationCreated` event：`ShouldBroadcastNow`，廣播至 `private-App.Models.User.{id}`（複用 channels.php 已有的授權）；`broadcastAs()` = `'notification.created'`
- [x] 8.5.3 [後端] `BookingMessageController::store()` 在 broadcast `MessageSent` 後，同步 notify receiver，再 broadcast `NotificationCreated`
- [x] 8.5.4 [前端] `notifications.js` store 新增 `startRealtime(userId)` / `stopRealtime()`：訂閱 `private-App.Models.User.{id}`，收到 `notification.created` 立刻呼叫 `fetchUnreadCount()`
- [x] 8.5.5 [前端] `auth.js` 與 `coachAuth.js` 的 `init()` / `setAuth()` / `logout()` 均呼叫 `startRealtime` / `stopRealtime`
- [x] 8.5.6 [前端] `BookingChat.vue` 新增瀏覽器通知（Web Notifications API）：mount 時請求權限；收到對方 `MessageSent` 且 `document.hidden` 時推送；`tag: booking-chat-{id}` 防止同一預約疊加通知
## 9. 整合測試與手動驗證
- [x] 9.1 [整合測試] 驗證 `/broadcasting/auth` 端點可存取（不是 404）：分別用 member token 與 coach token 送出請求，確認路由已正確註冊且 Sanctum middleware 生效；合法參與方回傳 200，非參與方回傳 403，非 confirmed 狀態回傳 403
- [x] 9.2 [整合測試] 驗證 `POST /api/bookings/{id}/messages`：text 訊息成功建立且廣播；image 上傳成功且 URL 可存取；invalid 檔案回傳 422
- [x] 9.3 [整合測試] 驗證 `markRead`：己方訊息不更新；對方訊息 `read_at` 被設定；`MessageRead` 廣播觸發
- [x] 9.4 [整合測試] 驗證封存：`completed` 預約 POST 訊息回傳 403，GET 歷史正常回傳
- [x] 9.5 [手動驗證] 開兩個瀏覽器分別登入 Member 與 Coach，確認訊息即時雙向傳達、在線狀態顯示正確、已讀回執正常觸發
- [x] 9.6 [手動驗證] 測試圖片訊息：上傳圖片後對方即時看到圖片
- [x] 9.7 [手動驗證] 關閉一個視窗，確認另一端顯示「對方已離線」
openspec/specs/booking-chat/spec.md
+132
View File
@@ -0,0 +1,132 @@
### Requirement: 發送文字訊息
Member 與 Provider SHALL 能在 `confirmed` 狀態的預約中透過 `POST /api/bookings/{id}/messages` 發送文字訊息。訊息儲存後系統 SHALL 廣播 `MessageSent` event 至 `presence-booking.{id}` 頻道。
#### Scenario: 成功發送文字訊息
- **WHEN** 已認證的 Member 或 Provider 對自己參與的 `confirmed` 預約送出 `POST /api/bookings/{id}/messages`，body 為 `{ type: 'text', content: '...' }`
- **THEN** 系統建立 `BookingMessage` 記錄，回傳 201，並透過 WebSocket 廣播 `MessageSent` event（含 `id`、`sender_id`、`sender_type`、`type`、`content`、`created_at`）
#### Scenario: 預約非 confirmed 狀態時不可發送
- **WHEN** 預約 status 不為 `confirmed`
- **THEN** 系統回傳 403，告知訊息功能僅在預約確認期間開放
#### Scenario: 非參與方不可發送
- **WHEN** 非該預約的 Member 或對應 Provider 嘗試發送訊息
- **THEN** 系統回傳 403 Forbidden
#### Scenario: 訊息內容不可為空
- **WHEN** `content` 為空字串或未提供
- **THEN** 系統回傳 422，`errors.content` 說明必填
### Requirement: 發送圖片訊息
Member 與 Provider SHALL 能在 `confirmed` 預約中上傳圖片作為訊息。圖片透過 HTTP multipart POST 上傳至 Laravel Storage，系統建立 `type: image` 的 `BookingMessage` 並廣播圖片 URL。
#### Scenario: 成功上傳並發送圖片
- **WHEN** 已認證使用者對 `confirmed` 預約送出 `POST /api/bookings/{id}/messages`，`Content-Type: multipart/form-data`，`type: image`，`file` 為有效圖片（jpg/png/gif/webp，≤ 10MB）
- **THEN** 系統儲存圖片至 Storage，建立 `BookingMessage`（`content` 存圖片 URL），廣播 `MessageSent` event，回傳 201
#### Scenario: 不支援的檔案類型被拒絕
- **WHEN** 上傳的 `file` 非 jpg/png/gif/webp
- **THEN** 系統回傳 422，`errors.file` 說明僅支援圖片格式
#### Scenario: 超過大小限制被拒絕
- **WHEN** 圖片檔案大小超過 10MB
- **THEN** 系統回傳 422，`errors.file` 說明大小限制
### Requirement: 讀取訊息歷史
Member 與 Provider SHALL 能透過 `GET /api/bookings/{id}/messages` 取得該預約的完整訊息歷史，按 `created_at` 升序排列。
#### Scenario: 成功取得訊息歷史
- **WHEN** 已認證的參與方送出 `GET /api/bookings/{id}/messages`
- **THEN** 系統回傳訊息陣列，每筆包含 `id`、`sender_id`、`sender_type`、`type`、`content`、`read_at`、`created_at`
#### Scenario: 非參與方無法讀取歷史
- **WHEN** 非該預約參與方嘗試讀取訊息
- **THEN** 系統回傳 403 Forbidden
#### Scenario: 預約完成後仍可讀取歷史
- **WHEN** 預約 status 為 `completed`，參與方送出 `GET /api/bookings/{id}/messages`
- **THEN** 系統回傳完整歷史訊息（唯讀，不可繼續發送）
### Requirement: 訊息封存
預約狀態轉換為 `completed` 時，系統 SHALL 自動關閉對應 Presence Channel，訊息歷史轉為唯讀。終態（rejected、expired、member_cancelled、provider_cancelled）的預約 SHALL 不具備訊息功能。
#### Scenario: completed 後不可發送新訊息
- **WHEN** 預約 status 為 `completed`，任一方嘗試 `POST /api/bookings/{id}/messages`
- **THEN** 系統回傳 403，告知預約已結束，訊息已封存
#### Scenario: 終態預約無訊息記錄也無法發送
- **WHEN** 預約 status 為 `rejected`、`expired`、`member_cancelled` 或 `provider_cancelled`
- **THEN** `GET /api/bookings/{id}/messages` 回傳空陣列；`POST` 回傳 403
### Requirement: 標記訊息已讀
接收方讀取訊息時，系統 SHALL 更新 `read_at`，並廣播 `MessageRead` event 至頻道。
#### Scenario: 成功標記已讀
- **WHEN** 已認證使用者送出 `POST /api/bookings/{id}/messages/read`（含 `last_read_message_id`）
- **THEN** 系統將該訊息及之前所有訊息（自己未讀的）的 `read_at` 更新為當前時間，廣播 `MessageRead` event（含 `reader_type`、`last_read_message_id`）
#### Scenario: 不可標記自己的訊息
- **WHEN** 發送方嘗試標記自己發出的訊息為已讀
- **THEN** 系統忽略（不更新、不廣播），回傳 200
### Requirement: 未讀訊息計數 Endpoint
系統 SHALL 提供 `GET /api/bookings/messages/unread-counts` endpoint，一次回傳當前使用者所有相關預約的未讀訊息數，避免前端逐筆呼叫造成 N+1 請求。
#### Scenario: 取得未讀計數
- **WHEN** 已認證的 Member 或 Provider 送出 `GET /api/bookings/messages/unread-counts`
- **THEN** 系統回傳 `{ status: true, data: { "{bookingId}": count, ... } }`，僅包含未讀數 > 0 的 booking；無未讀則回傳空物件 `{}`
- **AND** 計算邏輯為：對方發送（`sender_type` 為對方角色）且 `read_at IS NULL` 的訊息數量
#### Scenario: 路由優先順序正確
- **WHEN** 路由檔案定義 `/bookings/messages/unread-counts`
- **THEN** 該路由必須在 `/bookings/{booking}/messages` 之前註冊，以防 Route Model Binding 將 `messages` 誤判為 `{booking}` 參數
### Requirement: 預約列表未讀角標
前端 SHALL 在預約列表（Member 的 `MyBookingsView`、Coach 的 `BookingManagerView`）的每筆預約卡片上，以紅色角標顯示未讀訊息數。
#### Scenario: 有未讀訊息時顯示角標
- **WHEN** `GET /api/bookings/messages/unread-counts` 回傳某 booking 的 count > 0
- **THEN** 對應預約卡片上顯示紅色角標（數字）
#### Scenario: 開啟聊天視窗後角標即時清零
- **WHEN** 使用者展開某預約的 `BookingChat` 元件，元件 mount 時呼叫 `markRead`
- **THEN** `BookingChat` emit `read` 事件，父層呼叫 `clearCount(bookingId)` 即時清零角標，無需等下一輪 60s 輪詢
### Requirement: 站內通知（Bell Icon）即時更新
當使用者收到新的聊天訊息時，系統 SHALL 即時更新其 Bell Icon 的未讀通知計數，延遲不超過廣播傳輸時間（毫秒級），不依賴輪詢。
#### Scenario: 發送訊息觸發接收方 Bell 更新
- **WHEN** 使用者 A 透過 `POST /api/bookings/{id}/messages` 成功發送訊息
- **THEN** 系統同步（非 queue）寫入 `notifications` 資料表（`NewBookingMessageNotification`，database channel only）
- **AND** 系統 broadcast `NotificationCreated` event 至接收方的 `private-App.Models.User.{receiverId}` 頻道
- **AND** 接收方前端收到 `.notification.created` 事件後立即重新 fetch `/notifications/unread-count`
#### Scenario: 通知 title 包含寄件方姓名
- **WHEN** 通知寫入 DB
- **THEN** `title` 欄位格式為 `"{senderLabel} 傳來新訊息"`，其中 Provider 的 senderLabel 加上「教練 」前綴（例：「教練 王小明 傳來新訊息」），Member 直接使用姓名
#### Scenario: 不寄送 Email 通知
- **WHEN** 新訊息通知寫入
- **THEN** `via()` 僅回傳 `['database']`，不透過 mail channel 發送 Email
### Requirement: 瀏覽器 Web Notification（背景通知）
當使用者的瀏覽器分頁處於背景（`document.hidden === true`）時，系統 SHALL 觸發瀏覽器原生通知，告知有新的聊天訊息。
#### Scenario: 分頁在背景時收到訊息顯示通知
- **WHEN** `BookingChat` 收到對方的 `MessageSent` event
- **AND** `document.hidden === true`
- **AND** `Notification.permission === 'granted'`
- **THEN** 系統建立一則 `Notification`，`tag: 'booking-chat-{bookingId}'`（防止同預約疊加多則）
#### Scenario: 分頁在前景時不顯示通知
- **WHEN** `BookingChat` 收到對方的 `MessageSent` event
- **AND** `document.hidden === false`（使用者正在看畫面）
- **THEN** 系統不推送 Web Notification（避免干擾）
#### Scenario: 元件 mount 時請求通知權限
- **WHEN** `BookingChat` 元件 mount
- **THEN** 呼叫 `Notification.requestPermission()`，取得使用者授權後方可推送通知
#### Scenario: 自己的訊息不觸發通知
- **WHEN** `MessageSent` event 的 `sender_type` 與當前使用者角色相同
- **THEN** 不推送 Web Notification（只對「對方」的訊息觸發）
openspec/specs/booking-lifecycle/spec.md
+9
View File
@@ -31,10 +31,19 @@ Member SHALL 能選擇一個開放時段送出預約，系統記錄價格快照
- `confirmed` → `member_cancelled`（Member 取消） - `confirmed` → `member_cancelled`（Member 取消）
- `confirmed` → `provider_cancelled`（Provider 取消） - `confirmed` → `provider_cancelled`（Provider 取消）
各狀態對應訊息頻道語義：
- `confirmed`：`presence-booking.{id}` 頻道開放，可讀寫訊息
- `completed`：頻道關閉，訊息歷史封存唯讀
- 其餘狀態（`pending`、`rejected`、`expired`、`member_cancelled`、`provider_cancelled`）：無訊息頻道
#### Scenario: 非法狀態轉換被拒絕 #### Scenario: 非法狀態轉換被拒絕
- **WHEN** 任何角色嘗試執行上述以外的狀態轉換 - **WHEN** 任何角色嘗試執行上述以外的狀態轉換
- **THEN** 系統回傳 422，說明當前狀態不允許此操作 - **THEN** 系統回傳 422，說明當前狀態不允許此操作
#### Scenario: confirmed 轉 completed 時封存訊息頻道
- **WHEN** Scheduler 將 `confirmed` 預約轉為 `completed`
- **THEN** 對應 `presence-booking.{id}` 頻道不再授權新連線；現有訊息歷史保留，後續 POST 訊息回傳 403
### Requirement: Provider 確認或拒絕預約 ### Requirement: Provider 確認或拒絕預約
Provider SHALL 能對自己課程的 `pending` 預約執行確認或拒絕。確認時才真正佔用時段名額。 Provider SHALL 能對自己課程的 `pending` 預約執行確認或拒絕。確認時才真正佔用時段名額。
openspec/specs/user-presence/spec.md
+51
View File
@@ -0,0 +1,51 @@
### Requirement: 訂閱預約 Presence Channel
已認證的 Member 與 Provider SHALL 能透過 Laravel Echo 訂閱 `presence-booking.{booking_id}` 頻道，訂閱時系統 SHALL 驗證使用者確為該預約的參與方。
#### Scenario: 合法參與方成功訂閱
- **WHEN** 已認證使用者帶有效 Bearer token 連線至 `wss://ws.hank-space.com`，並訂閱 `presence-booking.{id}`
- **THEN** `broadcasting/auth` 端點回傳授權成功，使用者加入頻道，頻道廣播 `joining` event（含 `user_id`、`user_type`、`name`）
#### Scenario: 非參與方訂閱被拒絕
- **WHEN** 非該預約參與方嘗試訂閱頻道
- **THEN** `broadcasting/auth` 回傳 403，連線不建立
#### Scenario: 預約非 confirmed 狀態時頻道不授權
- **WHEN** 預約 status 不為 `confirmed`，任何使用者嘗試訂閱
- **THEN** `broadcasting/auth` 回傳 403
### Requirement: 在線狀態感知
訂閱 Presence Channel 後，系統 SHALL 回傳目前在線成員清單。任一方加入或離開時 SHALL 廣播對應事件。
#### Scenario: 取得目前在線清單
- **WHEN** 使用者成功加入 `presence-booking.{id}` 頻道
- **THEN** Echo `.here()` callback 收到目前在線的使用者清單（含 `user_id`、`user_type`、`name`）
#### Scenario: 對方加入頻道
- **WHEN** 對方（Member 或 Provider）開啟訊息視窗並成功訂閱頻道
- **THEN** 已在頻道中的使用者收到 `.joining()` event，可顯示「對方已上線」
#### Scenario: 對方離開頻道
- **WHEN** 對方關閉訊息視窗或斷線
- **THEN** 仍在頻道中的使用者收到 `.leaving()` event，可顯示「對方已離線」
### Requirement: 已讀回執顯示
前端 SHALL 依據 `MessageRead` event 更新訊息的已讀狀態，顯示「已讀」標記。
#### Scenario: 己方訊息被對方讀取後顯示已讀
- **WHEN** 頻道收到 `MessageRead` event，`reader_type` 為對方，`last_read_message_id` >= 某訊息 id
- **THEN** 前端將該訊息及之前的己方訊息顯示「已讀」標記
#### Scenario: 對方不在頻道時訊息顯示未讀
- **WHEN** 對方未訂閱頻道（離線）
- **THEN** 新發送的訊息 `read_at` 為 null，顯示「未讀」狀態
### Requirement: 未讀訊息計數
系統 SHALL 在預約列表頁顯示每個預約的未讀訊息數量角標。
#### Scenario: 有未讀訊息時顯示角標
- **WHEN** Member 或 Provider 進入預約列表，某預約有 `read_at IS NULL` 且 `sender_type` 為對方的訊息
- **THEN** 對應預約卡片顯示未讀數量角標（數字或紅點）
#### Scenario: 進入訊息視窗後角標清除
- **WHEN** 使用者進入該預約的訊息視窗，送出 `POST /api/bookings/{id}/messages/read`
- **THEN** 未讀角標消失