FULLI · OPERATOR HANDBOOK

從會開網站，
到能安心使用與維運

這是一套放在你電腦上的日本精緻小團情報系統。依照本手冊做，你會知道它何時在工作、哪些資料要手動更新，以及哪些操作需要交給維運人員。

開啟目前使用站我今天第一次用我要關閉系統

依實際程式及設定查核：2026-10-25。排程狀態可能被你之後的操作改變，請以畫面或 status.cmd 的當下結果為準。本頁可離線閱讀；列印請按 Ctrl＋P，折疊內容可先逐一展開。

00　先記住這三件事

電腦上的應用程式

關網頁 ≠ 關系統

網頁是操作面板；真正抓資料的是電腦裡的 Python 主程式。瀏覽器可以關，但主程式停止就不會採集。

部分自動

有排程，也有手動來源

目前18743的四站觀測已啟用8／24小時排程；新增聲量、匯率、警示等，仍需手動按更新。

保留使用中的資料

「驗證站」不是垃圾桶

你一直使用的18743有自己的帳戶、研究單及匯入資料。不能因為名稱有QA、驗證就刪掉。

兩個網址各自代表什麼？

網址用途與目前狀態資料位置
127.0.0.1:18743你保留操作的驗證站；本次查核服務正常，四站定時觀測已啟用。建議日常先固定使用這站。runtime\ui-qa\
127.0.0.1:18742獨立主工作區；本次查核服務正常，尚未設定定時觀測。帳號及資料與18743分開。runtime\ 下的主工作區資料，與其中的 ui-qa 分開處理
主站與驗證站的登入已按工作區隔離。1.2.0起使用不同Cookie名稱，避免同一瀏覽器登入兩站互相覆蓋。從舊版升級後需要用原帳密重新登入；帳戶及資料仍分開保存。

系統位置：D:\tool\ai_dev\trip_AI\1023.旅遊雷達\。127.0.0.1 的意思是「目前這台電腦」，不是同事或手機也能直接使用的公開網址。

01　第一次開啟：照這個順序

1

先試著開網站

在這台電腦的瀏覽器輸入 http://127.0.0.1:18743/。如果已出現登入畫面或儀表板，直接使用，不必再啟動一次。

成功標準：看得到登入畫面，或「經營與行銷總覽」。

2

網站開不起來時，再啟動18743

開啟檔案總管，把上面的系統資料夾路徑貼到位址列，雙擊 start-qa.cmd。看到 Ready 或 Already running 表示服務已啟動或原本就在運作。

這個啟動器會把18743放在背景。按任意鍵關閉啟動器，不會停止已啟動的服務。若顯示失敗、埠被占用或缺少Python，先看錯誤，不要連續開很多次。

3

登入你原有的帳號

18743可沿用原驗證帳號 ui-review 與原密碼。不要使用教學或測試程式建立的帳戶。18742第一次使用若要求建立帳號，需在該工作區獨立建立，密碼至少12字元。

重啟服務會要求重新登入，這不代表密碼或研究單被刪除。帳密錯誤時不要刪 users.json 來重置。

4

雙擊只讀狀態檢查

在系統資料夾雙擊 status.cmd，可查看兩站是否連得上、部分排程是否啟用、Python版本及磁碟剩餘。這個工具不會啟停服務、抓外站、啟用排程或清理資料。

「程式可連線」只代表程式在運作；各個來源是否成功，要登入網站看來源頁。

什麼時候才用 start.cmd、bootstrap.ps1？
  • start.cmd：開18742主工作區。它是前景黑視窗，要保留視窗；關閉視窗會停止這一站。
  • bootstrap.ps1：初次安裝或移機後重建Python環境。不是每天開機要跑的程式。
  • scripts 裡的 acceptance、test、install 等程式是工程工具，不是一般啟動器，請勿自行試跑。

02　每天先用這條路線，約5～10分鐘

