# VAT异步任务队列处理器 - 测试检查清单

## 部署前检查

### 数据库准备
- [ ] 确认 EPRRegInfo 表存在 `PushTaxBureauStatus` 和 `Remarks` 字段
- [ ] 确认 EPRHaiyaProcessingTasks 表存在且可写
- [ ] 验证索引已创建
- [ ] 备份数据库

### 代码检查
- [ ] 确认 `task/queue_processor.php` 已更新
- [ ] 确认 VATDataService 类可用
- [ ] 确认所有依赖类都已加载
- [ ] 运行 `php -l task/queue_processor.php` 检查语法

### 环境检查
- [ ] PHP 版本 >= 7.4
- [ ] 数据库连接正常
- [ ] 日志目录 `logs/` 存在且可写
- [ ] 临时目录 `temp/` 存在且可写

## 功能测试

### 1. 基础启动测试

```bash
# 启动处理器
php task/queue_processor.php

# 预期输出：
# ========== VAT异步任务队列处理器 ==========
# 检查间隔: 8秒
# 最大任务数: 1
# 模式: 交互式
# 按 Ctrl+C 停止处理器
# ==========================================
```

**检查项：**
- [ ] 处理器正常启动
- [ ] 显示正确的参数信息
- [ ] 没有错误信息

### 2. 待处理记录查询测试

**准备数据：**
```sql
-- 插入测试数据
INSERT INTO EPRRegInfo (
    Country, PushTaxBureauStatus, EPRBusinessRecordId, CreatedDate
) VALUES (
    'ES', 5, 1, GETDATE()
);
```

**预期日志：**
```
[时间] 查询待处理VAT记录 - count: 1
[时间] 开始处理VAT记录 - vat_id: X
```

**检查项：**
- [ ] 能够查询到待处理记录
- [ ] 记录数正确
- [ ] 日志输出正确

### 3. 任务创建测试

**预期日志：**
```
[时间] 创建新任务 - vat_id: X, task_id: Y
```

**数据库验证：**
```sql
-- 检查任务是否创建
SELECT * FROM EPRHaiyaProcessingTasks WHERE EPRBusinessRecordId = X;
```

**检查项：**
- [ ] 任务记录已创建
- [ ] 任务ID正确
- [ ] 任务状态为 PENDING (0)

### 4. 任务获取测试

**再次运行处理器，预期日志：**
```
[时间] 任务已存在 - vat_id: X, task_id: Y
```

**检查项：**
- [ ] 能够识别已存在的任务
- [ ] 不会重复创建任务
- [ ] 返回正确的任务ID

### 5. 文档生成测试

**预期日志：**
```
[时间] 开始处理任务 - task_id: Y, vat_id: X
[时间] 任务处理完成 - task_id: Y
```

**检查项：**
- [ ] 文档生成成功
- [ ] 没有错误信息
- [ ] 生成的文件存在

### 6. 推送日期更新测试

**预期日志：**
```
[时间] 更新推送日期成功 - vat_id: X, push_date: YYYY-MM-DD
```

**数据库验证：**
```sql
-- 检查任务状态是否更新
SELECT ID, PushTaxBureauStatus, Remarks 
FROM EPRRegInfo 
WHERE ID = X;
```

**检查项：**
- [ ] PushTaxBureauStatus 已更新
- [ ] Remarks 已更新（如适用）

### 7. 重试机制测试

**模拟失败：**
1. 删除必要的文件或数据
2. 运行处理器
3. 观察重试行为

**预期日志：**
```
[时间] 任务失败，将重试: [错误信息]
[时间] 任务失败，已达到最大重试次数: [错误信息]
```

**检查项：**
- [ ] 失败任务自动重试
- [ ] 重试次数正确
- [ ] 达到上限后标记为失败

### 8. 数据库连接保活测试

**运行处理器至少5分钟，预期日志：**
```
[时间] 数据库连接保活成功
```

**检查项：**
- [ ] 每5分钟出现一次保活日志
- [ ] 连接保持正常
- [ ] 没有连接超时错误

### 9. 心跳检测测试

**运行处理器至少1分钟，预期日志：**
```
[时间] ❤️ 心跳 - 运行时间: Xs, 已处理: X个任务, 内存: XMB
```

**检查项：**
- [ ] 每60秒出现一次心跳日志
- [ ] 运行时间递增
- [ ] 内存使用合理

### 10. 公共API受理测试（es_hague_api.php / es_030_api.php）

**前置：** `.env` 配置 `EPR_API_TOKEN`；本地测试可在**消费任务的那台机器**设 `EPR_API_TEST_LOCAL_FILES=true`（queue_processor 生成前用本机 `api_test_file/` 本地文件替代网络下载；受理机器上设不生效）。2026-08-15 起端点内 Bearer 认证已注释关闭（本地调试，与 es_haiya 一致），curl 可省略 `Authorization` 头；恢复认证后 `EPR_API_TOKEN` 必需。

