重構：將爬蟲層抽出成純 Dart 套件 nkust_crawler

[abc873693]

摘要

把 lib/api/、lib/models/、lib/utils/eucdist.dart、lib/utils/captcha_utils.dart 整套抽到新建的純 Dart 套件 packages/nkust_crawler/。merge 之後這個套件可以單獨 dart test（不需要 Flutter SDK）、可以 server-side 拿來用、也能給未來的 native 客戶端共用。

• 記錄了 63 個 git rename，分散在 5 個 phase commit（用 -c diff.renames=true log --diff-filter=R 可以看到）
• lib/api/ shim 檔：0 個 — 所有 consumer（pages / widgets / extensions / tests）在搬檔的同一個 commit 直接改 import 為 package:nkust_crawler/nkust_crawler.dart。lib/api/exceptions/api_exception_l10n.dart 是唯一留下的，因為它依賴 BuildContext + NkustLocalizations
• 5 個 dependency injection 介面 讓套件能維持 Flutter-free：CrashReporter、KeyValueStore、CaptchaSolver + CaptchaTemplateProvider、PdfTextExtractor。Host adapter 放在 lib/integrations/crawler/，由 main.dart 的 bootstrapCrawler() 一次接好

規模

• 改動 133 個檔案（+3019 / −639）。新增的部分大多是套件 skeleton + 測試代碼；主 app 的程式碼淨變動很小
• 最終 33 個 commit
• Commit 分組（Phase 0 cleanup + master merge 之後）：
  1. Package skeleton + git mv crash_reporter
  2. 資料層（exceptions、session、registry、capabilities、models）
  3. Parser（5 個檔）+ build_mode.dart（純 Dart kDebugMode shim）
  4. Helper + facade + CaptchaSolver / PdfTextExtractor 注入點
  5. Captcha（eucdist、captcha_utils → captcha_solver_impl）
  6. bootstrapCrawler() 集中 wiring
  7. 測試 + 後續修補（live integration test 架構、getSemesters 加 antiforgery、wall-clock 學期 helper、fixture 更新）

架構說明

packages/nkust_crawler/ — 純 Dart，依賴只有 ap_common_core、dio、cookie_jar、html、http、http_parser、image、intl、json_annotation、sprintf。沒有 Flutter、Firebase、ImagePicker、native_dio_adapter、syncfusion。

Host 端 adapter（在 lib/integrations/crawler/）：

• firebase_crash_reporter.dart — CrashReporter 接 Firebase
• preference_util_key_value_store.dart — KeyValueStore 接 PreferenceUtil
• asset_captcha_template_provider.dart — CaptchaTemplateProvider 接 rootBundle
• syncfusion_pdf_text_extractor.dart — PdfTextExtractor 接 syncfusion_flutter_pdf（這套 transitively 依賴 dart:ui，所以需要這個介面隔離）
• crawler_bootstrap.dart — 整合所有 wiring 的單一進入點，main.dart 啟動時呼叫

有持久化狀態的 model（bus_reservations_data、crawler_selector、leave_data）的 save / load 走 crawlerStorage，bootstrap 時用 PreferenceUtilKeyValueStore 接起來。

驗證

檢查	結果
flutter analyze lib/	0 errors
flutter test test/	37 pass / 1 skip / 0 fail
cd packages/nkust_crawler && dart analyze	0 errors / 0 warnings
cd packages/nkust_crawler && dart test	14 pass（hermetic，不需要 Flutter SDK）
dart test -P live-anonymous	真站 acad.nkust.edu.tw + 6 個 health check endpoint 全部通過
dart test -P live（帶 NKUST_USER / NKUST_PASS）	login + getUserInfo + getSemester + getCourseTables 對真站通過；getScores 故意 skip（PDF 解析需要 Flutter 綁定的 syncfusion）

CI 整合（順手解掉 #331）

Issue #331「方案 B 定期 cron 監控」原本因為原生相依（native_dio_adapter、syncfusion、image_picker）跑不起來，這個 PR 順便修：

• crawler-monitor.yml：flutter test → cd packages/nkust_crawler && dart test -P live，secrets 對應，subosito/flutter-action → dart-lang/setup-dart
• ci.yml：加 package 的 dart analyze + dart test、移除 flutter test \|\| true 的 \|\| true（讓 main test 失敗也擋 PR）
• 刪除 test/crawler_monitor_test.dart — coverage 全部搬到 packages/nkust_crawler/test/live/{health_check,notifications,authenticated}_live_test.dart

文件

docs/ 下新增兩份：