核對資料日期→必要時更新來源→看同口徑趨勢→點地區查證據→保存小團研究→以詢單驗證
  1. 先看「經營與行銷總覽」。確認正在使用正式觀測，並看每項指標的資料月份、單位及可用狀態。
  2. 到「來源與資料補充」看日期與失敗原因。需要更新時按一次「更新公開風向來源」，等這次工作結束，不要反覆連點。
  3. 看「趨勢與聲量」。先選來源市場與指標家族，核對本期、比較期及公式。官方住宿、文章閱讀、OTA商品與自家詢單要分開理解。
  4. 看「日本市場地圖」。先選台灣，再選閱讀或住宿圖層，點一個地區看原曲線、原頁與商品對照。灰色代表未取得或未發布，不是零人氣。
  5. 看「小團產品與服務」。閱讀在地依據、反證、核價與行前風向，再保存值得核實的研究單。定位是有人帶團的精緻小團。
  6. 安排下一個人工作業。核對出發日期、人數、車房票、中文帶團、實價、取消條件及容量，再決定內容或詢單測試。保存研究單不等於產品可售或廣告已發布。
  7. 有真實營運結果再匯入。用範本匯入同群組詢單／成熟成效，或去識別的服務滿意度與報價時間。未量測留空，不填0。
看兩個時間：「最近成功取得」表示何時抓到資料；「資料期／公表月份」表示數據談的是哪一天或哪個月。頁面今天重新計算，不會把7月的住宿數字變成今天的需求。
看一次實際地圖與曲線
台灣來源地區的日本文章閱讀觀測地圖，含日期與未發布圖例
2026-10-25驗收畫面；點位是地區代表位置，資料期依圖，不是遊客即時位置。
點北海道後顯示公開閱讀值、資料限制與14日曲線
閱讀公表值含隱私噪音；不能據此宣稱294名旅客，或把短期起伏直接當購買成長。

KPI目標怎麼設定？

在總覽展開「設定經營KPI目標」，填入你想達到的數字，並選目標月份。沒有填月份的數字只作參考；只有目標月份與可用觀測月份一致才會判定達標。成本試算中的售價、人數、匯率是你填的假設，並非富立已發生的收入或報價。

03　「重讀」和「抓新資料」差在哪？

入口／按鈕真正做的事目前是否定時
全域「重新載入」／全日本「重讀結果」重新讀取已保存資料、重算畫面；不向外站取得新情報。不用排程；你需要重讀時按。
經營總覽 → 來源與資料補充 →「更新公開風向來源」官方H.10匯率、Wikipedia閱讀、國家DP閱讀、日本氣象廳、領務局、日本旅客稅費，共6組。手動。四站排程不會順便更新這些。
全日本與四站 →「更新首頁線索」四家OTA固定首頁線索。18743目前每8小時；限已授權觀測範圍。
全日本與四站 →「更新日本資料與商品」四OTA商品觀測，另更新日本住宿、台灣年度出國、官方代表景點。18743目前每24小時。不是整套所有來源，也不保證全目錄。
左側「來源與資料缺口」→「↻ 擷取公開來源」舊管線啟用來源，包括JNTO月度訪日、富立公開商品、RSS及京都／北海道活動等。這個入口另行手動操作；不在上述每日full的全部範圍內。

定時觀測怎麼開、怎麼關？

  1. 登入你日常使用的18743，左側點「全日本與四站動態」。
  2. 頁面上方看「定時觀測：已啟用／未啟用」及下次時間。
  3. 要開按「啟用定時觀測」；要停按「暫停定時觀測」。若沒有按鈕，請由有權限的帳戶處理。
  4. 啟用後是安排下一次時間，不代表立刻抓取；需要當下資料可先手動更新一次。

程式約每30秒檢查是否到期。設定會保存；重新啟動且已過期時，會開始一輪當下更新，再排下一次。不會補造關機期間每天的歷史。全目錄未核實、有效觀測日不足時，單純等待或反覆更新不會自動解鎖所有異動比較。

