票IN 发票同步

票IN 本身已经承担了发票归集：手机拍照 OCR、邮箱采集、短信开票链接提取、自动分类、验真和初审。但归集结果沉淀在小程序/服务端，开发者拿到发票数据和文件仍需要一条可靠的链路。

要解决什么问题

当发票进入票IN 后，常见的后续动作其实很集中：把发票记录与文件拉到本地项目里做归档、分析或二次处理；或者把本地已收到的发票文件上传回票IN 等待 OCR、查重、验真和初审。

这件事的难点不在单次 HTTP 调用，而在三件事：

• 运行环境不确定：Agent 可能在线上（无法落盘），也可能在本地有 Python / curl / PowerShell，降级路径需要被显式记录。
• 状态需要持久化：下次增量同步依赖上次同步时间，API Key 和用户角色也需要在本地保存。
• 权限边界敏感：全租户下载需要租户管理员角色，错误地传 allTenant=true 可能触发无权限响应。

工作原理

技能围绕票IN PAT 开放接口，聚焦下载/同步和上传两个工作流。

下载/同步流程：

1. 读取本地状态文件 .piaoin_evn，没有 API Key 就停止并提示用户创建秘钥。
2. 判断下载范围：own（当前用户）或 tenant（全租户）。后者要求本地状态 USER_ROLE=tenantAdmin，且接口传 allTenant=true。
3. 增量同步时使用 --since-last，脚本会读取 LAST_SYNC_DATE 作为 startDate。
4. 分页调用 /api/v1/pat/invoices/list，直到 pageNum >= totalPage。
5. 每条记录按月份追加写入 JSONL，同时下载 invoiceUrl 对应的文件并保留合适扩展名。
6. 更新 LAST_SYNC_DATE，生成 Markdown 汇总表（Python CLI 会保存为 piaoin_invoice/summary_YYYYMMDD_HHMMSS.md）。

上传流程：

• 支持 file 或 fileUrl 二选一（绝不能同时发送）。
• 支持 jpg、jpeg、png、pdf。
• 接口同步完成 OCR、查重、验真、入库和初审，返回批次号和发票结果数组；对异常发票需要重点说明 invoiceStateName、isVerification、checkResultInfo。

执行方式按环境降级：线上 Agent 的请求工具优先、本地 Python CLI（最完整）、curl、PowerShell；如果都没有，只生成请求命令而不声称已同步。每次执行会把 RUNTIME_MODE 和 LAST_RUNTIME 写入 .piaoin_evn。

适用边界与注意点

• X-API-Key 属于敏感信息，展示时必须掩码为 py_...abcd。
• 列表接口只返回 invoice_state=1 的正常发票；上传接口返回的重复或异常发票可能不会出现在后续列表中。
• 如果接口返回「无权限: 仅租户管理员可查询全部发票」，说明当前 API Key 对应用户不是租户管理员；除非用户提供管理员 PAT，否则降级为只同步自己的发票。
• 生产环境使用 https://admin.piaoin.cn，测试环境使用 https://admintest.piaoin.cn。
• 历史兼容：旧版 .piaoin_env 仅作迁移读取，新状态统一写入 .piaoin_evn。