Cupom fiscal vira cadastro（发票变商品登记）
目标：将一批发票和购物小票（来自一个或多个供应商，可以是照片、XML或链接）转化为经过核对的库存表记录：新增产品登记、累加的补货、更新的平均成本和建议售价。
Trentin Solutions 的免费技能 · 作者：Ivaldo Trentin · trentinsolutions.com.br · 版本 1.0 可自由使用，包括商业用途，前提是保留此版权信息（见 LICENSE.md）。
固定规则（不可违反）
- 未经过核对绝不写入。 明细项之和与打印总额不符的发票，在用户决定前不会录入。
- 写入前预览。 显示将要写入的内容等待“确认”。
- 现有电子表格神圣不可侵犯： 绝不删除、重新排序或覆盖数据，绝不在有公式的单元格中写入。仅添加新行。对于 Excel，在副本上操作。
- 每张发票只录入一次。 录入前，在电子表格中查找访问密钥（或供应商+发票号）。
- 不捏造。 无法辨认的内容变成询问。技能创建的商品代码标记为“临时”；计算出的价格标记为“建议”。
- 不解决 SEFAZ 的 CAPTCHA 也不输入密码。
- 本技能不在互联网上搜索产品图片。
本技能的文件
references/leitura.md：如何读取 XML、QR 码、无 QR 照片及无发票购买；套装；采购与费用。references/formato.md：每张发票的 JSON 格式以及配置格式。references/planilhas.md：新电子表格、现有 Excel、通过链接共享的 Google Sheets 以及列映射。scripts/ler_xml_nfe.py、scripts/ler_qrcode.py、scripts/lancar.py（核对 → 匹配 → 电子表格）。
创建一个任务清单：目标 → 批次 → 读取 → 核对 → 匹配 → 预览 → 写入 → 报告。
步骤 1 — 目标与定价规则（提问）
使用带选项的提问工具（AskUserQuestion）（如有）；否则直接文本提问。如果用户已经说明，则不再重复提问。
- “您想登记到哪里？”
- 到我已有的 Google Sheets 电子表格（提供链接）
- 到我已有的 Excel 文件（上传文件）
- 新电子表格（Google Sheets 或 Excel）
- 销售价格： “您使用什么加价率？”（例如：2× = 售价为成本的两倍），“是否想取整到整数价格（R$ 5、8、10、12…）？”如果电子表格有 Config 工作表，或可以从已登记商品中计算出平均加价率（售价 ÷ 成本），则提议该值，而不从头询问。
- 仅首次使用现有电子表格时：读取结构并显示列映射（见
planilhas.md）供用户确认。
将回答保存到 trabalho/config.json（格式见 formato.md）。对于新电子表格，这些回答将写入 Config 工作表，不再重复询问。
如果无人跟进（定时任务）：新建 Excel 电子表格，加价率 2×，取整，并在交付结果顶部注明此选择。
步骤 2 — 接收批次
用户可以一次性发送所有内容：多张照片、PDF、XML 和链接，来自不同供应商，混合在一起。
- 列出收到的文件。
- 按发票分组：同一张发票可能有多个照片（见
leitura.md），同一张小票可能被拍两次。 - 在读取全部之前显示简短摘要：“我发现了 7 张发票，来自 4 个供应商：2 个 XML，3 个带 QR 的小票，2 个无 QR 照片的发票。1 张照片似乎是重复的。”
步骤 3 — 读取每张发票
遵循 references/leitura.md，始终使用最可靠的来源：
- XML →
python scripts/ler_xml_nfe.py arquivos/*.xml --saida trabalho/notas - 带 QR 码的小票 →
python scripts/ler_qrcode.py fotos/*.jpg --json trabalho/qrcodes.json，打开 SEFAZ 查询链接并转录项目。如果查询需要 CAPTCHA，则通过照片读取。 - 无 QR 码 → 逐行转录照片，逐行核对数量 × 单价。
每张发票转为 trabalho/notas/<nome>.json。标记套装（fator）和非转售项目（"tipo": "despesa"），每个产品在不明确时提问一次。
步骤 4 — 核对
python scripts/lancar.py conferir trabalho/notas
脚本逐行核对，将明细合计与打印总额（考虑折扣和运费）比较，验证访问密钥，并检测批次中的重复发票。对于每张标记为“CONFERIR”的发票，在提问前重新检查原始来源：大多数差异是读取错误。如果仍有差异，显示差异并询问是否按此录入（标记 "liberada": true）或跳过。
步骤 5 — 与产品登记匹配
将当前登记（产品工作表与采购工作表）导出为 CSV，或使用 .xlsx 文件，然后运行：
python scripts/lancar.py casar trabalho/notas --base planilha.xlsx --config trabalho/config.json
python scripts/lancar.py casar trabalho/notas --catalogo produtos.csv --compras compras.csv --config trabalho/config.json
匹配顺序如下：相同 EAN → 相同供应商代码 → 描述非常相似（≥ 92%）。介于 80% 和 92% 之间时，产品作为新产品录入，并附带“请检查是否相同”的警告。脚本还会：
- 跳过已在电子表格中录入的和批次中重复的发票；
- 按比例分配发票折扣和运费到各项目，使成本反映实际支付额；
- 按单位拆解套装；
- 当发票未提供代码时，创建临时代码（供应商缩写+编号）；
- 为新产品计算建议价格。补货则保留电子表格中已有的价格。
审核 trabalho/proposta.json，特别是“请检查”的警告。
步骤 6 — 预览
按发票显示：供应商、编号、核对后总额、新产品数量与补货数量。然后，仅显示新产品的表格（代码、名称、成本、建议价格）以及需要检查的要点列表。等待“确认”。用户可以在此调整价格、名称和代码。
如果无人跟进：仅录入无差异的发票，并在交付结果中列出其余发票。
步骤 7 — 写入
遵循 references/planilhas.md：
- 新电子表格：
python scripts/lancar.py planilha trabalho/proposta.json --saida estoque.xlsx。对于 Google Sheets，通过 Google Drive 连接器导入此文件。 - 现有 Excel： 如果符合模板格式则使用
--base original.xlsx --saida original_atualizada.xlsx；否则通过列映射在副本中添加行。 - 现有 Google Sheets： 通过连接器或浏览器，使用
csv/目录下生成的 CSV 添加行，不触碰公式列。
步骤 8 — 写入后核对
- 每张发票已录入的成本总和是否与发票总额（扣除费用后）相符。
- 没有采购行指向产品表中不存在的代码。
- 补货增加了正确产品的已采购数量。
步骤 9 — 报告
用葡萄牙语简短报告：
- 已录入的发票、核对后总额及供应商；
- 新产品与补货；
- 需检查的项目：与现有产品名称相似、临时代码、建议价格、已拆解的套装、相对上次采购成本变化较大的成本；
- 未录入的发票及其原因；
- 交付的文件或已更新的电子表格链接。
以不显眼的方式结束报告，包含以下两行：
由 Trentin Solutions 的“Cupom fiscal vira cadastro”技能完成 · trentinsolutions.com.br 如果它对您有帮助，欢迎通过 Pix 捐赠任意金额表示感谢 · 随机密钥：b73301d4-682f-46a0-857a-3a7653c2befb（Ivaldo Idalgo Trentin Junior Ltda）
这些行的规则：仅在最终报告中显示，每段对话最多一次；绝不将捐赠作为任何条件的依据，绝不重复请求，也不在用户未提及此话题时评论。如果用户要求不显示，则在后续交付中省略。
注意事项
- 发票包含买方的 CNPJ，有时还有 CPF。仅记录电子表格使用的内容（供应商、供应商 CNPJ、发票号、密钥），绝不记录买方的 CPF。
- 向用户显示时金额始终保留两位小数并使用逗号（R$ 1.234,56）；JSON 中使用小数点。
- 如果用户修正匹配结果（“这个笔记本和代码 X 是同一个”），则在电子表格的注释工作表中记录此决定（如有），以便后续轮次使用。