建議日常頻率（這是操作建議，不是已啟用設定）

  • 每天開始工作：檢查來源日期，手動更新公開風向一次；官方更新有延遲，頻繁按不會變成即時數據。
  • 四站觀測：維持原8／24小時設定即可，不需要每幾分鐘重抓。
  • 月度統計公表或要核對富立公開商品時：另用舊「來源與資料缺口」的擷取入口。
  • 實際核價或出發前：再次閱讀適用官方警示、稅費及供應商資料，不能只依先前儀表板。
  • Google Trends、社群／他站流量、富立實績：按取得的正式匯出與權限匯入；系統不會自己產生。

04　要讓它持續工作，哪些東西要開著？

你做的事對採集的影響
關閉瀏覽器分頁後端仍運作時，已啟用的排程繼續；下次開網頁看結果即可。
鎖定螢幕電腦保持清醒、登入及有網路時，通常可繼續運作。
筆電闔蓋、睡眠、休眠可能停止執行或斷網。要值守時，需確認Windows電源設定；請勿只看螢幕是否亮。
Windows登出、重新啟動、關機本機程序與排程會中斷。此專案尚未安裝開機自動啟動的Windows服務。
關閉18742的前景黑視窗停止該主站。正常停機先等工作完成，再在原視窗按Ctrl＋C。
關閉start-qa.cmd啟動器不會停止它已啟動的隱藏背景18743程序。
關閉目前聊天／Codex不要依賴聊天工作階段作長期託管。本輪工具啟動的程序，在關閉宿主程式後的存續未作保證；請以健康檢查確認，需要時再從檔案總管啟動。
網路斷線或外站回403／429新採集可能失敗，保留前次有效資料並看原因；重讀舊資料仍可能可用。
目前還不是24小時無人值守服務。它沒有完整的Windows服務管理、開機自啟、全部來源排程、失敗通知、磁碟自動輪替及備份還原演練。若要長期無人看管，這些是需補齊的維運工程。

05　正常關閉與下次重開

  1. 先保存工作。研究單、KPI目標或表單若尚未按保存，不要以為已寫入；成本試算也不是實際報價紀錄。
  2. 記下原排程狀態並暫停。進「全日本與四站動態」按「暫停定時觀測」。
  3. 等待工作結束。更新、匯入、保存都完成後再停機。完成、部分完成或失敗都是本輪已結束；更新中／等待中還不能當作結束。
  4. 依啟動方式停止。前景版在原黑視窗按Ctrl＋C；背景版目前沒有專用的一鍵優雅停止按鈕，應由維運人員核對本專案程序後停止。不要把關瀏覽器當停機。
  5. 確認真的停止。用狀態檢查或原健康網址確認該站已無法連線，再進行檔案備份或維護。
請勿在工作管理員「結束全部Python」。同一台電腦可能還有其他系統。背景程序需要核對18743的監聽程序、執行檔與命令內容，無法確認時交給維運人員。
給維運人員：目前背景停止的界線

目前沒有stop腳本、控制面板或對Waitress的優雅關閉接口。即使精準使用程序終止工具，也不等於讓採集工作自行完成；必須先暫停排程、等待寫入與更新結束。本手冊及status工具不會替你終止程序。

可先用系統工具查出18743的監聽PID，再核對完整執行檔及命令；只有確定是此專案後才由維運人員停止。程序查核受Windows權限限制時，不要以全部結束代替。

下次重開

雙擊 start-qa.cmd → 開18743 → 用原帳密登入 → 確認研究單與資料日期 → 手動重試未完成更新 → 原本需要排程時再啟用。

若曾被強制中斷，舊工作可能留著「RUNNING／更新中」文字；目前沒有原工作自動續跑機制。請核對最後成功時間，再由維運人員判斷後重開一輪，不能把舊文字當成它一直在工作。

