v1.8.0 新增物品分類篩選、物品資訊卡、分頁瀏覽、異常值標註

README.md

@@ -28,9 +28,11 @@ short_description: FF14 繁中服市場價格查詢與跨服比價工具
 
 ### 市場查詢
 - **物品搜尋** - 支援繁體中文、英文名稱、物品 ID，或直接貼上 Universalis 網址
+- **物品分類篩選** - 大分類（武器/防具/素材等）+ 子分類下拉選單，支援分頁瀏覽
+- **物品資訊卡** - 顯示獲取方式、用途、裝備屬性、外部連結
 - **市場查詢** - 查看當前上架價格（NQ/HQ 分離）
 - **交易歷史** - 查看近期成交記錄
-- **價格走勢** - 互動式價格歷史圖表
+- **價格走勢** - 互動式價格歷史圖表，自動標註異常價格
 - **跨服比價** - 比較所有繁中服伺服器的價格差異
 - **雇員篩選** - 可依雇員名稱篩選上架物品
 - **自動刷新** - 5 秒自動更新（使用 WebSocket 緩存）
@@ -111,23 +113,30 @@ ff14_tw_market/
 └── src/
     ├── api.py          # API 請求封裝
     ├── charts.py       # 圖表繪製
-    ├── config.py       # 設定與常數
+    ├── config.py       # 設定與常數（含物品分類定義）
     ├── crafting.py     # 製作利潤計算
     ├── display.py      # 顯示格式化
     ├── shopping.py     # 購物清單與雇員建議
     ├── collectables.py # 收藏品時間表
     ├── watchlist.py    # 監看清單
     ├── websocket_api.py # WebSocket 連線