• crawler-package-migration-plan.md — 這個 PR 的逐步實作計畫
• extracting-flutter-crawler-as-dart-package.md — 通用版 cookbook，給之後其他專案做類似抽取時參考，省掉重複調查

測試計畫

• iOS flutter run — 登入 + 抓課表 + 抓成績 smoke test（驗 native_dio_adapter 注入 + stdsys SSO 還能跑）
• Android flutter run — 同上
• flutter build web — 確認沒裝 NativeAdapter 的 fallback path 也能跑基本匿名 endpoint
• 校車預約建立 / 取消 — 手動測試（寫入路徑刻意不在 live test 裡）
• 請假上傳照片 — 手動測試（XFile→bytes-tuple 改動有碰到這條路徑）

未來工作（不在本次 PR 範圍）

• getRoomList、getRoomCourseTables、getEnrollmentLetter、getRewardAndPenalty、getMidtermAlerts 加進 live integration test（read-only，風險低）
• Helper.username / Helper.password 靜態欄位拿掉，把 Helper 改成 instance-based（reviewer 已點到 cacheSaveTag 用到這個 static field）
• 套件穩定後 publish nkust_crawler 到 pub.dev

[github-actions]

Failed to generate code suggestions for PR

[gemini-code-assist]

Code Review

This pull request extracts the NKUST crawler logic into a standalone pure-Dart package, nkust_crawler, to facilitate code reuse across different platforms. The refactoring involves moving core business logic, models, and parsers to the new package while introducing abstraction interfaces for host-side dependencies like storage and crash reporting. Feedback focuses on consolidating redundant imports across several page files, using dynamic filenames instead of hardcoded strings for proof image uploads, and refactoring extension methods to remove dependencies on static global state for improved maintainability.

[gemini-code-assist]

There are multiple redundant imports of package:nkust_crawler/nkust_crawler.dart. Please consolidate them into a single import statement to improve code clarity and maintainability.

Suggested change

	import 'package:nkust_crawler/nkust_crawler.dart';
	import 'package:nkust_crawler/nkust_crawler.dart';
	import 'package:nkust_crawler/nkust_crawler.dart';
	import 'package:nkust_crawler/nkust_crawler.dart';

[gemini-code-assist]

The filename for the proof image is hardcoded as 'proof_image.jpg'. It would be more robust to use the original filename from the XFile object via image.name, as XFile provides this information.

Suggested change

	filename: 'proof_image.jpg',
	filename: image.name,

[gemini-code-assist]

There are multiple redundant imports of package:nkust_crawler/nkust_crawler.dart. Please consolidate them into a single import statement to improve code clarity.

Suggested change

	import 'package:nkust_crawler/nkust_crawler.dart';
	import 'package:nkust_crawler/nkust_crawler.dart';
	import 'package:nkust_ap/api/exceptions/api_exception_l10n.dart';
	import 'package:nkust_ap/api/stdsys_helper.dart';
	import 'package:nkust_crawler/nkust_crawler.dart';
	import 'package:nkust_crawler/nkust_crawler.dart';
	import 'package:nkust_ap/api/exceptions/api_exception_l10n.dart';

[gemini-code-assist]

There are multiple redundant imports of package:nkust_crawler/nkust_crawler.dart. Please consolidate them into a single import statement to improve code clarity.

Suggested change

	import 'package:nkust_ap/api/exceptions/api_exception_l10n.dart';
	import 'package:nkust_ap/api/helper.dart';
	import 'package:nkust_crawler/nkust_crawler.dart';
	import 'package:nkust_ap/config/constants.dart';
	import 'package:nkust_crawler/nkust_crawler.dart';
	import 'package:nkust_ap/api/exceptions/api_exception_l10n.dart';

[gemini-code-assist]

There are multiple redundant imports of package:nkust_crawler/nkust_crawler.dart. Please consolidate them into a single import statement to improve code clarity.

Suggested change

	import 'package:nkust_crawler/nkust_crawler.dart';
	import 'package:nkust_ap/api/exceptions/api_exception_l10n.dart';
	import 'package:nkust_ap/api/helper.dart';
	import 'package:nkust_ap/models/room_data.dart';
	import 'package:nkust_crawler/nkust_crawler.dart';
	import 'package:nkust_crawler/nkust_crawler.dart';
	import 'package:nkust_ap/api/exceptions/api_exception_l10n.dart';

[gemini-code-assist]

This extension method relies on the static field Helper.username. Using static fields for user-specific data can be problematic, especially in scenarios involving user logout and login. While the PR description notes this as future work, consider making this dependency explicit to improve maintainability. For example, the method could accept the username as a parameter: String cacheSaveTag(String username) => '${username}_$code';