06　備份、匯出與還原

匯出報表

網站「匯出」方便分析與留存當下結果，沒有包含整套帳戶、設定、全部歷史及檔案，不能取代完整備份。

完整備份

停止寫入後，保存專案程式與全部必要資料。第一次最容易理解的方式是把整個「1023.旅遊雷達」資料夾複製到受控備份位置。

還原演練

把備份放到新的測試位置，實際驗證可啟動、登入、讀圖及找到研究單。只有檔案存在，還不代表備份能救回系統。

第一次備份：照這樣做

  1. 依上一節暫停排程、等待工作完成，停止會寫入的主站與18743。
  2. 在檔案總管複製整個 D:\tool\ai_dev\trip_AI\1023.旅遊雷達\ 到另一個受控位置，例如你實際擁有的備份磁碟。備份資料夾加日期；不要把備份放回被備份的專案裡面。
  3. 至少保留程式、config、fixtures、runtime、evidence、requirements與啟動腳本。runtime 包含主站及巢狀的 ui-qa，不要漏掉其中一站。
  4. 確認備份可讀，記下備份時間、資料來源截止及這次保存了哪些工作。不要立刻刪掉前一份可用備份。
  5. 重開原站並核對，再恢復你需要的排程。

目前沒有正式不停機一致性備份工具。OTA歷史使用SQLite及WAL；服務更新中直接拷貝幾個資料庫／指標檔，可能得到彼此不一致的版本。新手請採停機後完整備份。

備份有敏感資料，也有使用期限。runtime可能含帳戶雜湊、權限、公司營運資料與授權匯入。不要公開分享或上傳公開Git。撤回／到期不會自動清除你手動複製的歷史備份；還原前必須核對期限及撤回清單，不可從舊備份重新啟用已撤回的資料。

還原時的五個檢核

  • 先放新位置驗證，不直接覆蓋目前唯一可用的runtime；同機試跑前先停止原站並確認原埠已釋放，或由維運人員安排隔離埠。
  • 確認啟動的是還原副本的路徑，且18742／18743資料沒有互相蓋過。啟動器顯示Already running可能只是原站還在跑，不能算還原成功。
  • 登入原帳號後，看得到該帳號的研究單、目標及匯入範圍。
  • 資料數量、來源期與備份清冊對得上；缺值及過期來源沒有變成0或假成功。
  • 清理到期／撤回資料、完成試跑後，才決定切換正式使用。

07　Housekeeping：先清點，再封存，最後才清理

它是「整理系統的檔案與歷史」，不是刪掉看起來很大的資料夾。目前沒有全面自動清理工具。本次清點runtime約512 MiB，其中測試資料約365 MiB；這是查核當下的數量，後續以清點結果為準。

類型如何處理
.pytest_cache、__pycache__、pip下載快取、確認已結束的測試暫存通常可重建。先確認沒有安裝、測試或更新工作，由維運人員列清單再處理。
runtime\test* 等工程測試資料夾本次容量大宗。需先保留驗收證據、確認沒有實際營運資料再清；不要用萬用字元整批刪。
舊服務log可以依期間封存壓縮；先保留近期故障紀錄，避免處理正在寫入的檔案。
公開來源快取24小時是「是否重用」規則，不是24小時後自動刪檔。需先核對是否仍作證據／重算依據。
runtime\ui-qa、state、snapshots、national、voice、executive、decisions不要直接刪。可能包含你正在用的帳戶、指標、商品異動、研究單、目標與實際匯入。
SQLite資料庫／WAL、原始證據、current.json及內容指紋命名檔需要引用檢查、受控歸檔與還原驗證，不能只按日期或檔案大小刪除。

