109 行
9.1 KiB
Markdown
109 行
9.1 KiB
Markdown
# 实施计划
|
|
|
|
## 1. 外部前置门禁
|
|
|
|
- [x] 用户确认采用 OA OCR 专用最小权限子用户密钥。
|
|
- [x] 用户在腾讯云侧创建该专用子用户和密钥。
|
|
- [x] 在实际账号确认通用票据识别（高级版）每月 1,000 次专用免费包已到账，生产配置使用中国大陆地域。
|
|
- [x] 在 OCR 控制台设置页确认后付费关闭；额度耗尽时接受 OCR 失败关闭。
|
|
- [ ] 配置费用或余额告警作为二次兜底。
|
|
- [ ] 确认腾讯 OCR 服务和 `ocr:RecognizeGeneralInvoice` 最小权限可用，不接独立火车票接口。
|
|
- [ ] 确认住宿电子普通发票和铁路电子客票各一份 PDF 样票的测试授权及仓库外受控位置；不得向 Codex 或聊天提供票据。
|
|
|
|
## 2. 腾讯 adapter 修正
|
|
|
|
- [x] 将现有腾讯调用改为 `RecognizeGeneralInvoice`，固定单页 PDF 和最小返回选项。
|
|
- [x] 分别归一化住宿 VAT/电子普通发票和 `ElectronicTrainTicketFull`。
|
|
- [x] 按安全票种标识执行必填字段检查；删除代码/号码互相伪回填。
|
|
- [x] 不持久化腾讯原始响应、乘车人姓名、证件号或完整票面字段；命中旧版腾讯缓存时按同一白名单压缩。
|
|
- [x] 发票上传增加 7MiB OCR 输入上限和明确错误。
|
|
- [x] 增加两类票种、无代码、多票/不支持票据、敏感字段、大小门禁和 provider 错误聚焦测试。
|
|
|
|
## 3. 生产配置
|
|
|
|
- [x] 对当前生产环境文件制作受控、限权、短期回退副本，不输出内容。
|
|
- [x] 由用户在现场终端静默写入 `OCR_PROVIDER=tencent` 及专用凭证；地域设置为中国大陆地域。
|
|
- [x] 脱敏检查 provider、凭证非空、环境文件权限和配置合同。
|
|
- [x] 仅重建实际执行 jobs 的 server，不启动独立 worker。
|
|
|
|
### 3.1 生产部署根收敛
|
|
|
|
- [x] 只读确认活动 Compose、生产环境文件和四个运维 timer 均引用重复嵌套部署根。
|
|
- [x] 暂停相关 timer，将活动根原子改名为时间戳回退目录，并建立干净标准单层部署根。
|
|
- [x] 把生产环境文件在远端复制到标准相对位置，保持所有者和 `0600` 权限；不回显或经本地传输 Secret。
|
|
- [x] 使用 `DEPLOY_DATA_MODE=existing`、既有外置数据库/附件宿主目录和同一 Compose project 发布批准提交；未初始化数据或创建 worker。
|
|
- [x] 重新安装 daily、watchdog、drill-reminder 和 WARCH3 timer，确认 unit 不再引用重复目录。
|
|
- [x] 验证 `/ready`、构建标识、单一 job executor、四个 timer 状态和一次受控备份/新鲜度检查；旧根仅保留作短期回退，不在本任务删除。
|
|
|
|
回退点：标准根发布或任一 timer 验收失败，恢复时间戳回退根及原 unit 引用并重建原 server；数据库和附件宿主目录不移动、不重置。
|
|
|
|
回退点：外部依赖 smoke 前若任一配置门禁失败，恢复变更前环境文件并重建 server；保持真实票据禁止上传。
|
|
|
|
## 4. 生产与真实能力验证
|
|
|
|
- [x] 检查公网 `/ready` 和预期构建标识。
|
|
- [x] 在 server 内运行现有 external deps 和运行时 smoke，不输出 Secret 或原始响应。
|
|
- [x] 确认实际 provider 为 `tencent`，且只有一个 OCR job executor。
|
|
- [x] 修正 live 样票脚本：复用 `RecognizeGeneralInvoice`、按票种必填字段和安全持久化白名单，支持单 PDF 标准输入且仅输出脱敏摘要。
|
|
- [x] 使用合成 PDF/provider 响应覆盖住宿、铁路、非 PDF、超限、缺字段和原始响应不输出，并完成本地门禁、提交和生产部署。
|
|
- [x] 为铁路 `Total`/`Fare` 增加只含存在、类型、非空和可解析布尔值的临时诊断；证明持久化白名单丢弃诊断且 live runner 不输出真实值。
|
|
- [ ] 完成本地门禁、提交和生产部署后，使用剩余一次授权诊断铁路金额字段；铁路未 PASS 时仍不调用住宿样票。
|
|
- [ ] 经单独样票批准后分别运行住宿电子普通发票和铁路电子客票 live OCR PDF 验收。
|
|
- [ ] 只保存脱敏状态、耗时、provider 和字段命中摘要；确认不存在 mock 调用证据。
|
|
- [ ] 按正常 API/业务生命周期清理或归档测试记录，并执行只读残留检查。
|
|
|
|
回退点：真实调用失败时停止样票和真实票据上传，保留可解释失败摘要；不得改库伪造成功或切回 mock 处理真实票据。
|
|
|
|
## 5. 文档更新
|
|
|
|
- [x] 更新 `docs/员工快速上手.md` 的差旅报销一页指南。
|
|
- [x] 更新 `docs/报销发票附件规则.md` 的支付截图、实报实销差异、退款/代付和人工复核规则。
|
|
- [x] 不新建平行员工指南，不写入真实票据、支付信息、账号或环境路径。
|
|
|
|
## 6. 验证与审查
|
|
|
|
- [x] 静态核对页面/API 上传格式、明细绑定和员工/财务字段边界。
|
|
- [x] 运行腾讯 adapter、OCR service/job 和发票上传聚焦测试。
|
|
- [x] `cd server && npm run prisma:validate`
|
|
- [x] `node scripts/qa/check-process-contract.mjs --baseline --json`
|
|
- [x] `node scripts/qa/audit-docs.mjs --check-registry`（0 个错误；22 个既有未注册文档 warning，本任务未新增）
|
|
- [x] `node scripts/qa/check-trellis-governance.mjs`
|
|
- [x] `git diff --check`
|
|
- [ ] 对生产配置、样票证据和文档口径进行只读复核。
|
|
- [ ] 部署与公网检查均通过后，才通知杨俊可以提交真实差旅报销。
|
|
|
|
## 2026-07-29 live OCR 验收工具生产部署记录
|
|
|
|
- 已部署提交 `fa326f9`；公网 `/ready` 与运行容器构建标识一致。
|
|
- external deps smoke、runtime smoke 和公网前端资源扫描通过；实际 OCR provider 为 `tencent`。
|
|
- 运行拓扑为 server 单一 job executor，未启动 worker。
|
|
- 自动备份 daily、watchdog、drill-reminder 与 WARCH3 四个 timer 均为 enabled/active，冻结构建与标准部署根一致，未引用旧重复目录。
|
|
- 部署后受控自动备份和新鲜度检查均成功，未调用真实 OCR 样票。
|
|
- 真实住宿和铁路样票验收仍等待单独调用授权；在两类样票通过前，不通知员工上传真实票据。
|
|
|
|
## 2026-07-29 授权样票验收尝试
|
|
|
|
- 已匿名选择铁路 PDF 并执行最多一次 provider 调用，但外层 shell 在探针非零退出时提前终止，未保留已生成的脱敏 JSON，因此本次不能作为 PASS 或可解释 provider 终态证据。
|
|
- 按“第一份未取得明确 PASS 即停止”约束，未调用住宿样票，也未重试铁路样票。
|
|
- 空 stdin 捕获自检证明修正后的调用方式可在 provider 调用前保留 `HOLD/sample_empty` 摘要；该自检未消耗 OCR 次数。
|
|
- 本次没有创建 OA 发票、附件或数据库记录；真实样票仍未验收通过，员工上传门禁保持关闭。
|
|
- 经额外授权后，修正包装器重新验收铁路 PDF，明确得到 `HOLD/sample_pdf_invalid`；失败发生在 provider 调用前，本次未消耗腾讯 OCR 次数。
|
|
- 匿名结构预检确认铁路 PDF 的 EOF 后存在非空白尾随数据，不符合现行严格 PDF 终止边界；不截断原件、不放宽安全门禁，需重新取得官方原始电子票据。
|
|
- 住宿 PDF 的 PDF 头部、EOF 终止边界和 7 MiB 上限预检均通过，但因铁路票未 PASS，未调用住宿样票 provider。
|
|
- 用户另行指定的铁路 PDF 通过同一结构预检，证明上一份 `sample_pdf_invalid` 是旧文件特有的 EOF 尾随数据问题，不是所有铁路 PDF 或校验器普遍失败。
|
|
- 新铁路 PDF 经真实腾讯 OCR 识别为单张 `ElectronicTrainTicketFull`，票号、日期和购买方字段命中，但 `totalAmount` 未命中，终态为 `HOLD/missing_required_fields:totalAmount`；未输出或持久化任何识别值、原始响应或票面字段。
|
|
- 当前适配器已按腾讯 SDK 合同读取铁路票 `Total` 与 `Fare` 两个金额字段；现有脱敏摘要不能区分 provider 未返回金额与返回值格式不可解析，需在另行批准后增加字段形态布尔诊断。铁路票未 PASS，因此仍未调用住宿样票 provider。
|
|
|
|
## 2026-07-29 铁路金额字段诊断实现验证
|
|
|
|
- 聚焦测试 19 项、完整后端 168 个文件/1075 项、Prisma validate、前端 typecheck/build、流程合同、Trellis governance、敏感内容和 diff 门禁通过；仅有既有依赖弃用提示与 22 个既有未注册文档 warning。
|
|
- P2 聚合器的后端聚焦测试 94 项及前端门禁通过；其业务流因合成账号首次改密状态失败，live-readiness 因本地旧凭据和部署前构建标识不一致失败。进入 live OCR 步骤时已主动终止，生产最近 10 分钟新增发票和 OCR 尝试记录均为 0。
|
|
- 诊断只存在于 provider 返回到 live runner 的进程内对象，持久化 sanitizer 丢弃整个 diagnostics；合成敏感标记未出现在序列化摘要中。
|
|
|
|
## 风险文件与操作
|
|
|
|
- 生产环境文件：包含 Secret，只允许用户现场静默输入；不得由补丁、聊天或命令参数传入。
|
|
- server 重建：短暂影响 OA；仅操作当前实际 server，保留回退配置。
|
|
- 真实样票：包含发票和个人/企业信息；只留在仓库外受控位置。
|
|
- 文档：员工指南必须短且与生产费用类型、PDF-only 和附件入口一致，避免把财务付款回单误写成员工材料。
|