-    └── ai_analysis.py  # AI 分析功能
+    ├── ai_analysis.py  # AI 分析功能
+    ├── styles.py       # 自訂 CSS 樣式
+    └── changelog.py    # 更新紀錄
 ```
 
 ## 更新紀錄
 
+### v1.8.0 (2025-01)
+- 新增「物品分類篩選」功能（大分類 + 子分類 + 分頁瀏覽）
+- 新增「物品資訊卡」側欄（獲取方式/用途/裝備屬性/外部連結）
+- 價格走勢圖新增異常值標註（⚠️ 異常低價/高價）
+- 程式碼重構：CSS 和更新紀錄獨立為模組
+
 ### v1.7.2 (2025-01)
 - 即時追蹤新增「資料流狀態」圖表
 - 顯示各伺服器最後收到資料的時間
 - 以顏色標示資料新鮮度（綠/黃/橙/紅）
-- 讓使用者了解資料延遲來源
 
 ### v1.7.1 (2025-01)
 - 新增「即時追蹤」功能
@@ -139,26 +148,15 @@ ff14_tw_market/
 - 新增金色漸層頁首設計
 - 圖表配色優化
 
-### v1.6.1 (2025-01)
-- 收藏品時間表新增「老主顧」NPC 資訊
-- 顯示對應等級範圍的老主顧名稱與位置座標
-- 新增「老主顧位置一覽」快速參考表
-
-### v1.6.0 (2025-01)
+### v1.6.x (2025-01)
 - 新增「收藏品時間表」功能
-- 顯示大地使者（採礦工、園藝工、捕魚人）收藏品採集時間
-- 即時 ET（艾歐澤亞時間）顯示
-- 資料自動快取，支援強制刷新
+- 新增「老主顧」NPC 資訊
 
 ### v1.5.0 (2024-12)
 - 新增「購物助手」功能
-- 購物清單計算各伺服器總價
-- 雇員銷售建議
 
 ### v1.4.0 (2024-12)
 - 新增「製作利潤」功能
-- 遞迴計算材料成本
-- 賺錢排行榜
 
 ### v1.3.0 (2024-12)
 - 改用 WebSocket 驅動實時更新

app.py

@@ -6,63 +6,9 @@ import gradio as gr
 GRADIO_VERSION = int(gr.__version__.split(".")[0])
 USE_BROWSER_STATE = GRADIO_VERSION >= 5
 
-from src.config import POPULAR_ITEMS, WORLD_NAMES
-
-# 自訂 CSS 樣式 - 僅頁首裝飾
-CUSTOM_CSS = """
-/* 頁首樣式 */
-.header-box {
-    background: linear-gradient(135deg, #b8860b 0%, #daa520 50%, #b8860b 100%);
-    border-radius: 12px;
-    padding: 20px 24px;
-    margin-bottom: 16px;
-}
-
-.header-box h1 {
-    color: #1a1a2e !important;
-    margin: 0 0 8px 0 !important;
-}
-
-.header-box p {
-    color: #2c2c2c !important;
-    margin: 4px 0 !important;
-}
-
-.header-box a {
-    color: #1a1a2e !important;
-    font-weight: 700;
-    text-decoration: underline;
-}
-
-/* 伺服器標籤 */
-.server-tags {
-    display: flex;
-    flex-wrap: wrap;
-    gap: 6px;
-    margin-top: 10px;
-}
-
-.server-tag {
-    background: rgba(0,0,0,0.2);
-    color: #1a1a2e;
-    padding: 4px 10px;
-    border-radius: 12px;
-    font-size: 0.8em;
-    font-weight: 600;
-}
-
-/* 狀態標籤 */
-.status-badge {
-    display: inline-block;
-    background: #27ae60;
-    color: #ffffff;
-    padding: 6px 12px;
-    border-radius: 20px;
-    font-size: 0.85em;
-    margin-top: 12px;
-    font-weight: 500;
-}
-"""
+from src.config import POPULAR_ITEMS, WORLD_NAMES, ITEM_SUB_CATEGORIES
+from src.styles import CUSTOM_CSS
+from src.changelog import CHANGELOG_MD
 from src.display import (
     display_item_market,
     display_market_activity,
@@ -170,6 +116,22 @@ def create_app() -> gr.Blocks:
     return app
 
 
+def update_sub_categories(main_cat_id: int):
+    """根據大分類更新子分類選項."""
+    if main_cat_id == 0 or main_cat_id not in ITEM_SUB_CATEGORIES:
+        return gr.update(choices=[("全部子分類", 0)], value=0, visible=False)
+
+    sub_cats = ITEM_SUB_CATEGORIES[main_cat_id]
+    choices = [("全部子分類", 0)] + [(name, cid) for cid, name in sub_cats.items()]
+    return gr.update(choices=choices, value=0, visible=True)
+
+
+def get_effective_category(sub_cat: int) -> int:
+    """取得實際要查詢的分類 ID."""
+    # 如果有選擇子分類，使用子分類；否則不加分類限制
+    return sub_cat if sub_cat > 0 else 0
+
+
 def _build_market_tab() -> None:
     """建立市場查詢頁籤."""
     with gr.TabItem("市場查詢"):
@@ -184,6 +146,29 @@ def _build_market_tab() -> None:
                     placeholder="繁體中文、英文名稱、物品 ID 或 Universalis 網址",
                     lines=1,
                 )
+
+                # 分類篩選區塊
+                gr.Markdown("#### 物品分類篩選")
+                with gr.Group():
+                    main_category = gr.Radio(
+                        label="大分類",
+                        choices=[
+                            ("全部", 0), ("武器", 1), ("製作工具", 2), ("採集工具", 3),
+                            ("防具", 4), ("飾品", 5), ("藥品食品", 6), ("素材", 7), ("其他", 8),
+                        ],
+                        value=0,
+                        interactive=True,
+                        elem_classes=["category-radio"],
+                    )
+
+                    sub_category = gr.Dropdown(
+                        label="子分類",
+                        choices=[("全部子分類", 0)],
+                        value=0,
+                        interactive=True,
+                        visible=False,
+                    )
+
                 search_status = gr.Markdown(
                     "顯示常用物品，或輸入物品名稱/ID搜尋"
                 )
@@ -196,6 +181,16 @@ def _build_market_tab() -> None:
                     interactive=True,
                 )
 
+                # 分頁控制
+                with gr.Row():
+                    prev_page_btn = gr.Button("◀ 上一頁", size="sm")
+                    page_info = gr.Markdown("")
+                    next_page_btn = gr.Button("下一頁 ▶", size="sm")
+
+                # 分頁狀態
+                current_page_state = gr.State(value=1)
+                total_pages_state = gr.State(value=1)
+
             with gr.Column(scale=1):
                 world_select = gr.Dropdown(
                     label="選擇伺服器",
@@ -219,7 +214,11 @@ def _build_market_tab() -> None:
                         value=False,
                     )
 
-        item_info = gr.Markdown("")
+        with gr.Row():
+            with gr.Column(scale=1):
+                item_info = gr.Markdown("")
+            with gr.Column(scale=1):
+                item_card = gr.Markdown("")
 
         with gr.Row():
             with gr.Column():
@@ -253,18 +252,70 @@ def _build_market_tab() -> None:
         # 自動刷新用的計時器 (5秒，使用 WebSocket 緩存)
         timer = gr.Timer(value=5, active=False)
 
+        # 輔助函數：根據分類搜尋（含分頁）
+        def search_with_category(query, sub_cat, page=1):
+            category = get_effective_category(sub_cat)
+            dropdown, status, info, cur_page, total_pages = search_and_display(query, category, page)
+
+            # 更新分頁資訊顯示
+            if total_pages > 1:
+                page_text = f"第 {cur_page} / {total_pages} 頁"
+            else:
+                page_text = ""
+
+            return dropdown, status, info, cur_page, total_pages, page_text
+
+        def go_prev_page(query, sub_cat, current_page, _total_pages):
+            if current_page > 1:
+                return search_with_category(query, sub_cat, current_page - 1)
+            return search_with_category(query, sub_cat, current_page)
+
+        def go_next_page(query, sub_cat, current_page, total_pages):
+            if current_page < total_pages:
+                return search_with_category(query, sub_cat, current_page + 1)
+            return search_with_category(query, sub_cat, current_page)
+
         # 事件綁定
+        # 大分類變更 -> 更新子分類選項
+        main_category.change(
+            fn=update_sub_categories,
+            inputs=[main_category],
+            outputs=[sub_category],
+        )
+
+        # 搜尋輸入變更時，帶入分類參數（重置到第一頁）
         search_input.change(
-            fn=search_and_display,
-            inputs=[search_input],
-            outputs=[item_dropdown, search_status, item_info],
+            fn=search_with_category,
+            inputs=[search_input, sub_category],
+            outputs=[item_dropdown, search_status, item_info, current_page_state, total_pages_state, page_info],
+        )
+
+        # 子分類變更 -> 重新搜尋（重置到第一頁）
+        sub_category.change(
+            fn=search_with_category,
+            inputs=[search_input, sub_category],
+            outputs=[item_dropdown, search_status, item_info, current_page_state, total_pages_state, page_info],
+        )
+
+        # 上一頁按鈕
+        prev_page_btn.click(
+            fn=go_prev_page,
+            inputs=[search_input, sub_category, current_page_state, total_pages_state],
+            outputs=[item_dropdown, search_status, item_info, current_page_state, total_pages_state, page_info],
+        )
+
+        # 下一頁按鈕
+        next_page_btn.click(
+            fn=go_next_page,
+            inputs=[search_input, sub_category, current_page_state, total_pages_state],
+            outputs=[item_dropdown, search_status, item_info, current_page_state, total_pages_state, page_info],
         )
 
         search_btn.click(
             fn=display_item_market,
             inputs=[item_dropdown, world_select, quality_select, retainer_filter],
             outputs=[
-                item_info, listings_table, history_table,
+                item_info, item_card, listings_table, history_table,
                 price_chart, comparison_table, comparison_chart,
             ],
         )
@@ -273,7 +324,7 @@ def _build_market_tab() -> None:
             fn=display_item_market,
             inputs=[item_dropdown, world_select, quality_select, retainer_filter],
             outputs=[
-                item_info, listings_table, history_table,
+                item_info, item_card, listings_table, history_table,
                 price_chart, comparison_table, comparison_chart,
             ],
         )
@@ -290,7 +341,7 @@ def _build_market_tab() -> None:
             fn=display_item_market,
             inputs=[item_dropdown, world_select, quality_select, retainer_filter],
             outputs=[
-                item_info, listings_table, history_table,
+                item_info, item_card, listings_table, history_table,
                 price_chart, comparison_table, comparison_chart,
             ],
         )
@@ -1144,78 +1195,7 @@ def _build_ai_tab() -> None:
 def _build_changelog_tab() -> None:
     """建立更新紀錄頁籤."""
     with gr.TabItem("更新紀錄"):
-        gr.Markdown("""
-### 📝 更新紀錄
-
-### v1.7.2 (2025-01)
-- 即時追蹤新增「資料流狀態」圖表
-- 顯示各伺服器最後收到資料的時間
-- 以顏色標示資料新鮮度（綠/黃/橙/紅）
-- 讓使用者了解資料延遲來源
-
-### v1.7.1 (2025-01)
-- 新增「即時追蹤」功能
-- 顯示繁中服正在發生的市場交易（上架、售出）
-- 數據由 Universalis WebSocket 即時推送
-- 支援自動刷新（3秒）
-
-### v1.7.0 (2025-01)
-- 介面美化：採用 Gradio Soft 主題
-- 新增金色漸層頁首設計
-- 伺服器標籤視覺化呈現
-- 圖表配色優化（NQ 藍灰色、HQ 琥珀金色）
-
-### v1.6.1 (2025-01)
-- 收藏品時間表新增「老主顧」NPC 資訊
-- 顯示對應等級範圍的老主顧名稱與位置座標
-- 新增「老主顧位置一覽」快速參考表
-
-### v1.6.0 (2025-01)
-- 新增「收藏品時間表」功能
-- 顯示大地使者（採礦工、園藝工、捕魚人）收藏品採集時間
-- 即時 ET（艾歐澤亞時間）顯示
-- 顯示目前可採集和即將出現的收藏品
-- 包含採集地點、座標、工票獎勵
-- 資料自動快取，支援強制刷新
-
-### v1.5.0 (2024-12)
-- 新增「購物助手」功能
-- 購物清單：輸入多個物品，計算各伺服器總價，找最便宜的購買方案
-- 雇員銷售建議：分析銷售速度與價格，推薦值得上架的物品
-
-### v1.4.0 (2024-12)
-- 新增「製作利潤」功能
-- 計算製作成本 vs 市場售價
-- 遞迴計算材料成本（比較買 vs 自己做）
-- 賺錢排行榜：動態掃描最近交易物品
-- 職業篩選（木工、鍛冶、裁縫、烹調等）
-
-### v1.3.0 (2024-12)
-- 改用 WebSocket 驅動實時更新
-- 首次查詢用 REST API，之後用 WebSocket 緩存
-- 自動刷新改為 5 秒（使用緩存時幾乎無延遲）
-- 物品資訊與市場數據並行請求
-
-### v1.2.0 (2024-12)
-- 新增 AI 分析功能
-- 支援跨服套利判斷
-- 手機版面優化
-
-### v1.1.0 (2024-12)
-- 新增監看清單功能
-- 支援設定目標價格提醒
-- 資料儲存於瀏覽器 LocalStorage
-
-### v1.0.0 (2024-12)
-- 首次發布
-- 支援繁體中文搜尋物品
-- 市場價格查詢、交易紀錄
-- 跨伺服器比價
-- 稅率資訊、上傳統計
-
----
-資料來源: [Universalis API](https://universalis.app/)
-        """)
+        gr.Markdown(CHANGELOG_MD)
 
 
 if __name__ == "__main__":

src/api.py

@@ -44,18 +44,24 @@ def _extract_item_id(query: str) -> int:
     return 0
 
 
-def search_items(query: str, limit: int = 20) -> list:
+def search_items(query: str, limit: int = 20, category: int = 0, page: int = 1) -> dict:
     """搜尋物品 - 支援繁體中文、簡體中文、英文.
 
     Args:
         query: 搜尋關鍵字、物品 ID 或 Universalis 網址
-        limit: 結果數量限制
+        limit: 每頁結果數量限制
+        category: 物品分類 ID (ItemSearchCategory)，0 表示全部
+        page: 頁碼（從 1 開始）
 
     Returns:
-        物品列表，每個物品包含 id, name, icon, level
+        包含 items, pagination 的字典:
+        - items: 物品列表，每個物品包含 id, name, icon, level
+        - pagination: 分頁資訊 (page, page_total, results_total)
     """
+    empty_result = {"items": [], "pagination": {"page": 1, "page_total": 1, "results_total": 0}}
+
     if not query:
-        return []
+        return empty_result
 
     query = query.strip()
     results = []
@@ -71,22 +77,38 @@ def search_items(query: str, limit: int = 20) -> list:
                 "icon": "",
                 "level": item_info.get("LevelItem", 0),
             })
-            return results
+            return {"items": results, "pagination": {"page": 1, "page_total": 1, "results_total": 1}}
 
     # 2. 將繁體中文轉換為簡體中文（Cafemaker 使用簡體）
     query_simplified = _t2s_converter.convert(query)
 
     # 3. 使用 Cafemaker 搜尋（支援中文）
+    pagination = {"page": page, "page_total": 1, "results_total": 0}
     try:
         url = f"{CAFEMAKER_BASE}/search"
         params = {
             "string": query_simplified,
             "indexes": "Item",
             "limit": limit,
+            "page": page,
         }
+
+        # 如果有指定分類，加入篩選條件
+        if category > 0:
+            params["filters"] = f"ItemSearchCategory.ID={category}"
+
         response = requests.get(url, params=params, timeout=API_TIMEOUT)
         if response.status_code == 200:
             data = response.json()
+
+            # 取得分頁資訊
+            pag_info = data.get("Pagination", {})
+            pagination = {
+                "page": pag_info.get("Page", 1),
+                "page_total": pag_info.get("PageTotal", 1),
+                "results_total": pag_info.get("ResultsTotal", 0),
+            }
+
             for item in data.get("Results", []):
                 if not any(r["id"] == item.get("ID") for r in results):
                     # 將簡體中文名稱轉換為繁體中文
@@ -100,7 +122,7 @@ def search_items(query: str, limit: int = 20) -> list:
     except requests.RequestException as e:
         print(f"Cafemaker 搜尋錯誤: {e}")
 
-    return results[:limit]
+    return {"items": results, "pagination": pagination}
 
 
 def get_item_info(item_id: int) -> dict:

src/changelog.py

@@ -0,0 +1,88 @@
+"""更新紀錄."""
+
+CHANGELOG_MD = """
+### 📝 更新紀錄
+
+### v1.8.0 (2025-01)
+- 新增「物品分類篩選」功能
+  - 大分類：武器、防具、飾品、素材等 8 大類
+  - 子分類：根據大分類動態更新選項
+  - 分頁瀏覽：上一頁/下一頁按鈕
+- 新增「物品資訊卡」側欄
+  - 顯示獲取方式（製作/採集/商店/雇員探險）
+  - 顯示用途（製作材料/部隊工房/理符/軍票）
+  - 裝備屬性（職業/傷害/防禦/屬性加成）
+  - 外部連結（Universalis/Teamcraft/Garland Tools）
+- 價格走勢圖新增異常值標註
+  - 自動檢測異常低價/高價
+  - 以 ⚠️ 標記並保留原始數據
+
+### v1.7.2 (2025-01)
+- 即時追蹤新增「資料流狀態」圖表
+- 顯示各伺服器最後收到資料的時間
+- 以顏色標示資料新鮮度（綠/黃/橙/紅）
+- 讓使用者了解資料延遲來源
+
+### v1.7.1 (2025-01)
+- 新增「即時追蹤」功能
+- 顯示繁中服正在發生的市場交易（上架、售出）
+- 數據由 Universalis WebSocket 即時推送
+- 支援自動刷新（3秒）
+
+### v1.7.0 (2025-01)
+- 介面美化：採用 Gradio Soft 主題
+- 新增金色漸層頁首設計
+- 伺服器標籤視覺化呈現
+- 圖表配色優化（NQ 藍灰色、HQ 琥珀金色）
+
+### v1.6.1 (2025-01)
+- 收藏品時間表新增「老主顧」NPC 資訊
+- 顯示對應等級範圍的老主顧名稱與位置座標
+- 新增「老主顧位置一覽」快速參考表
+
+### v1.6.0 (2025-01)
+- 新增「收藏品時間表」功能
+- 顯示大地使者（採礦工、園藝工、捕魚人）收藏品採集時間
+- 即時 ET（艾歐澤亞時間）顯示
+- 顯示目前可採集和即將出現的收藏品
+- 包含採集地點、座標、工票獎勵
+- 資料自動快取，支援強制刷新
+
+### v1.5.0 (2024-12)
+- 新增「購物助手」功能
+- 購物清單：輸入多個物品，計算各伺服器總價，找最便宜的購買方案
+- 雇員銷售建議：分析銷售速度與價格，推薦值得上架的物品
+
+### v1.4.0 (2024-12)
+- 新增「製作利潤」功能
+- 計算製作成本 vs 市場售價
+- 遞迴計算材料成本（比較買 vs 自己做）
+- 賺錢排行榜：動態掃描最近交易物品
+- 職業篩選（木工、鍛冶、裁縫、烹調等）
+
+### v1.3.0 (2024-12)
+- 改用 WebSocket 驅動實時更新
+- 首次查詢用 REST API，之後用 WebSocket 緩存
+- 自動刷新改為 5 秒（使用緩存時幾乎無延遲）
+- 物品資訊與市場數據並行請求
+
+### v1.2.0 (2024-12)
+- 新增 AI 分析功能
+- 支援跨服套利判斷
+- 手機版面優化
+
+### v1.1.0 (2024-12)
+- 新增監看清單功能
+- 支援設定目標價格提醒
+- 資料儲存於瀏覽器 LocalStorage
+
+### v1.0.0 (2024-12)
+- 首次發布
+- 支援繁體中文搜尋物品
+- 市場價格查詢、交易紀錄
+- 跨伺服器比價
+- 稅率資訊、上傳統計
+
+---
+資料來源: [Universalis API](https://universalis.app/)
+"""

src/charts.py

@@ -71,6 +71,27 @@ def _normalize_timestamp(timestamp: int) -> int:
     return timestamp
 
 
+def _detect_outliers(prices: list) -> tuple:
+    """使用 IQR 方法檢測異常值.
+
+    Returns:
+        (lower_bound, upper_bound) 正常價格範圍
+    """
+    if len(prices) < 4:
+        return (0, float('inf'))
+
+    sorted_prices = sorted(prices)
+    n = len(sorted_prices)
+    q1 = sorted_prices[n // 4]
+    q3 = sorted_prices[3 * n // 4]
+    iqr = q3 - q1
+
+    lower_bound = q1 - 1.5 * iqr
+    upper_bound = q3 + 1.5 * iqr
+
+    return (max(0, lower_bound), upper_bound)
+
+
 def create_price_chart(market_data: dict, item_name: str) -> go.Figure:
     """建立價格歷史圖表.
 
@@ -114,8 +135,15 @@ def create_price_chart(market_data: dict, item_name: str) -> go.Figure:
         if not e.get("hq")
     ]
 
+    # 檢測異常值
+    all_prices = [e["pricePerUnit"] for e in entries]
+    lower_bound, upper_bound = _detect_outliers(all_prices)
+
     fig = go.Figure()
 
+    # 收集異常值用於標註
+    outliers = []
+
     if nq_data:
         nq_times, nq_prices = zip(*sorted(nq_data))
         fig.add_trace(go.Scatter(
@@ -134,6 +162,10 @@ def create_price_chart(market_data: dict, item_name: str) -> go.Figure:
             },
             hovertemplate="<b>NQ</b><br>價格: %{y:,.0f} Gil<br>時間: %{x}<extra></extra>",
         ))
+        # 找出 NQ 異常值
+        for t, p in zip(nq_times, nq_prices):
+            if p < lower_bound or p > upper_bound:
+                outliers.append((t, p, "NQ"))
 
     if hq_data:
         hq_times, hq_prices = zip(*sorted(hq_data))
@@ -154,6 +186,35 @@ def create_price_chart(market_data: dict, item_name: str) -> go.Figure:
             },
             hovertemplate="<b>HQ ★</b><br>價格: %{y:,.0f} Gil<br>時間: %{x}<extra></extra>",
         ))
+        # 找出 HQ 異常值
+        for t, p in zip(hq_times, hq_prices):
+            if p < lower_bound or p > upper_bound:
+                outliers.append((t, p, "HQ"))
+
+    # 標註異常值
+    for t, p, quality in outliers:
+        if p < lower_bound:
+            label = "異常低價"
+            color = "#ff6b6b"
+        else:
+            label = "異常高價"
+            color = "#ffd93d"
+
+        fig.add_annotation(
+            x=t,
+            y=p,
+            text=f"⚠️ {label}",
+            showarrow=True,
+            arrowhead=2,
+            arrowsize=1,
+            arrowwidth=2,
+            arrowcolor=color,
+            font={"color": color, "size": 10},
+            bgcolor="rgba(0,0,0,0.7)",
+            bordercolor=color,
+            borderwidth=1,
+            borderpad=3,
+        )
 
     fig.update_layout(
         **CHART_LAYOUT,

src/config.py

@@ -58,3 +58,57 @@ POPULAR_ITEMS = {
 # API 請求超時時間（秒）
 API_TIMEOUT = 10
 MARKET_API_TIMEOUT = 15
+
+# 物品搜尋分類 (ItemSearchCategory)
+# 大分類 ID
+ITEM_MAIN_CATEGORIES = {
+    0: "全部",
+    1: "武器",
+    2: "製作工具",
+    3: "採集工具",
+    4: "防具",
+    5: "飾品",
+    6: "藥品食品",
+    7: "素材",
+    8: "其他",
+}
+
+# 子分類對應（大分類 ID -> 子分類列表）
+ITEM_SUB_CATEGORIES = {
+    1: {  # 武器
+        9: "格鬥武器", 10: "劍", 11: "斧", 12: "弓", 13: "長槍",
+        14: "咒杖", 15: "幻杖", 16: "魔導書", 17: "盾", 18: "投擲武器",
+        73: "雙劍", 76: "雙手劍", 77: "火槍", 78: "天球儀",
+        83: "武士刀", 84: "刺劍", 85: "魔導書(學者)", 86: "槍刃",
+        88: "雙手鐮刀", 89: "賢具", 91: "蝰蛇對劍", 92: "畫筆",
+    },
+    2: {  # 製作工具
+        19: "刻木工具", 20: "鍛鐵工具", 21: "鑄甲工具", 22: "雕金工具",
+        23: "製革工具", 24: "裁衣工具", 25: "煉金工具", 26: "烹調工具",
+    },
+    3: {  # 採集工具
+        27: "採礦工具", 28: "園藝工具", 29: "捕魚用具", 30: "釣餌",
+    },
+    4: {  # 防具
+        31: "頭部防具", 32: "內衣", 33: "身體防具", 34: "內褲",
+        35: "腿部防具", 36: "手部防具", 37: "腳部防具", 38: "腰部防具",
+    },
+    5: {  # 飾品
+        39: "項鏈", 40: "耳飾", 41: "手鐲", 42: "戒指",
+    },
+    6: {  # 藥品食品
+        43: "藥品", 44: "食材", 45: "食品", 46: "水產品",
+    },
+    7: {  # 素材
+        47: "石材", 48: "金屬", 49: "木材", 50: "布料",
+        51: "皮革", 52: "骨材", 53: "煉金原料", 54: "染料", 55: "部件",
+    },
+    8: {  # 其他
+        56: "一般傢俱", 57: "魔晶石", 58: "水晶", 59: "觸媒", 60: "雜貨",
+        61: "靈魂水晶", 62: "箭", 65: "室外建材", 66: "室內建材",
+        67: "庭具", 68: "椅子睡床", 69: "桌台", 70: "桌上",
+        71: "壁掛", 72: "地毯", 74: "雜貨(季節)", 75: "寵物",
+        79: "飛空艇/潛水艇部件", 80: "管弦樂琴", 81: "栽培用品", 82: "繪畫作品",
+        90: "雜貨(學習/收錄)",
+    },
+}

src/display.py

@@ -38,36 +38,61 @@ from .utils import (
 )
 
 
-def search_and_display(query: str) -> tuple:
+def search_and_display(query: str, category: int = 0, page: int = 1) -> tuple:
     """搜尋並顯示結果.
 
     Args:
         query: 搜尋關鍵字
+        category: 物品分類 ID (ItemSearchCategory)，0 表示全部
+        page: 頁碼
 
     Returns:
-        (下拉選單更新, 狀態訊息, None)
+        (下拉選單更新, 狀態訊息, None, 頁碼, 總頁數)
     """
-    if not query:
+    # 如果沒有搜尋關鍵字且沒有選擇分類，顯示常用物品
+    if not query and category == 0:
         choices = [(name, item_id) for name, item_id in POPULAR_ITEMS.items()]
         return (
             gr.update(choices=choices, value=None),
             "顯示常用物品，或輸入物品名稱/ID搜尋",
             None,
+            1,  # 當前頁
+            1,  # 總頁數
         )
 
-    results = search_items(query)
-    if not results:
+    # 有分類時，即使沒有關鍵字也進行搜尋（使用空白作為萬用搜尋）
+    search_query = query if query else " "
+    result = search_items(search_query, category=category, page=page)
+    items = result.get("items", [])
+    pagination = result.get("pagination", {})
+
+    current_page = pagination.get("page", 1)
+    total_pages = pagination.get("page_total", 1)
+    total_results = pagination.get("results_total", 0)
+
+    if not items:
         return (
             gr.update(choices=[], value=None),
             "找不到符合的物品。提示：可直接輸入物品 ID",
             None,
+            1,
+            1,
         )
 
-    choices = [(f"{r['name']} (ID:{r['id']})", r["id"]) for r in results]
+    choices = [(f"{r['name']} (ID:{r['id']})", r["id"]) for r in items]
+
+    # 狀態訊息顯示分頁資訊
+    if total_pages > 1:
+        status = f"共 {total_results} 個結果，第 {current_page}/{total_pages} 頁"
+    else:
+        status = f"找到 {total_results} 個結果"
+
     return (
         gr.update(choices=choices, value=None),
-        f"找到 {len(results)} 個結果",
+        status,
         None,
+        current_page,
+        total_pages,
     )
 
 
@@ -86,13 +111,13 @@ def display_item_market(
         retainer_filter: 雇員名稱篩選
 
     Returns:
-        (物品資訊, 上架列表, 交易歷史, 價格圖表, 比價表格, 比價圖表)
+        (物品資訊, 物品卡片, 上架列表, 交易歷史, 價格圖表, 比價表格, 比價圖表)
     """
     empty_df = pd.DataFrame()
     empty_fig = go.Figure()
 
     if not item_selection:
-        return "", empty_df, empty_df, empty_fig, empty_df, empty_fig
+        return "", "", empty_df, empty_df, empty_fig, empty_df, empty_fig
 
     item_id = item_selection
     world_query = (
@@ -136,6 +161,7 @@ def display_item_market(
     if not market_data:
         return (
             f"## {item_name}\n\n無法取得市場數據",
+            "",
             empty_df,
             empty_df,
             empty_fig,
@@ -193,10 +219,222 @@ def display_item_market(
 | 日銷售量 | {sale_velocity:.1f} |
 
 *最後更新: {last_update}*
+"""
+
+    # 建立物品資訊卡
+    # 取得物品描述
+    item_desc = item_info.get("Description", "")
+    if item_desc:
+        # 截斷過長的描述
+        if len(item_desc) > 150:
+            item_desc = item_desc[:150] + "..."
+
+    # 判斷是否可交易
+    is_untradable = item_info.get("IsUntradable", False)
+    tradable_text = "❌ 不可交易" if is_untradable else "✅ 可交易"
+
+    # 堆疊上限
+    stack_size = item_info.get("StackSize", 1)
+
+    # NPC 售價（賣給商店的價格）
+    vendor_price = item_info.get("PriceLow", 0)
+
+    # ClassJob ID 對應表
+    craft_job_names = {
+        8: "刻木匠", 9: "鍛鐵匠", 10: "鑄甲匠", 11: "雕金匠",
+        12: "製革匠", 13: "裁縫師", 14: "煉金術士", 15: "烹調師",
+    }
+
+    # 職業縮寫對應表
+    job_abbr_names = {
+        "PLD": "騎士", "WAR": "戰士", "DRK": "暗黑騎士", "GNB": "絕槍戰士",
+        "WHM": "白魔法師", "SCH": "學者", "AST": "占星術士", "SGE": "賢者",
+        "MNK": "武僧", "DRG": "龍騎士", "NIN": "忍者", "SAM": "武士", "RPR": "鐮刀師", "VPR": "蝰蛇劍士",
+        "BRD": "吟遊詩人", "MCH": "機工士", "DNC": "舞者",
+        "BLM": "黑魔法師", "SMN": "召喚師", "RDM": "赤魔法師", "PCT": "繪靈法師",
+        "PGL": "格鬥家", "GLA": "劍術師", "MRD": "斧術師", "LNC": "槍術師",
+        "ARC": "弓箭手", "ROG": "雙劍師", "THM": "咒術師", "ACN": "秘術師", "CNJ": "幻術師",
+        "CRP": "刻木匠", "BSM": "鍛鐵匠", "ARM": "鑄甲匠", "GSM": "雕金匠",
+        "LTW": "製革匠", "WVR": "裁縫師", "ALC": "煉金術士", "CUL": "烹調師",
+        "MIN": "採礦工", "BTN": "園藝工", "FSH": "捕魚人",
+        "BLU": "青魔法師",
+    }
+
+    # === A. 獲取方式 ===
+    obtain_methods = []
+    gcl = item_info.get("GameContentLinks", {})
+    if not isinstance(gcl, dict):
+        gcl = {}
+
+    # 可製作
+    recipes = item_info.get("Recipes", [])
+    if recipes:
+        craft_jobs = []
+        for recipe in recipes[:2]:
+            job_id = recipe.get("ClassJobID", 0)
+            job_name = craft_job_names.get(job_id, "")
+            level = recipe.get("Level", 0)
+            if job_name:
+                craft_jobs.append(f"{job_name} Lv.{level}")
+        if craft_jobs:
+            obtain_methods.append(f"🔨 製作: {', '.join(craft_jobs)}")
+
+    # 可採集
+    if gcl.get("GatheringItem"):
+        obtain_methods.append("⛏️ 採集")
+
+    # NPC 商店
+    if gcl.get("GilShopItem"):
+        npc_price = item_info.get("PriceMid", 0)
+        if npc_price > 0:
+            obtain_methods.append(f"🏪 NPC 商店: {npc_price:,} Gil")
+        else:
+            obtain_methods.append("🏪 NPC 商店")
+
+    # 雇員探險
+    if gcl.get("RetainerTaskNormal"):
+        obtain_methods.append("📦 雇員探險")
+
+    obtain_text = "\n".join(obtain_methods) if obtain_methods else "（無資料）"
+
+    # === B. 用途資訊 ===
+    usage_methods = []
+
+    # 作為製作材料
+    recipe_links = gcl.get("Recipe", {})
+    ingredient_keys = [k for k in recipe_links.keys() if k.startswith("ItemIngredient")]
+    if ingredient_keys:
+        total_recipes = sum(len(recipe_links[k]) for k in ingredient_keys)
+        usage_methods.append(f"🔧 製作材料 ({total_recipes} 個配方)")
+
+    # 軍隊製作
+    if gcl.get("CompanyCraftSupplyItem"):
+        usage_methods.append("🏠 部隊工房材料")
+
+    # 理符任務
+    if gcl.get("CraftLeve") or gcl.get("LeveRewardItemGroup"):
+        usage_methods.append("📋 理符任務")
+
+    # 軍票上交
+    if gcl.get("GCSupplyDuty"):
+        usage_methods.append("🎖️ 軍票上交")
+
+    usage_text = "\n".join(usage_methods) if usage_methods else "（無資料）"
+
+    # === C. 裝備屬性 ===
+    equip_text = ""
+    equip_level = item_info.get("LevelEquip", 0)
+    damage_phys = item_info.get("DamagePhys", 0)
+    damage_mag = item_info.get("DamageMag", 0)
+    defense_phys = item_info.get("DefensePhys", 0)
+    defense_mag = item_info.get("DefenseMag", 0)
+
+    # 檢查是否為裝備（必須有傷害/防禦或裝備槽位）
+    equip_slot = item_info.get("EquipSlotCategory") or {}
+    is_equipment = (
+        damage_phys > 0 or damage_mag > 0 or
+        defense_phys > 0 or defense_mag > 0 or
+        equip_slot.get("MainHand") or equip_slot.get("OffHand") or
+        equip_slot.get("Head") or equip_slot.get("Body") or
+        equip_slot.get("Gloves") or equip_slot.get("Legs") or
+        equip_slot.get("Feet") or equip_slot.get("Ears") or
+        equip_slot.get("Neck") or equip_slot.get("Wrists") or
+        equip_slot.get("FingerL") or equip_slot.get("FingerR")
+    )
+
+    if is_equipment:
+        equip_lines = [f"**裝備等級:** Lv.{equip_level}"]
+
+        # 職業限制
+        cjc = item_info.get("ClassJobCategory") or {}
+        jobs = [job_abbr_names.get(k, k) for k, v in cjc.items()
+                if v == 1 and not k.endswith("Target") and k != "ID" and k in job_abbr_names]
+        if jobs:
+            if len(jobs) > 5:
+                equip_lines.append(f"**職業:** {', '.join(jobs[:5])} 等 {len(jobs)} 職業")
+            else:
+                equip_lines.append(f"**職業:** {', '.join(jobs)}")
+
+        # 武器傷害
+        if damage_phys > 0 or damage_mag > 0:
+            if damage_phys > damage_mag:
+                equip_lines.append(f"⚔️ 物理傷害: {damage_phys}")
+            else:
+                equip_lines.append(f"✨ 魔法傷害: {damage_mag}")
+
+        # 防具防禦
+        if defense_phys > 0 or defense_mag > 0:
+            equip_lines.append(f"🛡️ 防禦: {defense_phys} / 魔防: {defense_mag}")
+
+        # 屬性加成
+        stats = []
+        for i in range(6):
+            param = item_info.get(f"BaseParam{i}Target")
+            value = item_info.get(f"BaseParamValue{i}", 0)
+            if param and value:
+                # param 可能是字典或字串
+                if isinstance(param, dict):
+                    name = param.get("Name", "")
+                else:
+                    name = str(param) if param else ""
+                if name:
+                    stats.append(f"{name} +{value}")
+        if stats:
+            equip_lines.append(f"📊 {', '.join(stats[:4])}")
+
+        equip_text = "\n".join(equip_lines)
+
+    # 組合物品資訊卡
+    item_card = f"""### 🏷️ 物品資訊
+**物品 ID:** `{item_id}` | 📦 堆疊: {stack_size}
+
+{tradable_text}
+{f"💰 NPC 售價: {vendor_price:,} Gil" if vendor_price > 0 else ""}
+"""
+
+    # 裝備屬性（如果是裝備）
+    if equip_text:
+        item_card += f"""
+---
+### ⚔️ 裝備屬性
+{equip_text}
+"""
+
+    # 獲取方式
+    item_card += f"""
+---
+### 📍 獲取方式
+{obtain_text}
+"""
+
+    # 用途資訊
+    if usage_methods:
+        item_card += f"""
+---
+### 📦 用途
+{usage_text}
+"""
+
+    # 外部連結
+    item_card += f"""
+---
+### 🔗 外部連結
+- [Universalis](https://universalis.app/market/{item_id})
+- [Teamcraft](https://ffxivteamcraft.com/db/zh/item/{item_id})
+- [Garland Tools](https://garlandtools.org/db/#item/{item_id})
+"""
+
+    # 物品說明
+    if item_desc:
+        item_card += f"""
+---
+### 📜 說明
+*{item_desc}*
 """
 
     return (
         info_text,
+        item_card,
         listings_df,
         history_df,
         price_chart,

src/styles.py

@@ -0,0 +1,97 @@
+"""自訂 CSS 樣式."""
+
+CUSTOM_CSS = """
+/* 頁首樣式 */
+.header-box {
+    background: linear-gradient(135deg, #b8860b 0%, #daa520 50%, #b8860b 100%);
+    border-radius: 12px;
+    padding: 20px 24px;
+    margin-bottom: 16px;
+}
+
+.header-box h1 {
+    color: #1a1a2e !important;
+    margin: 0 0 8px 0 !important;
+}
+
+.header-box p {
+    color: #2c2c2c !important;
+    margin: 4px 0 !important;
+}
+
+.header-box a {
+    color: #1a1a2e !important;
+    font-weight: 700;
+    text-decoration: underline;
+}
+
+/* 伺服器標籤 */
+.server-tags {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 6px;
+    margin-top: 10px;
+}
+
+.server-tag {
+    background: rgba(0,0,0,0.2);
+    color: #1a1a2e;
+    padding: 4px 10px;
+    border-radius: 12px;
+    font-size: 0.8em;
+    font-weight: 600;
+}
+
+/* 狀態標籤 */
+.status-badge {
+    display: inline-block;
+    background: #27ae60;
+    color: #ffffff;
+    padding: 6px 12px;
+    border-radius: 20px;
+    font-size: 0.85em;
+    margin-top: 12px;
+    font-weight: 500;
+}
+
+/* 分類 Radio 按鈕群組樣式 */
+.category-radio {
+    margin: 8px 0;
+}
+
+.category-radio .wrap {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 6px;
+}
+
+.category-radio label {
+    padding: 6px 14px !important;
+    border: 1px solid var(--border-color-primary) !important;
+    border-radius: 8px !important;
+    background: var(--background-fill-secondary) !important;
+    cursor: pointer;
+    transition: all 0.2s ease;
+    font-size: 0.9em;
+}
+
+.category-radio label:hover {
+    background: var(--background-fill-primary) !important;
+    border-color: var(--color-accent) !important;
+}
+
+.category-radio input[type="radio"]:checked + span {
+    background: var(--color-accent) !important;
+    color: #1a1a2e !important;
+    border-color: var(--color-accent) !important;
+    font-weight: 600;
+}
+
+/* Gradio 5 相容 */
+.category-radio .selected {
+    background: var(--color-accent) !important;
+    color: #1a1a2e !important;
+    border-color: var(--color-accent) !important;
+    font-weight: 600;
+}
+"""