==================================================
N-SRM 订单下载工具  ·  使用说明
==================================================

【这是什么】
一个小工具，自动从 vivo 供应商系统抓取指定日期范围的采购订单
明细，并导出为 Excel。双击即用，不需要安装 Python。

【怎么用】
1. 把本文件夹放到一个有读写权限的地方（推荐：桌面新建一个文件夹，
   把 N-SRM-Tool.exe 和本说明一起放进去）。不要直接放进
   C:\Program Files 这类受保护的目录。
2. 双击 N-SRM-Tool.exe 启动。
3. 首次启动会【自动在后台下载浏览器 Chromium（约 150MB）】，
   此时会弹出「准备中」进度窗，请耐心等待，完成后会自动消失并继续。
   之后再次使用会直接复用，不再下载。
   （如果公司网络无法访问下载源导致失败，请联网后重试，
    或联系提供此工具的人。）
4. 在界面填写：
   - 网站地址：默认已填好，一般不用改
   - 账号 / 密码：你的 vivo 供应商系统登录信息
   - 创建人：可选，多个用逗号分隔，下载后会自动只保留匹配的行
   - 日期范围：可用「上周 / 本周 / 上月」按钮快速选择
   - 输出目录：导出的 Excel 保存位置
   - 文件命名：可选，自定义导出文件名（留空用默认）。
     支持 {date} 占位符（自动替换为导出当天的 YYYYMMDD），
     例如填「vivo订单_{date}」会生成「vivo订单_20260708.xlsx」。
     文件已存在时不会覆盖，自动追加序号。
5. 点击「▶ 开始下载」。日志区会实时显示进度。
6. 关于【滑块验证 / 重新登录】：
   - vivo 登录会话有效期较短（约一周）。若隔较久才运行，会话可能已过期。
     此时工具【会自动弹出浏览器窗口并提示“需要重新登录”】，
     你只需在弹窗里手动滑动一次验证码（几秒），
     之后工具【自动继续并完成抓取】，无需全程守着前台。
   - 若在会话有效期内运行，则完全无感，直接后台完成。

6. 关于「♻ 刷新登录」按钮（会话保活）：
   - 作用：用已存的登录信息静默访问一次 vivo 订单页，刷新服务端会话有效期。
     相当于“摸一下鱼”让会话别过期，从而降低之后抓取时遇到验证码的概率。
   - 用法：填好账号密码并勾选「记住密码」、点「💾 保存配置」后，
     点「♻ 刷新登录」即可。登录态有效时几秒完成（无弹窗）；
     若已过期则弹出浏览器让你滑一次码再保存。
   - 进阶：可让工具每天自动保活——见下方「每日自动保活」。

7. 关于「每日自动保活」（减少每周滑码频率）：
   - 原理：很多网站会话是“空闲超时”型，定期访问就会顺延有效期。
     每天自动保活一次，到你每周抓取时会话大概率还活着 → 不重新登录 → 不弹码。
   - 已为你创建每天 09:00 的自动任务（在 WorkBuddy 的自动化里可查看/暂停）。
     运行日志在 output/keepalive.log，可随时查看。
   - 诚实边界：若 vivo 用的是“绝对过期时间”（固定 7 天强踢），保活可能无效；
     届时每周抓取前手动点一次「♻ 刷新登录」或滑一次码即可。

【产出的文件】
- 导出 Excel：output/ 目录下，文件名带日期范围
- 会话缓存：output/vivo_cookies.json、output/browser_profile
  （下次运行可免登录，建议保留，不要删）

【常见问题】
Q：一直卡在「准备中」？
A：首次需要下载约 150MB 浏览器，网速慢时可能需要几分钟，属正常。
   若长时间无进展，多为网络无法访问下载服务器，请检查网络后重开。

Q：提示“浏览器可能未下载完成”？
A：通常是网络问题导致 Chromium 没下全。请联网后重新打开工具再试一次。

Q：明明之前装过浏览器，换台电脑 / 新版本却报“Executable doesn't exist / 浏览器未安装”？
A：新版已彻底修复。根因有两个，都已解决：
   ① 后台无头模式用的是独立的「无头变体」(chrome-headless-shell.exe)，
      旧版只装了常规 chromium，导致后台一启动就找不到文件、陷入反复重装的死循环。
      现在工具会同时下载常规 chromium + 无头变体两个包。
   ② 别人机器上可能是【旧版工具装的旧构建号】，与新版 exe 内置的浏览器驱动版本不匹配，
      旧检查逻辑误判“已安装”就跳过重装，照样启动失败。
      现在检测到启动失败时，会【强制重装当前版本匹配的浏览器】，不用手动处理。
   若仍反复失败，删掉 %LOCALAPPDATA%\ms-playwright 目录后重开工具让其重新下载即可。

Q：导出的 Excel 是空的 / 数据不对？
A：确认日期范围和创建人填写正确；订单页默认是「整单」视图，
   工具会自动切到「明细」再导出，无需手动操作。

Q：换台电脑还能用吗？
A：可以。把整个文件夹拷过去即可。新电脑首次运行也会自动下载浏览器。

Q：界面卡住 / 点不开 / 关不掉怎么办？
A：旧版在「准备中」遮罩异常残留时，会卡死整个界面且无法关闭（只能强杀进程）。
   新版已修复：①遮罩不再独占鼠标键盘；②遮罩右上角 X 随时可关；
   ③窗口 X 一定可以关掉（会自动清理残留浏览器进程）；
   ④每次启动时自动清理占用缓存目录的残留浏览器，避免再次卡死。
   若极端情况下仍卡住，可在任务管理器结束 N-SRM-Tool.exe 进程，
   重新打开即可，不会损坏任何数据。

Q：我每周只跑一次，是不是每次都得滑验证码？
A：基本是——vivo 会话约一周过期，滑块验证又必须人工滑动（无法自动）。
   但工具已优化：你【只需在弹窗里滑那一下】，滑完自动续跑抓完，
   不用再像以前那样“先前台跑一次刷新会话、再后台跑”两遍。

【技术说明（给分发者）】
- 本 exe 由 PyInstaller 单文件打包，体积约 65MB，不含浏览器，
  浏览器在首次运行时按需下载到用户本地的
  %LOCALAPPDATA%\ms-playwright 目录，之后复用。
- 数据目录（配置 / 日志 / 导出）一律写在 exe 同级目录，
  因此请保证 exe 所在目录可写。
==================================================