**受理阶段文件校验（2026-09-08 起，对齐 es_haiya）**：受理机器会**真实下载**校验文件——香港公司 CR/BR/BR脚码/CR签发人/查册 5 个文件（COS 桶对象走签名 URL，`local_path` 随任务落库，消费端复用）；非香港公司 `CreditReportPic` 受理时下载并校验内容（需为有效企业信用报告 PDF，否则 400）。本地测试文件 URL 必须从**受理机器**可访问，`EPR_API_TEST_LOCAL_FILES` 只覆盖消费端、不能豁免受理校验。

```bash
# 启动测试服务器（两个端点分别起）
php -S 127.0.0.1:8899 public/es_hague_api.php
php -S 127.0.0.1:8900 public/es_030_api.php

# 301 海牙受理（请求体：西班牙EPR海牙.json，PushType=ES_EPR_REGISTER_HAGUE_FILE）
curl -X POST http://127.0.0.1:8899/ \
  -H "Authorization: Bearer $EPR_API_TOKEN" -H "Content-Type: application/json" \
  --data-binary @西班牙EPR海牙.json

# 030 受理（PushType 换成 ES_EPR_REGISTER_030_FILE，Data 至少含 NameCN/LegalSignedFile/AR）
# AR 必填（M/O），决定 030 文件模板（M=原 mokj 模板，O=Onesea 模板）
curl -X POST http://127.0.0.1:8900/ \
  -H "Authorization: Bearer $EPR_API_TOKEN" -H "Content-Type: application/json" \
  --data-binary @西班牙EPR030.json
```

**检查项：**
- [ ] 响应 `{"code":200,"msg":"success","ProcessMode":"async","data":null,"bizParam":{...}}`
- [ ] 文件参数无效/URL 不可访问/下载失败时返回 400 且错误消息带接口字段名（如 `CR文件(注册证书)（BusinessCRFile）文件下载失败: <URL>`）；非香港公司传非信用报告 PDF 返回 400 内容校验失败提示
- [ ] 301：任务表落 `PushType=301, DataSource=API, TaskStatus=0`；队列处理后 `TaskStatus=2` 且 `ResultData` 含 file1（盖章要求完整 URL）/file2/file3（**OSS 相对路径**，2026-08-31 契约 + 2026-09-02 唯一性子目录 `es_epr_haiya/{业务流水号}/`，file4 待 RPA 030 回填；030 完成后 rpa_030_save.py 调异步结果通知接口，成功 `data` 含 file1~file4+pdf030_url+bizParam）
- [ ] 030：任务表落 `PushType=352, DataSource=API, TaskStatus=2, pdf030_fid=NULL`，且**全量业务字段列已写入**（LegalPersonFullNamePinYin=API 传拆分字段 `LegalPersonNamePinyin`+`LegalPersonSurnamePinyin` 按「名 姓」拼接结果 /LegalPersonIdNumber/LegalPersonCountry(英文)/LegalPersonGender(H/M)/公司地址/CompanyCountry(英文)/CompanyCountryCode 等，与 source 352 任务形态一致），`CompanyName`=Data.NameCN，`BusinessMobile`=NULL，`AR`=M/O（030 模板选择）
- [ ] 交叉请求返回 400（端点只收自己的 PushType，并提示正确端点）
- [ ] 重复提交返回 400 防重；错误 token 返回 401（恢复认证后验证；本地调试认证已注释关闭）
- [ ] 测试任务行验证后删除（避免旧代码队列或 RPA 误处理）
### 11. 内存监控测试

**长时间运行处理器（>30分钟），检查日志：**

**正常情况：**
- [ ] 内存使用稳定
- [ ] 没有内存警告

**异常情况：**
```
[时间] ⚠️ 警告: 内存使用过高 XXX.XXMB
```

**检查项：**
- [ ] 如果出现警告，检查是否有内存泄漏
- [ ] 考虑调整参数或增加服务器内存

## 参数测试

### 1. 自定义间隔测试

```bash
php task/queue_processor.php --interval=10
```

**检查项：**
- [ ] 处理器每10秒检查一次
- [ ] 日志显示正确的间隔

### 2. 自定义任务数测试

```bash
php task/queue_processor.php --max-tasks=3
```

**准备数据：**
```sql
-- 插入3条以上的测试数据
INSERT INTO EPRRegInfo (...) VALUES (...);
INSERT INTO EPRRegInfo (...) VALUES (...);
INSERT INTO EPRRegInfo (...) VALUES (...);
INSERT INTO EPRRegInfo (...) VALUES (...);
```

**检查项：**
- [ ] 每次最多处理3个任务
- [ ] 日志显示正确的任务数

### 3. 守护进程模式测试

```bash
php task/queue_processor.php --daemon
```

**检查项：**
- [ ] 处理器在后台运行
- [ ] 没有控制台输出
- [ ] 日志文件正常记录

### 4. 帮助信息测试

```bash
php task/queue_processor.php --help
```

