# VAT异步任务队列处理器 - 文档索引

**最后更新：** 2026-09-08

---

## 文档导航

### 快速开始

| 文档 | 说明 |
|------|------|
| [QUICK_REFERENCE.md](QUICK_REFERENCE.md) | 常用命令速查表 |
| [QUEUE_PROCESSOR_README.md](QUEUE_PROCESSOR_README.md) | 完整使用指南 |

### 证件支持

| 文档 | 说明 |
|------|------|
| [PDF_ID_CARD_SUPPORT.md](PDF_ID_CARD_SUPPORT.md) | 身份证PDF支持 + 护照处理说明 |

### 配置与部署

| 文档 | 说明 |
|------|------|
| [ENV.md](ENV.md) | 环境变量说明 |
| [TABLE_MIGRATION_GUIDE.md](TABLE_MIGRATION_GUIDE.md) | 数据库表迁移指南 |
| [IMPLEMENTATION_SUMMARY.md](IMPLEMENTATION_SUMMARY.md) | 实现概要 |

### 测试与运维

| 文档 | 说明 |
|------|------|
| [TESTING_CHECKLIST.md](TESTING_CHECKLIST.md) | 测试清单 |
| [WECHAT_NOTIFICATION.md](WECHAT_NOTIFICATION.md) | 企微通知配置 |

### 其他

| 文档 | 说明 |
|------|------|
| [CONTRIBUTING.md](CONTRIBUTING.md) | 贡献指南 |
| [PDF_FLOW_DIAGRAM.txt](PDF_FLOW_DIAGRAM.txt) | PDF生成流程图 |
| UNIFIED_API_DESIGN.md（本地参考，不入库） | 统一接收分发接口设计 + 本项目 es_hague_api.php 公共API；主副本在 app_withdrawn 项目 `docs/UNIFIED_API_DESIGN.md` |

---

## 更新历史

