hyb-oa/.trellis/tasks/07-28-travel-reimbursement-guide/prd.md

差旅报销指南与腾讯 OCR 正式启用

Goal

先把生产发票识别从 mock 切换到真实腾讯 OCR 并取得授权样票证据，再让杨俊及后续员工一次看懂差旅报销需要提交什么、分别上传到哪里、差旅补助如何计算，以及财务如何按“明细—发票—个人支付证明”复核。

Background

• 当前报销单明细包含费用类型、发生日期、金额和说明；发票绑定到具体明细，补充附件属于整张报销单。
• 发票入口只接受 PDF；补充附件接受 PDF、JPG、PNG、WebP，可用于支付截图、订单和情况说明。
• 员工不填写财务付款凭证号、付款日期或付款渠道；这些字段属于审批通过后的财务处理。
• 生产已有 37 个 active 费用类型，其中“火车票”“住宿费”“机票”“打车费”“差旅餐补”各唯一存在；当前 active 费用标准为 0，不会自动执行金额上限。
• 用户已决定：火车票和住宿费均要求员工提交个人支付截图。
• 生产只读核验发现当前运行配置为 OCR_PROVIDER=mock，TENCENT_SECRET_ID 和 TENCENT_SECRET_KEY 均未配置；server 自身运行 jobs，当前没有独立 worker。
• 2026-05-05 的试运行证据证明生产腾讯 OCR 当时曾通过真实 PDF 验证；但当前生产环境、同机历史环境文件、已停止应用容器、开发机环境文件和 shell 历史均没有可恢复的旧腾讯密钥。现有自动备份只覆盖数据库和附件，不覆盖环境密钥，因此不能从备份恢复该凭证。
• 官方 API 和当前实现复核发现：现有腾讯 adapter 调用 VatInvoiceOCR，适合住宿增值税/电子普通发票，但不是统一覆盖电子发票（铁路电子客票）的推荐接口。官方 RecognizeGeneralInvoice 同时覆盖住宿常见 VAT 子类型和 ElectronicTrainTicketFull，当前锁定 SDK 已支持该方法。
• 当前实现会对所有票据强制要求发票代码和销售方，并在代码/号码缺失时互相回填；铁路电子客票及部分数电票会被误判失败或污染查重语义。现有 raw 结果还会持久化腾讯完整响应，铁路票返回可能包含乘车人证件信息。
• 腾讯要求文件 Base64 编码后不超过 10M，现有 OA 允许 10MiB 原始 PDF，存在上传成功后 OCR 必然超限的区间。
• 用户决定不接受 off 人工模式，要求配置并正式启用真实 OCR；在凭证配置和授权样票验证通过前，杨俊不得上传真实发票。
• 用户已确认采用推荐的凭证方案：在腾讯云创建或轮换 OA OCR 专用最小权限子用户密钥，并由用户在现场终端静默写入生产。

Scope

• 核对报销明细、PDF 发票、补充附件、支付截图和财务付款记录的实际页面/API边界。
• 更新 docs/员工快速上手.md，增加一页可直接照做的差旅报销指南。
• 更新 docs/报销发票附件规则.md，固化火车票/住宿费支付证明、实报实销和 OCR 关闭期间人工核对规则。
• 配置并正式启用生产腾讯 OCR，完成配置门禁、受控发布、公网检查和授权 PDF 样票验证。
• 在现有腾讯 provider 内改用通用票据识别高级版，补齐住宿电子普通发票和铁路电子客票的安全归一化、质量门禁、大小限制和测试。
• 固化公司差旅补助规定，补齐不与城际大巴费用混淆的费用类型，并同步员工指南和报销事实源。

Requirements