「會過期」不一定代表「會自動省磁碟」

  • 來源的TTL或「過舊」門檻，不是全部檔案的自動刪除期限；部分Voice來源目前只保存此宣告，沒有完整的TTL自動提醒。
  • Google Trends／授權聲量時序匯入預設保存30日、最多366日，實際期限依你宣告的使用權。到期清除在讀取／匯入時觸發，服務停著時沒有獨立清理時鐘；富立詢單群組及服務成效匯入沒有同等的自動到期清除機制，需另行管理。
  • 公開證據、OTA歷史、快取及舊快照可能持續增加，沒有全面自動歸檔政策。
  • 畫面只顯示最近幾個工作，不表示舊檔案已刪。部分研究／服務資料有2000筆上限，達上限會拒絕新增，不會自動清掉舊資料。

建議流程：每月清點一次 → 確認備份 → 列出候選檔與理由 → 停止相關寫入 → 先封存 → 驗證網站與研究單 → 再依核定清單清理。只讀清點可由維運人員執行：

.\.venv\Scripts\python.exe -X utf8 scripts\operations_status.py --inventory

08　之後移到另一台電腦

  1. 先選一台當正式寫入主機。記下目前日常用18743或18742、Python版本、帳號、排程狀態及資料期。
  2. 完成停機備份。舊機先暫停排程，等更新完成，停止舊服務；不要讓兩台同時寫自己的版本，再期待自動合併。
  3. 搬專案程式與資料。保留完整資料夾層級，尤其兩站runtime。不要只搬HTML，也不要把QA資料移到主站資料位置。
  4. 新機重建Python環境。本機驗證版本為Python 3.12.14，優先使用同版。搬檔時不要複製舊.venv；若整包備份已含它，先由維運人員把新機副本裡的舊環境移到隔離位置，再在新專案位置執行 bootstrap.ps1 建立新環境。腳本遇到既有.venv會沿用，並不會自動替你重建。
  5. 試跑與驗收。啟動相同站別，重新登入，核對圖表、來源期、原研究單、目標、匯入及原始依據。同機還原須先停止原站並確認啟動路徑；先不要讓兩份副本同時排程。
  6. 完成切換。只在新機恢復你核定的排程；舊機保留為受控備份，避免繼續分頭更新。
移到雲端或讓同事遠端使用，需要另外部署。目前只監聽本機127.0.0.1，且有本機Host檢查。不是改成一個IP、開防火牆或掛tunnel就完成正式多人服務；需另處理HTTPS、帳戶隔離、服務管理、監控、備份與資料權限。

若PowerShell執行政策擋住初始化腳本，請由維運人員確認腳本與執行原則，不要為了啟動而關閉全機安全設定。

09　限制與禁忌：這些不要做

  • 不要把公開關注當成交。閱讀、搜尋、OTA商品、住宿人夜與富立詢單是不同的量；沒有實績不推導利潤。
  • 不要把缺值填0。低量、隱私抑制、未發布、未量測與失敗，要保留原因。
  • 不要把研究單當可售商品。人數、日期、車房票、帶團能力、價格、稅費與取消條件都要核實。
  • 不要只看「最近成功」或頁面產生時間。還要看資料本身的日期與比較口徑。
  • 不要連點更新或繞過403／429／驗證頁。等待來源恢復，或依規格匯入合法取得的資料。
  • 不要把未完成期間硬拿來比較。不同頻率、語言、來源地區、相對指數批次不能直接混算。
  • 不要手改runtime JSON、資料庫或current指標。不要改內容指紋檔名，也不要任意刪WAL。
  • 不要把ui-qa當測試垃圾清除。它是你保留操作站的資料。
  • 不要把密碼、金鑰、姓名、電話或完整對話貼入公開情報匯入。依核准用途用去識別群組資料。
  • 不要任意跑工程驗收／安裝腳本。帳戶、來源範圍及測試資料可能因此改動。
  • 不要隨意改電腦日期。完整期間、資料過舊、期限與排程都依賴正確時鐘。
  • 不要假設已取得所有外部服務。Google Trends、付費社群／他站流量與富立營運資料，目前有取得條件或尚待匯入。

