Compare commits
34 Commits
66ff30f863
..
master
| Author | SHA1 | Date | |
|---|---|---|---|
 a620906209
|
d1fe3d4138 | ||
|
a620906209
|
0bffa909e2 | ||
|
a620906209
|
9222bf17fc | ||
|
a620906209
|
b218fa0964 | ||
|
a620906209
|
a7e8468613 | ||
|
a620906209
|
60ff56a571 | ||
|
a620906209
|
4afe7b5fd5 | ||
|
a620906209
|
c3572682ad | ||
|
a620906209
|
13b6b4145c | ||
|
a620906209
|
d423cf5079 | ||
|
a620906209
|
55b2bff1b8 | ||
|
a620906209
|
e08c6652a5 | ||
|
a620906209
|
2d14c058d1 | ||
|
a620906209
|
be629feef9 | ||
|
a620906209
|
998f34139a | ||
|
a620906209
|
0080e2da84 | ||
|
a620906209
|
4720dc53f9 | ||
|
a620906209
|
95a93b2d72 | ||
|
a620906209
|
c0616b17df | ||
|
a620906209
|
6a74f766db | ||
|
a620906209
|
d8340de322 | ||
|
a620906209
|
aebce80152 | ||
|
a620906209
|
5fdd5b3329 | ||
|
a620906209
|
daf72711e8 | ||
|
a620906209
|
2fbcd0c50d | ||
|
a620906209
|
979ea4df75 | ||
|
a620906209
|
6b1e31c4af | ||
|
a620906209
|
64874e1c12 | ||
|
a620906209
|
19705fc8d7 | ||
|
a620906209
|
80f5cf179f | ||
|
a620906209
|
d99ffb0fd6 | ||
|
a620906209
|
afdca18c67 | ||
|
a620906209
|
4383239bab | ||
|
a620906209
|
49a4b89655 |
+22
-5
@@ -15,8 +15,7 @@ APP_MAINTENANCE_STORE=database
|
||||
|
||||
BCRYPT_ROUNDS=12
|
||||
|
||||
LOG_CHANNEL=stack
|
||||
LOG_STACK=single
|
||||
LOG_CHANNEL=stderr
|
||||
LOG_DEPRECATIONS_CHANNEL=null
|
||||
LOG_LEVEL=debug
|
||||
|
||||
@@ -28,15 +27,15 @@ DB_CONNECTION=sqlite
|
||||
# DB_PASSWORD=
|
||||
# MYSQL_ROOT_PASSWORD=
|
||||
|
||||
SESSION_DRIVER=database
|
||||
SESSION_DRIVER=redis
|
||||
SESSION_LIFETIME=120
|
||||
SESSION_ENCRYPT=false
|
||||
SESSION_PATH=/
|
||||
SESSION_DOMAIN=null
|
||||
|
||||
BROADCAST_CONNECTION=log
|
||||
FILESYSTEM_DISK=local
|
||||
QUEUE_CONNECTION=database
|
||||
FILESYSTEM_DISK=local # 雲端應改為 s3（local 在容器重啟後會遺失上傳檔案）
|
||||
QUEUE_CONNECTION=redis # 雲端建議值；database 效能較差且不利擴容
|
||||
|
||||
CACHE_STORE=redis
|
||||
CACHE_PREFIX=
|
||||
@@ -67,3 +66,21 @@ VITE_APP_NAME="${APP_NAME}"
|
||||
|
||||
SENTRY_LARAVEL_DSN=
|
||||
SENTRY_ENVIRONMENT="${APP_ENV}"
|
||||
|
||||
REVERB_APP_ID=
|
||||
REVERB_APP_KEY=
|
||||
REVERB_APP_SECRET=
|
||||
REVERB_HOST=localhost
|
||||
REVERB_PORT=8085
|
||||
REVERB_SCHEME=http
|
||||
|
||||
VITE_REVERB_APP_KEY="${REVERB_APP_KEY}"
|
||||
VITE_REVERB_HOST="${REVERB_HOST}"
|
||||
VITE_REVERB_PORT="${REVERB_PORT}"
|
||||
VITE_REVERB_SCHEME="${REVERB_SCHEME}"
|
||||
|
||||
# Swagger UI — API 伺服器 Base URL（結尾不加斜線）
|
||||
# 本地：http://localhost:8080/api
|
||||
# 生產：https://api.hank-space.com/api
|
||||
L5_SWAGGER_CONST_HOST=http://localhost:8080/api
|
||||
L5_SWAGGER_GENERATE_ALWAYS=false
|
||||
@@ -33,6 +33,11 @@ jobs:
|
||||
docker compose exec -T app php artisan view:cache
|
||||
docker compose exec -T app php artisan event:cache
|
||||
|
||||
- name: Generate Swagger docs
|
||||
run: |
|
||||
cd /root/myproject/CFDivePlatform
|
||||
docker compose exec -T app php artisan l5-swagger:generate
|
||||
|
||||
- name: Restart queue worker
|
||||
run: |
|
||||
cd /root/myproject/CFDivePlatform
|
||||
|
||||
@@ -8,18 +8,22 @@ on:
|
||||
|
||||
jobs:
|
||||
test:
|
||||
runs-on: ubuntu-latest
|
||||
runs-on: self-hosted
|
||||
|
||||
steps:
|
||||
- name: Checkout code
|
||||
uses: actions/checkout@v4
|
||||
|
||||
- name: Setup PHP
|
||||
uses: shivammathur/setup-php@v2
|
||||
with:
|
||||
php-version: '8.2'
|
||||
extensions: mbstring, dom, fileinfo, gd, pdo_sqlite, sqlite3
|
||||
coverage: none
|
||||
run: |
|
||||
apk add --no-cache \
|
||||
php84 php84-phar php84-mbstring php84-dom php84-fileinfo php84-gd \
|
||||
php84-pdo php84-pdo_sqlite php84-sqlite3 php84-tokenizer \
|
||||
php84-xml php84-xmlwriter php84-ctype php84-curl php84-openssl \
|
||||
php84-json php84-session php84-iconv \
|
||||
curl unzip
|
||||
ln -sf /usr/bin/php84 /usr/local/bin/php
|
||||
curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer --quiet
|
||||
|
||||
- name: Copy .env
|
||||
run: cp .env.example .env
|
||||
|
||||
@@ -27,3 +27,4 @@ yarn-error.log
|
||||
/frontend/dist
|
||||
/frontend/.env
|
||||
|
||||
|
||||
|
||||
@@ -0,0 +1,26 @@
|
||||
# Ponytail, lazy senior dev mode
|
||||
|
||||
You are a lazy senior developer. Lazy means efficient, not careless. The best code is the code never written.
|
||||
|
||||
## Before writing any code
|
||||
|
||||
Stop at the first rung that holds:
|
||||
|
||||
- Does this need to be built at all? (YAGNI)
|
||||
- Does the standard library already do this? Use it.
|
||||
- Does a native platform feature cover it? Use it.
|
||||
- Does an already-installed dependency solve it? Use it.
|
||||
- Can this be one line? Make it one line.
|
||||
- Only then: write the minimum code that works.
|
||||
|
||||
## Rules
|
||||
|
||||
- No abstractions that weren't explicitly requested.
|
||||
- No new dependency if it can be avoided.
|
||||
- No boilerplate nobody asked for.
|
||||
- Deletion over addition. Boring over clever. Fewest files possible.
|
||||
- Question complex requests: "Do you actually need X, or does Y cover it?"
|
||||
- Pick the edge-case-correct option when two stdlib approaches are the same size, lazy means less code, not the flimsier algorithm.
|
||||
- Mark intentional simplifications with a ponytail: comment. If the shortcut has a known ceiling (global lock, O(n²) scan, naive heuristic), the comment names the ceiling and the upgrade path.
|
||||
|
||||
Not lazy about: input validation at trust boundaries, error handling that prevents data loss, security, accessibility, the calibration real hardware needs (the platform is never the spec ideal, a clock drifts, a sensor reads off), anything explicitly requested. Lazy code without its check is unfinished: non-trivial logic leaves ONE runnable check behind, the smallest thing that fails if the logic breaks (an assert-based demo/self-check or one small test file; no frameworks, no fixtures). Trivial one-liners need no test.
|
||||
+1
-8
@@ -17,8 +17,7 @@ RUN apt-get update && apt-get install -y \
|
||||
libzip-dev \
|
||||
default-mysql-client \
|
||||
netcat-openbsd \
|
||||
grep \
|
||||
cron
|
||||
grep
|
||||
|
||||
# 清理 apt 快取以減小鏡像大小
|
||||
RUN apt-get clean && rm -rf /var/lib/apt/lists/*
|
||||
@@ -53,12 +52,6 @@ COPY docker/php/local.ini /usr/local/etc/php/conf.d/local.ini
|
||||
COPY docker/php/docker-entrypoint.sh /usr/local/bin/docker-entrypoint.sh
|
||||
RUN chmod +x /usr/local/bin/docker-entrypoint.sh
|
||||
|
||||
# 加入 Laravel Scheduler cron job
|
||||
RUN echo "* * * * * www-data php /var/www/artisan schedule:run >> /var/log/laravel-scheduler.log 2>&1" \
|
||||
> /etc/cron.d/laravel-scheduler \
|
||||
&& chmod 0644 /etc/cron.d/laravel-scheduler \
|
||||
&& crontab /etc/cron.d/laravel-scheduler
|
||||
|
||||
# 設置容器啟動時執行的入口點
|
||||
# 這將在 CMD 指令之前執行
|
||||
ENTRYPOINT ["/usr/local/bin/docker-entrypoint.sh"]
|
||||
|
||||
@@ -8,6 +8,7 @@
|
||||
|
||||
**會員（Member）**
|
||||
- 註冊 / 登入（Email + Google OAuth）
|
||||
- Token 自動續期（401 refresh-then-retry，sessionStorage 儲存）
|
||||
- 瀏覽、搜尋、篩選潛水課程
|
||||
- 查看課程時段並送出預約
|
||||
- 與教練即時訊息（文字 + 圖片，含已讀回執）
|
||||
@@ -15,14 +16,16 @@
|
||||
- 站內通知（Bell Icon 即時更新 + 瀏覽器推播）
|
||||
|
||||
**教練（Provider）**
|
||||
- 課程 CRUD（含封面 + 相簿圖片上傳）
|
||||
- 課程 CRUD（含封面 + 相簿圖片上傳，伺服器端壓縮）
|
||||
- 課程時段管理
|
||||
- 預約管理（確認 / 拒絕 / 完成 / 取消）
|
||||
- 與學員即時訊息
|
||||
- 證照上傳與教練資格送審
|
||||
|
||||
**管理員（Admin）**
|
||||
- 平台統計數據（會員數、教練數、課程數）
|
||||
- 會員與教練帳號管理（啟用 / 停用 / 審核）
|
||||
- 會員與教練帳號管理（啟用 / 停用）
|
||||
- 教練資格審核（送審 / 通過 / 駁回 / 撤銷）
|
||||
- 課程、預約、評價管理
|
||||
|
||||
---
|
||||
@@ -36,23 +39,29 @@
|
||||
| 資料庫 | MySQL 8.0 |
|
||||
| 快取 | Redis |
|
||||
| 即時通訊 | Laravel Reverb（WebSocket，`wss://ws.hank-space.com`）|
|
||||
| 認證 | Laravel Sanctum + Google OAuth |
|
||||
| 認證 | Laravel Sanctum + Google OAuth + Token Refresh |
|
||||
| 容器 | Docker / Docker Compose |
|
||||
| API 文件 | Swagger UI（l5-swagger）|
|
||||
| 錯誤監控 | Sentry |
|
||||
| CI/CD | Gitea Actions（自動部署至 VPS）|
|
||||
| 測試 | PHPUnit / Laravel Feature & Unit Tests |
|
||||
|
||||
---
|
||||
|
||||
## API 文件
|
||||
|
||||
共 73 個端點，涵蓋：
|
||||
- 認證（Email + Google OAuth）
|
||||
Swagger UI（由 l5-swagger 生成）涵蓋所有端點，包含：
|
||||
- 認證（Email + Google OAuth）、Token 刷新
|
||||
- 公開課程查詢
|
||||
- 會員預約 / 訊息 / 評價 / 通知
|
||||
- 教練課程 / 時段 / 預約管理
|
||||
- 會員預約 / 即時訊息 / 評價 / 通知
|
||||
- 教練課程 / 時段 / 預約管理 / 資格驗證申請（證照送審）
|
||||
- 管理員後台
|
||||
|
||||
| 環境 | Swagger UI |
|
||||
|------|-----------|
|
||||
| 本地 | http://localhost:8080/api/documentation |
|
||||
| 生產 | https://api.hank-space.com/api/documentation |
|
||||
|
||||
---
|
||||
|
||||
## 健康檢查
|
||||
@@ -67,25 +76,22 @@ GET /health
|
||||
|
||||
## 本地開發
|
||||
|
||||
**啟動**
|
||||
**測試用帳號**
|
||||
|
||||
```bash
|
||||
docker compose up -d
|
||||
```
|
||||
| 角色 | 帳號 | 密碼 | 用途 |
|
||||
|------|------|------|------|
|
||||
| 會員 | Guest@cfdive.com | guestpassword | 體驗課程瀏覽、預約、會員預約紀錄 |
|
||||
| 教練 | Guest_Coach@cfdive.com | coachpassword | 體驗課程管理、時段管理、預約管理 |
|
||||
|
||||
| 服務 | URL |
|
||||
|------|-----|
|
||||
| API / 前端 | http://localhost:8080 |
|
||||
| phpMyAdmin | http://localhost:8081 |
|
||||
| Mailpit | http://localhost:8025 |
|
||||
| Reverb WebSocket | ws://localhost:8085 |
|
||||
**教練頁入口**
|
||||
|
||||
**環境設定**
|
||||
目前首頁尚未提供明顯導引到教練後台的入口。若要體驗教練功能，請直接開啟 `/coach/login`，使用上方教練試用帳號登入後會進入 `/coach/dashboard`。
|
||||
|
||||
複製 `.env.example` 為 `.env`，填入以下必要值：
|
||||
|
||||
```env
|
||||
REVERB_APP_KEY= # 32 字元隨機字串
|
||||
REVERB_APP_SECRET= # 32 字元隨機字串
|
||||
SENTRY_LARAVEL_DSN= # Sentry DSN（留空則停用）
|
||||
```
|
||||
| 服務 | 本地 | 生產 |
|
||||
|------|------|------|
|
||||
| 前端 | http://localhost:8080 | https://app.hank-space.com |
|
||||
| API | http://localhost:8080/api | https://api.hank-space.com/api |
|
||||
| Swagger UI | http://localhost:8080/api/documentation | https://api.hank-space.com/api/documentation |
|
||||
| phpMyAdmin | http://localhost:8081 | http://\<vps-ip\>:8081 |
|
||||
| Mailpit | http://localhost:8025 | http://\<vps-ip\>:8025 |
|
||||
| Reverb WebSocket | ws://localhost:8085 | wss://ws.hank-space.com |
|
||||
|
||||
+100
-4
@@ -12,7 +12,7 @@ use OpenApi\Annotations as OA;
|
||||
* )
|
||||
*
|
||||
* @OA\Server(
|
||||
* url="/api",
|
||||
* url=L5_SWAGGER_CONST_HOST,
|
||||
* description="API 伺服器"
|
||||
* )
|
||||
*
|
||||
@@ -207,9 +207,41 @@ class AuthApiDoc
|
||||
{
|
||||
}
|
||||
|
||||
/**
|
||||
* 會員 Token 刷新
|
||||
*
|
||||
* @OA\Post(
|
||||
* path="/member/refresh",
|
||||
* summary="會員 Token 刷新",
|
||||
* description="撤銷當前 Token 並發放新的 Bearer token（不需要重新登入）",
|
||||
* operationId="refreshMember",
|
||||
* tags={"會員"},
|
||||
* security={{"bearerAuth": {}}},
|
||||
* @OA\Response(
|
||||
* response=200,
|
||||
* description="刷新成功",
|
||||
* @OA\JsonContent(
|
||||
* @OA\Property(property="status", type="boolean", example=true),
|
||||
* @OA\Property(property="token", type="string", example="24|newtoken..."),
|
||||
* @OA\Property(property="token_type", type="string", example="Bearer")
|
||||
* )
|
||||
* ),
|
||||
* @OA\Response(
|
||||
* response=401,
|
||||
* description="未認證",
|
||||
* @OA\JsonContent(
|
||||
* @OA\Property(property="message", type="string", example="Unauthenticated.")
|
||||
* )
|
||||
* )
|
||||
* )
|
||||
*/
|
||||
public function refreshMember()
|
||||
{
|
||||
}
|
||||
|
||||
/**
|
||||
* 會員登出
|
||||
*
|
||||
*
|
||||
* @OA\Post(
|
||||
* path="/member/logout",
|
||||
* summary="會員登出",
|
||||
@@ -580,9 +612,41 @@ class AuthApiDoc
|
||||
{
|
||||
}
|
||||
|
||||
/**
|
||||
* 服務提供者 Token 刷新
|
||||
*
|
||||
* @OA\Post(
|
||||
* path="/provider/refresh",
|
||||
* summary="服務提供者 Token 刷新",
|
||||
* description="撤銷當前 Token 並發放新的 Bearer token",
|
||||
* operationId="refreshProvider",
|
||||
* tags={"服務提供者"},
|
||||
* security={{"bearerAuth": {}}},
|
||||
* @OA\Response(
|
||||
* response=200,
|
||||
* description="刷新成功",
|
||||
* @OA\JsonContent(
|
||||
* @OA\Property(property="status", type="boolean", example=true),
|
||||
* @OA\Property(property="token", type="string", example="25|newtoken..."),
|
||||
* @OA\Property(property="token_type", type="string", example="Bearer")
|
||||
* )
|
||||
* ),
|
||||
* @OA\Response(
|
||||
* response=401,
|
||||
* description="未認證",
|
||||
* @OA\JsonContent(
|
||||
* @OA\Property(property="message", type="string", example="Unauthenticated.")
|
||||
* )
|
||||
* )
|
||||
* )
|
||||
*/
|
||||
public function refreshProvider()
|
||||
{
|
||||
}
|
||||
|
||||
/**
|
||||
* 服務提供者登出
|
||||
*
|
||||
*
|
||||
* @OA\Post(
|
||||
* path="/provider/logout",
|
||||
* summary="服務提供者登出",
|
||||
@@ -906,9 +970,41 @@ class AuthApiDoc
|
||||
{
|
||||
}
|
||||
|
||||
/**
|
||||
* 管理員 Token 刷新
|
||||
*
|
||||
* @OA\Post(
|
||||
* path="/admin/refresh",
|
||||
* summary="管理員 Token 刷新",
|
||||
* description="撤銷當前 Token 並發放新的 Bearer token",
|
||||
* operationId="refreshAdmin",
|
||||
* tags={"管理員"},
|
||||
* security={{"bearerAuth": {}}},
|
||||
* @OA\Response(
|
||||
* response=200,
|
||||
* description="刷新成功",
|
||||
* @OA\JsonContent(
|
||||
* @OA\Property(property="status", type="boolean", example=true),
|
||||
* @OA\Property(property="token", type="string", example="26|newtoken..."),
|
||||
* @OA\Property(property="token_type", type="string", example="Bearer")
|
||||
* )
|
||||
* ),
|
||||
* @OA\Response(
|
||||
* response=401,
|
||||
* description="未認證",
|
||||
* @OA\JsonContent(
|
||||
* @OA\Property(property="message", type="string", example="Unauthenticated.")
|
||||
* )
|
||||
* )
|
||||
* )
|
||||
*/
|
||||
public function refreshAdmin()
|
||||
{
|
||||
}
|
||||
|
||||
/**
|
||||
* 管理員登出
|
||||
*
|
||||
*
|
||||
* @OA\Post(
|
||||
* path="/admin/logout",
|
||||
* summary="管理員登出",
|
||||
|
||||
@@ -17,6 +17,10 @@ use OpenApi\Annotations as OA;
|
||||
* name="通知",
|
||||
* description="站內通知管理（Member / Provider 共用）"
|
||||
* )
|
||||
* @OA\Tag(
|
||||
* name="即時訊息",
|
||||
* description="預約聊天室訊息（Member / Provider 共用，僅限 confirmed / completed 預約的參與方）"
|
||||
* )
|
||||
*/
|
||||
class MemberApiDoc
|
||||
{
|
||||
@@ -277,6 +281,152 @@ class MemberApiDoc
|
||||
{
|
||||
}
|
||||
|
||||
// -----------------------------------------------------------------------
|
||||
// Booking Messages（即時訊息，Member + Provider 共用）
|
||||
// -----------------------------------------------------------------------
|
||||
|
||||
/**
|
||||
* 取得各預約未讀訊息數
|
||||
*
|
||||
* @OA\Get(
|
||||
* path="/bookings/messages/unread-counts",
|
||||
* summary="取得各預約未讀訊息數",
|
||||
* description="回傳當前使用者每個預約中對方發送的未讀訊息數量（Key 為 booking_id）",
|
||||
* operationId="getMessageUnreadCounts",
|
||||
* tags={"即時訊息"},
|
||||
* security={{"bearerAuth": {}}},
|
||||
* @OA\Response(
|
||||
* response=200,
|
||||
* description="取得成功",
|
||||
* @OA\JsonContent(
|
||||
* @OA\Property(property="status", type="boolean", example=true),
|
||||
* @OA\Property(
|
||||
* property="data",
|
||||
* type="object",
|
||||
* description="Key 為 booking_id（string），value 為未讀數（integer）",
|
||||
* example={"12": 3, "17": 1}
|
||||
* )
|
||||
* )
|
||||
* )
|
||||
* )
|
||||
*/
|
||||
public function getMessageUnreadCounts()
|
||||
{
|
||||
}
|
||||
|
||||
/**
|
||||
* 取得預約訊息列表
|
||||
*
|
||||
* @OA\Get(
|
||||
* path="/bookings/{booking}/messages",
|
||||
* summary="取得預約訊息列表",
|
||||
* description="回傳指定預約的所有訊息（依時間升冪排列），僅限預約參與方存取，且預約狀態需為 confirmed 或 completed",
|
||||
* operationId="listBookingMessages",
|
||||
* tags={"即時訊息"},
|
||||
* security={{"bearerAuth": {}}},
|
||||
* @OA\Parameter(name="booking", in="path", required=true, description="預約 ID", @OA\Schema(type="integer")),
|
||||
* @OA\Response(
|
||||
* response=200,
|
||||
* description="取得成功",
|
||||
* @OA\JsonContent(
|
||||
* @OA\Property(property="status", type="boolean", example=true),
|
||||
* @OA\Property(
|
||||
* property="data",
|
||||
* type="array",
|
||||
* @OA\Items(
|
||||
* type="object",
|
||||
* @OA\Property(property="id", type="integer", example=1),
|
||||
* @OA\Property(property="booking_id", type="integer", example=12),
|
||||
* @OA\Property(property="sender_type", type="string", enum={"member","provider"}, example="member"),
|
||||
* @OA\Property(property="message", type="string", nullable=true, example="請問需要自備潛水裝備嗎？"),
|
||||
* @OA\Property(property="image_url", type="string", nullable=true, example=null),
|
||||
* @OA\Property(property="read_at", type="string", nullable=true, example=null),
|
||||
* @OA\Property(property="created_at", type="string", example="2025-07-01T10:00:00.000000Z")
|
||||
* )
|
||||
* )
|
||||
* )
|
||||
* ),
|
||||
* @OA\Response(response=403, description="非參與方或預約狀態不符", @OA\JsonContent(ref="#/components/schemas/ApiErrorResponse")),
|
||||
* @OA\Response(response=404, description="預約不存在", @OA\JsonContent(ref="#/components/schemas/ApiErrorResponse"))
|
||||
* )
|
||||
*/
|
||||
public function listBookingMessages()
|
||||
{
|
||||
}
|
||||
|
||||
/**
|
||||
* 發送預約訊息
|
||||
*
|
||||
* @OA\Post(
|
||||
* path="/bookings/{booking}/messages",
|
||||
* summary="發送預約訊息",
|
||||
* description="向指定預約的對方發送文字訊息或圖片（multipart/form-data）",
|
||||
* operationId="sendBookingMessage",
|
||||
* tags={"即時訊息"},
|
||||
* security={{"bearerAuth": {}}},
|
||||
* @OA\Parameter(name="booking", in="path", required=true, description="預約 ID", @OA\Schema(type="integer")),
|
||||
* @OA\RequestBody(
|
||||
* required=true,
|
||||
* @OA\MediaType(
|
||||
* mediaType="multipart/form-data",
|
||||
* @OA\Schema(
|
||||
* @OA\Property(property="message", type="string", nullable=true, example="請問需要自備潛水裝備嗎？"),
|
||||
* @OA\Property(property="image", type="string", format="binary", nullable=true, description="圖片（jpg/png，message 與 image 至少擇一）")
|
||||
* )
|
||||
* )
|
||||
* ),
|
||||
* @OA\Response(
|
||||
* response=201,
|
||||
* description="訊息已送出",
|
||||
* @OA\JsonContent(
|
||||
* @OA\Property(property="status", type="boolean", example=true),
|
||||
* @OA\Property(
|
||||
* property="data",
|
||||
* type="object",
|
||||
* @OA\Property(property="id", type="integer", example=42),
|
||||
* @OA\Property(property="booking_id", type="integer", example=12),
|
||||
* @OA\Property(property="sender_type", type="string", example="member"),
|
||||
* @OA\Property(property="message", type="string", nullable=true, example="請問需要自備潛水裝備嗎？"),
|
||||
* @OA\Property(property="image_url", type="string", nullable=true, example=null),
|
||||
* @OA\Property(property="read_at", type="string", nullable=true, example=null),
|
||||
* @OA\Property(property="created_at", type="string", example="2025-07-01T10:05:00.000000Z")
|
||||
* )
|
||||
* )
|
||||
* ),
|
||||
* @OA\Response(response=403, description="非參與方或預約狀態不符", @OA\JsonContent(ref="#/components/schemas/ApiErrorResponse")),
|
||||
* @OA\Response(response=422, description="message 與 image 皆為空", @OA\JsonContent(ref="#/components/schemas/ApiErrorResponse"))
|
||||
* )
|
||||
*/
|
||||
public function sendBookingMessage()
|
||||
{
|
||||
}
|
||||
|
||||
/**
|
||||
* 標記訊息為已讀
|
||||
*
|
||||
* @OA\Post(
|
||||
* path="/bookings/{booking}/messages/read",
|
||||
* summary="標記訊息為已讀",
|
||||
* description="將指定預約中對方發送的所有未讀訊息批次標記為已讀",
|
||||
* operationId="markMessagesRead",
|
||||
* tags={"即時訊息"},
|
||||
* security={{"bearerAuth": {}}},
|
||||
* @OA\Parameter(name="booking", in="path", required=true, description="預約 ID", @OA\Schema(type="integer")),
|
||||
* @OA\Response(
|
||||
* response=200,
|
||||
* description="標記成功",
|
||||
* @OA\JsonContent(
|
||||
* @OA\Property(property="status", type="boolean", example=true),
|
||||
* @OA\Property(property="message", type="string", example="已標記為已讀")
|
||||
* )
|
||||
* ),
|
||||
* @OA\Response(response=403, description="非參與方", @OA\JsonContent(ref="#/components/schemas/ApiErrorResponse"))
|
||||
* )
|
||||
*/
|
||||
public function markMessagesRead()
|
||||
{
|
||||
}
|
||||
|
||||
// -----------------------------------------------------------------------
|
||||
// Notifications (Member + Provider 共用)
|
||||
// -----------------------------------------------------------------------
|
||||
|
||||
@@ -21,9 +21,150 @@ use OpenApi\Annotations as OA;
|
||||
* name="教練預約",
|
||||
* description="服務提供者的預約管理"
|
||||
* )
|
||||
* @OA\Tag(
|
||||
* name="教練驗證",
|
||||
* description="服務提供者的資格驗證申請（證照送審）"
|
||||
* )
|
||||
*/
|
||||
class ProviderApiDoc
|
||||
{
|
||||
// -----------------------------------------------------------------------
|
||||
// Provider Verification (證照送審)
|
||||
// -----------------------------------------------------------------------
|
||||
|
||||
/**
|
||||
* 取得驗證申請狀態
|
||||
*
|
||||
* @OA\Get(
|
||||
* path="/provider/verification",
|
||||
* summary="取得驗證申請狀態",
|
||||
* description="回傳當前服務提供者的驗證狀態與已上傳的證照清單",
|
||||
* operationId="getProviderVerification",
|
||||
* tags={"教練驗證"},
|
||||
* security={{"bearerAuth": {}}},
|
||||
* @OA\Response(
|
||||
* response=200,
|
||||
* description="取得成功",
|
||||
* @OA\JsonContent(
|
||||
* @OA\Property(property="status", type="boolean", example=true),
|
||||
* @OA\Property(
|
||||
* property="data",
|
||||
* type="object",
|
||||
* @OA\Property(property="verification_status", type="string", enum={"unsubmitted","pending","approved","rejected"}, example="pending"),
|
||||
* @OA\Property(property="rejection_reason", type="string", nullable=true, example=null),
|
||||
* @OA\Property(
|
||||
* property="certifications",
|
||||
* type="array",
|
||||
* @OA\Items(
|
||||
* type="object",
|
||||
* @OA\Property(property="id", type="integer", example=1),
|
||||
* @OA\Property(property="url", type="string", example="http://localhost:8080/storage/providers/5/certifications/uuid.jpg")
|
||||
* )
|
||||
* )
|
||||
* )
|
||||
* )
|
||||
* ),
|
||||
* @OA\Response(response=403, description="無權限", @OA\JsonContent(ref="#/components/schemas/ApiErrorResponse"))
|
||||
* )
|
||||
*/
|
||||
public function getProviderVerification()
|
||||
{
|
||||
}
|
||||
|
||||
/**
|
||||
* 上傳證照圖片
|
||||
*
|
||||
* @OA\Post(
|
||||
* path="/provider/verification/certifications",
|
||||
* summary="上傳證照圖片",
|
||||
* description="上傳一張證照圖片（multipart/form-data），未送審前可多次上傳",
|
||||
* operationId="uploadCertification",
|
||||
* tags={"教練驗證"},
|
||||
* security={{"bearerAuth": {}}},
|
||||
* @OA\RequestBody(
|
||||
* required=true,
|
||||
* @OA\MediaType(
|
||||
* mediaType="multipart/form-data",
|
||||
* @OA\Schema(
|
||||
* required={"certification"},
|
||||
* @OA\Property(property="certification", type="string", format="binary", description="證照圖片（jpg/png，最大 5MB）")
|
||||
* )
|
||||
* )
|
||||
* ),
|
||||
* @OA\Response(
|
||||
* response=200,
|
||||
* description="上傳成功",
|
||||
* @OA\JsonContent(
|
||||
* @OA\Property(property="status", type="boolean", example=true),
|
||||
* @OA\Property(
|
||||
* property="data",
|
||||
* type="object",
|
||||
* @OA\Property(property="id", type="integer", example=1),
|
||||
* @OA\Property(property="url", type="string", example="http://localhost:8080/storage/providers/5/certifications/uuid.jpg")
|
||||
* )
|
||||
* )
|
||||
* ),
|
||||
* @OA\Response(response=422, description="圖片驗證失敗", @OA\JsonContent(ref="#/components/schemas/ApiErrorResponse")),
|
||||
* @OA\Response(response=403, description="無權限", @OA\JsonContent(ref="#/components/schemas/ApiErrorResponse"))
|
||||
* )
|
||||
*/
|
||||
public function uploadCertification()
|
||||
{
|
||||
}
|
||||
|
||||
/**
|
||||
* 刪除證照圖片
|
||||
*
|
||||
* @OA\Delete(
|
||||
* path="/provider/verification/certifications/{id}",
|
||||
* summary="刪除證照圖片",
|
||||
* description="刪除指定的已上傳證照，已送審（pending/approved）狀態不可刪除",
|
||||
* operationId="deleteCertification",
|
||||
* tags={"教練驗證"},
|
||||
* security={{"bearerAuth": {}}},
|
||||
* @OA\Parameter(name="id", in="path", required=true, description="證照 ID", @OA\Schema(type="integer")),
|
||||
* @OA\Response(
|
||||
* response=200,
|
||||
* description="刪除成功",
|
||||
* @OA\JsonContent(
|
||||
* @OA\Property(property="status", type="boolean", example=true),
|
||||
* @OA\Property(property="message", type="string", example="證照已刪除")
|
||||
* )
|
||||
* ),
|
||||
* @OA\Response(response=403, description="無權限或當前狀態不可刪除", @OA\JsonContent(ref="#/components/schemas/ApiErrorResponse")),
|
||||
* @OA\Response(response=404, description="證照不存在", @OA\JsonContent(ref="#/components/schemas/ApiErrorResponse"))
|
||||
* )
|
||||
*/
|
||||
public function deleteCertification()
|
||||
{
|
||||
}
|
||||
|
||||
/**
|
||||
* 送出驗證申請
|
||||
*
|
||||
* @OA\Post(
|
||||
* path="/provider/verification/submit",
|
||||
* summary="送出驗證申請",
|
||||
* description="將驗證狀態由 unsubmitted/rejected 轉為 pending，至少需有一張已上傳的證照",
|
||||
* operationId="submitVerification",
|
||||
* tags={"教練驗證"},
|
||||
* security={{"bearerAuth": {}}},
|
||||
* @OA\Response(
|
||||
* response=200,
|
||||
* description="送審成功",
|
||||
* @OA\JsonContent(
|
||||
* @OA\Property(property="status", type="boolean", example=true),
|
||||
* @OA\Property(property="message", type="string", example="驗證申請已送出")
|
||||
* )
|
||||
* ),
|
||||
* @OA\Response(response=422, description="尚未上傳證照或當前狀態不可送審", @OA\JsonContent(ref="#/components/schemas/ApiErrorResponse")),
|
||||
* @OA\Response(response=403, description="無權限", @OA\JsonContent(ref="#/components/schemas/ApiErrorResponse"))
|
||||
* )
|
||||
*/
|
||||
public function submitVerification()
|
||||
{
|
||||
}
|
||||
|
||||
// -----------------------------------------------------------------------
|
||||
// Provider Offers CRUD
|
||||
// -----------------------------------------------------------------------
|
||||
|
||||
@@ -13,6 +13,7 @@ return Application::configure(basePath: dirname(__DIR__))
|
||||
health: '/up',
|
||||
)
|
||||
->withMiddleware(function (Middleware $middleware) {
|
||||
$middleware->trustProxies(at: ['*']);
|
||||
$middleware->alias([
|
||||
'admin' => \App\Http\Middleware\EnsureAdmin::class,
|
||||
]);
|
||||
|
||||
@@ -0,0 +1,27 @@
|
||||
services:
|
||||
phpmyadmin:
|
||||
image: phpmyadmin/phpmyadmin
|
||||
container_name: cfdive-phpmyadmin
|
||||
restart: unless-stopped
|
||||
ports:
|
||||
- "127.0.0.1:8081:80"
|
||||
environment:
|
||||
PMA_HOST: db
|
||||
PMA_PORT: 3306
|
||||
PMA_USER: ${DB_USERNAME:-cfdiveuser}
|
||||
PMA_PASSWORD: ${DB_PASSWORD}
|
||||
MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD}
|
||||
networks:
|
||||
- cfdive-network
|
||||
depends_on:
|
||||
db:
|
||||
condition: service_healthy
|
||||
|
||||
mailpit:
|
||||
image: axllent/mailpit
|
||||
container_name: cfdive-mailpit
|
||||
restart: unless-stopped
|
||||
ports:
|
||||
- "127.0.0.1:8025:8025"
|
||||
networks:
|
||||
- cfdive-network
|
||||
@@ -5,7 +5,7 @@ return [
|
||||
'documentations' => [
|
||||
'default' => [
|
||||
'api' => [
|
||||
'title' => 'L5 Swagger UI',
|
||||
'title' => 'CFDive Platform API',
|
||||
],
|
||||
|
||||
'routes' => [
|
||||
|
||||
+24
-20
@@ -38,11 +38,11 @@ services:
|
||||
|
||||
# 健康檢查配置
|
||||
healthcheck:
|
||||
test: ["CMD", "php", "-v"] # 檢查 PHP 版本確認服務正常
|
||||
interval: 30s # 每30秒檢查一次
|
||||
timeout: 10s # 超時時間10秒
|
||||
retries: 3 # 重試3次
|
||||
start_period: 40s # 容器啟動後40秒開始檢查
|
||||
test: ["CMD-SHELL", "nc -z 127.0.0.1 9000 || exit 1"]
|
||||
interval: 30s
|
||||
timeout: 10s
|
||||
retries: 3
|
||||
start_period: 40s
|
||||
|
||||
nginx:
|
||||
image: nginx:alpine
|
||||
@@ -109,20 +109,26 @@ services:
|
||||
ports:
|
||||
- "127.0.0.1:3306:3306" # 只綁 localhost，不對外
|
||||
|
||||
phpmyadmin:
|
||||
image: phpmyadmin/phpmyadmin
|
||||
container_name: cfdive-phpmyadmin
|
||||
|
||||
scheduler:
|
||||
image: cfdive-platform
|
||||
container_name: cfdive-scheduler
|
||||
restart: unless-stopped
|
||||
working_dir: /var/www/
|
||||
command: php artisan schedule:work
|
||||
volumes:
|
||||
- ./:/var/www
|
||||
environment:
|
||||
PMA_HOST: db
|
||||
PMA_PORT: 3306
|
||||
PMA_USER: ${DB_USERNAME:-cfdiveuser}
|
||||
PMA_PASSWORD: ${DB_PASSWORD}
|
||||
MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD}
|
||||
- DB_CONNECTION=mysql
|
||||
- DB_HOST=db
|
||||
- DB_PORT=3306
|
||||
- DB_DATABASE=${DB_DATABASE:-CFDivePlatform}
|
||||
- DB_USERNAME=${DB_USERNAME:-cfdiveuser}
|
||||
- DB_PASSWORD=${DB_PASSWORD}
|
||||
networks:
|
||||
- cfdive-network
|
||||
depends_on:
|
||||
db:
|
||||
app:
|
||||
condition: service_healthy
|
||||
|
||||
queue-worker:
|
||||
@@ -146,12 +152,6 @@ services:
|
||||
app:
|
||||
condition: service_healthy
|
||||
|
||||
mailpit:
|
||||
image: axllent/mailpit
|
||||
container_name: cfdive-mailpit
|
||||
restart: unless-stopped
|
||||
networks:
|
||||
- cfdive-network
|
||||
|
||||
redis:
|
||||
image: redis:alpine
|
||||
@@ -159,6 +159,8 @@ services:
|
||||
restart: unless-stopped
|
||||
networks:
|
||||
- cfdive-network
|
||||
volumes:
|
||||
- redis-data:/data
|
||||
healthcheck:
|
||||
test: ["CMD", "redis-cli", "ping"]
|
||||
interval: 30s
|
||||
@@ -205,3 +207,5 @@ networks:
|
||||
volumes:
|
||||
mysql-data:
|
||||
driver: local
|
||||
redis-data:
|
||||
driver: local
|
||||
|
||||
@@ -59,8 +59,5 @@ fi
|
||||
echo "✅ [背景] 初始化完成"
|
||||
) &
|
||||
|
||||
# 啟動 cron（Laravel Scheduler）
|
||||
service cron start || cron || true
|
||||
|
||||
echo "🚀 啟動 php-fpm..."
|
||||
exec "$@"
|
||||
|
||||
+271
@@ -0,0 +1,271 @@
|
||||
# CFDivePlatform 啟動指令
|
||||
|
||||
## 部署模式
|
||||
|
||||
專案根目錄有兩個 compose 檔：
|
||||
|
||||
| 檔案 | 用途 |
|
||||
|------|------|
|
||||
| `docker-compose.yml` | 正式服務（app、nginx、frontend、db、redis、reverb、queue-worker、scheduler） |
|
||||
| `compose.override.yml` | 開發工具（phpmyadmin、mailpit），已進版控 |
|
||||
|
||||
**本機 / VPS（預設）**：Docker Compose 自動合併兩檔，開發工具一同啟動：
|
||||
|
||||
```bash
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
**雲端正式環境**：明確指定單一檔案，排除開發工具：
|
||||
|
||||
```bash
|
||||
docker compose -f docker-compose.yml up -d
|
||||
```
|
||||
|
||||
> VPS 首次部署或更新後執行 `git pull` 即可取得最新的 `compose.override.yml`，不需手動建立。
|
||||
|
||||
---
|
||||
|
||||
## 專案位置
|
||||
|
||||
```powershell
|
||||
C:\laragon\www\CFDivePlatform
|
||||
```
|
||||
|
||||
## 1. 進入專案目錄
|
||||
|
||||
```powershell
|
||||
cd C:\laragon\www\CFDivePlatform
|
||||
```
|
||||
|
||||
## 2. 準備 `.env`
|
||||
|
||||
如果尚未建立 `.env`：
|
||||
|
||||
```powershell
|
||||
copy .env.example .env
|
||||
```
|
||||
|
||||
確認 `.env` 至少設定以下項目：
|
||||
|
||||
```env
|
||||
APP_KEY=
|
||||
DB_DATABASE=CFDivePlatform
|
||||
DB_USERNAME=cfdiveuser
|
||||
DB_PASSWORD=your_password
|
||||
MYSQL_ROOT_PASSWORD=your_root_password
|
||||
|
||||
REVERB_APP_ID=your_reverb_app_id
|
||||
REVERB_APP_KEY=your_reverb_app_key
|
||||
REVERB_APP_SECRET=your_reverb_app_secret
|
||||
VITE_REVERB_APP_KEY=your_reverb_app_key
|
||||
```
|
||||
|
||||
如果 `APP_KEY` 是空的，可在容器啟動後執行：
|
||||
|
||||
```powershell
|
||||
docker compose exec app php artisan key:generate
|
||||
```
|
||||
|
||||
## 3. 啟動 Docker 服務
|
||||
|
||||
第一次啟動，或 Dockerfile / compose 設定有變更時：
|
||||
|
||||
```powershell
|
||||
docker compose up -d --build
|
||||
```
|
||||
|
||||
平常啟動：
|
||||
|
||||
```powershell
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
## 4. 查看服務狀態
|
||||
|
||||
```powershell
|
||||
docker compose ps
|
||||
```
|
||||
|
||||
查看所有服務 log：
|
||||
|
||||
```powershell
|
||||
docker compose logs -f
|
||||
```
|
||||
|
||||
只查看 Laravel App log：
|
||||
|
||||
```powershell
|
||||
docker compose logs -f app
|
||||
```
|
||||
|
||||
## 5. 初始化與維護指令
|
||||
|
||||
容器啟動時會自動執行部分初始化流程：
|
||||
|
||||
- 安裝 Composer 依賴
|
||||
- 等待 MySQL 啟動
|
||||
- 執行 migration
|
||||
- 清除 Laravel cache
|
||||
- 建立 storage link
|
||||
- 產生 Swagger 文件
|
||||
|
||||
如需手動執行，可使用：
|
||||
|
||||
```powershell
|
||||
docker compose exec app composer install
|
||||
docker compose exec app php artisan migrate
|
||||
docker compose exec app php artisan storage:link
|
||||
docker compose exec app php artisan l5-swagger:generate
|
||||
```
|
||||
|
||||
清除 Laravel 快取：
|
||||
|
||||
```powershell
|
||||
docker compose exec app php artisan config:clear
|
||||
docker compose exec app php artisan cache:clear
|
||||
docker compose exec app php artisan route:clear
|
||||
docker compose exec app php artisan view:clear
|
||||
```
|
||||
|
||||
## 6. 建立管理員帳號
|
||||
|
||||
```powershell
|
||||
docker compose exec app php artisan app:create-admin "Admin" "admin@example.com" --password="your_password"
|
||||
```
|
||||
|
||||
密碼至少需要 8 碼。
|
||||
|
||||
## 7. 前端 Vite 開發模式
|
||||
|
||||
如果要使用本機 Vite 開發模式：
|
||||
|
||||
```powershell
|
||||
npm install
|
||||
npm run dev
|
||||
```
|
||||
|
||||
正式建置：
|
||||
|
||||
```powershell
|
||||
npm run build
|
||||
```
|
||||
|
||||
Docker Compose 內也有 `frontend` 服務，預設網址為：
|
||||
|
||||
```text
|
||||
http://localhost:5173
|
||||
```
|
||||
|
||||
## 8. 重啟 frontend
|
||||
|
||||
如果 frontend 是透過 Docker Compose 啟動：
|
||||
|
||||
```powershell
|
||||
docker compose restart frontend
|
||||
```
|
||||
|
||||
如果有修改 frontend 的 Dockerfile、環境變數或 build 內容，建議重建：
|
||||
|
||||
```powershell
|
||||
docker compose up -d --build frontend
|
||||
```
|
||||
|
||||
如果是使用本機 Vite 開發模式，先在原本終端機按 `Ctrl + C` 停止，再重新執行：
|
||||
|
||||
```powershell
|
||||
npm run dev
|
||||
```
|
||||
|
||||
## 9. 服務網址
|
||||
|
||||
| 服務 | URL |
|
||||
| --- | --- |
|
||||
| API / Laravel + Nginx | <http://localhost:8080> |
|
||||
| Frontend Docker | <http://localhost:5173> |
|
||||
| phpMyAdmin | <http://localhost:8081> |
|
||||
| Mailpit | <http://localhost:8025> |
|
||||
| Reverb WebSocket | <ws://localhost:8085> |
|
||||
| Health Check | <http://localhost:8080/health> |
|
||||
|
||||
## 10. Log 查看
|
||||
|
||||
Laravel 日誌走 stderr，透過 Docker 查看（不再有 `storage/logs/` 檔案）：
|
||||
|
||||
```bash
|
||||
# 即時串流
|
||||
docker compose logs -f app
|
||||
|
||||
# 查看最後 50 行
|
||||
docker compose logs app --tail=50
|
||||
```
|
||||
|
||||
## 11. VPS 維護窗口操作（P1 部署）
|
||||
|
||||
PR merge 後 CI/CD 自動跑 composer/migrate/cache，完成後 SSH 進 VPS 執行：
|
||||
|
||||
```bash
|
||||
cd /root/myproject/CFDivePlatform
|
||||
|
||||
# 1. 更新 .env（一次性）
|
||||
sed -i 's/SESSION_DRIVER=database/SESSION_DRIVER=redis/' .env
|
||||
sed -i 's/LOG_CHANNEL=stack/LOG_CHANNEL=stderr/' .env
|
||||
sed -i '/^LOG_STACK=/d' .env
|
||||
sed -i '/^LOG_DAILY_DAYS=/d' .env
|
||||
|
||||
# 2. Rebuild + 重啟（entrypoint 自動 config:clear）
|
||||
docker compose up -d --build
|
||||
|
||||
# 3. 驗證
|
||||
docker compose ps # scheduler 應顯示 Up
|
||||
docker compose logs app --tail=20 # 應有 stderr 日誌
|
||||
docker compose exec redis redis-cli keys "laravel_session*" # 登入後應有 session key
|
||||
docker compose exec app sh -c "which cron 2>/dev/null || echo 'cron binary not found'" # 應輸出 not found
|
||||
```
|
||||
|
||||
**Rollback（若需還原）：**
|
||||
|
||||
Session/Log 還原（不需 rebuild）：
|
||||
```bash
|
||||
sed -i 's/SESSION_DRIVER=redis/SESSION_DRIVER=database/' .env
|
||||
sed -i 's/LOG_CHANNEL=stderr/LOG_CHANNEL=stack/' .env
|
||||
echo "LOG_STACK=daily" >> .env
|
||||
echo "LOG_DAILY_DAYS=14" >> .env
|
||||
docker compose exec app php artisan config:clear
|
||||
docker compose restart app
|
||||
```
|
||||
|
||||
Scheduler 還原（需 rebuild）：
|
||||
```bash
|
||||
git revert <commit-hash>
|
||||
docker compose up -d --build
|
||||
```
|
||||
|
||||
## 12. 停止服務
|
||||
|
||||
停止容器，但保留資料庫 volume：
|
||||
|
||||
```powershell
|
||||
docker compose down
|
||||
```
|
||||
|
||||
停止容器並移除 volume，會清除 MySQL 資料：
|
||||
|
||||
```powershell
|
||||
docker compose down -v
|
||||
```
|
||||
|
||||
## 最短啟動流程
|
||||
|
||||
```powershell
|
||||
cd C:\laragon\www\CFDivePlatform
|
||||
copy .env.example .env
|
||||
docker compose up -d --build
|
||||
docker compose exec app php artisan key:generate
|
||||
docker compose ps
|
||||
```
|
||||
|
||||
啟動完成後開啟：
|
||||
|
||||
```text
|
||||
http://localhost:8080
|
||||
```
|
||||
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-06-16
|
||||
@@ -0,0 +1,56 @@
|
||||
## Context
|
||||
|
||||
現有 187 個 Feature test 分佈在認證、狀態機邊界、聊天授權等安全層，核心業務端點（Provider 課程管理、時段管理、Admin 使用者操作、通知觸發、預約列表）完全未覆蓋。缺口已於 2026-06-11 稽核報告中識別（通知系統「僅 Scheduler 路徑覆蓋」），此 change 補齊這五個區塊。
|
||||
|
||||
**現有 Factory 狀況**：`database/factories/` 只有 `UserFactory`。`DivingOffer`、`CourseSchedule`、`Booking` 均無 factory——現有測試一律使用 `Model::create([...])` 直接建立，新測試沿用此慣例，不新增 factory（避免引入 app 行為）。
|
||||
|
||||
**認證方式**：現有 Feature test 全部使用 `$this->actingAs($user)` + `getJson/postJson` 等 HTTP helpers，不手動建立 token。新測試維持相同模式。
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
- 5 個新 Feature test 類別：`ProviderOfferCrudTest`、`ProviderScheduleCrudTest`、`AdminUserManagementTest`、`NotificationTriggerTest`、`BookingListTest`
|
||||
- 涵蓋正常流程（happy path）+ 所有權邊界（403）+ 輸入驗證（422）
|
||||
- 通知測試補齊直接事件路徑（建立/確認/拒絕/取消），不只驗證 Scheduler 完課路徑
|
||||
|
||||
**Non-Goals:**
|
||||
- 不修改任何 app 程式碼
|
||||
- 不補 Unit test（已於上一個 change 完成）
|
||||
- 不測試 UI / 前端行為
|
||||
- 不測試通知 Email 實際發送（`notification-email` 規格另有覆蓋）
|
||||
|
||||
## Decisions
|
||||
|
||||
### D1：延續現有 Feature test 架構，不引入 Service layer mock
|
||||
|
||||
現有測試全部使用 `RefreshDatabase` + 真實 DB，未 mock 任何 repository/service。維持一致性優先於執行速度——187 案例目前 42 秒，新增 ~50 案例後預估 55 秒以內，可接受。
|
||||
|
||||
**替代方案**：mock `Cache::tags()` 與 `Notification`。決議：`Notification::fake()` 繼續使用（現有慣例），`Cache::tags()` 讓它真實運行（Redis 在 Docker 中可用）。
|
||||
|
||||
### D2：通知測試使用 `Notification::fake()` + `assertSentTo()`
|
||||
|
||||
現有 `BookingSchedulerTest` 已驗證 Scheduler 完課觸發通知。`NotificationTriggerTest` 補齊 controller 直接觸發的路徑（`store`、`confirm`、`reject`、`member cancel`、`provider cancel`），同樣 fake 後斷言 `Notification::assertSentTo()`，不依賴 queue worker。
|
||||
|
||||
### D3：預約列表測試不涵蓋分頁（暫緩 O3.2）
|
||||
|
||||
`MemberBookingController::index()` 目前為 `->get()` 全量回傳（O3.2 未完成），測試僅斷言回傳正確的資料集合（`data` 陣列包含/不包含正確的 booking）。分頁斷言待 O3.2 實作後加入。
|
||||
|
||||
### D4：所有權邊界是必測案例，非選測
|
||||
|
||||
Provider CRUD 的「他人不可操作」403 路徑在現有 `BookingLifecycleTest` 已有先例，這裡對 Offer 和 Schedule 同樣必須測。Admin 操作已有 `AdminEndpointAuthTest` 覆蓋角色層的 401/403，`AdminUserManagementTest` 聚焦資料正確性與操作副作用（is_active 切換、is_verified 切換 + 快取清除）。
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
- **`Cache::tags()` 與 driver 相容性**：`phpunit.xml` 設定 `CACHE_STORE=array`。Laravel 11 的 `array` store 繼承 `TaggableStore`，因此 `Cache::tags(['diving_offers'])->flush()` 在測試環境可正常執行（`DivingOfferVisibilityTest::test_toggle_verified_takes_effect_immediately_despite_cache` 已驗證）。真正的風險是：若未來 CI 或本機改用 `file`、`database` 等不支援 tags 的 driver，所有呼叫 `Cache::tags()` 的 controller 測試都會拋出 `BadMethodCallException`。→ 緩解：在 tasks 加上驗收項目，確認 `phpunit.xml` 的 `CACHE_STORE` 為 `array` 或 `redis`，並加入 README 說明。
|
||||
- **Admin toggle-verified 的快取副作用驗證方式**：`DivingOfferVisibilityTest` 已有端對端驗證（toggle → 公開列表立即消失）。`AdminUserManagementTest` 不重複這個斷言，只驗證 `is_verified` 欄位變更與 HTTP 200 即可，避免測試重複。
|
||||
- **Notification::fake() 無法驗證 mail 實際送出**：這是刻意的邊界——只驗證通知物件被派發至正確收件者，不驗證 email 模板內容（屬於 `notification-email` 規格的範疇）。
|
||||
|
||||
## 各測試類別案例清單
|
||||
|
||||
| 測試類別 | 案例 | 涵蓋邊界 |
|
||||
|----------|------|---------|
|
||||
| `ProviderOfferCrudTest` | store 成功、缺必填 422、update 成功、update 他人 403、destroy 成功、destroy 他人 403、未認證 401 | happy path + ownership + auth |
|
||||
| `ProviderScheduleCrudTest` | store 成功、store 他人課程 403、過去日期 422、update max_participants 成功、update 低於 current 422、update 他人 403、destroy 同時取消 bookings | happy path + 容量不變式 + ownership |
|
||||
| `AdminUserManagementTest` | 列出 members 只含 member role、列出 providers 只含 provider role、toggle-active 改變 is_active、toggle-verified 改變 is_verified、非 admin 403 | 資料正確性 + 角色隔離 |
|
||||
| `NotificationTriggerTest` | BookingCreated→provider、Confirmed→member、Rejected→member、CancelledByMember→provider、CancelledByProvider→member | 5 條直接觸發路徑，收件者各不同 |
|
||||
| `BookingListTest` | `GET /api/member/bookings`（MemberBookingController::index）、`GET /api/provider/bookings`（ProviderBookingController::index）、`GET /api/admin/bookings`（AdminBookingController::index）——各建兩方資料斷言隔離、admin 全看、未認證 401 | 路由已確認存在；角色資料隔離邊界 |
|
||||
@@ -0,0 +1,26 @@
|
||||
## Why
|
||||
|
||||
稽核報告（2026-06-11）標註通知系統「僅 Scheduler 路徑覆蓋」，且 Provider Offer/Schedule CRUD、Admin 使用者管理、預約列表端點至今零 Feature test。187 個現有案例全集中在認證與狀態機邊界，核心業務流程端點的回歸一旦發生，測試套件無法攔截。
|
||||
|
||||
## What Changes
|
||||
|
||||
- 新增 `ProviderOfferCrudTest`：教練課程的建立、更新、刪除，含所有權驗證（他人不可操作）
|
||||
- 新增 `ProviderScheduleCrudTest`：課程時段的建立、更新、刪除，含容量驗證與所有權邊界
|
||||
- 新增 `AdminUserManagementTest`：Admin 查詢使用者列表、切換教練驗證狀態（toggle-verified）
|
||||
- 新增 `NotificationTriggerTest`：預約事件直接觸發通知（建立、確認、拒絕、取消、完成）；補足現有 Scheduler 路徑以外的觸發路徑
|
||||
- 新增 `BookingListTest`：Member / Provider / Admin 各自的預約列表端點（分頁與角色過濾）
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
- `feature-test-coverage`：定義核心業務流程端點的測試覆蓋契約，涵蓋 Provider Offer CRUD、Schedule CRUD、Admin 使用者管理、通知觸發路徑、預約列表端點；對應 auth-test-coverage 在認證層的角色
|
||||
|
||||
### Modified Capabilities
|
||||
<!-- 現有行為規格無異動，僅補測試覆蓋，無須 delta spec -->
|
||||
|
||||
## Impact
|
||||
|
||||
- 新增 Feature test 檔案：`tests/Feature/` 下 5 個新測試類別（約 40~55 案例）
|
||||
- 不修改任何 app 程式碼
|
||||
- 不影響現有 API 行為或資料結構
|
||||
- 現有 187 案例零 regression（Unit test 已驗證）
|
||||
+146
@@ -0,0 +1,146 @@
|
||||
# feature-test-coverage Specification
|
||||
|
||||
## Purpose
|
||||
定義核心業務流程端點的測試覆蓋契約：Provider 課程 CRUD、時段管理、Admin 使用者操作、通知直接觸發路徑、預約列表端點。補齊 2026-06-11 稽核報告識別的 Feature test 缺口，確保這些端點的回歸能被測試套件即時攔截。
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
---
|
||||
|
||||
### Requirement: Provider 課程 CRUD 測試覆蓋
|
||||
測試套件 SHALL 驗證 `POST /api/provider/offers`、`PUT /api/provider/offers/{id}`、`DELETE /api/provider/offers/{id}` 的正常流程與所有權邊界。
|
||||
|
||||
#### Scenario: Provider 建立課程成功
|
||||
- **WHEN** 已認證的 Provider 送出有效的 title / location / price / region 至 `POST /api/provider/offers`
|
||||
- **THEN** 回傳 HTTP 201，body 包含 `{ status: true, data: { id, title, provider_id } }`，DB 存在對應記錄且 `provider_id` 為當前 Provider
|
||||
|
||||
#### Scenario: 建立課程缺少必填欄位回傳 422
|
||||
- **WHEN** Provider 送出缺少 `title` 或 `price` 的請求至 `POST /api/provider/offers`
|
||||
- **THEN** 回傳 HTTP 422，body 包含對應欄位的驗證錯誤
|
||||
|
||||
#### Scenario: Provider 更新自己的課程
|
||||
- **WHEN** 已認證的 Provider 送出有效更新欄位至 `PUT /api/provider/offers/{id}`（該課程屬於此 Provider）
|
||||
- **THEN** 回傳 HTTP 200，body 包含更新後的課程資料，DB 記錄已變更
|
||||
|
||||
#### Scenario: Provider 不可更新他人課程
|
||||
- **WHEN** Provider A 嘗試 `PUT /api/provider/offers/{id}`，但該課程屬於 Provider B
|
||||
- **THEN** 回傳 HTTP 403，body 包含 `{ status: false }`
|
||||
|
||||
#### Scenario: Provider 刪除自己的課程
|
||||
- **WHEN** 已認證的 Provider 送出 `DELETE /api/provider/offers/{id}`（該課程屬於此 Provider）
|
||||
- **THEN** 回傳 HTTP 200，body 包含 `{ status: true }`，DB 記錄已不存在
|
||||
|
||||
#### Scenario: Provider 不可刪除他人課程
|
||||
- **WHEN** Provider A 嘗試 `DELETE /api/provider/offers/{id}`，但該課程屬於 Provider B
|
||||
- **THEN** 回傳 HTTP 403
|
||||
|
||||
#### Scenario: 未認證請求被拒絕
|
||||
- **WHEN** 未帶任何 token 送出 `POST /api/provider/offers`
|
||||
- **THEN** 回傳 HTTP 401
|
||||
|
||||
---
|
||||
|
||||
### Requirement: Provider 時段管理測試覆蓋
|
||||
測試套件 SHALL 驗證 `POST /api/provider/schedules`、`PUT /api/provider/schedules/{id}`、`DELETE /api/provider/schedules/{id}` 的正常流程、所有權邊界與容量驗證。
|
||||
|
||||
#### Scenario: Provider 建立時段成功
|
||||
- **WHEN** Provider 送出有效的 diving_offer_id / scheduled_date（未來日期）/ start_time / max_participants 至 `POST /api/provider/schedules`
|
||||
- **THEN** 回傳 HTTP 201，body 包含 `{ status: true, data: { id, scheduled_date, status: "open" } }`
|
||||
|
||||
#### Scenario: Provider 不可為他人課程建立時段
|
||||
- **WHEN** Provider A 送出 Provider B 課程的 diving_offer_id 至 `POST /api/provider/schedules`
|
||||
- **THEN** 回傳 HTTP 403
|
||||
|
||||
#### Scenario: 時段日期不可為過去
|
||||
- **WHEN** Provider 送出 scheduled_date 為過去日期
|
||||
- **THEN** 回傳 HTTP 422
|
||||
|
||||
#### Scenario: Provider 更新時段人數上限
|
||||
- **WHEN** Provider 送出新的 max_participants 至 `PUT /api/provider/schedules/{id}`（新值 ≥ 目前 current_participants）
|
||||
- **THEN** 回傳 HTTP 200，DB 記錄已更新
|
||||
|
||||
#### Scenario: 人數上限不可低於已確認人數
|
||||
- **WHEN** Provider 嘗試將 max_participants 設為低於時段 current_participants 的值
|
||||
- **THEN** 回傳 HTTP 422，message 說明不可低於已確認人數
|
||||
|
||||
#### Scenario: Provider 不可更新他人時段
|
||||
- **WHEN** Provider A 嘗試 `PUT /api/provider/schedules/{id}`，但該時段屬於 Provider B
|
||||
- **THEN** 回傳 HTTP 403
|
||||
|
||||
#### Scenario: 刪除（取消）時段同時將進行中預約標記為 provider_cancelled
|
||||
- **WHEN** Provider 對有 pending/confirmed 預約的時段送出 `DELETE /api/provider/schedules/{id}`
|
||||
- **THEN** 回傳 HTTP 200；時段 status 改為 `cancelled`（記錄保留，不刪除）；該時段的 pending/confirmed booking status 改為 `provider_cancelled`（記錄保留，不刪除）；已是終態的 booking（completed/expired/已取消）不受影響
|
||||
|
||||
---
|
||||
|
||||
### Requirement: Admin 使用者管理測試覆蓋
|
||||
測試套件 SHALL 驗證 Admin 查詢會員/教練列表、切換帳號啟用狀態、切換教練驗證狀態的正確行為。
|
||||
|
||||
#### Scenario: Admin 取得會員列表
|
||||
- **WHEN** Admin 送出 `GET /api/admin/members`
|
||||
- **THEN** 回傳 HTTP 200，data 陣列只包含 role=member 的使用者，含 meta 分頁資訊
|
||||
|
||||
#### Scenario: Admin 取得教練列表
|
||||
- **WHEN** Admin 送出 `GET /api/admin/providers`
|
||||
- **THEN** 回傳 HTTP 200，data 陣列只包含 role=provider 的使用者
|
||||
|
||||
#### Scenario: Admin 切換會員帳號啟用狀態
|
||||
- **WHEN** Admin 送出 `POST /api/admin/members/{id}/toggle-active`（目標會員 is_active=true）
|
||||
- **THEN** 回傳 HTTP 200，DB 記錄 is_active 由 true 變為 false
|
||||
|
||||
#### Scenario: Admin 切換教練驗證狀態並清除快取
|
||||
- **WHEN** Admin 送出 `POST /api/admin/providers/{id}/toggle-verified`（目標教練 is_verified=false）
|
||||
- **THEN** 回傳 HTTP 200，provider_profiles.is_verified 由 false 變為 true，diving_offers 快取被清除（後續公開列表可見該教練課程）
|
||||
|
||||
#### Scenario: 非 Admin 角色被拒絕
|
||||
- **WHEN** role=member 的使用者送出 `GET /api/admin/members`
|
||||
- **THEN** 回傳 HTTP 403
|
||||
|
||||
---
|
||||
|
||||
### Requirement: 通知直接觸發路徑測試覆蓋
|
||||
測試套件 SHALL 驗證預約 controller 操作直接觸發的通知事件，補足 Scheduler 路徑以外的覆蓋缺口。收件者依實際 controller 實作：新預約與 member 取消通知教練，其餘通知學員。
|
||||
|
||||
#### Scenario: 建立預約觸發 BookingCreatedNotification 至教練
|
||||
- **WHEN** Member 成功建立預約（`POST /api/member/bookings`）
|
||||
- **THEN** `BookingCreatedNotification` 被派發至該預約所屬的 **Provider**（`MemberBookingController::store` 呼叫 `$provider->notify(...)`）
|
||||
|
||||
#### Scenario: Provider 確認預約觸發 BookingConfirmedNotification 至學員
|
||||
- **WHEN** Provider 對 pending 預約呼叫 `PUT /api/provider/bookings/{id}/confirm`
|
||||
- **THEN** `BookingConfirmedNotification` 被派發至該預約的 **Member**
|
||||
|
||||
#### Scenario: Provider 拒絕預約觸發 BookingRejectedNotification 至學員
|
||||
- **WHEN** Provider 對 pending 預約呼叫 `PUT /api/provider/bookings/{id}/reject`
|
||||
- **THEN** `BookingRejectedNotification` 被派發至該預約的 **Member**
|
||||
|
||||
#### Scenario: Member 取消預約觸發 BookingCancelledNotification 至教練
|
||||
- **WHEN** Member 對 pending 預約呼叫 `DELETE /api/member/bookings/{id}`
|
||||
- **THEN** `BookingCancelledNotification` 被派發至該預約所屬的 **Provider**（`cancelledBy: 'member'`）
|
||||
|
||||
#### Scenario: Provider 取消預約觸發 BookingCancelledNotification 至學員
|
||||
- **WHEN** Provider 對 confirmed 預約呼叫 `PUT /api/provider/bookings/{id}/cancel`
|
||||
- **THEN** `BookingCancelledNotification` 被派發至該預約的 **Member**（`cancelledBy: 'provider'`）
|
||||
|
||||
---
|
||||
|
||||
### Requirement: 預約列表端點測試覆蓋
|
||||
測試套件 SHALL 驗證下列三個已存在路由的資料隔離行為：
|
||||
- `GET /api/member/bookings`（middleware: `auth:sanctum`，資料隔離在 controller `where member_id = auth()->id()`）
|
||||
- `GET /api/provider/bookings`（middleware: `auth:sanctum`，資料隔離在 controller `whereHas schedule.provider_id`）
|
||||
- `GET /api/admin/bookings`（middleware: `auth:sanctum` + `admin`，EnsureAdmin 於 middleware 層強制 403）
|
||||
|
||||
#### Scenario: Member 只能看到自己的預約
|
||||
- **WHEN** Member A 呼叫 `GET /api/member/bookings`，系統中同時存在 Member A 與 Member B 各一筆預約
|
||||
- **THEN** 回傳 data 陣列長度為 1，且 id 為 Member A 的 booking id；Member B 的 booking id 不在 data 中
|
||||
|
||||
#### Scenario: Provider 只能看到屬於自己課程的預約
|
||||
- **WHEN** Provider A 呼叫 `GET /api/provider/bookings`，系統中有屬於 Provider A 課程與 Provider B 課程各一筆預約
|
||||
- **THEN** 回傳 data 中只包含 Provider A 課程的 booking id；Provider B 課程的 booking id 不在 data 中
|
||||
|
||||
#### Scenario: Admin 可查看所有預約
|
||||
- **WHEN** Admin 呼叫 `GET /api/admin/bookings`，系統中有 2 筆不同 Member 的預約
|
||||
- **THEN** 回傳 data count ≥ 2，兩筆 booking id 均在 data 中
|
||||
|
||||
#### Scenario: 未認證請求被拒絕
|
||||
- **WHEN** 未帶 token 呼叫 `GET /api/member/bookings`
|
||||
- **THEN** 回傳 HTTP 401
|
||||
@@ -0,0 +1,83 @@
|
||||
## 0. 前置確認（實作前一次性）
|
||||
|
||||
- [x] 0.1 確認 `phpunit.xml` 的 `CACHE_STORE=array`（Laravel 11 array store 支援 tags，若非 array/redis 須先修正再實作）
|
||||
- [x] 0.2 確認現有認證模式：所有新測試使用 `$this->actingAs($user)` + `postJson/putJson`，不手動建立 Sanctum token
|
||||
- [x] 0.3 確認 factory 狀況：`DivingOffer`、`CourseSchedule`、`Booking` 均無 factory，一律使用 `Model::create([...])` 直接建立，不新增 factory
|
||||
|
||||
## 1. Provider 課程 CRUD 測試
|
||||
|
||||
- [x] 1.1 [整合測試] 建立 `tests/Feature/ProviderOfferCrudTest.php`，加入 private helpers：
|
||||
- `makeProvider(): User`（User::create + ProviderProfile::create，is_verified=true）
|
||||
- `makeOffer(User $provider): DivingOffer`（DivingOffer::create 最小必填欄位）
|
||||
- [x] 1.2 [整合測試] `test_provider_creates_offer_successfully`：POST 201，data.provider_id = auth provider id，DB 存在
|
||||
- [x] 1.3 [整合測試] `test_create_offer_missing_required_field_returns_422`：缺 title 送出，回傳 422（代表性一個欄位即可）
|
||||
- [x] 1.4 [整合測試] `test_provider_updates_own_offer`：PUT 200，DB 欄位已變更
|
||||
- [x] 1.5 [整合測試] `test_provider_cannot_update_others_offer`：Provider B 更新 Provider A 的課程，403
|
||||
- [x] 1.6 [整合測試] `test_provider_deletes_own_offer`：DELETE 200，DB 記錄不存在
|
||||
- [x] 1.7 [整合測試] `test_provider_cannot_delete_others_offer`：403
|
||||
- [x] 1.8 [整合測試] `test_unauthenticated_request_is_rejected`：無 token POST，401
|
||||
|
||||
## 2. Provider 時段管理測試
|
||||
|
||||
- [x] 2.1 [整合測試] 建立 `tests/Feature/ProviderScheduleCrudTest.php`，加入 private helpers：
|
||||
- `makeProvider(): User`
|
||||
- `makeOffer(User $provider): DivingOffer`
|
||||
- `makeSchedule(DivingOffer $offer, int $currentParticipants = 0): CourseSchedule`
|
||||
- [x] 2.2 [整合測試] `test_provider_creates_schedule_successfully`：POST 201，status=open
|
||||
- [x] 2.3 [整合測試] `test_provider_cannot_create_schedule_for_others_offer`：403
|
||||
- [x] 2.4 [整合測試] `test_past_date_returns_422`：scheduled_date = yesterday，422（代表性驗證案例）
|
||||
- [x] 2.5 [整合測試] `test_provider_updates_schedule_max_participants`：PUT 200，DB 更新
|
||||
- [x] 2.6 [整合測試] `test_max_participants_below_current_returns_422`：current_participants=3，PUT max_participants=2，422
|
||||
- [x] 2.7 [整合測試] `test_provider_cannot_update_others_schedule`：403
|
||||
- [x] 2.8 [整合測試] `test_delete_schedule_marks_active_bookings_as_provider_cancelled`：建立一筆 pending + 一筆 confirmed booking，DELETE 200；斷言時段 status=`cancelled`（記錄保留）；兩筆 booking status=`provider_cancelled`（記錄保留，不刪除）；不在 pending/confirmed 的 booking 不受影響
|
||||
|
||||
## 3. Admin 使用者管理測試
|
||||
|
||||
- [x] 3.1 [整合測試] 建立 `tests/Feature/AdminUserManagementTest.php`，加入 private helpers：
|
||||
- `makeAdmin(): User`（role=admin）
|
||||
- `makeMember(): User`（role=member + MemberProfile）
|
||||
- `makeProvider(bool $isVerified = false): User`（role=provider + ProviderProfile）
|
||||
- [x] 3.2 [整合測試] `test_admin_lists_members_only`：建立 member + provider 各一，GET /api/admin/members 回傳 data 只含 member role
|
||||
- [x] 3.3 [整合測試] `test_admin_lists_providers_only`：GET /api/admin/providers 回傳 data 只含 provider role
|
||||
- [x] 3.4 [整合測試] `test_admin_toggles_member_active_status`：目標 is_active=true → POST toggle-active → DB is_active=false
|
||||
- [x] 3.5 [整合測試] `test_admin_toggles_provider_verified_status`：目標 is_verified=false → POST toggle-verified → DB is_verified=true（不重複 DivingOfferVisibilityTest 的快取副作用驗證，只斷言 DB 欄位與 HTTP 200）
|
||||
- [x] 3.6 [整合測試] `test_non_admin_is_forbidden`：role=member actingAs，GET /api/admin/members 回傳 403
|
||||
|
||||
## 4. 通知直接觸發路徑測試
|
||||
|
||||
收件者依實際 controller 實作（已查閱原始碼 + app/Notifications/ 確認 class 存在）：
|
||||
- `BookingCreatedNotification`：`MemberBookingController::store` → `$provider->notify(new BookingCreatedNotification($booking))` → **教練**收到
|
||||
- `BookingConfirmedNotification`：`ProviderBookingController::confirm` → `$booking->member->notify(...)` → **學員**收到
|
||||
- `BookingRejectedNotification`：`ProviderBookingController::reject` → `$booking->member->notify(...)` → **學員**收到
|
||||
- `BookingCancelledNotification`（cancelledBy: 'member'）：`MemberBookingController::destroy` → `$provider->notify(...)` → **教練**收到
|
||||
- `BookingCancelledNotification`（cancelledBy: 'provider'）：`ProviderBookingController::cancel` → `$booking->member->notify(...)` → **學員**收到
|
||||
- 注意：member/provider cancel 使用**同一個 class** `BookingCancelledNotification`，`assertSentTo` 只需確認 class 名稱與收件者即可
|
||||
|
||||
- [x] 4.1 [整合測試] 建立 `tests/Feature/NotificationTriggerTest.php`，setUp 加 `Notification::fake()`；加入 helper 建立 member + provider（含 ProviderProfile） + offer + schedule（open, 未來日期） + pending booking
|
||||
- [x] 4.2 [整合測試] `test_booking_created_notifies_provider`：Member `POST /api/member/bookings` → `assertSentTo($provider, BookingCreatedNotification::class)`
|
||||
- [x] 4.3 [整合測試] `test_booking_confirmed_notifies_member`：Provider `PUT /api/provider/bookings/{id}/confirm` → `assertSentTo($member, BookingConfirmedNotification::class)`
|
||||
- [x] 4.4 [整合測試] `test_booking_rejected_notifies_member`：Provider `PUT /api/provider/bookings/{id}/reject` → `assertSentTo($member, BookingRejectedNotification::class)`
|
||||
- [x] 4.5 [整合測試] `test_member_cancel_notifies_provider`：Member `DELETE /api/member/bookings/{id}`（pending, 遠未來日期） → `assertSentTo($provider, BookingCancelledNotification::class)`
|
||||
- [x] 4.6 [整合測試] `test_provider_cancel_notifies_member`：Provider `PUT /api/provider/bookings/{id}/cancel`（先 confirm 再 cancel） → `assertSentTo($member, BookingCancelledNotification::class)`
|
||||
|
||||
## 5. 預約列表端點測試
|
||||
|
||||
路由對應（已查閱 routes/api.php + EnsureAdmin middleware 確認）：
|
||||
- `GET /api/member/bookings` → middleware: `auth:sanctum`（無 role 檢查）→ `MemberBookingController::index`，隔離靠 `where member_id = auth()->id()`
|
||||
- `GET /api/provider/bookings` → middleware: `auth:sanctum`（無 role 檢查）→ `ProviderBookingController::index`，隔離靠 `whereHas schedule.provider_id`
|
||||
- `GET /api/admin/bookings` → middleware: `auth:sanctum` + `admin`（`EnsureAdmin` 強制 403）→ `AdminBookingController::index`
|
||||
|
||||
- [x] 5.1 [整合測試] 建立 `tests/Feature/BookingListTest.php`，加入 helpers：
|
||||
- `makeProviderWithSchedule(): array`（回傳 [provider, schedule]，含 ProviderProfile + DivingOffer + CourseSchedule）
|
||||
- `makePendingBooking(User $member, CourseSchedule $schedule): Booking`
|
||||
- [x] 5.2 [整合測試] `test_member_sees_only_own_bookings`：MemberA 和 MemberB 各建一筆 pending booking（同一 schedule），actingAs MemberA → `GET /api/member/bookings`，斷言 data count=1 且 data[0].id = MemberA booking id
|
||||
- [x] 5.3 [整合測試] `test_provider_sees_only_own_course_bookings`：ProviderA 和 ProviderB 各有一筆 booking，actingAs ProviderA → `GET /api/provider/bookings`，斷言 data 中只含 ProviderA schedule 的 booking id
|
||||
- [x] 5.4 [整合測試] `test_admin_sees_all_bookings`：建立 2 筆不同 member 的 booking，actingAs admin → `GET /api/admin/bookings`，斷言兩個 booking id 均在 data 中
|
||||
- [x] 5.5 [整合測試] `test_unauthenticated_request_returns_401`：無 token `GET /api/member/bookings`，401
|
||||
|
||||
## 6. 驗收
|
||||
|
||||
- [x] 6.1 容器內 `php artisan test` 全綠（基準 187 passed，預估完成後 ≥ 230 passed）
|
||||
- [x] 6.2 確認 5 個新測試類別的案例方法數與 spec scenarios 對應（可多不可少）
|
||||
- [x] 6.3 確認 `phpunit.xml` 仍為 `CACHE_STORE=array`，未被意外改動
|
||||
- [x] 6.4 將本 change 的 specs 增量套用至主規格 `openspec/specs/feature-test-coverage/spec.md`
|
||||
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-06-17
|
||||
@@ -0,0 +1,151 @@
|
||||
## Context
|
||||
|
||||
P0 完成後 VPS 目前狀態：
|
||||
- Session：`SESSION_DRIVER=database`（MySQL）
|
||||
- Log：`LOG_CHANNEL=stack`、`LOG_STACK=daily`（寫檔案）
|
||||
- Scheduler：cron daemon 跑在 app container 內，entrypoint 啟動
|
||||
|
||||
三項都是雲端不友善的設定：多實例時 cron 重複執行、檔案 log 無法被雲端 aggregator 收集、DB session 擴容效率低。
|
||||
|
||||
**Bind mount 暫時保留**：`./:/var/www` 目前仍保留，移除 bind mount 屬於 P0 剩餘項目（需將 code bake 進 image），本 change 不處理。scheduler service 同樣沿用 bind mount，與 app/queue-worker 一致。
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
- Session 存 Redis，擴容時不需共享 DB session table
|
||||
- Log 走 stderr，`docker compose logs` 及雲端 aggregator 皆可收
|
||||
- Scheduler 獨立 container，水平擴容 app 時不會重複跑定時任務
|
||||
- Dockerfile 移除 cron 依賴，image 更精簡
|
||||
|
||||
**Non-Goals:**
|
||||
- 不處理 S3 檔案儲存（P0 待辦）
|
||||
- 不移除 bind mount（P0 待辦）
|
||||
- 不動任何 PHP 業務邏輯、config/ 目錄下的 PHP 設定檔
|
||||
|
||||
## Pre-flight 確認（實作前已驗證）
|
||||
|
||||
| 項目 | 結果 |
|
||||
|---|---|
|
||||
| `config/logging.php` 有 `stderr` channel | ✅ 已存在（line 97），不需改 code |
|
||||
| `config/session.php` 的 `driver` 讀 `.env` | ✅ `env('SESSION_DRIVER', 'database')`（line 21） |
|
||||
| `SESSION_CONNECTION` | 預設 `null`（使用 default Redis connection），VPS Redis 已在跑，不需額外設定 |
|
||||
|
||||
## Decisions
|
||||
|
||||
### D1：Scheduler 用 `php artisan schedule:work` 而非 crontab
|
||||
|
||||
`schedule:work` 是 Laravel 10+ 內建指令，在前台以無限迴圈每分鐘執行一次 `schedule:run`，不需要 cron daemon。符合 12-factor「一個 container 跑一個 process」原則。
|
||||
|
||||
**`depends_on` 取捨**：scheduler 設 `depends_on: app: condition: service_healthy`，確保首次啟動時 PHP-FPM 就緒後 scheduler 才開始執行。注意：`depends_on` 只控制啟動順序，不控制運行時依賴——app container 重啟時 scheduler **不會**跟著重啟，會繼續跑；若 app 還沒 ready 而 scheduler 已觸發任務，任務本身可能失敗，但 scheduler 程序不會崩潰。這是可接受的，定時任務本身應有冪等與錯誤處理。
|
||||
|
||||
```yaml
|
||||
scheduler:
|
||||
image: cfdive-platform
|
||||
container_name: cfdive-scheduler
|
||||
restart: unless-stopped
|
||||
working_dir: /var/www/
|
||||
command: php artisan schedule:work
|
||||
volumes:
|
||||
- ./:/var/www
|
||||
environment:
|
||||
- DB_CONNECTION=mysql
|
||||
- DB_HOST=db
|
||||
- DB_PORT=3306
|
||||
- DB_DATABASE=${DB_DATABASE:-CFDivePlatform}
|
||||
- DB_USERNAME=${DB_USERNAME:-cfdiveuser}
|
||||
- DB_PASSWORD=${DB_PASSWORD}
|
||||
networks:
|
||||
- cfdive-network
|
||||
depends_on:
|
||||
app:
|
||||
condition: service_healthy
|
||||
```
|
||||
|
||||
### D2：Log 改 `LOG_CHANNEL=stderr`
|
||||
|
||||
`config/logging.php` 已內建 `stderr` channel（`php://stderr`），Docker 自動對應到 container stderr stream，`docker compose logs app` 即可看到。不需新增任何 PHP 設定。
|
||||
|
||||
`.env.example` 同步移除 `LOG_STACK` 與 `LOG_DAILY_DAYS`（改 stderr 後這兩個無作用，留著造成混淆）。
|
||||
|
||||
**Config cache 注意**：VPS `.env` 改完後需清除 config cache 才能生效：
|
||||
```bash
|
||||
docker compose exec app php artisan config:clear
|
||||
```
|
||||
或直接 `docker compose up -d --build`（entrypoint 會自動 `config:clear`）。
|
||||
|
||||
### D3：Session 改 Redis，不需建新資料表
|
||||
|
||||
Redis 已在跑（`cfdive-redis`），`config/session.php` 讀 `.env`，開箱即用。`sessions` table 保留不刪（避免 rollback 需要重建）。
|
||||
|
||||
### D4：VPS `.env` 更新方式
|
||||
|
||||
選手動 SSH 更新（不進 deploy.yml 自動化），原因：`.env` 含機敏值，CI 自動覆寫風險高；此為一次性變更。
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
- **[Risk] Session 失效**：改 driver 後所有現有 session 立即失效，用戶需重新登入。
|
||||
→ **Mitigation**：排低流量時段；VPS `.env` 改完後直接 rebuild，縮短空窗。
|
||||
|
||||
- **[Risk] Rebuild image 期間短暫停機**：Dockerfile 移除 cron 需 rebuild。
|
||||
→ **Mitigation**：`docker compose up -d --build` 滾動更新，停機窗口約 30 秒。
|
||||
|
||||
- **[Risk] Config cache 未清除**：`.env` 改了但 `bootstrap/cache/config.php` 仍是舊值，session/log 不生效。
|
||||
→ **Mitigation**：Migration Plan 步驟明確包含 `config:clear`；entrypoint 在 rebuild 後也會自動清除。
|
||||
|
||||
- **[Risk] Log 遺失歷史**：改 stderr 後 `storage/logs/` 不再更新，但舊檔保留在磁碟。
|
||||
→ **Mitigation**：Sentry 持續收錯誤；需要查歷史時直接看舊檔案。
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] `docker compose ps` 顯示 `cfdive-scheduler` 容器 Up
|
||||
- [ ] `docker compose exec app sh -c "which cron 2>/dev/null || echo 'cron binary not found'"` 輸出 `cron binary not found`（binary 已從 image 移除）
|
||||
- [ ] 呼叫任意 API 後，`docker compose logs app` 有日誌輸出（stderr log 生效）
|
||||
- [ ] `storage/logs/` 下無新增日誌檔（舊檔保留）
|
||||
- [ ] 登入後 `docker compose exec redis redis-cli keys "laravel_session*"` 有輸出（session 走 Redis）
|
||||
|
||||
## Migration Plan
|
||||
|
||||
**程式碼（PR 合併前）：**
|
||||
1. `Dockerfile`：移除 cron 安裝與 crontab 設定
|
||||
2. `docker/php/docker-entrypoint.sh`：移除 `service cron start`
|
||||
3. `docker-compose.yml`：新增 `scheduler` service
|
||||
4. `.env.example`：`SESSION_DRIVER=redis`、`LOG_CHANNEL=stderr`、移除 `LOG_STACK`/`LOG_DAILY_DAYS`
|
||||
5. `docs/STARTUP.md`：補充 scheduler、log 查看、VPS 操作說明
|
||||
|
||||
**VPS 維護窗口（PR merge + CI/CD 完成後）：**
|
||||
```bash
|
||||
# SSH 進 VPS
|
||||
cd /root/myproject/CFDivePlatform
|
||||
|
||||
# 1. 更新 .env
|
||||
sed -i 's/SESSION_DRIVER=database/SESSION_DRIVER=redis/' .env
|
||||
sed -i 's/LOG_CHANNEL=stack/LOG_CHANNEL=stderr/' .env
|
||||
sed -i '/^LOG_STACK=/d' .env
|
||||
sed -i '/^LOG_DAILY_DAYS=/d' .env
|
||||
|
||||
# 2. Rebuild + 重啟（entrypoint 自動 config:clear）
|
||||
docker compose up -d --build
|
||||
|
||||
# 3. 驗證
|
||||
docker compose ps
|
||||
docker compose logs app | tail -20
|
||||
docker compose exec redis redis-cli keys "laravel_session*"
|
||||
```
|
||||
|
||||
## Rollback Plan
|
||||
|
||||
Session/Log 還原（不需 rebuild）：
|
||||
```bash
|
||||
sed -i 's/SESSION_DRIVER=redis/SESSION_DRIVER=database/' .env
|
||||
sed -i 's/LOG_CHANNEL=stderr/LOG_CHANNEL=stack/' .env
|
||||
echo "LOG_STACK=daily" >> .env
|
||||
echo "LOG_DAILY_DAYS=14" >> .env
|
||||
docker compose exec app php artisan config:clear
|
||||
docker compose restart app
|
||||
```
|
||||
|
||||
Scheduler 還原（需 rebuild）：
|
||||
```bash
|
||||
git revert <commit-hash>
|
||||
docker compose up -d --build
|
||||
```
|
||||
@@ -0,0 +1,31 @@
|
||||
## Why
|
||||
|
||||
P0 零影響改動完成後，P1 處理三個需要維護窗口但改完後功能完全等效的雲端就緒項目：Session 存 Redis 取代 MySQL（擴容必要）、Log 走 stdout 取代檔案（雲端 logging 標準）、Scheduler 抽成獨立 container 取代 app 容器內 cron（水平擴容不重複執行）。
|
||||
|
||||
## What Changes
|
||||
|
||||
- **`.env.example`**：`SESSION_DRIVER` 預設改 `redis`；`LOG_CHANNEL` 預設改 `stderr`
|
||||
- **`Dockerfile`**：移除 `cron` 安裝、移除 scheduler cron job 寫入
|
||||
- **`docker/php/docker-entrypoint.sh`**：移除 `service cron start`
|
||||
- **`docker-compose.yml`**：新增 `scheduler` service（`php artisan schedule:work`）
|
||||
- **`docs/STARTUP.md`**：更新服務清單，說明 scheduler container 與 log 查看方式
|
||||
- **VPS `.env`**：需在維護窗口更新 `SESSION_DRIVER=redis` 與 `LOG_CHANNEL=stderr`（不進版控）
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
|
||||
- `scheduler-container`：Scheduler 以獨立 container 方式執行，不依賴 app container 內的 cron daemon
|
||||
|
||||
### Modified Capabilities
|
||||
|
||||
- `env-cloud-annotations`：補充 `SESSION_DRIVER` 與 `LOG_CHANNEL` 的正確雲端預設值（原 spec 已標注說明，現在升級為實際預設值）
|
||||
|
||||
## Impact
|
||||
|
||||
- **`Dockerfile`**：移除 cron 相關 2 行，需 rebuild image
|
||||
- **`docker/php/docker-entrypoint.sh`**：移除 1 行
|
||||
- **`docker-compose.yml`**：新增 `scheduler` service
|
||||
- **`.env.example`**：2 個預設值變動
|
||||
- **不影響**：所有 PHP 業務邏輯、API 行為、前端、資料庫 schema
|
||||
- **部署影響**：Session 失效一次（用戶登出）、需 rebuild app image
|
||||
+27
@@ -0,0 +1,27 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: QUEUE_CONNECTION 預設值為 redis
|
||||
`.env.example` 的 `QUEUE_CONNECTION` SHALL 預設為 `redis`，與 VPS 實際運作設定一致，避免新環境按範本初始化後跑在效能較差的 database queue。
|
||||
|
||||
#### Scenario: 新環境照 .env.example 初始化
|
||||
- **WHEN** 開發者或 CI 以 `.env.example` 為基礎建立 `.env`，未手動修改 `QUEUE_CONNECTION`
|
||||
- **THEN** Laravel queue driver 使用 Redis，queue worker 正常消費 Redis 佇列中的 job
|
||||
|
||||
### Requirement: .env.example 標示雲端必要變數
|
||||
`.env.example` SHALL 以行內註解或正確預設值標示以下雲端部署時必須明確設定的變數：
|
||||
- `FILESYSTEM_DISK`：雲端應設為 `s3`（預設 `local` 在容器重啟後遺失上傳檔案）
|
||||
- `LOG_CHANNEL`：預設改為 `stderr`（雲端 logging aggregator 標準；原 `stack/daily` 寫檔案不適合雲端）
|
||||
- `QUEUE_CONNECTION`：預設為 `redis`
|
||||
- `SESSION_DRIVER`：預設改為 `redis`（取代 `database`，擴容更高效）
|
||||
|
||||
#### Scenario: 新環境照 .env.example 初始化 session driver
|
||||
- **WHEN** 開發者以 `.env.example` 為基礎建立 `.env`，未手動修改 `SESSION_DRIVER`
|
||||
- **THEN** Laravel session driver 使用 Redis
|
||||
|
||||
#### Scenario: 新環境照 .env.example 初始化 log channel
|
||||
- **WHEN** 開發者以 `.env.example` 為基礎建立 `.env`，未手動修改 `LOG_CHANNEL`
|
||||
- **THEN** Laravel 日誌寫入 stderr，可透過 `docker compose logs app` 查看
|
||||
|
||||
#### Scenario: 操作者閱讀 .env.example 進行雲端部署
|
||||
- **WHEN** 操作者參照 `.env.example` 設定雲端環境的 `.env`
|
||||
- **THEN** 每個雲端關鍵變數旁有說明，提示預設值在雲端環境的限制與建議替代值
|
||||
@@ -0,0 +1,19 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Scheduler 以獨立 container 執行
|
||||
`docker-compose.yml` SHALL 定義 `scheduler` service，使用 `cfdive-platform` image，以 `php artisan schedule:work` 前台輪詢方式執行 Laravel Scheduler，取代原本在 app container 內的 cron daemon。
|
||||
|
||||
#### Scenario: Scheduler container 隨 app 啟動
|
||||
- **WHEN** 執行 `docker compose up -d` 且 `app` container 已 healthy
|
||||
- **THEN** `scheduler` container 啟動並持續執行 `php artisan schedule:work`
|
||||
|
||||
#### Scenario: App container 重啟時 scheduler 等待就緒
|
||||
- **WHEN** `app` container 重啟中（unhealthy）
|
||||
- **THEN** `scheduler` container 依 `depends_on` 等待 `app` healthy 後才啟動，避免 scheduler 在 PHP-FPM 未就緒時執行任務
|
||||
|
||||
### Requirement: App container 不再包含 cron daemon
|
||||
`Dockerfile` SHALL 不安裝 `cron` 套件，`docker-entrypoint.sh` SHALL 不執行 `service cron start`，確保 app container 職責單一（只跑 PHP-FPM）。
|
||||
|
||||
#### Scenario: App container 啟動不啟動 cron
|
||||
- **WHEN** `app` container 啟動並執行 entrypoint
|
||||
- **THEN** 不存在 cron daemon 程序，`pgrep cron` 回傳 exit code 1
|
||||
@@ -0,0 +1,45 @@
|
||||
## 1. Dockerfile 移除 cron
|
||||
|
||||
- [x] 1.1 [後端] 從 `Dockerfile` 的 `apt-get install -y` 清單移除 `cron`
|
||||
- [x] 1.2 [後端] 從 `Dockerfile` 移除寫入 `/etc/cron.d/laravel-scheduler` 的 `RUN echo ...` 指令
|
||||
- [x] 1.3 [後端] 從 `Dockerfile` 移除 `crontab /etc/cron.d/laravel-scheduler` 指令
|
||||
|
||||
## 2. docker-entrypoint.sh 移除 cron 啟動
|
||||
|
||||
- [x] 2.1 [後端] 從 `docker/php/docker-entrypoint.sh` 移除 `service cron start || cron || true` 這一行
|
||||
|
||||
## 3. docker-compose.yml 新增 scheduler service
|
||||
|
||||
- [x] 3.1 [後端] 在 `docker-compose.yml` 新增 `scheduler` service，設定如下：
|
||||
- `image: cfdive-platform`、`container_name: cfdive-scheduler`、`restart: unless-stopped`
|
||||
- `working_dir: /var/www/`、`command: php artisan schedule:work`
|
||||
- `volumes: - ./:/var/www`
|
||||
- 環境變數：`DB_CONNECTION`、`DB_HOST=db`、`DB_PORT`、`DB_DATABASE`、`DB_USERNAME`、`DB_PASSWORD`（與 queue-worker 相同）
|
||||
- `networks: - cfdive-network`
|
||||
- `depends_on: app: condition: service_healthy`
|
||||
|
||||
## 4. .env.example 更新
|
||||
|
||||
- [x] 4.1 [後端] 將 `.env.example` 的 `SESSION_DRIVER=database # 雲端建議改為 redis` 改為 `SESSION_DRIVER=redis`（升級為預設值，移除說明）
|
||||
- [x] 4.2 [後端] 將 `.env.example` 的 `LOG_CHANNEL=stack` 改為 `LOG_CHANNEL=stderr`
|
||||
- [x] 4.3 [後端] 從 `.env.example` 移除 `LOG_STACK=daily` 與 `LOG_DAILY_DAYS=14` 兩行（改 stderr 後無作用）
|
||||
|
||||
## 5. 文件更新
|
||||
|
||||
- [x] 5.1 [後端] 更新 `docs/STARTUP.md`，補充以下內容：
|
||||
- 服務清單新增 `scheduler`（`docker compose ps` 應見 `cfdive-scheduler`）
|
||||
- Log 查看方式：`docker compose logs -f app`（不再有 `storage/logs/` 檔案）
|
||||
- **VPS 維護窗口操作**：說明 `sed` 更新 `.env` 的四個指令 + `docker compose up -d --build`
|
||||
- **Config cache 注意**：`.env` 改完須清 cache（rebuild 時 entrypoint 自動處理）
|
||||
- **Rollback 步驟**：Session/Log 還原指令（不需 rebuild）+ Scheduler 還原（需 rebuild）
|
||||
|
||||
## 6. 手動驗證（本機，不需 VPS .env）
|
||||
|
||||
- [x] 6.1 [整合測試] 在本機 rebuild 後確認 `cfdive-scheduler` 正常啟動：`docker compose ps` 顯示 scheduler Up
|
||||
- [x] 6.2 [整合測試] 確認 app container 無 cron：`docker compose exec app sh -c "which cron 2>/dev/null || echo 'cron binary not found'"`（cron binary 已從 image 移除，輸出 `cron binary not found`）
|
||||
|
||||
## 7. 手動驗證（VPS，需更新 .env 後）
|
||||
|
||||
- [x] 7.1 [整合測試] 確認 log 走 stderr：呼叫任意 API 後 `docker compose logs app | tail -20` 有日誌輸出
|
||||
- [x] 7.2 [整合測試] 確認 `storage/logs/` 無新增日誌檔（舊檔保留）
|
||||
- [x] 7.3 [整合測試] 確認 session 走 Redis：登入後 `docker compose exec redis redis-cli keys "cfdiveplatform_database_*"` 有輸出（prefix 為 APP_NAME_database_，非 laravel_session*）
|
||||
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-06-17
|
||||
@@ -0,0 +1,76 @@
|
||||
## Context
|
||||
|
||||
CFDivePlatform 跑在單台 VPS 上，全部服務以 Docker Compose 管理。現有設定有三個雲端就緒問題：
|
||||
1. `app` service healthcheck 用 `php -v`，只驗證 binary 存在，無法確認 PHP-FPM 是否監聽
|
||||
2. `phpmyadmin`、`mailpit` 這兩個開發/管理工具寫死在 `docker-compose.yml`，雲端正式環境不應存在
|
||||
3. `.env.example` 的 `QUEUE_CONNECTION=database` 與 VPS 實際使用 Redis 不一致，新環境按範本初始化會跑在效能較差的 DB queue
|
||||
|
||||
本次只改 compose 設定和 `.env.example`，不觸碰任何 PHP 程式碼。
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
- healthcheck 改為確認 PHP-FPM FastCGI port 9000 正常監聽，比 `php -v` 更能反映 FPM 是否就緒
|
||||
- 透過 `compose.override.yml` 機制隔離開發工具，VPS 行為不變，雲端部署只需 `-f docker-compose.yml`
|
||||
- `.env.example` 的 queue 預設值與雲端慣例對齊，並補充雲端必要變數的說明
|
||||
|
||||
**Non-Goals:**
|
||||
- 不修改 Session driver（留待 P1 change）
|
||||
- 不修改 Log 輸出方式（留待 P1 change）
|
||||
- 不修改 Scheduler 架構（留待 P1 change）
|
||||
- 不改任何 PHP 程式碼或 image 內容
|
||||
- 不處理 S3 檔案儲存（P0 項目，需獨立 change）
|
||||
|
||||
## Decisions
|
||||
|
||||
### D1：healthcheck 用 `nc -z 127.0.0.1 9000` 檢查 PHP-FPM port
|
||||
|
||||
**為什麼不用 `/health` HTTP 端點：**
|
||||
app container 跑的是 PHP-FPM（FastCGI，port 9000），容器內**沒有 HTTP server**。
|
||||
`/health` 路由必須經過 Nginx 才能到達 PHP-FPM，而 Nginx 是另一個 container。
|
||||
所以 `curl` 或 `wget` 打 `http://127.0.0.1/health` 在 app container 內部完全打不到任何東西。
|
||||
|
||||
**為什麼不用 `wget`：**
|
||||
Dockerfile 安裝清單確認 `wget` 未安裝（僅裝 `curl`）。Nginx container 的 `wget` 是 busybox-wget（Alpine），兩者環境不同，不可混用。
|
||||
|
||||
**選定方案：**
|
||||
```yaml
|
||||
healthcheck:
|
||||
test: ["CMD-SHELL", "nc -z 127.0.0.1 9000 || exit 1"]
|
||||
```
|
||||
`netcat-openbsd` 已在 Dockerfile 安裝。`nc -z` 只做 TCP connect，確認 PHP-FPM 的 FastCGI port 正在監聽，是 app container 內部能做到最準確的 FPM 就緒判斷。
|
||||
|
||||
**能力邊界：** 此 healthcheck 確認 PHP-FPM 程序已啟動並監聽 port，但不驗證 Nginx；Nginx 有自己的獨立 healthcheck。
|
||||
|
||||
### D2：`compose.override.yml` 放在 repo 根目錄並加進版控
|
||||
|
||||
**選項 A**：放進 `.gitignore`，每台機器手動建立
|
||||
**選項 B**：放進 repo，所有環境共用
|
||||
|
||||
選 B。`compose.override.yml` 只定義開發工具（phpmyadmin、mailpit），不含任何 secret 或環境特定值，放進版控讓新成員 `git clone` 後直接可用。雲端部署 CI 指定 `-f docker-compose.yml` 排除即可。
|
||||
|
||||
### D3：`mailpit` 同步移入 override
|
||||
|
||||
`mailpit` 與 `phpmyadmin` 性質相同（開發輔助工具），一起移入 override，保持 `docker-compose.yml` 只含正式服務。
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
- **[Risk] healthcheck 只驗證 TCP 連線，不驗證請求成功**：`nc -z` 確認 port 開著，但不確認 PHP-FPM 能正確處理 FastCGI 請求。
|
||||
→ **Mitigation**：對 `depends_on` 的用途（等待 FPM 啟動再起 Nginx）已足夠；若要更深層驗證需用 `cgi-fcgi` 工具（過度工程，暫不引入）。
|
||||
|
||||
- **[Risk] VPS 若沒有 `compose.override.yml`**：移除後首次 `docker compose up` 會少 phpmyadmin/mailpit。
|
||||
→ **Mitigation**：`compose.override.yml` 已進版控，VPS 執行 `git pull` 即可取得，不需手動建立。STARTUP.md 同步更新說明此流程。
|
||||
|
||||
## Migration Plan
|
||||
|
||||
1. `docker-compose.yml`：改 healthcheck、移除 phpmyadmin service、移除 mailpit service
|
||||
2. 新增 `compose.override.yml`：加入 phpmyadmin、mailpit
|
||||
3. `.env.example`：改 QUEUE_CONNECTION 預設值、補說明
|
||||
4. `STARTUP.md`：新增「部署模式」章節，明確區分：
|
||||
- **VPS（預設）**：`docker compose up -d`，自動合併 override，含 phpmyadmin + mailpit
|
||||
- **雲端正式環境**：`docker compose -f docker-compose.yml up -d`，排除開發工具
|
||||
5. **VPS 部署**：執行 `git pull` 取得版控內的 `compose.override.yml`，不需 rebuild image，`docker compose up -d` 即可
|
||||
|
||||
## Open Questions
|
||||
|
||||
無。本次改動範圍明確，無待決事項。
|
||||
@@ -0,0 +1,27 @@
|
||||
## Why
|
||||
|
||||
現有 Docker Compose 設定存在若干與雲端部署不相容的配置（開發工具混入正式服務、healthcheck 無法真實反映 app 狀態、queue 預設值不一致），在不動任何 PHP 程式碼、不重建 image、不影響 VPS 現有運作的前提下，先修正這四個零風險項目，作為雲端就緒路線圖的第一步。
|
||||
|
||||
## What Changes
|
||||
|
||||
- **`.env.example`**：`QUEUE_CONNECTION` 預設值從 `database` 改為 `redis`；補充 `FILESYSTEM_DISK` 與 log 相關變數的說明與分組，標記哪些是雲端部署時必須設定的項目
|
||||
- **`docker-compose.yml`**：app service healthcheck 從 `php -v` 改為呼叫 `/health` 端點；移除 `phpmyadmin` service
|
||||
- **新增 `compose.override.yml`**：將 `phpmyadmin`、`mailpit` 放入 override 檔，VPS/開發環境自動載入，正式雲端部署時只用 `-f docker-compose.yml` 即可排除
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
|
||||
- `compose-cloud-baseline`：Docker Compose 雲端基準設定——healthcheck 使用真實端點、正式 compose 不含開發工具、dev-only 服務透過 override 隔離
|
||||
- `env-cloud-annotations`：`.env.example` 補充雲端部署必要環境變數的說明與正確預設值
|
||||
|
||||
### Modified Capabilities
|
||||
|
||||
（本次不修改任何既有 spec 的需求行為）
|
||||
|
||||
## Impact
|
||||
|
||||
- **`docker-compose.yml`**：healthcheck 指令、移除 phpmyadmin service
|
||||
- **新增 `compose.override.yml`**：phpmyadmin、mailpit service 定義搬移至此
|
||||
- **`.env.example`**：QUEUE_CONNECTION 預設值、新增說明行
|
||||
- **不影響**：所有 PHP 程式碼、VPS `.env`、image 內容、Scheduler、Session、Log
|
||||
+32
@@ -0,0 +1,32 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: App service healthcheck 驗證 PHP-FPM FastCGI port
|
||||
`docker-compose.yml` 的 `app` service healthcheck SHALL 使用 `nc -z 127.0.0.1 9000` 確認 PHP-FPM FastCGI port 正在監聽，而非執行 `php -v`（只驗證 binary 存在）。
|
||||
|
||||
注意：app container 內無 HTTP server，無法透過 HTTP 打 `/health`；`netcat-openbsd` 已在 Dockerfile 安裝。
|
||||
|
||||
#### Scenario: PHP-FPM 啟動後 healthcheck 通過
|
||||
- **WHEN** `app` container 啟動且 PHP-FPM 程序已監聽 port 9000
|
||||
- **THEN** `nc -z 127.0.0.1 9000` 回傳 exit code 0，container 標記為 healthy
|
||||
|
||||
#### Scenario: PHP-FPM 未啟動時 healthcheck 失敗
|
||||
- **WHEN** `app` container 啟動但 PHP-FPM 程序尚未就緒（port 9000 未開）
|
||||
- **THEN** `nc -z 127.0.0.1 9000` 回傳非 0 exit code，container 維持 unhealthy 狀態直到重試成功
|
||||
|
||||
### Requirement: 正式 compose 不含開發工具服務
|
||||
`docker-compose.yml` SHALL 不包含 `phpmyadmin` 及 `mailpit` service 定義。這兩個服務屬開發/管理工具，不得出現在正式雲端部署的 compose 設定中。
|
||||
|
||||
#### Scenario: 只使用 docker-compose.yml 啟動
|
||||
- **WHEN** 執行 `docker compose -f docker-compose.yml up -d`
|
||||
- **THEN** 啟動的服務不包含 `phpmyadmin`（port 8081）及 `mailpit`（port 8025）
|
||||
|
||||
### Requirement: 開發工具服務透過 compose.override.yml 提供
|
||||
`compose.override.yml` SHALL 定義 `phpmyadmin` 與 `mailpit` service，供本機開發與 VPS 管理使用。
|
||||
|
||||
#### Scenario: 有 override 檔時開發工具正常啟動
|
||||
- **WHEN** 專案根目錄存在 `compose.override.yml` 且執行 `docker compose up -d`（不指定 -f）
|
||||
- **THEN** Docker Compose 自動合併 override，`phpmyadmin`（port 8081）與 `mailpit`（port 8025）一同啟動
|
||||
|
||||
#### Scenario: 雲端部署排除開發工具
|
||||
- **WHEN** CI/CD 執行 `docker compose -f docker-compose.yml up -d`（明確指定單一檔案）
|
||||
- **THEN** `phpmyadmin` 與 `mailpit` 不啟動，不佔用任何 port 或資源
|
||||
+19
@@ -0,0 +1,19 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: QUEUE_CONNECTION 預設值為 redis
|
||||
`.env.example` 的 `QUEUE_CONNECTION` SHALL 預設為 `redis`，與 VPS 實際運作設定一致，避免新環境按範本初始化後跑在效能較差的 database queue。
|
||||
|
||||
#### Scenario: 新環境照 .env.example 初始化
|
||||
- **WHEN** 開發者或 CI 以 `.env.example` 為基礎建立 `.env`，未手動修改 `QUEUE_CONNECTION`
|
||||
- **THEN** Laravel queue driver 使用 Redis，queue worker 正常消費 Redis 佇列中的 job
|
||||
|
||||
### Requirement: .env.example 標示雲端必要變數
|
||||
`.env.example` SHALL 以行內註解或分組說明標示以下雲端部署時必須明確設定的變數，協助操作者識別必填項目：
|
||||
- `FILESYSTEM_DISK`：雲端應設為 `s3`（目前預設 `local`，雲端會導致檔案在容器重啟後遺失）
|
||||
- `LOG_CHANNEL` / `LOG_STACK`：雲端建議改為 `stderr` 以接入雲端 logging aggregator
|
||||
- `QUEUE_CONNECTION`：應為 `redis`
|
||||
- `SESSION_DRIVER`：雲端建議改為 `redis`
|
||||
|
||||
#### Scenario: 操作者閱讀 .env.example 進行雲端部署
|
||||
- **WHEN** 操作者參照 `.env.example` 設定雲端環境的 `.env`
|
||||
- **THEN** 每個雲端關鍵變數旁有說明，提示預設值在雲端環境的限制與建議替代值
|
||||
@@ -0,0 +1,31 @@
|
||||
## 1. docker-compose.yml 調整
|
||||
|
||||
- [x] 1.1 [後端] 修改 `docker-compose.yml` app service healthcheck：將 `test: ["CMD", "php", "-v"]` 改為 `test: ["CMD-SHELL", "nc -z 127.0.0.1 9000 || exit 1"]`（app container 無 HTTP server，用 nc 驗證 PHP-FPM FastCGI port 9000）
|
||||
- [x] 1.2 [後端] 從 `docker-compose.yml` 移除 `phpmyadmin` service 完整定義（包含 image、container_name、environment、networks、depends_on）
|
||||
- [x] 1.3 [後端] 從 `docker-compose.yml` 移除 `mailpit` service 完整定義
|
||||
|
||||
## 2. 新增 compose.override.yml
|
||||
|
||||
- [x] 2.1 [後端] 在專案根目錄新建 `compose.override.yml`，加入 `phpmyadmin` service（保留原有的 PMA_HOST、PMA_PORT、PMA_USER、PMA_PASSWORD、MYSQL_ROOT_PASSWORD 環境變數設定與 networks、depends_on）
|
||||
- [x] 2.2 [後端] 在 `compose.override.yml` 加入 `mailpit` service（保留原有設定與 networks）
|
||||
|
||||
## 3. .env.example 更新
|
||||
|
||||
- [x] 3.1 [後端] 將 `.env.example` 的 `QUEUE_CONNECTION` 值從 `database` 改為 `redis`
|
||||
- [x] 3.2 [後端] 在 `.env.example` 的 `FILESYSTEM_DISK=local` 旁加上行內說明，標示雲端應改為 `s3`
|
||||
- [x] 3.3 [後端] 在 `.env.example` 的 `LOG_CHANNEL` / `LOG_STACK` 區段加上說明，標示雲端建議改為 `stderr`
|
||||
- [x] 3.4 [後端] 在 `.env.example` 的 `SESSION_DRIVER=database` 旁加上說明，標示雲端建議改為 `redis`
|
||||
- [x] 3.5 [後端] 在 `.env.example` 的 `QUEUE_CONNECTION=redis` 旁加上說明，確認此為雲端建議值
|
||||
|
||||
## 4. 文件更新
|
||||
|
||||
- [x] 4.1 [後端] 更新 `docs/STARTUP.md`，新增「部署模式」章節，明確列出兩組指令：
|
||||
- **本機 / VPS**：`docker compose up -d`（自動合併 override，含 phpmyadmin + mailpit）
|
||||
- **雲端正式環境**：`docker compose -f docker-compose.yml up -d`（排除開發工具）
|
||||
- 說明 `compose.override.yml` 已進版控，VPS `git pull` 後即可取得，不需手動建立
|
||||
|
||||
## 5. 手動驗證
|
||||
|
||||
- [x] 5.1 [整合測試] 在本機執行 `docker compose up -d`，確認 phpmyadmin（8081）與 mailpit（8025）仍可正常存取
|
||||
- [x] 5.2 [整合測試] 執行 `docker compose -f docker-compose.yml up -d --remove-orphans`，確認 phpmyadmin 與 mailpit 不啟動
|
||||
- [x] 5.3 [整合測試] 確認 `app` container 的 healthcheck 狀態在啟動後顯示 healthy（`docker compose ps` 查看）
|
||||
@@ -0,0 +1,36 @@
|
||||
# compose-cloud-baseline
|
||||
|
||||
Docker Compose 雲端基準設定——healthcheck 使用真實端點、正式 compose 不含開發工具、dev-only 服務透過 override 隔離。
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: App service healthcheck 驗證 PHP-FPM FastCGI port
|
||||
`docker-compose.yml` 的 `app` service healthcheck SHALL 使用 `nc -z 127.0.0.1 9000` 確認 PHP-FPM FastCGI port 正在監聽，而非執行 `php -v`（只驗證 binary 存在）。
|
||||
|
||||
注意：app container 內無 HTTP server，無法透過 HTTP 打 `/health`；`netcat-openbsd` 已在 Dockerfile 安裝。
|
||||
|
||||
#### Scenario: PHP-FPM 啟動後 healthcheck 通過
|
||||
- **WHEN** `app` container 啟動且 PHP-FPM 程序已監聽 port 9000
|
||||
- **THEN** `nc -z 127.0.0.1 9000` 回傳 exit code 0，container 標記為 healthy
|
||||
|
||||
#### Scenario: PHP-FPM 未啟動時 healthcheck 失敗
|
||||
- **WHEN** `app` container 啟動但 PHP-FPM 程序尚未就緒（port 9000 未開）
|
||||
- **THEN** `nc -z 127.0.0.1 9000` 回傳非 0 exit code，container 維持 unhealthy 狀態直到重試成功
|
||||
|
||||
### Requirement: 正式 compose 不含開發工具服務
|
||||
`docker-compose.yml` SHALL 不包含 `phpmyadmin` 及 `mailpit` service 定義。這兩個服務屬開發/管理工具，不得出現在正式雲端部署的 compose 設定中。
|
||||
|
||||
#### Scenario: 只使用 docker-compose.yml 啟動
|
||||
- **WHEN** 執行 `docker compose -f docker-compose.yml up -d`
|
||||
- **THEN** 啟動的服務不包含 `phpmyadmin`（port 8081）及 `mailpit`（port 8025）
|
||||
|
||||
### Requirement: 開發工具服務透過 compose.override.yml 提供
|
||||
`compose.override.yml` SHALL 定義 `phpmyadmin`（port 8081）與 `mailpit`（port 8025）service，供本機開發與 VPS 管理使用。
|
||||
|
||||
#### Scenario: 有 override 檔時開發工具正常啟動
|
||||
- **WHEN** 專案根目錄存在 `compose.override.yml` 且執行 `docker compose up -d`（不指定 -f）
|
||||
- **THEN** Docker Compose 自動合併 override，`phpmyadmin`（port 8081）與 `mailpit`（port 8025）一同啟動
|
||||
|
||||
#### Scenario: 雲端部署排除開發工具
|
||||
- **WHEN** CI/CD 執行 `docker compose -f docker-compose.yml up -d --remove-orphans`
|
||||
- **THEN** `phpmyadmin` 與 `mailpit` 不啟動，不佔用任何 port 或資源
|
||||
@@ -0,0 +1,31 @@
|
||||
# env-cloud-annotations
|
||||
|
||||
`.env.example` 補充雲端部署必要環境變數的說明與正確預設值。
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: QUEUE_CONNECTION 預設值為 redis
|
||||
`.env.example` 的 `QUEUE_CONNECTION` SHALL 預設為 `redis`，與 VPS 實際運作設定一致，避免新環境按範本初始化後跑在效能較差的 database queue。
|
||||
|
||||
#### Scenario: 新環境照 .env.example 初始化
|
||||
- **WHEN** 開發者或 CI 以 `.env.example` 為基礎建立 `.env`，未手動修改 `QUEUE_CONNECTION`
|
||||
- **THEN** Laravel queue driver 使用 Redis，queue worker 正常消費 Redis 佇列中的 job
|
||||
|
||||
### Requirement: .env.example 標示雲端必要變數
|
||||
`.env.example` SHALL 以行內註解或正確預設值標示以下雲端部署時必須明確設定的變數：
|
||||
- `FILESYSTEM_DISK`：雲端應設為 `s3`（預設 `local` 在容器重啟後遺失上傳檔案）
|
||||
- `LOG_CHANNEL`：預設改為 `stderr`（雲端 logging aggregator 標準；原 `stack/daily` 寫檔案不適合雲端）
|
||||
- `QUEUE_CONNECTION`：預設為 `redis`
|
||||
- `SESSION_DRIVER`：預設改為 `redis`（取代 `database`，擴容更高效）
|
||||
|
||||
#### Scenario: 新環境照 .env.example 初始化 session driver
|
||||
- **WHEN** 開發者以 `.env.example` 為基礎建立 `.env`，未手動修改 `SESSION_DRIVER`
|
||||
- **THEN** Laravel session driver 使用 Redis
|
||||
|
||||
#### Scenario: 新環境照 .env.example 初始化 log channel
|
||||
- **WHEN** 開發者以 `.env.example` 為基礎建立 `.env`，未手動修改 `LOG_CHANNEL`
|
||||
- **THEN** Laravel 日誌寫入 stderr，可透過 `docker compose logs app` 查看
|
||||
|
||||
#### Scenario: 操作者閱讀 .env.example 進行雲端部署
|
||||
- **WHEN** 操作者參照 `.env.example` 設定雲端環境的 `.env`
|
||||
- **THEN** 每個雲端關鍵變數旁有說明，提示預設值在雲端環境的限制與建議替代值
|
||||
@@ -0,0 +1,147 @@
|
||||
# feature-test-coverage Specification
|
||||
|
||||
## Purpose
|
||||
定義核心業務流程端點的測試覆蓋契約：Provider 課程 CRUD、時段管理、Admin 使用者操作、通知直接觸發路徑、預約列表端點。補齊 2026-06-11 稽核報告識別的 Feature test 缺口，確保這些端點的回歸能被測試套件即時攔截。
|
||||
|
||||
---
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: Provider 課程 CRUD 測試覆蓋
|
||||
測試套件 SHALL 驗證 `POST /api/provider/offers`、`PUT /api/provider/offers/{id}`、`DELETE /api/provider/offers/{id}` 的正常流程與所有權邊界。
|
||||
|
||||
#### Scenario: Provider 建立課程成功
|
||||
- **WHEN** 已認證的 Provider 送出有效的 title / location / price / region 至 `POST /api/provider/offers`
|
||||
- **THEN** 回傳 HTTP 201，body 包含 `{ status: true, data: { id, title, provider_id } }`，DB 存在對應記錄且 `provider_id` 為當前 Provider
|
||||
|
||||
#### Scenario: 建立課程缺少必填欄位回傳 422
|
||||
- **WHEN** Provider 送出缺少 `title` 的請求至 `POST /api/provider/offers`
|
||||
- **THEN** 回傳 HTTP 422，body 包含對應欄位的驗證錯誤
|
||||
|
||||
#### Scenario: Provider 更新自己的課程
|
||||
- **WHEN** 已認證的 Provider 送出有效更新欄位至 `PUT /api/provider/offers/{id}`（該課程屬於此 Provider）
|
||||
- **THEN** 回傳 HTTP 200，body 包含更新後的課程資料，DB 記錄已變更
|
||||
|
||||
#### Scenario: Provider 不可更新他人課程
|
||||
- **WHEN** Provider A 嘗試 `PUT /api/provider/offers/{id}`，但該課程屬於 Provider B
|
||||
- **THEN** 回傳 HTTP 403，body 包含 `{ status: false }`
|
||||
|
||||
#### Scenario: Provider 刪除自己的課程
|
||||
- **WHEN** 已認證的 Provider 送出 `DELETE /api/provider/offers/{id}`（該課程屬於此 Provider）
|
||||
- **THEN** 回傳 HTTP 200，body 包含 `{ status: true }`，DB 記錄已不存在
|
||||
|
||||
#### Scenario: Provider 不可刪除他人課程
|
||||
- **WHEN** Provider A 嘗試 `DELETE /api/provider/offers/{id}`，但該課程屬於 Provider B
|
||||
- **THEN** 回傳 HTTP 403
|
||||
|
||||
#### Scenario: 未認證請求被拒絕
|
||||
- **WHEN** 未帶任何 token 送出 `POST /api/provider/offers`
|
||||
- **THEN** 回傳 HTTP 401
|
||||
|
||||
---
|
||||
|
||||
### Requirement: Provider 時段管理測試覆蓋
|
||||
測試套件 SHALL 驗證 `POST /api/provider/schedules`、`PUT /api/provider/schedules/{id}`、`DELETE /api/provider/schedules/{id}` 的正常流程、所有權邊界與容量驗證。
|
||||
|
||||
#### Scenario: Provider 建立時段成功
|
||||
- **WHEN** Provider 送出有效的 diving_offer_id / scheduled_date（未來日期）/ start_time / max_participants 至 `POST /api/provider/schedules`
|
||||
- **THEN** 回傳 HTTP 201，body 包含 `{ status: true, data: { id, scheduled_date, status: "open" } }`
|
||||
|
||||
#### Scenario: Provider 不可為他人課程建立時段
|
||||
- **WHEN** Provider A 送出 Provider B 課程的 diving_offer_id 至 `POST /api/provider/schedules`
|
||||
- **THEN** 回傳 HTTP 403
|
||||
|
||||
#### Scenario: 時段日期不可為過去
|
||||
- **WHEN** Provider 送出 scheduled_date 為過去日期
|
||||
- **THEN** 回傳 HTTP 422
|
||||
|
||||
#### Scenario: Provider 更新時段人數上限
|
||||
- **WHEN** Provider 送出新的 max_participants 至 `PUT /api/provider/schedules/{id}`（新值 ≥ 目前 current_participants）
|
||||
- **THEN** 回傳 HTTP 200，DB 記錄已更新
|
||||
|
||||
#### Scenario: 人數上限不可低於已確認人數
|
||||
- **WHEN** Provider 嘗試將 max_participants 設為低於時段 current_participants 的值
|
||||
- **THEN** 回傳 HTTP 422，message 說明不可低於已確認人數
|
||||
|
||||
#### Scenario: Provider 不可更新他人時段
|
||||
- **WHEN** Provider A 嘗試 `PUT /api/provider/schedules/{id}`，但該時段屬於 Provider B
|
||||
- **THEN** 回傳 HTTP 403
|
||||
|
||||
#### Scenario: 刪除時段同時將進行中預約標記為 provider_cancelled
|
||||
- **WHEN** Provider 對有 pending/confirmed 預約的時段送出 `DELETE /api/provider/schedules/{id}`
|
||||
- **THEN** 回傳 HTTP 200；時段 status 改為 `cancelled`（記錄保留，不刪除）；該時段的 pending/confirmed booking status 改為 `provider_cancelled`（記錄保留，不刪除）；已是終態的 booking（completed/expired/已取消）不受影響
|
||||
|
||||
---
|
||||
|
||||
### Requirement: Admin 使用者管理測試覆蓋
|
||||
測試套件 SHALL 驗證 Admin 查詢會員/教練列表、切換帳號啟用狀態、切換教練驗證狀態的正確行為。
|
||||
|
||||
#### Scenario: Admin 取得會員列表
|
||||
- **WHEN** Admin 送出 `GET /api/admin/members`
|
||||
- **THEN** 回傳 HTTP 200，data 陣列只包含 role=member 的使用者
|
||||
|
||||
#### Scenario: Admin 取得教練列表
|
||||
- **WHEN** Admin 送出 `GET /api/admin/providers`
|
||||
- **THEN** 回傳 HTTP 200，data 陣列只包含 role=provider 的使用者
|
||||
|
||||
#### Scenario: Admin 切換會員帳號啟用狀態
|
||||
- **WHEN** Admin 送出 `PUT /api/admin/members/{id}/toggle-active`（目標會員 is_active=true）
|
||||
- **THEN** 回傳 HTTP 200，DB 記錄 is_active 由 true 變為 false
|
||||
|
||||
#### Scenario: Admin 核准教練審核
|
||||
- **WHEN** Admin 對 `verification_status=pending` 的教練送出 `PUT /api/admin/verifications/{userId}/approve`
|
||||
- **THEN** 回傳 HTTP 200，provider_profiles.verification_status 變為 `approved`
|
||||
- **NOTE** `toggle-verified` 路由已由 provider-verification-workflow 移除，驗證狀態變更一律透過審核狀態機
|
||||
|
||||
#### Scenario: 非 Admin 角色被拒絕
|
||||
- **WHEN** role=member 的使用者送出 `GET /api/admin/members`
|
||||
- **THEN** 回傳 HTTP 403
|
||||
|
||||
---
|
||||
|
||||
### Requirement: 通知直接觸發路徑測試覆蓋
|
||||
測試套件 SHALL 驗證預約 controller 操作直接觸發的通知事件，補足 Scheduler 路徑以外的覆蓋缺口。收件者依實際 controller 實作：新預約與 member 取消通知教練，其餘通知學員。
|
||||
|
||||
#### Scenario: 建立預約觸發 BookingCreatedNotification 至教練
|
||||
- **WHEN** Member 成功建立預約（`POST /api/member/bookings`）
|
||||
- **THEN** `BookingCreatedNotification` 被派發至該預約所屬的 **Provider**
|
||||
|
||||
#### Scenario: Provider 確認預約觸發 BookingConfirmedNotification 至學員
|
||||
- **WHEN** Provider 對 pending 預約呼叫 `PUT /api/provider/bookings/{id}/confirm`
|
||||
- **THEN** `BookingConfirmedNotification` 被派發至該預約的 **Member**
|
||||
|
||||
#### Scenario: Provider 拒絕預約觸發 BookingRejectedNotification 至學員
|
||||
- **WHEN** Provider 對 pending 預約呼叫 `PUT /api/provider/bookings/{id}/reject`
|
||||
- **THEN** `BookingRejectedNotification` 被派發至該預約的 **Member**
|
||||
|
||||
#### Scenario: Member 取消預約觸發 BookingCancelledNotification 至教練
|
||||
- **WHEN** Member 對 pending 預約呼叫 `DELETE /api/member/bookings/{id}`
|
||||
- **THEN** `BookingCancelledNotification` 被派發至該預約所屬的 **Provider**
|
||||
|
||||
#### Scenario: Provider 取消預約觸發 BookingCancelledNotification 至學員
|
||||
- **WHEN** Provider 對 confirmed 預約呼叫 `PUT /api/provider/bookings/{id}/cancel`
|
||||
- **THEN** `BookingCancelledNotification` 被派發至該預約的 **Member**
|
||||
|
||||
---
|
||||
|
||||
### Requirement: 預約列表端點測試覆蓋
|
||||
測試套件 SHALL 驗證下列三個路由的資料隔離行為：
|
||||
- `GET /api/member/bookings`（middleware: `auth:sanctum`，隔離靠 `where member_id = auth()->id()`）
|
||||
- `GET /api/provider/bookings`（middleware: `auth:sanctum`，隔離靠 `whereHas schedule.provider_id`）
|
||||
- `GET /api/admin/bookings`（middleware: `auth:sanctum` + `admin`，EnsureAdmin 於 middleware 層強制 403）
|
||||
|
||||
#### Scenario: Member 只能看到自己的預約
|
||||
- **WHEN** Member A 呼叫 `GET /api/member/bookings`，系統中同時存在 Member A 與 Member B 各一筆預約
|
||||
- **THEN** 回傳 data 只包含 Member A 的 booking id；Member B 的 booking id 不在 data 中
|
||||
|
||||
#### Scenario: Provider 只能看到屬於自己課程的預約
|
||||
- **WHEN** Provider A 呼叫 `GET /api/provider/bookings`，系統中有屬於 Provider A 與 Provider B 課程各一筆預約
|
||||
- **THEN** 回傳 data 只包含 Provider A 課程的 booking id；Provider B 課程的 booking id 不在 data 中
|
||||
|
||||
#### Scenario: Admin 可查看所有預約
|
||||
- **WHEN** Admin 呼叫 `GET /api/admin/bookings`，系統中有 2 筆不同 Member 的預約
|
||||
- **THEN** 回傳 data 包含兩筆 booking id
|
||||
|
||||
#### Scenario: 未認證請求被拒絕
|
||||
- **WHEN** 未帶 token 呼叫 `GET /api/member/bookings`
|
||||
- **THEN** 回傳 HTTP 401
|
||||
@@ -0,0 +1,23 @@
|
||||
# scheduler-container
|
||||
|
||||
Laravel Scheduler 以獨立 container 執行，取代 app container 內的 cron daemon。
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: Scheduler 以獨立 container 執行
|
||||
`docker-compose.yml` SHALL 定義 `scheduler` service，使用 `cfdive-platform` image，以 `php artisan schedule:work` 前台輪詢方式執行 Laravel Scheduler，取代原本在 app container 內的 cron daemon。
|
||||
|
||||
#### Scenario: Scheduler container 隨 app 啟動
|
||||
- **WHEN** 執行 `docker compose up -d` 且 `app` container 已 healthy
|
||||
- **THEN** `scheduler` container 啟動並持續執行 `php artisan schedule:work`
|
||||
|
||||
#### Scenario: App container 重啟時 scheduler 等待就緒
|
||||
- **WHEN** `app` container 重啟中（unhealthy）
|
||||
- **THEN** `scheduler` container 依 `depends_on` 等待 `app` healthy 後才啟動，避免 scheduler 在 PHP-FPM 未就緒時執行任務
|
||||
|
||||
### Requirement: App container 不再包含 cron daemon
|
||||
`Dockerfile` SHALL 不安裝 `cron` 套件，`docker-entrypoint.sh` SHALL 不執行 `service cron start`，確保 app container 職責單一（只跑 PHP-FPM）。
|
||||
|
||||
#### Scenario: App container 啟動不啟動 cron
|
||||
- **WHEN** `app` container 啟動並執行 entrypoint
|
||||
- **THEN** 不存在 cron daemon 程序，`pgrep cron` 回傳 exit code 1
|
||||
@@ -0,0 +1,120 @@
|
||||
<?php
|
||||
|
||||
namespace Tests\Feature;
|
||||
|
||||
use App\Models\MemberProfile;
|
||||
use App\Models\ProviderProfile;
|
||||
use App\Models\User;
|
||||
use Illuminate\Foundation\Testing\RefreshDatabase;
|
||||
use Tests\TestCase;
|
||||
|
||||
/**
|
||||
* Admin 使用者管理（admin-user-management 規格）。
|
||||
*
|
||||
* 列表端點必須依 role 過濾，否則 admin 介面會混入不同角色資料；
|
||||
* toggle-verified 的快取清除副作用已由 DivingOfferVisibilityTest 覆蓋，
|
||||
* 這裡只驗資料庫欄位變更與 HTTP 200。
|
||||
*/
|
||||
class AdminUserManagementTest extends TestCase
|
||||
{
|
||||
use RefreshDatabase;
|
||||
|
||||
private function makeAdmin(): User
|
||||
{
|
||||
return User::factory()->create(['role' => 'admin']);
|
||||
}
|
||||
|
||||
private function makeMember(): User
|
||||
{
|
||||
$member = User::factory()->create(['role' => 'member']);
|
||||
MemberProfile::create(['user_id' => $member->id]);
|
||||
return $member;
|
||||
}
|
||||
|
||||
private function makeProvider(string $verificationStatus = 'unsubmitted'): User
|
||||
{
|
||||
$provider = User::factory()->create(['role' => 'provider']);
|
||||
ProviderProfile::create(['user_id' => $provider->id, 'verification_status' => $verificationStatus]);
|
||||
return $provider;
|
||||
}
|
||||
|
||||
// ── 列表 ─────────────────────────────────────────────────
|
||||
|
||||
public function test_admin_lists_members_only(): void
|
||||
{
|
||||
$admin = $this->makeAdmin();
|
||||
$member = $this->makeMember();
|
||||
$provider = $this->makeProvider();
|
||||
|
||||
$response = $this->actingAs($admin)->getJson('/api/admin/members');
|
||||
|
||||
$response->assertOk()->assertJsonPath('status', true);
|
||||
|
||||
$ids = array_column($response->json('data'), 'id');
|
||||
$this->assertContains($member->id, $ids);
|
||||
$this->assertNotContains($provider->id, $ids);
|
||||
}
|
||||
|
||||
public function test_admin_lists_providers_only(): void
|
||||
{
|
||||
$admin = $this->makeAdmin();
|
||||
$member = $this->makeMember();
|
||||
$provider = $this->makeProvider();
|
||||
|
||||
$response = $this->actingAs($admin)->getJson('/api/admin/providers');
|
||||
|
||||
$response->assertOk()->assertJsonPath('status', true);
|
||||
|
||||
$ids = array_column($response->json('data'), 'id');
|
||||
$this->assertContains($provider->id, $ids);
|
||||
$this->assertNotContains($member->id, $ids);
|
||||
}
|
||||
|
||||
// ── toggle-active ────────────────────────────────────────
|
||||
|
||||
public function test_admin_toggles_member_active_status(): void
|
||||
{
|
||||
$admin = $this->makeAdmin();
|
||||
// is_active 預設由 DB 決定，factory 不設值；直接測試 toggle 的翻轉效果
|
||||
$member = User::factory()->create(['role' => 'member', 'is_active' => true]);
|
||||
|
||||
$this->actingAs($admin)
|
||||
->putJson("/api/admin/members/{$member->id}/toggle-active")
|
||||
->assertOk()
|
||||
->assertJsonPath('data.is_active', false);
|
||||
|
||||
$this->assertDatabaseHas('users', [
|
||||
'id' => $member->id,
|
||||
'is_active' => false,
|
||||
]);
|
||||
}
|
||||
|
||||
// ── approve ─────────────────────────────────────────────
|
||||
|
||||
public function test_admin_approves_provider_verification(): void
|
||||
{
|
||||
$admin = $this->makeAdmin();
|
||||
$provider = $this->makeProvider(verificationStatus: 'pending');
|
||||
|
||||
$this->actingAs($admin)
|
||||
->putJson("/api/admin/verifications/{$provider->id}/approve")
|
||||
->assertOk()
|
||||
->assertJsonPath('status', true);
|
||||
|
||||
$this->assertDatabaseHas('provider_profiles', [
|
||||
'user_id' => $provider->id,
|
||||
'verification_status' => 'approved',
|
||||
]);
|
||||
}
|
||||
|
||||
// ── 角色保護 ─────────────────────────────────────────────
|
||||
|
||||
public function test_non_admin_is_forbidden(): void
|
||||
{
|
||||
$member = $this->makeMember();
|
||||
|
||||
$this->actingAs($member)
|
||||
->getJson('/api/admin/members')
|
||||
->assertStatus(403);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,131 @@
|
||||
<?php
|
||||
|
||||
namespace Tests\Feature;
|
||||
|
||||
use App\Enums\BookingStatus;
|
||||
use App\Enums\ScheduleStatus;
|
||||
use App\Models\Booking;
|
||||
use App\Models\CourseSchedule;
|
||||
use App\Models\DivingOffer;
|
||||
use App\Models\ProviderProfile;
|
||||
use App\Models\User;
|
||||
use Illuminate\Foundation\Testing\RefreshDatabase;
|
||||
use Tests\TestCase;
|
||||
|
||||
/**
|
||||
* 預約列表端點資料隔離（booking-lifecycle 規格）。
|
||||
*
|
||||
* 路由對應（routes/api.php 已確認）：
|
||||
* GET /api/member/bookings → MemberBookingController::index（auth:sanctum，無 role check）
|
||||
* GET /api/provider/bookings → ProviderBookingController::index（auth:sanctum，無 role check）
|
||||
* GET /api/admin/bookings → AdminBookingController::index（auth:sanctum + admin middleware）
|
||||
*
|
||||
* 資料隔離靠 controller query 條件，不靠 middleware role 強制，
|
||||
* 因此測試需分別以正確角色 actingAs 驗證隔離邊界。
|
||||
*/
|
||||
class BookingListTest extends TestCase
|
||||
{
|
||||
use RefreshDatabase;
|
||||
|
||||
private function makeProviderWithSchedule(): array
|
||||
{
|
||||
$provider = User::factory()->create(['role' => 'provider']);
|
||||
ProviderProfile::create(['user_id' => $provider->id, 'verification_status' => 'approved']);
|
||||
|
||||
$offer = DivingOffer::create([
|
||||
'provider_id' => $provider->id,
|
||||
'title' => 'Dive Course',
|
||||
'location' => 'Kenting',
|
||||
'price' => 3000,
|
||||
'region' => '南部',
|
||||
'rating' => 0,
|
||||
'reviews' => 0,
|
||||
]);
|
||||
|
||||
$schedule = CourseSchedule::create([
|
||||
'diving_offer_id' => $offer->id,
|
||||
'provider_id' => $provider->id,
|
||||
'scheduled_date' => now()->addDays(30)->toDateString(),
|
||||
'start_time' => '09:00',
|
||||
'max_participants' => 10,
|
||||
'current_participants' => 0,
|
||||
'status' => ScheduleStatus::Open,
|
||||
]);
|
||||
|
||||
return [$provider, $schedule];
|
||||
}
|
||||
|
||||
private function makePendingBooking(User $member, CourseSchedule $schedule): Booking
|
||||
{
|
||||
return Booking::create([
|
||||
'schedule_id' => $schedule->id,
|
||||
'member_id' => $member->id,
|
||||
'participants' => 1,
|
||||
'total_price' => 3000,
|
||||
'status' => BookingStatus::Pending,
|
||||
]);
|
||||
}
|
||||
|
||||
// ── Member 列表 ──────────────────────────────────────────
|
||||
|
||||
public function test_member_sees_only_own_bookings(): void
|
||||
{
|
||||
[$provider, $schedule] = $this->makeProviderWithSchedule();
|
||||
$memberA = User::factory()->create(['role' => 'member']);
|
||||
$memberB = User::factory()->create(['role' => 'member']);
|
||||
$bookingA = $this->makePendingBooking($memberA, $schedule);
|
||||
$bookingB = $this->makePendingBooking($memberB, $schedule);
|
||||
|
||||
$response = $this->actingAs($memberA)->getJson('/api/member/bookings');
|
||||
|
||||
$response->assertOk();
|
||||
$ids = array_column($response->json('data'), 'id');
|
||||
$this->assertContains($bookingA->id, $ids);
|
||||
$this->assertNotContains($bookingB->id, $ids);
|
||||
}
|
||||
|
||||
// ── Provider 列表 ────────────────────────────────────────
|
||||
|
||||
public function test_provider_sees_only_own_course_bookings(): void
|
||||
{
|
||||
[$providerA, $scheduleA] = $this->makeProviderWithSchedule();
|
||||
[$providerB, $scheduleB] = $this->makeProviderWithSchedule();
|
||||
$member = User::factory()->create(['role' => 'member']);
|
||||
$bookingA = $this->makePendingBooking($member, $scheduleA);
|
||||
$bookingB = $this->makePendingBooking($member, $scheduleB);
|
||||
|
||||
$response = $this->actingAs($providerA)->getJson('/api/provider/bookings');
|
||||
|
||||
$response->assertOk();
|
||||
$ids = array_column($response->json('data'), 'id');
|
||||
$this->assertContains($bookingA->id, $ids);
|
||||
$this->assertNotContains($bookingB->id, $ids);
|
||||
}
|
||||
|
||||
// ── Admin 列表 ───────────────────────────────────────────
|
||||
|
||||
public function test_admin_sees_all_bookings(): void
|
||||
{
|
||||
$admin = User::factory()->create(['role' => 'admin']);
|
||||
[$providerA, $scheduleA] = $this->makeProviderWithSchedule();
|
||||
[$providerB, $scheduleB] = $this->makeProviderWithSchedule();
|
||||
$memberA = User::factory()->create(['role' => 'member']);
|
||||
$memberB = User::factory()->create(['role' => 'member']);
|
||||
$bookingA = $this->makePendingBooking($memberA, $scheduleA);
|
||||
$bookingB = $this->makePendingBooking($memberB, $scheduleB);
|
||||
|
||||
$response = $this->actingAs($admin)->getJson('/api/admin/bookings');
|
||||
|
||||
$response->assertOk();
|
||||
$ids = array_column($response->json('data'), 'id');
|
||||
$this->assertContains($bookingA->id, $ids);
|
||||
$this->assertContains($bookingB->id, $ids);
|
||||
}
|
||||
|
||||
// ── 未認證 ───────────────────────────────────────────────
|
||||
|
||||
public function test_unauthenticated_request_returns_401(): void
|
||||
{
|
||||
$this->getJson('/api/member/bookings')->assertStatus(401);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,167 @@
|
||||
<?php
|
||||
|
||||
namespace Tests\Feature;
|
||||
|
||||
use App\Enums\BookingStatus;
|
||||
use App\Enums\ScheduleStatus;
|
||||
use App\Models\Booking;
|
||||
use App\Models\CourseSchedule;
|
||||
use App\Models\DivingOffer;
|
||||
use App\Models\ProviderProfile;
|
||||
use App\Models\User;
|
||||
use App\Notifications\BookingCancelledNotification;
|
||||
use App\Notifications\BookingConfirmedNotification;
|
||||
use App\Notifications\BookingCreatedNotification;
|
||||
use App\Notifications\BookingRejectedNotification;
|
||||
use Illuminate\Foundation\Testing\RefreshDatabase;
|
||||
use Illuminate\Support\Facades\Notification;
|
||||
use Tests\TestCase;
|
||||
|
||||
/**
|
||||
* 預約通知直接觸發路徑（notification-triggers 規格）。
|
||||
*
|
||||
* 補齊 BookingSchedulerTest 以外的 controller 直接觸發路徑，
|
||||
* 確保收件者正確：新預約與 member 取消通知教練，其餘通知學員。
|
||||
*
|
||||
* 收件者依 controller 原始碼確認：
|
||||
* - BookingCreated → $provider->notify()
|
||||
* - BookingConfirmed → $booking->member->notify()
|
||||
* - BookingRejected → $booking->member->notify()
|
||||
* - BookingCancelled (member) → $provider->notify()
|
||||
* - BookingCancelled (provider) → $booking->member->notify()
|
||||
*/
|
||||
class NotificationTriggerTest extends TestCase
|
||||
{
|
||||
use RefreshDatabase;
|
||||
|
||||
protected function setUp(): void
|
||||
{
|
||||
parent::setUp();
|
||||
Notification::fake();
|
||||
}
|
||||
|
||||
private function makeProvider(): User
|
||||
{
|
||||
$provider = User::factory()->create(['role' => 'provider']);
|
||||
ProviderProfile::create(['user_id' => $provider->id, 'verification_status' => 'approved']);
|
||||
return $provider;
|
||||
}
|
||||
|
||||
private function makeSchedule(User $provider): CourseSchedule
|
||||
{
|
||||
$offer = DivingOffer::create([
|
||||
'provider_id' => $provider->id,
|
||||
'title' => 'Dive Course',
|
||||
'location' => 'Kenting',
|
||||
'price' => 3000,
|
||||
'region' => '南部',
|
||||
'rating' => 0,
|
||||
'reviews' => 0,
|
||||
]);
|
||||
|
||||
return CourseSchedule::create([
|
||||
'diving_offer_id' => $offer->id,
|
||||
'provider_id' => $provider->id,
|
||||
'scheduled_date' => now()->addDays(60)->toDateString(),
|
||||
'start_time' => '09:00',
|
||||
'max_participants' => 10,
|
||||
'current_participants' => 0,
|
||||
'status' => ScheduleStatus::Open,
|
||||
]);
|
||||
}
|
||||
|
||||
private function makePendingBooking(User $member, CourseSchedule $schedule): Booking
|
||||
{
|
||||
return Booking::create([
|
||||
'schedule_id' => $schedule->id,
|
||||
'member_id' => $member->id,
|
||||
'participants' => 1,
|
||||
'total_price' => 3000,
|
||||
'status' => BookingStatus::Pending,
|
||||
]);
|
||||
}
|
||||
|
||||
// ── 建立預約 → 通知教練 ──────────────────────────────────
|
||||
|
||||
public function test_booking_created_notifies_provider(): void
|
||||
{
|
||||
$provider = $this->makeProvider();
|
||||
$schedule = $this->makeSchedule($provider);
|
||||
$member = User::factory()->create(['role' => 'member']);
|
||||
|
||||
$this->actingAs($member)->postJson('/api/member/bookings', [
|
||||
'schedule_id' => $schedule->id,
|
||||
'participants' => 1,
|
||||
])->assertStatus(201);
|
||||
|
||||
Notification::assertSentTo($provider, BookingCreatedNotification::class);
|
||||
}
|
||||
|
||||
// ── 確認預約 → 通知學員 ──────────────────────────────────
|
||||
|
||||
public function test_booking_confirmed_notifies_member(): void
|
||||
{
|
||||
$provider = $this->makeProvider();
|
||||
$schedule = $this->makeSchedule($provider);
|
||||
$member = User::factory()->create(['role' => 'member']);
|
||||
$booking = $this->makePendingBooking($member, $schedule);
|
||||
|
||||
$this->actingAs($provider)
|
||||
->putJson("/api/provider/bookings/{$booking->id}/confirm")
|
||||
->assertOk();
|
||||
|
||||
Notification::assertSentTo($member, BookingConfirmedNotification::class);
|
||||
}
|
||||
|
||||
// ── 拒絕預約 → 通知學員 ──────────────────────────────────
|
||||
|
||||
public function test_booking_rejected_notifies_member(): void
|
||||
{
|
||||
$provider = $this->makeProvider();
|
||||
$schedule = $this->makeSchedule($provider);
|
||||
$member = User::factory()->create(['role' => 'member']);
|
||||
$booking = $this->makePendingBooking($member, $schedule);
|
||||
|
||||
$this->actingAs($provider)
|
||||
->putJson("/api/provider/bookings/{$booking->id}/reject")
|
||||
->assertOk();
|
||||
|
||||
Notification::assertSentTo($member, BookingRejectedNotification::class);
|
||||
}
|
||||
|
||||
// ── Member 取消 → 通知教練 ───────────────────────────────
|
||||
|
||||
public function test_member_cancel_notifies_provider(): void
|
||||
{
|
||||
$provider = $this->makeProvider();
|
||||
$schedule = $this->makeSchedule($provider);
|
||||
$member = User::factory()->create(['role' => 'member']);
|
||||
$booking = $this->makePendingBooking($member, $schedule);
|
||||
|
||||
$this->actingAs($member)
|
||||
->deleteJson("/api/member/bookings/{$booking->id}")
|
||||
->assertOk();
|
||||
|
||||
Notification::assertSentTo($provider, BookingCancelledNotification::class);
|
||||
}
|
||||
|
||||
// ── Provider 取消 → 通知學員 ─────────────────────────────
|
||||
|
||||
public function test_provider_cancel_notifies_member(): void
|
||||
{
|
||||
$provider = $this->makeProvider();
|
||||
$schedule = $this->makeSchedule($provider);
|
||||
$member = User::factory()->create(['role' => 'member']);
|
||||
$booking = $this->makePendingBooking($member, $schedule);
|
||||
|
||||
// 先確認，再取消（provider_cancelled 只能從 confirmed 轉換）
|
||||
$booking->update(['status' => BookingStatus::Confirmed]);
|
||||
$schedule->increment('current_participants', 1);
|
||||
|
||||
$this->actingAs($provider)
|
||||
->putJson("/api/provider/bookings/{$booking->id}/cancel")
|
||||
->assertOk();
|
||||
|
||||
Notification::assertSentTo($member, BookingCancelledNotification::class);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,143 @@
|
||||
<?php
|
||||
|
||||
namespace Tests\Feature;
|
||||
|
||||
use App\Models\DivingOffer;
|
||||
use App\Models\ProviderProfile;
|
||||
use App\Models\User;
|
||||
use Illuminate\Foundation\Testing\RefreshDatabase;
|
||||
use Tests\TestCase;
|
||||
|
||||
/**
|
||||
* Provider 課程 CRUD（coach-offers-api 規格）。
|
||||
*
|
||||
* 所有權驗證是核心不變式：provider_id 決定哪位教練可操作，
|
||||
* 未加檢查會讓任何已登入教練刪改他人課程。
|
||||
*/
|
||||
class ProviderOfferCrudTest extends TestCase
|
||||
{
|
||||
use RefreshDatabase;
|
||||
|
||||
private function makeProvider(): User
|
||||
{
|
||||
$provider = User::factory()->create(['role' => 'provider']);
|
||||
ProviderProfile::create(['user_id' => $provider->id, 'verification_status' => 'approved']);
|
||||
return $provider;
|
||||
}
|
||||
|
||||
private function makeOffer(User $provider): DivingOffer
|
||||
{
|
||||
return DivingOffer::create([
|
||||
'provider_id' => $provider->id,
|
||||
'title' => 'Test Dive Course',
|
||||
'location' => 'Kenting',
|
||||
'price' => 3000,
|
||||
'region' => '南部',
|
||||
'rating' => 0,
|
||||
'reviews' => 0,
|
||||
]);
|
||||
}
|
||||
|
||||
// ── store ────────────────────────────────────────────────
|
||||
|
||||
public function test_provider_creates_offer_successfully(): void
|
||||
{
|
||||
$provider = $this->makeProvider();
|
||||
|
||||
$response = $this->actingAs($provider)->postJson('/api/provider/offers', [
|
||||
'title' => 'New Dive Course',
|
||||
'location' => 'Kenting',
|
||||
'price' => 5000,
|
||||
'region' => '南部',
|
||||
]);
|
||||
|
||||
$response->assertStatus(201)
|
||||
->assertJsonPath('status', true)
|
||||
->assertJsonPath('data.provider_id', $provider->id);
|
||||
|
||||
$this->assertDatabaseHas('diving_offers', [
|
||||
'title' => 'New Dive Course',
|
||||
'provider_id' => $provider->id,
|
||||
]);
|
||||
}
|
||||
|
||||
public function test_create_offer_missing_required_field_returns_422(): void
|
||||
{
|
||||
$provider = $this->makeProvider();
|
||||
|
||||
$this->actingAs($provider)->postJson('/api/provider/offers', [
|
||||
// title is missing
|
||||
'location' => 'Kenting',
|
||||
'price' => 5000,
|
||||
'region' => '南部',
|
||||
])->assertStatus(422);
|
||||
}
|
||||
|
||||
public function test_unauthenticated_request_is_rejected(): void
|
||||
{
|
||||
$this->postJson('/api/provider/offers', [
|
||||
'title' => 'New Dive Course',
|
||||
'location' => 'Kenting',
|
||||
'price' => 5000,
|
||||
'region' => '南部',
|
||||
])->assertStatus(401);
|
||||
}
|
||||
|
||||
// ── update ───────────────────────────────────────────────
|
||||
|
||||
public function test_provider_updates_own_offer(): void
|
||||
{
|
||||
$provider = $this->makeProvider();
|
||||
$offer = $this->makeOffer($provider);
|
||||
|
||||
$this->actingAs($provider)->putJson("/api/provider/offers/{$offer->id}", [
|
||||
'title' => 'Updated Title',
|
||||
'price' => 9999,
|
||||
])->assertOk()->assertJsonPath('status', true);
|
||||
|
||||
$this->assertDatabaseHas('diving_offers', [
|
||||
'id' => $offer->id,
|
||||
'title' => 'Updated Title',
|
||||
'price' => 9999,
|
||||
]);
|
||||
}
|
||||
|
||||
public function test_provider_cannot_update_others_offer(): void
|
||||
{
|
||||
$ownerProvider = $this->makeProvider();
|
||||
$otherProvider = $this->makeProvider();
|
||||
$offer = $this->makeOffer($ownerProvider);
|
||||
|
||||
$this->actingAs($otherProvider)
|
||||
->putJson("/api/provider/offers/{$offer->id}", ['title' => 'Hacked Title'])
|
||||
->assertStatus(403);
|
||||
}
|
||||
|
||||
// ── destroy ──────────────────────────────────────────────
|
||||
|
||||
public function test_provider_deletes_own_offer(): void
|
||||
{
|
||||
$provider = $this->makeProvider();
|
||||
$offer = $this->makeOffer($provider);
|
||||
|
||||
$this->actingAs($provider)
|
||||
->deleteJson("/api/provider/offers/{$offer->id}")
|
||||
->assertOk()
|
||||
->assertJsonPath('status', true);
|
||||
|
||||
$this->assertDatabaseMissing('diving_offers', ['id' => $offer->id]);
|
||||
}
|
||||
|
||||
public function test_provider_cannot_delete_others_offer(): void
|
||||
{
|
||||
$ownerProvider = $this->makeProvider();
|
||||
$otherProvider = $this->makeProvider();
|
||||
$offer = $this->makeOffer($ownerProvider);
|
||||
|
||||
$this->actingAs($otherProvider)
|
||||
->deleteJson("/api/provider/offers/{$offer->id}")
|
||||
->assertStatus(403);
|
||||
|
||||
$this->assertDatabaseHas('diving_offers', ['id' => $offer->id]);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,202 @@
|
||||
<?php
|
||||
|
||||
namespace Tests\Feature;
|
||||
|
||||
use App\Enums\BookingStatus;
|
||||
use App\Enums\ScheduleStatus;
|
||||
use App\Models\Booking;
|
||||
use App\Models\CourseSchedule;
|
||||
use App\Models\DivingOffer;
|
||||
use App\Models\ProviderProfile;
|
||||
use App\Models\User;
|
||||
use Illuminate\Foundation\Testing\RefreshDatabase;
|
||||
use Tests\TestCase;
|
||||
|
||||
/**
|
||||
* Provider 時段管理（course-scheduling 規格）。
|
||||
*
|
||||
* 容量不變式：max_participants 不可低於 current_participants，
|
||||
* 否則已確認名額會被靜默截斷；destroy 必須同步取消進行中預約，
|
||||
* 不處理會讓 member 對不存在/取消的時段保有 pending/confirmed 狀態。
|
||||
*/
|
||||
class ProviderScheduleCrudTest extends TestCase
|
||||
{
|
||||
use RefreshDatabase;
|
||||
|
||||
private function makeProvider(): User
|
||||
{
|
||||
$provider = User::factory()->create(['role' => 'provider']);
|
||||
ProviderProfile::create(['user_id' => $provider->id, 'verification_status' => 'approved']);
|
||||
return $provider;
|
||||
}
|
||||
|
||||
private function makeOffer(User $provider): DivingOffer
|
||||
{
|
||||
return DivingOffer::create([
|
||||
'provider_id' => $provider->id,
|
||||
'title' => 'Dive Course',
|
||||
'location' => 'Kenting',
|
||||
'price' => 3000,
|
||||
'region' => '南部',
|
||||
'rating' => 0,
|
||||
'reviews' => 0,
|
||||
]);
|
||||
}
|
||||
|
||||
private function makeSchedule(DivingOffer $offer, int $currentParticipants = 0): CourseSchedule
|
||||
{
|
||||
return CourseSchedule::create([
|
||||
'diving_offer_id' => $offer->id,
|
||||
'provider_id' => $offer->provider_id,
|
||||
'scheduled_date' => now()->addDays(30)->toDateString(),
|
||||
'start_time' => '09:00',
|
||||
'max_participants' => 10,
|
||||
'current_participants' => $currentParticipants,
|
||||
'status' => ScheduleStatus::Open,
|
||||
]);
|
||||
}
|
||||
|
||||
// ── store ────────────────────────────────────────────────
|
||||
|
||||
public function test_provider_creates_schedule_successfully(): void
|
||||
{
|
||||
$provider = $this->makeProvider();
|
||||
$offer = $this->makeOffer($provider);
|
||||
|
||||
$response = $this->actingAs($provider)->postJson('/api/provider/schedules', [
|
||||
'diving_offer_id' => $offer->id,
|
||||
'scheduled_date' => now()->addDays(10)->toDateString(),
|
||||
'start_time' => '09:00',
|
||||
'max_participants' => 8,
|
||||
]);
|
||||
|
||||
$response->assertStatus(201)
|
||||
->assertJsonPath('status', true)
|
||||
->assertJsonPath('data.status', 'open');
|
||||
}
|
||||
|
||||
public function test_provider_cannot_create_schedule_for_others_offer(): void
|
||||
{
|
||||
$ownerProvider = $this->makeProvider();
|
||||
$otherProvider = $this->makeProvider();
|
||||
$offer = $this->makeOffer($ownerProvider);
|
||||
|
||||
$this->actingAs($otherProvider)->postJson('/api/provider/schedules', [
|
||||
'diving_offer_id' => $offer->id,
|
||||
'scheduled_date' => now()->addDays(10)->toDateString(),
|
||||
'start_time' => '09:00',
|
||||
'max_participants' => 8,
|
||||
])->assertStatus(403);
|
||||
}
|
||||
|
||||
public function test_past_date_returns_422(): void
|
||||
{
|
||||
$provider = $this->makeProvider();
|
||||
$offer = $this->makeOffer($provider);
|
||||
|
||||
$this->actingAs($provider)->postJson('/api/provider/schedules', [
|
||||
'diving_offer_id' => $offer->id,
|
||||
'scheduled_date' => now()->subDay()->toDateString(),
|
||||
'start_time' => '09:00',
|
||||
'max_participants' => 8,
|
||||
])->assertStatus(422);
|
||||
}
|
||||
|
||||
// ── update ───────────────────────────────────────────────
|
||||
|
||||
public function test_provider_updates_schedule_max_participants(): void
|
||||
{
|
||||
$provider = $this->makeProvider();
|
||||
$offer = $this->makeOffer($provider);
|
||||
$schedule = $this->makeSchedule($offer);
|
||||
|
||||
$this->actingAs($provider)
|
||||
->putJson("/api/provider/schedules/{$schedule->id}", ['max_participants' => 20])
|
||||
->assertOk()
|
||||
->assertJsonPath('data.max_participants', 20);
|
||||
|
||||
$this->assertDatabaseHas('course_schedules', [
|
||||
'id' => $schedule->id,
|
||||
'max_participants' => 20,
|
||||
]);
|
||||
}
|
||||
|
||||
public function test_max_participants_below_current_returns_422(): void
|
||||
{
|
||||
$provider = $this->makeProvider();
|
||||
$offer = $this->makeOffer($provider);
|
||||
$schedule = $this->makeSchedule($offer, currentParticipants: 3);
|
||||
|
||||
$this->actingAs($provider)
|
||||
->putJson("/api/provider/schedules/{$schedule->id}", ['max_participants' => 2])
|
||||
->assertStatus(422);
|
||||
}
|
||||
|
||||
public function test_provider_cannot_update_others_schedule(): void
|
||||
{
|
||||
$ownerProvider = $this->makeProvider();
|
||||
$otherProvider = $this->makeProvider();
|
||||
$offer = $this->makeOffer($ownerProvider);
|
||||
$schedule = $this->makeSchedule($offer);
|
||||
|
||||
$this->actingAs($otherProvider)
|
||||
->putJson("/api/provider/schedules/{$schedule->id}", ['max_participants' => 20])
|
||||
->assertStatus(403);
|
||||
}
|
||||
|
||||
// ── destroy ──────────────────────────────────────────────
|
||||
|
||||
public function test_delete_schedule_marks_active_bookings_as_provider_cancelled(): void
|
||||
{
|
||||
$provider = $this->makeProvider();
|
||||
$offer = $this->makeOffer($provider);
|
||||
$schedule = $this->makeSchedule($offer);
|
||||
$member = User::factory()->create(['role' => 'member']);
|
||||
|
||||
$pendingBooking = Booking::create([
|
||||
'schedule_id' => $schedule->id,
|
||||
'member_id' => $member->id,
|
||||
'participants' => 1,
|
||||
'total_price' => 3000,
|
||||
'status' => BookingStatus::Pending,
|
||||
]);
|
||||
|
||||
$confirmedBooking = Booking::create([
|
||||
'schedule_id' => $schedule->id,
|
||||
'member_id' => User::factory()->create(['role' => 'member'])->id,
|
||||
'participants' => 1,
|
||||
'total_price' => 3000,
|
||||
'status' => BookingStatus::Confirmed,
|
||||
]);
|
||||
|
||||
$completedBooking = Booking::create([
|
||||
'schedule_id' => $schedule->id,
|
||||
'member_id' => User::factory()->create(['role' => 'member'])->id,
|
||||
'participants' => 1,
|
||||
'total_price' => 3000,
|
||||
'status' => BookingStatus::Completed,
|
||||
]);
|
||||
|
||||
$this->actingAs($provider)
|
||||
->deleteJson("/api/provider/schedules/{$schedule->id}")
|
||||
->assertOk();
|
||||
|
||||
$this->assertDatabaseHas('course_schedules', [
|
||||
'id' => $schedule->id,
|
||||
'status' => ScheduleStatus::Cancelled->value,
|
||||
]);
|
||||
$this->assertDatabaseHas('bookings', [
|
||||
'id' => $pendingBooking->id,
|
||||
'status' => BookingStatus::ProviderCancelled->value,
|
||||
]);
|
||||
$this->assertDatabaseHas('bookings', [
|
||||
'id' => $confirmedBooking->id,
|
||||
'status' => BookingStatus::ProviderCancelled->value,
|
||||
]);
|
||||
// 終態 booking 不受影響
|
||||
$this->assertDatabaseHas('bookings', [
|
||||
'id' => $completedBooking->id,
|
||||
'status' => BookingStatus::Completed->value,
|
||||
]);
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user