**检查项：**
- [ ] 显示帮助信息
- [ ] 参数说明清晰

## 错误处理测试

### 1. 数据库连接失败

**模拟：** 关闭数据库或断开网络

**预期行为：**
- [ ] 记录连接错误
- [ ] 尝试重新连接
- [ ] 继续运行

**预期日志：**
```
[时间] 数据库连接保活失败，尝试重新连接
[时间] 数据库连接重建成功
```

### 2. 查询失败

**模拟：** 删除表或修改权限

**预期行为：**
- [ ] 记录查询错误
- [ ] 继续运行
- [ ] 不会崩溃

**预期日志：**
```
[时间] 查询待处理VAT记录失败
```

### 3. 任务创建失败

**模拟：** 删除 EPRHaiyaProcessingTasks 表或修改权限

**预期行为：**
- [ ] 记录创建错误
- [ ] 任务处理失败
- [ ] 继续处理下一个任务

**预期日志：**
```
[时间] 创建或获取任务失败
```

### 4. 文档生成失败

**模拟：** 删除必要的文件或数据

**预期行为：**
- [ ] 记录生成错误
- [ ] 触发重试机制
- [ ] 继续处理

**预期日志：**
```
[时间] 任务处理失败
[时间] 任务失败，将重试
```

## 性能测试

### 1. 单任务处理时间

**测试：** 处理1个任务的平均时间

**记录：**
- [ ] 开始时间：___
- [ ] 结束时间：___
- [ ] 处理时间：___ 秒

### 2. 批量处理性能

**测试：** 处理10个任务的总时间

```bash
php task/queue_processor.php --max-tasks=10
```

**记录：**
- [ ] 开始时间：___
- [ ] 结束时间：___
- [ ] 总处理时间：___ 秒
- [ ] 平均每个任务：___ 秒

### 3. 内存使用

**测试：** 长时间运行的内存使用情况

**记录：**
- [ ] 启动时内存：___ MB
- [ ] 处理10个任务后：___ MB
- [ ] 处理100个任务后：___ MB
- [ ] 最大内存：___ MB

### 4. CPU使用

**测试：** 处理器的CPU占用率

**记录：**
- [ ] 空闲时CPU：___ %
- [ ] 处理时CPU：___ %
- [ ] 平均CPU：___ %

## 集成测试

### 1. 完整流程测试

**步骤：**
1. [ ] 启动处理器
2. [ ] 插入测试数据
3. [ ] 观察处理过程
4. [ ] 验证数据库更新
5. [ ] 检查日志记录
6. [ ] 停止处理器

### 2. 多次运行测试

**步骤：**
1. [ ] 第一次运行：创建任务
2. [ ] 第二次运行：获取现有任务
3. [ ] 第三次运行：处理完成的任务

### 3. 并发测试

**步骤：**
1. [ ] 启动多个处理器实例
2. [ ] 观察是否有冲突
3. [ ] 检查数据一致性

## 回归测试

### 1. 旧功能验证

- [ ] 任务状态更新正常
- [ ] 错误通知发送正常
- [ ] 临时文件清理正常
- [ ] 日志记录正常

### 2. 新功能验证

- [ ] 直接查询VAT表正常
- [ ] 自动创建任务正常
- [ ] 推送日期更新正常
- [ ] 重试机制正常

## 生产部署前最终检查

- [ ] 所有功能测试通过
- [ ] 所有错误处理测试通过
- [ ] 性能测试结果满足要求
- [ ] 日志记录完整清晰
- [ ] 数据库备份已完成
- [ ] 回滚方案已准备
- [ ] 监控告警已配置
- [ ] 文档已更新
- [ ] 团队已培训

## 测试报告模板

```
测试日期：YYYY-MM-DD
测试人员：___
测试环境：___
PHP版本：___
数据库：___

总体结果：[ ] 通过 [ ] 失败

功能测试：
- 基础启动：[ ] 通过 [ ] 失败
- 记录查询：[ ] 通过 [ ] 失败
- 任务创建：[ ] 通过 [ ] 失败
- 文档生成：[ ] 通过 [ ] 失败
- 日期更新：[ ] 通过 [ ] 失败

错误处理：
- 连接失败：[ ] 通过 [ ] 失败
- 查询失败：[ ] 通过 [ ] 失败
- 创建失败：[ ] 通过 [ ] 失败

性能指标：
- 单任务时间：___ 秒
- 批量处理：___ 秒
- 内存使用：___ MB
- CPU占用：___ %

备注：
___

签名：___ 日期：___
```

## 常见问题排查

| 问题 | 检查项 | 解决方案 |
|------|-------|--------|
| 没有找到待处理记录 | 数据库中是否有数据 | 插入测试数据 |
| 任务创建失败 | 表权限 | 检查数据库权限 |
| 推送日期未更新 | 文件生成是否成功 | 检查日志 |
| 内存持续增长 | 是否有内存泄漏 | 检查日志警告 |
| 处理器崩溃 | 错误日志 | 查看详细错误信息 |