10　遇到問題，先照這張表判斷

看到什麼先做什麼先不要做什麼
網站完全開不起來確認在同一台電腦，執行status.cmd；需要時啟動start-qa.cmd。不要先刪資料、重裝環境或開放外網。
「Already running」直接開18743登入，這通常表示原本已在執行。不要再開多份或結束全部Python。
一直被登出確認是否剛升級或重啟服務，並核對工作區與帳號；再用原帳密登入。不要把資料檔清掉重建帳戶。
研究單突然找不到核對網址18742／18743、登入帳號、篩選及是否真的按保存。不要立即用另一站或舊備份覆蓋現在資料。
有些地區灰色／待量測看資料範圍與原因：可能未涵蓋、未發布、低量或未匯入。不要當作零人氣或系統全部故障。
資料日期沒有變新分清重讀／採集；看來源是否已公表新一期及採集結果。不要把頁面今天的時間當成資料今天已更新。
部分完成、失敗或403／429保留前次資料，看來源原因與最近成功時間；必要時交維運人員查log。不要反覆連點、改代理或繞過驗證。
更新中很久或重啟後仍顯示RUNNING核對最近工作與來源時間；中斷工作可能沒有續跑，由維運人員判斷後重開一輪。不要只靠舊文字認定仍在抓，也不要同時啟動大量工作。
資料庫／快照校驗或JSON錯誤停止自行修改，保留錯誤畫面，備妥時間與操作步驟交維運處理。不要用記事本隨意補欄位或改指紋。

11　你可以照抄的維運清單

每天

  • 站別與帳號正確。
  • 資料期與最近成功時間可理解。
  • 必要時手動更新風向一次。
  • 檢查四站排程及最新工作結果。
  • 研究有保存，未知資料沒有代填。

每週

  • 檢查來源失敗與限流。
  • 固定定義匯入詢單／服務結果。
  • 核對目標月份與資料月份。
  • 安排停機備份；確認可讀。
  • 檢查授權資料期限與撤回。

每月／版本更新前

  • 看官方月度資料是否公表。
  • 清點磁碟、測試資料、log與證據。
  • 由維運人員核定清理名單。
  • 實際做一次還原演練。
  • 檢查來源定義、條款與方法版本。

12　把系統交給別人維運時，要交什麼？

  1. 目前使用網址、站別、專案路徑、Python版本、啟動方式。
  2. 服務是否運行、排程開關、來源範圍、上次成功時間；不要只交「網站正常」四個字。
  3. 帳戶的安全交接方式及權限，不把明文密碼放進公開文件。
  4. 最後完整備份位置、備份日期、還原演練結果及到期／撤回資料清單。
  5. 目前已知限制：新風向未排程、部分外站受阻、沒有一鍵優雅停機／全面自動清理／不停機備份。
  6. 版本更新或移機前後，核對登入、圖表、來源證據、研究單、目標、匯入隔離與成本試算。

長期24小時運作，需補齊的維運能力

  • 單一受管控啟動器、可查狀態的正式常駐服務與安全停機。
  • 逐來源排程、配額與退避，以及可見的失敗通知。
  • 經測試的備份／還原、磁碟容量與歷史歸檔政策。
  • 跨備份的到期／撤回資料管理與還原前核對。
  • 多使用者、跨主機隔離與正式對外部署所需的安全設計；1.2.0已完成本機兩工作區Cookie分開。

本手冊依現行程式與設定撰寫，沒有把上述待補能力宣稱為已完成。網站功能驗收與維運成熟度應分別核對。

本機版本紀錄

目前採本機Git版控，不上傳GitHub。雙擊專案根目錄的 version-history.cmd 查看目前版本、固定基準及未提交修改；它不連外、不切換版本。基準標籤是 baseline-20261025，另有離線版本包。本機Git不包含帳戶、研究單及採集歷史的完整資料備份。