feat(qw): onboard QW site (LM來財娛樂城) with P0 smoke + visual regression (#58)

- pages/qw/{login_page,home_page}.py: Nuxt/Vue site with /auth standalone
  login flow, popup-mask dismiss loop, hover-triggered avatar dropdown
  (logout via JS dispatchEvent to avoid mouseleave race)
- tests/qw/test_p0_smoke.py: 4 P0 cases (login_success / login_invalid /
  logout / home_loads) - 4/4 pass in 1:05
- tests/qw/feature/visual/test_visual_regression.py: 3 VR cases
  (home_shell / auth_page / navbar) - 3/3 pass
- pages/factory.py: append 'qw' to LoginPage + HomePage registries
- pytest.ini: register 'qw' marker
- .env.example: rename QW section to "LM來財娛樂城（現金版）"
- CLAUDE.md: Architecture / Markers / Visual Regression sections updated

Site characteristics (Nuxt + multi-locale):
- Login at /auth (not /login - /login is Nuxt 404)
- Submit button has no `type` HTML attribute, requires class selector only
- Avatar dropdown is hover-triggered; logout requires dispatchEvent
- popup-mask intercepts pointer events, dismiss loop until hidden

Verification:
- QW P0 smoke: 4/4 pass (1:05) via CDP
- QW VR: 3/3 pass, screenshots saved to screenshots/qw/vr_reference/
- Existing 4 sites (rc/lt/re/rd) P0 smoke: 37/37 executed pass, 5 skipped
  (LT known skips), 6:10 - factory.py append-only change verified safe

Author: nohungry

.env.example

@@ -196,7 +196,7 @@ SITE_RC_COMPANYCODE=drc
 # SITE_KS_COMPANYCODE=dks
 
 # -----------------------------------------------
-# QW 站點 (qw) — 現金版（暫時未使用，預先加入）
+# QW 站點 (qw) — LM來財娛樂城（現金版）
 # -----------------------------------------------
 # 前台
 # SITE_QW_URL=https://<your-qw-domain>/

CLAUDE.md

@@ -88,6 +88,7 @@ pages/rc/                   — rc site Page Objects (LoginPage, HomePage) — 
 pages/lt/                   — lt site Page Objects (LoginPage, HomePage) — LT來財
 pages/re/                   — re site Page Objects (LoginPage, HomePage) — BeWin
 pages/rd/                   — rd site Page Objects (LoginPage, HomePage) — 狗狗娛樂城
+pages/qw/                   — qw site Page Objects (LoginPage, HomePage) — LM來財娛樂城（Nuxt/Vue，多語系）
 pages/dashboard/<site_id>/   — backend dashboard page objects (DashboardLoginPage, ManagementPage); per dashboard factory registry
 tests/api/<site_id>/         — API-layer tests (requests only, no browser, no pages/* import); per-site conftest
 tests/dashboard/<site_id>/   — backend dashboard tests; state-mutating tests should be reversible (rollback / teardown compensation)
@@ -99,6 +100,8 @@ tests/re/                   — re site tests (test_p0_smoke.py p0, feature/<nam
 tests/re/conftest.py        — re-specific overrides: site_config=re, go_home
 tests/rd/                   — rd site tests (test_p0_smoke.py p0, feature/<name>/ p1: announcement_popup, i18n, navigation)
 tests/rd/conftest.py        — rd-specific overrides: site_config=rd, go_home
+tests/qw/                   — qw site tests (test_p0_smoke.py p0, feature/visual/ p2)
+tests/qw/conftest.py        — qw-specific overrides: site_config=qw, go_home (+ dismiss popup-mask)
 utils/locale_helper.py       — set_locale(): injects i18n_locale cookie for lt site
 utils/dialog_helper.py       — helpers: dismiss server error popups, wait for loading animation
 utils/screenshot_helper.py   — element-highlight screenshot system, auto README.md generation
@@ -119,7 +122,7 @@ dev-notes/                   — personal developer notes (gitignored except REA
 - `auto_screenshot` (autouse) — attaches `ScreenshotHelper` to page; auto-categorizes tests into `smoke/` or `feature/` subfolder; generates `screenshots/<site_id>/<timestamp>/<category>/<test_name>/README.md` after each test
 - `auto_logout_after_test` (autouse) — logs out after each smoke test (`page` fixture only)
 
-**Markers** (pytest.ini): `p0`, `p1`, `p2`, `login`, `home`, `member`, `wallet`, `i18n`, `language`, `copy`, `visual`, `visual_regression`, `locale_layout`, `docker_only`, `api`, `dashboard`, `game`, `flaky`, `lt`, `rc`, `re`, `rd`
+**Markers** (pytest.ini): `p0`, `p1`, `p2`, `login`, `home`, `member`, `wallet`, `i18n`, `language`, `copy`, `visual`, `visual_regression`, `locale_layout`, `docker_only`, `api`, `dashboard`, `game`, `flaky`, `lt`, `rc`, `re`, `rd`, `qw`
 
 ## Multi-site Factory Pattern
 
@@ -204,14 +207,15 @@ This repo has **two distinct documentation folders** with different purposes and
 
 若某份 `dev-notes/` 的筆記後來成熟並獲得團隊共識，請**升級**移到 `docs/` 並調整內容為正式文件。反之，若 `docs/` 中某份文件變成僅個人觀點的 WIP 清單，應移到 `dev-notes/`。
 
-## Visual Regression (lt / rc)
+## Visual Regression (lt / rc / qw)
 
-LT 與 RC 皆採用 **reference screenshot** 策略：存檔供人工確認，不做 pixel 比對（跨環境解析度不穩定）。
+LT、RC、QW 皆採用 **reference screenshot** 策略：存檔供人工確認，不做 pixel 比對（跨環境解析度不穩定）。
 
 ```bash
 # VR reference 截圖（輸出至 screenshots/<site_id>/vr_reference/）
 .venv/bin/pytest tests/lt/feature/visual/test_visual_regression.py -m visual_regression
 .venv/bin/pytest tests/rc/feature/visual/test_visual_regression.py -m visual_regression
+.venv/bin/pytest tests/qw/feature/visual/test_visual_regression.py -m visual_regression
 
 # DOM 層視覺健康度（非截圖）
 .venv/bin/pytest -m visual

pages/factory.py

@@ -23,13 +23,15 @@ def _import_class(module_path: str, class_name: str):
     'lt': ('pages.lt.login_page', 'LoginPage'),
     're': ('pages.re.login_page', 'LoginPage'),
     'rd': ('pages.rd.login_page', 'LoginPage'),
+    'qw': ('pages.qw.login_page', 'LoginPage'),
 }
 
 _HOME_PAGE_REGISTRY = {
     'rc': ('pages.rc.home_page', 'HomePage'),
     'lt': ('pages.lt.home_page', 'HomePage'),
     're': ('pages.re.home_page', 'HomePage'),
     'rd': ('pages.rd.home_page', 'HomePage'),
+    'qw': ('pages.qw.home_page', 'HomePage'),
 }
 
 

pages/qw/__init__.py

@@ -0,0 +1,162 @@
+"""
+首頁 Page Object — qw 站點（LM來財娛樂城）
+登入成功後的首頁驗證、彈窗清理、登出
+
+probe 結果（2026-05-22）：
+- Avatar：img[alt="avatar"]（與 RC 同 alt，巧合）
+- Avatar 容器：.avatar-trigger（cursor-pointer）
+- Username 顯示：.avatar-trigger p
+- Dropdown：hover 觸發（非 click！Vue/Nuxt behavior）
+- 登出按鈕：button.avatar-menu__logout
+- 公告彈窗：.popup-mask（全屏 mask）+ .popup-close（X 按鈕）
+- TOTP 提示：button，text 含「下次再說」（多語系：用 has_text 配合 try-except）
+
+多語系注意：QW 多語系站（LaiBetLanguage cookie），不綁文案 selector。
+登出按鈕用 CSS class（.avatar-menu__logout）而非文案。
+"""
+
+from playwright.sync_api import Page, expect, TimeoutError as PlaywrightTimeoutError
+from utils.screenshot_helper import get_screenshotter
+
+
+class HomePage:
+
+    def __init__(self, page: Page):
+        self.page = page
+
+        # 登入後主要元素
+        self.avatar = page.locator('img[alt="avatar"]')
+        self.avatar_trigger = page.locator('.avatar-trigger')
+
+        # 未登入狀態：登入入口按鈕（多語系：用 CSS class）
+        # probe 確認 class 為 .outline-btn-shared 或 .active-btn-shadow
+        # 以 .outline-btn-shared 為主（較明確區分 login CTA）
+        self.login_entry_btn = page.locator('button.outline-btn-shared').first
+
+    # ------------------------------------------------------------------
+    # 登入狀態驗證
+    # ------------------------------------------------------------------
+
+    def is_logged_in(self) -> bool:
+        """判斷目前是否已登入（avatar 可見）"""
+        try:
+            return self.avatar.is_visible(timeout=3000)
+        except Exception:
+            return False
+
+    def verify_logged_in(self):
+        """輕量驗證：avatar 可見即代表已登入。無副作用。
+        fixture 與單純確認登入狀態時使用。
+        """
+        sh = get_screenshotter(self.page)
+        expect(self.avatar).to_be_visible(timeout=10000)
+        self.avatar.scroll_into_view_if_needed()
+        if sh: sh.capture(self.avatar, "verify_已登入_頭像")
+
+    def verify_login_success(self, username: str):
+        """驗證登入成功：avatar 可見 + .avatar-trigger 區塊含 username 文字。
+        E2E 登入 TC 使用（test_login_success）。
+
+        斷言策略：avatar visible + avatar_trigger 整體文字含 username。
+        不對特定 p 元素斷言（avatar_trigger 內有 3 個 p：username、VIP 等級、餘額，
+        會 strict mode violation；且各 p 的顏色 class fragile）。
+        """
+        sh = get_screenshotter(self.page)
+
+        expect(self.avatar).to_be_visible(timeout=10000)
+        self.avatar.scroll_into_view_if_needed()
+        if sh: sh.capture(self.avatar, "verify_avatar_visible")
+
+        self.avatar_trigger.scroll_into_view_if_needed()
+        if sh: sh.capture(self.avatar_trigger, f"verify_帳號顯示_{username}")
+        expect(self.avatar_trigger).to_contain_text(username, timeout=5000)
+
+    def verify_logged_out(self):
+        """驗證已登出：首頁登入入口按鈕重新出現。"""
+        sh = get_screenshotter(self.page)
+        expect(self.login_entry_btn).to_be_visible(timeout=10000)
+        self.login_entry_btn.scroll_into_view_if_needed()
+        if sh: sh.capture(self.login_entry_btn, "verify_已登出_登入按鈕出現")
+
+    # ------------------------------------------------------------------
+    # 彈窗清理
+    # ------------------------------------------------------------------
+
+    def dismiss_any_popups(self):
+        """清除首頁可能出現的彈窗（公告 + TOTP 提示）。
+
+        QW 兩種彈窗都用 `.popup-mask` 包覆並會 intercept pointer events：
+          1. 公告彈窗（首頁）— `.popup-close` X 按鈕
+          2. TOTP 安全中心提示（登入後）— button text=「下次再說」
+
+        策略：loop 最多 3 輪 dismiss，直到 `.popup-mask` 完全消失或 timeout。
+        TOTP 提示可能在公告 popup 關掉後才 render，所以單次 dismiss 不夠。
+        """
+        for _ in range(3):
+            # 1. 公告彈窗
+            try:
+                popup_close = self.page.locator('.popup-close').first
+                popup_close.wait_for(state="visible", timeout=1500)
+                popup_close.click()
+            except PlaywrightTimeoutError:
+                pass
+
+            # 2. TOTP 提示（「下次再說」；多語系站台僅繁中模式下 text 如此）
+            # TODO: 待主 context probe 確認其他語系的文案後，補充對應文案或改 CSS selector
+            try:
+                totp_dismiss = self.page.locator('button', has_text="下次再說")
+                totp_dismiss.wait_for(state="visible", timeout=1500)
+                totp_dismiss.click()
+            except PlaywrightTimeoutError:
+                pass
+
+            # 檢查所有 .popup-mask 是否都已隱藏，若是則跳出 loop
+            try:
+                self.page.locator('.popup-mask').first.wait_for(state="hidden", timeout=1000)
+                break
+            except PlaywrightTimeoutError:
+                continue
+
+    # ------------------------------------------------------------------
+    # 登出
+    # ------------------------------------------------------------------
+
+    def logout(self):
+        """登出：hover avatar_trigger 展開 dropdown → click 登出按鈕 → 驗證登出。
+
+        QW avatar dropdown 由 hover 觸發（非 click，Vue/Nuxt behavior）。
+        probe 確認 click 不展開，必須用 hover。
+        """
+        sh = get_screenshotter(self.page)
+
+        # logout 之前再清一次彈窗（dismiss_any_popups loop 結束後 TOTP 提示可能才淡入完成）
+        self.dismiss_any_popups()
+
+        # 展開 dropdown：用 JS evaluate 派發 mouseenter/mouseover
+        # 不用 Playwright hover()（即使 force=True，Vue 的 @mouseleave 仍可能立即觸發收起 dropdown；
+        # JS dispatch 不會觸發後續 mouseleave，dropdown 維持 open 狀態）
+        if sh: sh.capture(self.avatar_trigger, "hover_avatar_trigger")
+        self.avatar_trigger.evaluate("""el => {
+            const rect = el.getBoundingClientRect();
+            const opts = { bubbles: true, cancelable: true,
+                clientX: rect.left + rect.width / 2, clientY: rect.top + rect.height / 2 };
+            el.dispatchEvent(new MouseEvent('mouseenter', opts));
+            el.dispatchEvent(new MouseEvent('mouseover', opts));
+        }""")
+
+        # 等待 dropdown panel 出現
+        avatar_menu_panel = self.page.locator('.avatar-menu__panel')
+        expect(avatar_menu_panel).to_be_visible(timeout=5000)
+        if sh: sh.capture(avatar_menu_panel, "verify_dropdown_opened")
+
+        # 點擊登出按鈕（用 CSS class，locale-agnostic）
+        # 注意：dropdown 由 hover 維持顯示；scroll_into_view 或一般 click 會打斷 hover
+        # 導致 dropdown 收起 → element detach。改用 dispatch_event 直接派發 click DOM event。
+        logout_btn = self.page.locator('button.avatar-menu__logout')
+        if sh: sh.capture(logout_btn, "click_登出")
+        logout_btn.dispatch_event("click")
+
+        # 驗證登出成功：登入入口按鈕重新出現
+        expect(self.login_entry_btn).to_be_visible(timeout=10000)
+        self.login_entry_btn.scroll_into_view_if_needed()
+        if sh: sh.capture(self.login_entry_btn, "verify_登出成功")

pages/qw/home_page.py

@@ -0,0 +1,79 @@
+"""
+登入頁面 Page Object — qw 站點（LM來財娛樂城）
+框架：Nuxt (Vue)；selector 來源：Chrome DevTools MCP probe（2026-05-22）
+
+登入流程：
+  首頁 → 點「登入」按鈕 → 跳轉 /auth → 填帳密 → submit → 回首頁 /
+
+注意：
+- /login 是 Nuxt 404，正確 auth 頁是 /auth
+- username/password 的 placeholder 相同，必須用 type 屬性區分
+- 多語系站台：selector 全部 CSS-based，不綁文案
+- wait_until="networkidle" 保護 Nuxt hydration（與 LT 策略對齊）
+"""
+
+from playwright.sync_api import Page, expect, TimeoutError as PlaywrightTimeoutError
+from utils.screenshot_helper import get_screenshotter
+
+
+class LoginPage:
+
+    def __init__(self, page: Page, base_url: str):
+        self.page = page
+        self.base_url = base_url
+        self.auth_url = base_url.rstrip("/") + "/auth"
+
+        # /auth 頁面 selectors（locale-agnostic；用 type 屬性區分帳密）
+        # 兩個 input 的 placeholder 相同，不可用 placeholder 區分
+        self.username_input = page.locator("input.auth-input__field[type='text']")
+        self.password_input = page.locator("input.auth-input__field[type='password']")
+
+        # submit 按鈕：用 class 精準命中「立即登入」送出按鈕
+        # 注意：button DOM 上沒有 `type` attribute（HTMLButtonElement 預設 type 是 submit
+        # 但屬性未寫），所以 [type='submit'] selector 命不中。直接靠 class 組合區分：
+        # - 立即登入：.solid-btn-shared.auth-btn
+        # - 先去逛逛：.outline-btn-shared.auth-btn（不含 solid）
+        self.submit_button = page.locator("button.solid-btn-shared.auth-btn")
+
+    def goto(self):
+        """直接導向 /auth（Nuxt：等 networkidle 確保 hydration 完成再 fill）"""
+        self.page.goto(self.auth_url, wait_until="networkidle")
+        self.username_input.wait_for(state="visible", timeout=10000)
+
+    def goto_and_login(self, username: str, password: str):
+        """完整登入流程：導向 /auth → 填帳密 → 送出 → 等跳轉回首頁
+
+        wait_until="networkidle" 策略：
+        - QW 為 Nuxt，hydration 前 fill 可能造成 submit 無效（與 LT React SPA 相同症狀）
+        - 保守選擇 networkidle；若實跑發現過慢，主 context 可切換為 domcontentloaded + retry
+        """
+        sh = get_screenshotter(self.page)
+
+        self.goto()
+
+        # 填入帳號
+        self.username_input.scroll_into_view_if_needed()
+        if sh: sh.capture(self.username_input, "fill_username")
+        self.username_input.fill(username)
+
+        # 填入密碼
+        self.password_input.scroll_into_view_if_needed()
+        if sh: sh.capture(self.password_input, "fill_password")
+        self.password_input.fill(password)
+
+        # 點擊送出按鈕
+        self.submit_button.scroll_into_view_if_needed()
+        if sh: sh.capture(self.submit_button, "click_login_submit")
+        self.submit_button.click()
+
+        # 等待跳轉回首頁（URL 離開 /auth）
+        try:
+            self.page.wait_for_url(
+                lambda url: "/auth" not in url,
+                timeout=15000
+            )
+        except PlaywrightTimeoutError:
+            # URL 未離開 /auth：可能登入失敗（錯誤帳密），留給 test 驗證
+            pass
+
+        if sh: sh.full_page("verify_login_success")

pages/qw/login_page.py

@@ -29,6 +29,7 @@ markers =
     rc: rc 站點（王老吉娛樂城）專屬測試
     re: re 站點（BeWin）專屬測試
     rd: rd 站點（狗狗娛樂城）專屬測試
+    qw: qw 站點（LM來財娛樂城）專屬測試
     i18n: 多語系文案驗證
     copy: 文案一致性驗證
     visual: 視覺健康度驗證（DOM metrics）

pytest.ini

@@ -0,0 +1,33 @@
+"""
+qw 站點測試專用 conftest（LM來財娛樂城）
+- 覆寫 site_config fixture，讓 tests/qw/ 下的測試不需加 --site=qw 即可執行
+- 不覆寫 page fixture：QW 無 toast-confirm-btn MutationObserver 需求；
+  但全域 conftest.py 注入的 observer 對 QW 是 no-op（selector 不匹配），可沿用。
+- 覆寫 go_home fixture：每個 functional test 前回首頁並清掉彈窗
+"""
+
+import pytest
+from config.settings import get_site_config
+from pages.factory import get_home_page_class
+
+
+@pytest.fixture(scope="session")
+def site_config():
+    """固定使用 qw 站設定"""
+    return get_site_config("qw")
+
+
+@pytest.fixture(scope="function")
+def go_home(class_logged_in_page, site_config):
+    """
+    [QW 覆寫] 每個測試前回到首頁並清理彈窗。
+    使用 HomePage.dismiss_any_popups() 清除公告彈窗與 TOTP 提示。
+    """
+    pg = class_logged_in_page
+    pg.goto(site_config.url, wait_until="networkidle")
+
+    HomeCls = get_home_page_class("qw")
+    home = HomeCls(pg)
+    home.dismiss_any_popups()
+
+    yield