# VAT队列处理器 - 快速参考卡片

## 🚀 快速启动

```bash
# 交互模式（开发/测试）
php task/queue_processor.php

# 守护进程模式（生产）
php task/queue_processor.php --daemon

# 自定义参数
php task/queue_processor.php --interval=60 --max-tasks=3

# 显示帮助
php task/queue_processor.php --help
```

> ⚠️ **生产与本地分离**：生产部署在 `E:\phpProject\PRO\es\es_haiya_epr`（nssm 服务 `EsEprHaiyaFileProcess`，PHP `E:\amazonProject\php-8.3.25\php.exe`；历史日志中的 `E:\phpProject\es_haiya_epr` 为旧部署路径），与本地开发仓库（`E:\ou\meiou-app\es_haiya_epr`）不是同一份。排查生产行为差异时先确认生产代码已同步（**2026-09-08 生产已同步仓库最新代码，含 aac1372**；此前基线 10d47c0 已作废；API 接口流程未测试，生产仅 source 流程在用）。

## 📊 监控

```bash
# 查看实时日志
tail -f logs/queue_processor_*.log

# 查看进程
ps aux | grep queue_processor

# 查看内存
top -p <pid>
```

## 🛑 停止处理器

```bash
# 交互模式
Ctrl+C

# 守护进程模式
kill <pid>
# 或
taskkill /PID <pid>  # Windows
```

## 🗄️ 数据库检查

```sql
-- 查看待处理记录
SELECT COUNT(*) FROM EPRRegInfo 
WHERE Country = 'ES' AND PushTaxBureauStatus = 5;

-- 查看任务状态
SELECT Status, COUNT(*) FROM EPRHaiyaProcessingTasks 
GROUP BY Status;

-- 查看推送日期
SELECT ID, PushTaxBureauDate, PushApiDate 
FROM EPRRegInfo 
WHERE Country = 'ES' LIMIT 10;
```

## 📝 日志位置

```
logs/queue_processor_YYYYMMDD.log
```

## ⚙️ 参数说明

| 参数 | 默认值 | 说明 |
|------|-------|------|
| --interval | 8 | 检查间隔（秒） |
| --max-tasks | 1 | 每次处理任务数 |
| --daemon | - | 守护进程模式 |
| --help | - | 显示帮助 |

## 🔄 工作流程

```
查询VAT表 → 创建/获取任务 → 生成文件 → 更新推送日期 & 任务状态
```

> 每轮循环依次处理：030 流程（PushType=352：任务直接以 TaskStatus=2 落库交 RPA 处理，PHP 不设 PushTaxBureauStatus=6）→ API 海牙任务（DataSource=API, PushType=301：从 TaskData.generator_data 生成，不写 source 业务表）→ 301 海牙流程（生成文件成功后 PHP 设 6）。详见 CLAUDE.md。

## 📄 更新海牙认证签字盖章要求静态文件

```bash
# 1. 新 PDF 放入 template/，文件名带日期（如 2.海牙认证签字盖章要求 20260819.pdf）
#    三处同步：scripts/upload_haiya_requirement.php + config/config.php + src/VATAsyncProcessor.php 兜底默认值
# 2. 上传 COS，输出 URL 填入 .env 的 HAIYA_SIGNATURE_REQUIREMENT_URL（路径含双段 vat_factory/es/ 属 CosUploader 自动前缀，勿改）
php scripts/upload_haiya_requirement.php
# 3. 重启生产 queue_processor（进程内缓存旧配置）
# 4. 存量订单由业务重新点「重新生成」→ 附件表自动删旧插新（按 InfoId+FileFrom=3+文件名关键字）
```

## 📋 任务状态

| 值 | 状态 | 说明 |
|----|------|------|
| 0 | PENDING | 待处理 |
| 1 | PROCESSING | 处理中 |
| 2 | COMPLETED | 已完成 |
| 3 | FAILED | 失败 |
| 4 | CANCELLED | 已取消 |

## 🎯 常见命令

```bash
# 启动并监控
php task/queue_processor.php 2>&1 | tee logs/manual.log

# 后台运行
nohup php task/queue_processor.php --daemon > /dev/null 2>&1 &

# 查看最新日志
tail -20 logs/queue_processor_*.log

# 统计处理数
grep "任务处理完成" logs/queue_processor_*.log | wc -l

# 查看错误
grep "ERROR\|FAILED" logs/queue_processor_*.log
```

## 🚨 常见问题

| 问题 | 解决方案 |
|------|--------|
| 没有找到记录 | 检查 PushTaxBureauStatus = 5 |
| 任务创建失败 | 检查表权限 |
| 状态未更新 | 检查文件生成是否成功 |
| 内存持续增长 | 调整 --max-tasks 参数 |
| 处理器崩溃 | 查看日志找出原因 |
| 生成文件报 40001 死锁 | vat_db 禁止修改，只能应用层重试缓解；跑 `php scripts/diagnose_vat_deadlock.php [订单号]`（只读） |
| 香港公司报缺少查册文件 | `php scripts/diagnose_missing_particulars.php [订单号]`（只读全链路复现）；重推可救 |

## 📚 文档导航

- **完整指南：** `docs/QUEUE_PROCESSOR_README.md`
- **测试清单：** `docs/TESTING_CHECKLIST.md`

## 💡 性能建议

| 场景 | 参数 |
|------|------|
| 高吞吐量 | `--interval=10 --max-tasks=5` |
| 低资源占用 | `--interval=60 --max-tasks=1` |
| 平衡 | `--interval=30 --max-tasks=2` |

## 🔍 监控指标

- **心跳：** 每60秒
- **数据库保活：** 每5分钟
- **内存警告：** 超过800MB
- **默认间隔：** 8秒

## 📞 获取帮助

1. 查看日志：`logs/queue_processor_*.log`
2. 查看文档：`docs/` 目录
3. 检查数据库：运行SQL查询
4. 查看测试清单：`docs/TESTING_CHECKLIST.md`

---

**快速参考卡片** | 更新于 2026-09-08