prepare github open-source release

Author: tangtaizong666

.env.example

@@ -1,7 +1,13 @@
 APP_DB_PATH=data/app.db
 PLAYWRIGHT_PROFILE_DIR=data/playwright-profile
 PLAYWRIGHT_BROWSERS_PATH=runtime/ms-playwright
-CTRIP_SNAPSHOT_DIR=tests/fixtures
+CTRIP_SNAPSHOT_DIR=data/debug
+CTRIP_SAVE_DEBUG_SNAPSHOT=0
+CTRIP_DEBUG_SNAPSHOT_DIR=data/debug
 CTRIP_SEARCH_URL_TEMPLATE=https://flights.ctrip.com/online/list/oneway-{origin}-{destination}?depdate={departure_date}&cabin=y_s_c_f&adult=1&child=0&infant=0&containstax=1
 CTRIP_SESSION_URL=https://flights.ctrip.com/online/channel/domestic
 APP_BASE_URL=http://127.0.0.1:8000
+MONITOR_REALERT_COOLDOWN_ENABLED=1
+MONITOR_REALERT_COOLDOWN_HOURS=6
+MONITOR_FAILURE_BACKOFF_MINUTES=5
+CTRIP_AUTO_RELOGIN_COOLDOWN_MINUTES=30

.github/workflows/ci.yml

@@ -0,0 +1,32 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  release-hygiene:
+    runs-on: windows-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -r requirements-dev.txt
+
+      - name: Check installed packages
+        run: python -m pip check
+
+      - name: Compile Python sources
+        run: python -m compileall -q app scripts
+
+      - name: Run tests
+        run: python -m pytest -q

.gitignore

@@ -6,9 +6,13 @@ __pycache__/
 *.pyo
 *.db
 *.sqlite3