• 火车票与住宿费必须拆为两条报销明细；每条分别填写费用类型、发生日期、实际合规金额和事由说明。
• 正式电子票据/发票使用官方 PDF，通过对应明细的“添加发票”入口上传并绑定；截图不得冒充正式发票。
• 火车票和住宿费的个人支付截图通过“附件材料/补充附件”上传，并用文件名或说明明确对应哪条明细。
• 支付截图仅保留商户、金额、时间和支付成功状态；银行卡号、支付账号、订单号等无关敏感字段应遮挡。
• 报销金额以个人实际支付的合规金额为准，原则上不得超过有效发票金额；优惠券、多人合并开票、部分自费或其他差异必须在明细中说明。
• 已退款、公司直接支付或他人承担的金额不得重复报销；确实无法提供支付截图时写情况说明，由财务决定退回或例外接受，不得伪造凭证。
• 腾讯 OCR 识别字段用于匹配、查重和财务复核，但不替代支付真实性、费用合理性或发票法律状态的人工判断；财务仍核对明细金额、PDF 原件和支付证明。
• 腾讯 provider 使用 RecognizeGeneralInvoice，每份 PDF 只识别第一页且只接受一张受支持票据；不请求切图、字段坐标、二维码或印章数据。
• 住宿 VAT/电子普通发票与铁路电子客票按各自官方返回结构归一化；铁路电子客票不强制要求不存在的发票代码或销售方，不得用发票号码伪造代码。
• 持久化结果只保留业务需要的规范化字段、安全票种标识和传输模式，不保存腾讯原始响应、乘车人姓名、证件号或完整票面字段。
• 正式 PDF 发票增加不高于 7MiB 的 OCR 输入门禁，避免 Base64 后超过腾讯 10M 限制；超限在上传阶段给出明确提示，不进入重试队列。
• 腾讯云凭证使用最小权限子用户或专用身份，不使用主账号永久密钥；凭证只通过用户现场终端写入生产受控环境文件，不进入聊天、命令参数、日志、仓库或 Trellis。
• 不复用来源、权限或有效性无法确认的历史密钥；优先在腾讯云侧为 OA OCR 创建或轮换专用子用户密钥，并撤销确认不再使用的旧密钥。
• 正式启用前需确认 OCR 服务已开通、调用费用/免费额度和告警边界；无凭证、权限不足、欠费或 API 未开通均不得把 provider 切成 tencent。
• 只使用 RecognizeGeneralInvoice 的通用票据识别（高级版）每月 1,000 次专用免费额度，不接仅老客户续费的独立火车票接口；生产使用中国大陆地域，必须在实际账号确认免费包到账、关闭后付费并配置费用或余额告警。额度耗尽时允许 OCR 明确失败，不得自动产生费用。
• 当前无独立 worker 且 server 自身运行 jobs，配置变更只重建实际加载配置的 server；不得额外启动第二个 OCR job executor。
• 真实能力必须使用已授权 PDF 样票验证；缺少授权样票只能证明配置齐全，不能宣称真实 OCR 已通过。
• 指南明确审批链：员工提交、直属主管审批、财务复核；财务付款和回单不由员工预填。
• 伙食补助费按 100 元/人/天包干，市内交通补助费按 80 元/人/天包干；两项补助均不要求发票。
• 补助按出差自然日计算，出发日和返回日均计 1 天，当天往返计 1 天；因个人原因延长的天数不计补助。
• 领取伙食补助后个人餐费不得另报；领取市内交通补助后，出差期间公交、地铁、出租车、网约车等不得另报。
• 公司或其他单位已直接承担餐食或车辆费用的，不重复领取相应补助；城际交通、住宿及其他经批准的必要差旅费用凭有效材料实报实销。
• 当前报销明细没有天数字段，两项补助分别作为独立明细人工填写总额和计算式，例如“伙食补助费：3 天 × 100 元”；不得把现有 per_unit=day 费用标准直接配置为 100/80 元，因为当前校验不会按天数乘算，会误判多日补助。
• travel_bus 保留为城际大巴车票费用；市内交通补助使用独立费用类型，不得共用代码或混同展示。
• 文档不放真实票据、支付截图、账号、订单号、银行信息或完整业务数据。

Acceptance Criteria

• 员工指南能在一页内回答“交什么、传到哪里、金额怎么填、哪些材料不能混传、提交后谁处理”。
• 指南内容与当前页面、服务端格式限制及生产费用类型一致。
• 业务事实源明确火车票和住宿费支付截图为必交补充材料，并包含遮挡、差异、退款和无截图例外规则。
• 腾讯 adapter 使用 RecognizeGeneralInvoice，聚焦测试覆盖住宿电子普通发票、铁路电子客票、无代码票据、多票/不支持票据、大小门禁和敏感原始字段不持久化。
• 腾讯云控制台确认通用票据识别（高级版）每月 1,000 次免费包已到账、中国大陆地域、后付费关闭和费用/余额告警可用；额度耗尽不产生后付费。
• 生产实际 provider 为 tencent，只授予 ocr:RecognizeGeneralInvoice，两个凭证字段已配置但不泄露，external deps smoke、/ready 和运行 job 拓扑通过。
• 住宿电子普通发票和铁路电子客票各一份已授权 PDF 经真实腾讯 OCR 进入可解释终态，并证明没有调用 mock；样票和原始识别 payload 不进入仓库或聊天。
• 明确 OCR 只辅助字段识别/查重，财务仍执行明细—PDF 原件—支付证明复核。
• 员工指南和报销事实源完整写明两项补助的单价、自然日口径、包干不另报、直接承担不重复领取和个人延长不计补助规则。
• 生产种子数据中“伙食补助费”“市内交通补助费”均为独立 enabled 费用类型，travel_bus 仍明确表示城际大巴车票。
• 未配置会把多日补助误判为超标的 100/80 元单条费用标准；指南要求员工按天数人工计算并在说明中写出算式。
• 在真实 OCR 验收完成前不得仅因指南已完成就通知杨俊可以提交。
• 全程不把真实票据、支付截图、完整账号、银行资料、Secret 或原始 payload 写入仓库、任务或聊天。

Out of Scope

• 新增第二个 OCR provider、开放图片发票、自动验真或增加人工发票字段。
• 本轮不做通用发票平台或覆盖全部票种；仅支持现有住宿 VAT/电子普通发票和电子发票（铁路电子客票）主路径。
• 修改报销页面、上传格式、审批规则或自动按天计算；本轮只调整差旅相关费用类型名称并新增独立的市内交通补助类型，不配置 100/80 元费用标准。
• 代替杨俊上传票据、创建报销、提交审批，或代替主管/财务处理。
• 制定覆盖所有费用类别的完整财务制度；本轮只收口首笔差旅的实报实销材料和两项包干补助。

Test Plan

• 静态核对前后端上传格式、明细绑定、员工/财务字段边界。
• 运行腾讯 adapter 和 OCR job 聚焦单测，覆盖两类票种、缺字段、错误分类、大小限制和敏感字段最小化。
• 生产只读核对费用类型、OCR provider 和必要运行状态，仅输出类别与计数。
• 运行文档注册、敏感内容、流程合同、Trellis governance 和 git diff --check。
• 启用真实 OCR 后验证 /ready、构建标识、运行 provider=tencent、单一 job executor 和配置 smoke。
• 经单独样票批准后运行现有 live OCR 验收，输出只保留状态、耗时和脱敏字段命中摘要，并按正常业务/API 生命周期清理或归档测试记录。