# Contributing Guide

<!-- AUTO-GENERATED -->
<!-- Generator: update-docs skill -->
<!-- Last Generated: 2026-04-20 -->

## Prerequisites

| Software | Version | Purpose |
|----------|---------|---------|
| PHP | >=7.4 | Runtime |
| SQL Server | 2016+ | Database |
| LibreOffice | Latest | Word-to-PDF conversion |
| Ghostscript | 9.x+ | PDF manipulation |
| Composer | 2.x | PHP dependency management |

### Required PHP Extensions

- `ext-zip` - ZIP archive support
- `ext-gd` - Image processing
- `ext-sqlsrv` - SQL Server driver
- `ext-pdo` - PDO support

## Installation

```bash
# Clone repository
git clone <repository-url>
cd es_haiya_epr

# Install dependencies
composer install

# Configure environment
cp .env.example .env
# Edit .env with your database credentials

# Initialize database
sqlcmd -S localhost -U sa -P password -i database/EPRHaiyaProcessingTasks.sql
```

## Available Commands

### Queue Processor Commands

```bash
# Interactive mode (development/testing)
php task/queue_processor.php

# Daemon mode (production)
php task/queue_processor.php --daemon

# Custom parameters
php task/queue_processor.php --interval=60 --max-tasks=3

# Show help
php task/queue_processor.php --help
```

### Testing Commands

```bash
# Test HK OCR functionality
php scripts/test_hk_ocr.php

# Test Baidu OCR
php scripts/test_baidu_general_ocr.php

# Test CR/BR template
php scripts/test_cr_br_template.php

# Diagnose HK CR/BR OCR HTTP 421 (image longest-side >8192px limit)
php scripts/test_cr_421_diagnose.php

# Diagnose SQL 40001 deadlocks (read-only, production-safe)
php scripts/diagnose_vat_deadlock.php
```

### Monitoring

```bash
# Linux/Mac - follow logs
tail -f logs/queue_processor_*.log

# Windows PowerShell - follow logs
Get-Content logs\queue_processor_*.log -Wait

# Monitor queue processor
powershell scripts/monitor_queue_processor.ps1
```

## Code Style

This project follows PSR-12 coding standards.

## Testing Procedures

### Manual Testing Checklist

1. **Database Connection**
   ```bash
   # Test database connectivity
   php -r "require 'vendor/autoload.php'; \$db = new PDO('sqlsrv:...');"
   ```

2. **Queue Processor**
   - Start in interactive mode
   - Verify logs show heartbeat
   - Check database for status updates

3. **Document Generation**
   - Submit test application
   - Verify PDF output
   - Check log for errors

### Database Verification

```sql
-- Check pending records
SELECT COUNT(*) FROM EPRRegInfo
WHERE Country = 'ES' AND PushTaxBureauStatus = 5;

-- Check task status
SELECT Status, COUNT(*) FROM EPRHaiyaProcessingTasks GROUP BY Status;
```

## Project Structure

```
es_haiya_epr/
├── src/                    # Main source code
│   ├── DocumentGenerator.php
│   ├── VATDocumentGenerator.php
│   └── ...
├── task/                   # Queue processor
│   └── queue_processor.php
├── scripts/                # Testing/utilities
│   └── test_*.php
├── docs/                   # Documentation
├── logs/                   # Log files
├── template/               # Document templates
└── config/
    └── config.php
```

## Common Issues

| Issue | Solution |
|-------|----------|
| LibreOffice not found | Check path in `config/config.php` |
| Database connection failed | Verify `.env` credentials |
| PDF merge errors | Install Ghostscript |
| OCR failures (ID card) | Check Tencent Cloud API credentials |
| OCR failures (business license) | Check Baidu OCR API credentials; ensure ImageMagick is installed |
| HK CR/BR OCR 返回 421 | 图片最长边 >8192px(阿里云 `multiBlicenseHk` 限制)；`HKCompanyOCR::ensureDimensionLimit` 已约束 ≤8000px。排查用 `scripts/test_cr_421_diagnose.php`(须用大图复现) |
| SQL 40001 deadlock during document generation | vat_db 生产库禁止任何修改（无索引堆表全表扫描是根因），只能应用层重试缓解；排查跑 `php scripts/diagnose_vat_deadlock.php [订单号]`（只读） |

## Submitting Changes

1. Commit directly to `main` (no feature branches)
2. Make changes following code style
3. Test locally
4. `git push` to `origin` (codeup.aliyun.com, configured 2026-08-13)

## Documentation

- [DOCUMENTATION_INDEX.md](DOCUMENTATION_INDEX.md) - Complete doc navigation
- [QUEUE_PROCESSOR_README.md](QUEUE_PROCESSOR_README.md) - Queue processor guide
- [TESTING_CHECKLIST.md](TESTING_CHECKLIST.md) - Testing procedures