| 日期 | 更新内容 |
|------|--------|
| 2026-09-08 | 公共 API 受理文件访问对齐 es_haiya（**未提交**）：香港 CR/BR/BR脚码/CR签发人/查册 5 文件受理即真实预下载（`VATDataService::buildFileArrayFromParam` 增 `preDownload`/`fieldName`，下载走 COS 签名 URL `q-sign` 参数，`local_path` 随 generator_data 落库、消费端复用，文件被清/跨机回退 F_FilePath 重下）；非香港公司信用报告受理真实下载 + `isCreditReportPDF` 内容校验（新增 `downloadApiFileToTemp`，es_hague_api.php 调用，临时文件 `finally` 即清）；全部文件错误消息带接口字段名。解决「CR文件(注册证书)（BusinessCRFile）文件不存在或不可访问（HTTP 403）」——受理 URL 探测对私桶/HEAD 403 误报。生成阶段完整校验（validateCreditReportFile PDF/ZIP/RAR）不变；source 流程零改动 |
| 2026-09-08 | 查册检测链路容错+失败日志（aac1372，对齐信用报告 6670e7a 修复模式）：`is_company_particulars_pdf` 取最后一行 JSON（兼容 BOM）+ 执行/解析失败记日志（return_code/raw_output）、`company_particulars_detector.py` 抑制第三方 warnings、`VATDataService::findCompanyParticularsFile` 下载失败记 warning；新增 `scripts/diagnose_missing_particulars.php`（只读全链路复现+时间线）与 `scripts/test_company_particulars_detector.php`。**2026-09-07 用户确认生产已同步仓库最新代码（含 6670e7a），基线 10d47c0 作废**；aac1372 已推送 main 并于 2026-09-08 部署生产；全量代码已上正式环境，但 **API 接口流程未测试**——生产目前在跑的只有 source 流程 |
| 2026-09-03 | ① 异步结果回调默认地址：`ES_HAGUE_RESULT_CALLBACK_URL` 默认 `https://test-cloud.usaeu.com/prod-api/delivery/rpa/callback`（.env 未配置此键即生效，显式留空禁用；config/.env.example/ENV.md 同步）；② source 流程隔离加固：`insertHaiyaSignatureRequirement` 改先插后删（插入失败保留旧记录，防附件永久丢失）、`getOldTaskAttachment`/`process030Flow` 防重加 `DataSource` 过滤、API 侧 `findUnprocessed030TaskByBusinessId` 对称加 `DataSource='API'`；③ 信用报告检测器解析容错：`OCRDataProcessor::isCreditReportPDF` 取最后一行 JSON 解析 + 失败打印完整原始输出，`credit_report_detector.py` 抑制第三方警告（解决生产"无法解析Python脚本输出"盲区）；已用 POEPR20260902000001 生产原件（MD5=91ec094a，与 COS ETag 一致）本地验证通过（is_credit_report=true，文本命中）。以上待生产部署（生产基线 10d47c0，2026-08-06） |
| 2026-09-02 | API 流程生成结果 COS 键追加唯一性子目录（对齐 es_haiya）：`{api_flow_oss_prefix}{当前年}/es_epr_haiya/{业务流水号}/{文件名}`——业务流水号 = bizParam.BusinessSerialNumber（受理必填）、PHP 侧兜底 BusinessId、python 030 侧兜底任务ID；`src/functions.php` 新增 `sanitize_business_code`（目录名清洗，红线）；`VATDocumentGenerator::uploadToTencentCOS` 海牙整本与 APODERAMIENTO 两处调用点、`python/rpa_030_save.py` 030 同规则；契约同步 docs/ENV.md、docs/QUEUE_PROCESSOR_README.md、python/README.md、.env.example（UNIFIED_API_DESIGN.md 本地保留） |
| 2026-08-31 | API 流程生成结果改 **OSS 相对路径契约**（对齐 es_haiya）：COS 键 = `{api_flow_oss_prefix}{当前年}/es_epr_haiya/{文件名}`（不带域名、不生成 COS 签名，域名由对方拼接），COS 桶分流（API→SaaS 共享桶 usaeu，source→vat 桶），入库（ResultData.file2/file3/cos_key/cos_url、pdf030_result_url）与结果通知 files.url 均用相对路径；file1 盖章要求为外部静态完整 URL（例外）；`python/rpa_030_save.py` 移除上传签名（仅 rpa_030_get.py 取数下载保留）；queue_processor 重启依赖 |
| 2026-08-19 | 海牙认证签字盖章要求静态文件更新为 20260819 版本（config/config.php、scripts/upload_haiya_requirement.php、VATAsyncProcessor 兜底默认值三处同步）；`insertHaiyaSignatureRequirement` 重新生成时改为按 InfoId+FileFrom=3+文件名关键字删旧插新（修复原精确文件名查重跳过导致重新生成时旧文件不更新、新文件不插入）；更新静态文件后需重启生产 queue_processor，存量订单由业务重新点「重新生成」自动替换 |
| 2026-08-18 | 030 文件增加 Onesea 模板：EPRHaiyaProcessingTasks 新增 `AR` 列（迁移 2026_08_18_add_ar，M=mokj 原模板/O=Onesea 模板）；030 流程（source/API）AR 强制必填（与 301 共用 validateArField）；四个落库路径（source/API × 301/352）写 AR；rpa_030_get.py AR 加入必填检查并归一化交 RPA 选模板；接口文档（app_withdrawn 主副本 §4.4/§14）同步 AR 必填说明 |
| 2026-08-14 | 公共API 改造为异步受理（对齐 UNIFIED_API_DESIGN §6/§13）并拆分为两个独立端点：`public/es_hague_api.php`（`ES_EPR_REGISTER_HAGUE`/301，落 pending 由队列消费生成）与 `public/es_030_api.php`（`ES_EPR_REGISTER_030`/030，直接 TaskStatus=2 落库等 RPA，API 流程不写 BusinessMobile）；传输层助手 `src/EprApiEndpoint.php`；已执行迁移 2026_08_11_add_data_source（DataSource 列+索引，此前未执行）；新增配置 SOURCE_OSS_BASE_URL/ALLOWED_DOWNLOAD_HOSTS/EPR_API_TEST_LOCAL_FILES（api_test_file 本地测试） |
| 2026-08-14 | API 流程彻底脱离 source 库：030 受理升级为全量业务字段校验并写入全量任务表字段列（与 source 352 形态一致）；删除 CountryCache 查库（国家英文名以接口传值 `*_en` 为准）；`pdf030_save.py` 补 DataSource 分流（API 任务只回填任务表，不写 Base_AnnexesFile/EPRRegInfo）；测试 JSON 030 改为全量字段（西班牙EPR030.json） |
| 2026-08-15 | 同步 es_haiya 的 API 配置：移植 `AsyncResultNotifier`（`ES_HAGUE_RESULT_CALLBACK_URL`/`ES_HAGUE_CALLBACK_TIMEOUT`，301 任务最终失败时回调调用方）；`SOURCE_OSS_BASE_URL`/`ALLOWED_DOWNLOAD_HOSTS` 默认值改为上游 SaaS OSS（usaeu bucket，与 es_haiya 一致） |
| 2026-08-13 | UNIFIED_API_DESIGN.md 移出版本库（本地保留不入库）：主副本在 app_withdrawn 项目 docs/，使用前 git pull、勿在那边 push，字段变更两边同步 |
| 2026-08-15 | 公共API 端点内 Bearer 认证暂时注释关闭（本地调试，与 es_haiya 一致）；ResultData 文件槽契约统一为**完整 OSS URL**：file1=盖章要求（PHP 写静态共享 URL）、file2/file3=海牙/APODERAMIENTO、file4=030（RPA 经 rpa_030_save.py merge 回填，含被重定向 API 任务）；rpa_test 任务表结构同步至与 rpa 一致（补 4 列 + pdf_result 改 INT）；`pdf030_save.py` 改名 `rpa_030_save.py`，新增 `rpa_030_get.py`（030 生成前取任务，source/API 都支持）；RPA 030 脚本加异步结果通知：rpa_030_save.py 030 处理完成/失败时、rpa_030_get.py 字段检查失败/异常时调异步结果通知接口（信封同 AsyncResultNotifier，通知失败不阻断主流程） |
| 2026-08-13 | 新增死锁排查脚本 scripts/diagnose_vat_deadlock.php（vat_db 只读诊断 40001）；索引补录根目录 UNIFIED_API_DESIGN.md（es_hague_api.php 公共API + 任务表 DataSource 列） |
| 2026-08-10 | 030 文件保存（pdf030_save.py）改为按 EPRBusinessRecordId 清理 301/352 两套流程的旧 030 文件，只保留最新一份；pdf030_save.py 纳入版本管理 |
| 2026-08-08 | 030 流程补齐：EPRHaiyaProcessingTasks 新增 `BusinessMobile`（业务手机号，来源 Base_User.F_Mobile）、`CompanyName`（公司中文名称，来源 Base_Customer_Company.NameCN）列；修复 352 任务落库失败（补传 BusinessSerialNumber/EPRRegInfoId）；防重复改为仅挡 `pdf030_fid IS NULL` 的任务，支持「重新生成文件」重建任务 |
| 2026-08-07 | 队列处理器新增 030 流程（PushType=352）：只校验数据不查文件，复制签名文件字段到任务表，任务直接以 TaskStatus=2 落库交 RPA 030 程序处理；EPRHaiyaProcessingTasks 新增 `PushType` 列区分 301/352 任务，防重复/重试查询按流程过滤 |
| 2026-06-17 | PushTaxBureauStatus=6 由 PHP 端文件生成成功后设置；EPRHaiyaProcessingTasks: `pdf_result` 改为 INT（状态码 0/1/2/3），新增 `pdf030_fid`、`EPRRegInfoId` 字段；启用 `database/migrations/` 目录 |
| 2026-04-29 | 清理冗余文档（29→11）；新增护照处理说明 |
| 2026-04-20 | 状态字段迁移到 EPRRegInfo 表 |
| 2026-03-19 | 初始版本 |