-/data/playwright-profile/
-/data/*.html
+/data/*
+!/data/.gitkeep
 /tests/fixtures/last_live_search.html
 .superpowers/
 .worktrees/
+.hermes/
 dist/
+/runtime/
+*.zip
+*.tmp

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tangtaizhong
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,6 +1,6 @@
-# 飞票监控
+# 票价哨兵
 
-飞票监控是一个本地运行的机票监控工作台。它可以搜索携程国内单程机票，保存目标价监控任务，并在价格达到目标时通过本机提醒、页面高亮和声音提示把你叫回来。
+票价哨兵是一个本地运行的机票监控工作台。它可以搜索携程国内单程机票，保存目标价监控任务，并在价格达到目标时通过本机提醒、页面高亮和声音提示把你叫回来。
 
 它适合这些场景：
 
@@ -11,15 +11,23 @@
 
 ## 普通用户路径
 
-从 GitHub Release 下载：
+你可以直接从 GitHub 项目页下载源码：
+
+1. 点击 `Code → Download ZIP`。
+2. 解压下载到的 zip。
+3. 双击根目录里的 `start_fly_ticket.bat`。
+
+首次运行会联网下载内置 Python、安装运行依赖和 Playwright Chromium，不需要提前安装 Python。之后再次双击会复用本地 `runtime/` 和 `.env`，启动会更快。
+
+也可以从 GitHub Release 下载已经打包好的便携版：
 
 `FlyTicket-Windows-<version>.zip`
 
 解压后双击：
 
 `启动机票监控.bat`
 
-发布包自带 Python 运行环境、依赖和 Playwright Chromium。普通用户不需要手动安装 Python、pip 依赖或浏览器组件。
+Release 发布包自带 Python 运行环境、依赖和 Playwright Chromium。普通用户不需要手动安装 Python、pip 依赖或浏览器组件。压缩包体积较大是因为内置了这些运行环境。
 
 启动后按这个顺序使用：
 
@@ -80,13 +88,22 @@
 - 如果价格继续下降，会再次提醒
 - 如果价格一直命中但没有更低，会在冷却时间后再次提醒
 
-默认冷却时间是 6 小时，可通过 `.env` 调整：
+默认开启重复提醒冷却，冷却时间是 6 小时，可通过 `.env` 调整：
 
 ```env
+MONITOR_REALERT_COOLDOWN_ENABLED=1
 MONITOR_REALERT_COOLDOWN_HOURS=6
 ```
 
-即使桌面通知没有弹出，命中记录仍会写入本地数据库，你可以在网页里查看。
+如果希望每次检查到目标价都提醒，把冷却开关关掉：
+
+```env
+MONITOR_REALERT_COOLDOWN_ENABLED=0
+```
+
+关闭后，重复提醒频率会跟监控任务的检查间隔一致。例如任务每 30 分钟检查一次，只要每次检查仍命中目标价，就会约每 30 分钟提醒一次。
+
+即使桌面通知没有弹出，命中记录仍会写入本地数据库，你可以在网页里查看。任务栏提醒依赖系统通知能力，当前以页面高亮、桌面通知和声音提示为主。
 
 ## 开发者路径
 
@@ -96,19 +113,28 @@ MONITOR_REALERT_COOLDOWN_HOURS=6
 
 它会自动尝试：
 
-1. 检查 Python
-2. 创建 `.venv`
-3. 安装依赖
-4. 安装 Playwright Chromium
-5. 从 `.env.example` 生成 `.env`
-6. 启动本地网页服务
-7. 自动打开浏览器
+1. 使用已有 Python 3.10+ 创建 `.venv`，或在没有 Python 时下载内置 Python
+2. 安装运行依赖
+3. 安装 Playwright Chromium
+4. 从 `.env.example` 生成 `.env`
+5. 启动本地网页服务
+6. 自动打开浏览器
 
-手动运行方式：
+手动运行方式（Windows PowerShell）：
+
+```powershell
+py -3 -m venv .venv
+.\.venv\Scripts\python.exe -m pip install -r requirements-dev.txt
+.\.venv\Scripts\python.exe -m playwright install chromium
+Copy-Item .env.example .env
+.\.venv\Scripts\python.exe -m uvicorn app.main:app --host 127.0.0.1 --port 8000
+```
+
+手动运行方式（macOS / Linux）：
 
 ```bash
 python -m venv .venv
-.venv/bin/pip install -r requirements.txt -r requirements-dev.txt
+.venv/bin/python -m pip install -r requirements-dev.txt
 .venv/bin/python -m playwright install chromium
 cp .env.example .env
 .venv/bin/python -m uvicorn app.main:app --host 127.0.0.1 --port 8000
@@ -133,6 +159,8 @@ powershell -ExecutionPolicy Bypass -File scripts/build_windows_portable.ps1 -Ver
 - `dist/FlyTicket-Windows/`
 - `dist/FlyTicket-Windows-dev.zip`
 
+发布 GitHub Release 时，建议同时在 Release 说明里提供压缩包 SHA256，方便用户确认文件没有损坏或被替换。
+
 ## 配置说明
 
 项目读取根目录下的 `.env`。
@@ -143,10 +171,13 @@ powershell -ExecutionPolicy Bypass -File scripts/build_windows_portable.ps1 -Ver
 APP_DB_PATH=data/app.db
 PLAYWRIGHT_PROFILE_DIR=data/playwright-profile
 PLAYWRIGHT_BROWSERS_PATH=runtime/ms-playwright
-CTRIP_SNAPSHOT_DIR=tests/fixtures
+CTRIP_SNAPSHOT_DIR=data/debug
+CTRIP_SAVE_DEBUG_SNAPSHOT=0
+CTRIP_DEBUG_SNAPSHOT_DIR=data/debug
 CTRIP_SEARCH_URL_TEMPLATE=
 CTRIP_SESSION_URL=
 APP_BASE_URL=http://127.0.0.1:8000
+MONITOR_REALERT_COOLDOWN_ENABLED=1
 MONITOR_REALERT_COOLDOWN_HOURS=6
 ```
 
@@ -167,6 +198,45 @@ CTRIP_SESSION_URL=https://flights.ctrip.com/online/channel/domestic
 
 升级新版本时，保留 `data/` 和 `.env` 即可继续使用原来的数据。
 
+## 隐私和本地数据
+
+本项目默认只在本机保存数据，不会把你的搜索历史、监控任务或携程登录状态上传到项目作者的服务器。
+
+但是请注意：
+
+- `data/playwright-profile/` 可能包含携程登录态、Cookie、浏览历史、Local Storage 等敏感信息。
+- `data/app.db` 可能包含你的搜索历史、监控任务、目标价和命中记录。
+- `.env` 可能包含你的本地配置。
+- 如果开启 `CTRIP_SAVE_DEBUG_SNAPSHOT=1`，`data/debug/` 里可能保存携程页面 HTML，里面可能包含个人化内容。
+
+不要把这些文件上传到 GitHub、网盘、论坛、Issue 或发给别人：
+
+```text
+.env
+data/
+runtime/
+dist/
+.venv/
+*.log
+*.err.log
+```
+
+## 安全边界
+
+票价哨兵是本地工具，默认只监听 `127.0.0.1`。
+
+请不要把服务改成 `0.0.0.0` 后暴露到公网或局域网。如果你确实需要远程访问，请自行增加登录认证、防火墙和网络安全措施。
+
+## 免责声明
+
+本项目仅供个人本地学习和自用。
+
+- 不提供自动购票、抢票、下单功能。
+- 不提供绕过验证码、绕过风控或批量抓取能力。
+- 用户应自行遵守相关网站的服务条款以及所在地法律法规。
+- 携程页面结构、登录策略或风控策略变化时，本工具可能无法正常搜索。
+- 使用本项目产生的账号、网络、数据或法律风险由使用者自行承担。
+
 ## 问题排查
 
 ### 双击后页面没打开
@@ -194,11 +264,15 @@ CTRIP_SESSION_URL=https://flights.ctrip.com/online/channel/domestic
 
 不同系统环境的桌面通知后端表现不完全一致。即使通知没弹出，命中记录仍会保存，页面里也会显示最近命中。
 
+### Windows 或杀毒软件提示风险
+
+请确认压缩包来自你信任的 GitHub Release，并优先核对 Release 页面提供的 SHA256。便携版内置 Python 和浏览器运行环境，部分安全软件可能对未知压缩包或脚本启动器给出提示。
+
 ## 目录说明
 
 - `app/`：后端代码、模板、静态资源
 - `tests/`：自动化测试
-- `data/`：本地数据库和浏览器登录状态
+- `data/`：本地数据库和浏览器登录状态，默认不应提交
 - `scripts/`：启动和构建脚本
 - `docs/superpowers/`：设计和实现计划文档
 
@@ -209,3 +283,7 @@ CTRIP_SESSION_URL=https://flights.ctrip.com/online/channel/domestic
 - 不做自动购票或自动下单
 - 不接入邮件、微信、Telegram 等外部通知
 - 不做云端长期运行；程序关闭后不会继续监控
+
+## 许可证
+
+本项目使用 MIT License，详见 `LICENSE`。

README_使用说明.txt

@@ -23,9 +23,16 @@
 本地数据库、监控任务和登录状态保存在 data 文件夹。
 升级新版本时，保留旧版本的 data 文件夹和 .env 文件即可继续使用原来的数据。
 
+请注意：data 文件夹可能包含你的携程登录状态、Cookie、浏览历史、搜索历史和监控任务，不要把 data 文件夹、.env 文件或日志文件发给别人，也不要上传到 GitHub、网盘、论坛或 Issue。
+
 五、常见问题
-如果 Windows 或杀毒软件提示风险，请确认压缩包来自你信任的 GitHub Release。
+如果 Windows 或杀毒软件提示风险，请确认压缩包来自你信任的 GitHub Release，并优先核对 Release 页面提供的 SHA256。
 如果页面打不开，可能是端口被占用，重新双击启动脚本通常会自动换端口。
 如果搜索失败，请重新登录携程，或检查网络连接。
 如果登录失效，请在首页点击“重新登录”。
 如果没有看到桌面通知，请回到网页查看最近命中记录。
+
+六、使用边界
+本工具仅供个人本地学习和自用。
+它不提供自动购票、抢票、下单、绕过验证码或绕过风控功能。
+请自行遵守相关网站服务条款和所在地法律法规。

app/ctrip_capture.py

@@ -10,7 +10,7 @@ def save_live_snapshot(
     html: str,
     filename: str = "last_live_search.html",
 ) -> Path:
-    settings.ctrip_snapshot_dir.mkdir(parents=True, exist_ok=True)
-    path = settings.ctrip_snapshot_dir / filename
+    settings.ctrip_debug_snapshot_dir.mkdir(parents=True, exist_ok=True)
+    path = settings.ctrip_debug_snapshot_dir / filename
     path.write_text(html, encoding="utf-8")
     return path

app/ctrip_parser.py

@@ -19,6 +19,7 @@
 EMBEDDED_FLIGHT_NO_RE = re.compile(r"([A-Z]{2}\d{3,4})(?=[^A-Z0-9]|$)")
 TIME_RE = re.compile(r"\b(\d{2}:\d{2})\b")
 PRICE_RE = re.compile(r"[¥￥]\s*(\d+)")
+PRICE_WITH_START_RE = re.compile(r"[¥￥]\s*(\d+)\s*起")
 AIRLINE_FALLBACK_RE = re.compile(r"([一-鿿]{2,}(?:航空|航司))")
 DIRECT_WORDS = ("直飞", "无中转")
 STOP_WORDS = ("经停", "中转")
@@ -68,15 +69,15 @@ def _parse_card(
     price = _extract_price(card, text)
     airline = _extract_airline(card, text)
 
-    if not flight_no or len(times) < 2 or price is None or not airline:
+    if len(times) < 2 or price is None or not airline:
         return None
 
     href = _extract_deeplink(card, fallback_search_url)
     stop_info = _extract_stop_info(card, text)
     is_direct = stop_info == "直飞"
 
     return FlightResult(
-        flight_no=flight_no,
+        flight_no=flight_no or "未知航班",
         airline=airline,
         origin_city=request.origin_city,
         destination_city=request.destination_city,
@@ -103,14 +104,32 @@ def _extract_flight_no(card: Tag, text: str) -> str | None:
 
 
 def _extract_price(card: Tag, text: str) -> int | None:
-    match = PRICE_RE.search(text)
+    price_node = card.select_one(
+        ".price.over-size .price, .flight-price .price, "
+        "[class*='price'] [class='price'], [class*='price']"
+    )
+    if price_node is None:
+        start_match = PRICE_WITH_START_RE.search(text)
+        if start_match:
+            return int(start_match.group(1))
+
+        for match in PRICE_RE.finditer(text):
+            prefix = text[max(0, match.start() - 6) : match.start()]
+            if "已减" in prefix or "优惠" in prefix:
+                continue
+            return int(match.group(1))
+        return None
+
+    price_text = price_node.get_text(" ", strip=True)
+    match = PRICE_RE.search(price_text)
     if match:
         return int(match.group(1))
 
-    price_node = card.select_one(".price.over-size .price, .flight-price .price")
-    if price_node is None:
-        return None
-    digits = "".join(ch for ch in price_node.get_text(strip=True) if ch.isdigit())
+    start_match = PRICE_WITH_START_RE.search(price_text)
+    if start_match:
+        return int(start_match.group(1))
+
+    digits = "".join(ch for ch in price_text if ch.isdigit())
     return int(digits) if digits else None