hipass-receipt

Hi-Pass 发票/收据开具

Skill 功能说明

在 Hi-Pass 官网（https://www.hipass.co.kr）中复用已登录的浏览器 Session，半自动化提供以下功能：

• 查询通行记录/使用明细
• 选中特定数据行
• 进入发票/收据打印弹窗页面
• 识别 Session 过期并提示重新登录

硬性限制与边界

• 必须由用户手动完成登录。
• 本 Skill 仅在已登录的 Session 下有效。
• 不会自动输入账号密码、验证码、OTP、联合认证证书（공동인증서）等凭据。
• 不支持仅保存 JSESSIONID Cookie 进行长期复用的模式。
• 推荐使用 Playwright persistent context 或 Chrome user-data-dir / 远程调试（remote-debugging）端口复用 Session。
• 一旦 Session 过期，须立即中断操作并重新登录。

设计考量

根据当前公开页面逻辑：

• 登录页与主页均显式包含 session_time=1200。
• Session 续期接口为 /comm/sessionCheck.do
• Session 结束接口为 /comm//sessionout.do
• 未登录或 Session 结束保护机制会返回 mgs_type 11/12，随后跳转至 /comm/lginpg.do。
• 通行记录查询流程：/usepculr/InitUsePculrTabSearch.do → 提交 hpForm → /usepculr/UsePculrTabSearchList.do。
• 发票开具流程：调起 /usepculr/UsePculrReceiptPrint.do 弹窗。

因此在 v1 阶段，“复用已登录的 Chrome Session” 是最合理的实现方案。

前置条件

• macOS 或支持运行 Chrome 的操作系统环境
• 执行 npm install hipass-receipt 或在本仓库执行 npm install（包含 playwright-core）
• Chrome 远程调试端口可用
• 用户能够手动登录 Hi-Pass 账号

工作流程

1. 使用专用 Chrome 配置启动浏览器并登录

hipass-receipt chrome-command --profile-dir "$HOME/.cache/k-skill/hipass-chrome" --debugging-port 9222

使用上述命令输出的 Chrome 启动语句打开浏览器，随后由用户手动访问 https://www.hipass.co.kr/comm/lginpg.do 完成登录。

2. 查询通行记录

hipass-receipt list \
  --cdp-url http://127.0.0.1:9222 \
  --start-date 2026-04-01 \
  --end-date 2026-04-07 \
  --page-size 30

• 若已知发卡机构或已加密的卡号，可通过 --encrypted-card-number 等参数进一步缩小查询范围。
• --encrypted-card-number 为 CLI 中现有 --ecd-no 参数的别名。
• 从返回的 JSON 结果中确认 rowIndex。

3. 调起特定数据行的发票弹窗

hipass-receipt receipt \
  --cdp-url http://127.0.0.1:9222 \
  --start-date 2026-04-01 \
  --end-date 2026-04-07 \
  --row-index 1

• 点击所选数据行中的“发票/收据（영수증）”或“打印（출력）”控件。
• 弹窗打开后返回对应的 URL 和标题（title）。

响应与交互策略

• 始终明确提示“必须登录”以及“Session 过期时须重新登录”。
• 切勿索取、存储 Hi-Pass 账号密码，也不要为此新建环境变量。
• 若检测到 Session 已过期，应立即报错中断，并引导用户访问 /comm/lginpg.do 重新登录。
• 不承诺超出 v1 范围的无人值守登录保持或后台自动重新认证功能。

验证方式

• 自动化验证：基于 Fixture 的查询/解析/Session 检测测试
• 冒烟测试（Smoke Test）：hipass-receipt fixture-demo --fixture ...
• 最终线上验证：在真实登录 Session 下进行手动冒烟测试

完成标准

• 能够利用已登录的 Session 正常查询通行记录。
• 能够选中指定数据行并成功调起发票弹窗。
• 能够准确识别 Session 结束响应并提示重新登录。