# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

This is a PHP-based document generation system that creates consolidated PDF documents for VAT registration and Hague apostille applications. The system handles two types of companies:

- **Mainland Chinese companies**: Generate authorization documents + credit report + business license + ID card translations
- **Hong Kong companies**: Generate authorization documents + CR/BR translations + 查册文件 (only for HagueType 1/2) + ID card translations

## Core Business Logic (CRITICAL)

### Document Generation Flow at Line 310 (`VATDocumentGenerator.php`)

```
generateFromCreditReport() line 310:
│
├── Is Hong Kong Company?
│   ├── YES → Always use 海牙 flow (never 免海牙)
│   │         Pass HagueType to determine 查册文件 generation:
│   │         • HagueType 1 (包装法): Generate 查册文件
│   │         • HagueType 2 (包装法+VAT): Generate 查册文件
│   │         • HagueType 3 (VAT): Skip 查册文件
│   │
│   └── NO → Check SpecsName for 海牙/免海牙
│             ├── Contains "免海牙" → Use 免海牙 flow
│             └── Otherwise → Use 海牙 flow
```

### HagueType Values
- `1` = 包装法 (Packaging Law)
- `2` = 包装法+VAT (Packaging Law + VAT)
- `3` = VAT only

### Key Flags
- `$isHongKongCompany`: Detected via `CompanyCountry` field (香港/HK/Hong Kong)
- `$isApostilleNotRequired`: Detected via `SpecsName` containing "免海牙"
- `$hagueType`: Read from `HagueType` field, determines document requirements for HK companies

### Documents Generated

**Non-Hong Kong Companies (海牙 flow):**
1. 海牙授权书 (西班牙语)
2. 海牙授权书 (英语)
3. 收信授权书 (西班牙语)
4. 收信授权书 (英语)
5. 企业信用报告 (原件)
6. 企业信用报告 (西班牙语翻译件)
7. 营业执照 (原件)
8. 营业执照 (西班牙语翻译件)
9. 身份证 (原件)
10. 身份证 (西班牙语翻译件)

**Non-Hong Kong Companies (免海牙 flow):**
1. 免海牙授权书
2. 企业信用报告 (原件+翻译件)
3. 营业执照 (原件+翻译件)
4. 身份证 (原件+翻译件)

**Hong Kong Companies (always 海牙 flow):**
1. 海牙授权书 (西班牙语)
2. 海牙授权书 (英语)
3. 收信授权书 (西班牙语)
4. 收信授权书 (英语)
5. CR翻译件 (Certificate of Registration)
6. BR翻译件 (Business Registration)
7. 查册文件 (only for HagueType 1 or 2)
8. 身份证 (原件+翻译件)

## Core Architecture

### Main Components

1. **VATDocumentGenerator.php** (`src/VATDocumentGenerator.php`) - Primary orchestrator for VAT document generation with Hong Kong company support
2. **VATDataService.php** (`src/VATDataService.php`) - Database queries for VAT business data
3. **VATAsyncProcessor.php** / **VATAsyncTaskProcessor.php** / **VATAsyncDataProcessor.php** - Async VAT document generation pipeline
4. **DocumentGenerator.php** (`src/DocumentGenerator.php`) - General document generation orchestrator
5. **LibreOfficeConverter.php** (`src/LibreOfficeConverter.php`) - Converts Word documents to PDF using LibreOffice
6. **WordTemplateProcessor.php** (`src/WordTemplateProcessor.php`) - Processes Word templates with placeholder replacement
7. **PdfMerger.php** (`src/PdfMerger.php`) - Merges multiple PDFs into a single document
8. **AsyncTaskManager.php** (`src/AsyncTaskManager.php`) - Manages async task queue in RPA database

### Service Classes

- **OCRDataProcessor.php** - Processes OCR data from ID cards and business licenses using Baidu OCR
- **BaiduOCR.php** - Baidu Cloud OCR integration for intelligent document extraction
- **AIDataExtractor.php** - AI-powered data extraction from OCR results
- **HKCompanyOCR.php** - OCR processing for Hong Kong company documents (CR/BR)
- **PortraitExtractor.php** - Extracts portraits from ID cards using Tencent Cloud OCR
- **IdCardTranslator.php** - ID card data translation (Chinese to Spanish/English)
- **SignatureToWordConverter.php** - Converts signature images to Word-compatible format
- **TranslatorWithFallback.php** - Translation with fallback (Volcano → DeepL)
- **TranslationCache.php** - Caches translation results to improve performance
- **QrCodeGenerator.php** / **QrCodeManager.php** / **QrCodeExtractor.php** - QR code generation, management, and extraction
- **CosUploader.php** - Tencent Cloud Object Storage upload functionality
- **BusinessLicenseTypeDetector.php** - Detects business license type (individual/enterprise)
- **NameFormatter.php** / **CityNameFormatter.php** - Name and city formatting utilities
- **DistrictExtractor.php** - Extracts district information from addresses
- **CountryCache.php** - Country data caching for translation lookups

### PDF Processing Classes

- **ImageToPdfConverter.php** - JPG/PNG to PDF conversion (Python Pillow preferred, FPDF fallback)
- **PDFToImageConverter.php** - PDF to image conversion using Ghostscript
- **PdfMerger.php** - Merges multiple PDFs into a single document
- **PdfNormalizer.php** - Normalizes PDF pages to A4 size
- **ParallelPdfConverter.php** - Parallel LibreOffice conversion for batch processing

### Utility Classes

- **TempFileCleanupManager.php** / **TempDirectoryCleanup.php** - Temporary file/directory cleanup
- **SimpleRarZipExtractor.php** - RAR/ZIP archive extraction
- **DataTransformer.php** - Data format transformation utilities
- **DatabaseHelper.php** / **Database.php** - SQL Server database operations
- **Logger.php** - UTF-8 encoded logging with console output levels
- **WeChatWorkNotifier.php** - Enterprise WeChat webhook notifications
- **EnvLoader.php** - Environment variable loader (.env file support)

### Database Structure

**Two databases:**
1. **VAT Database** - Main business data (config: `database.development/production`)
2. **RPA Database** - Async task queue (config: `rpa_database.development/production`)

**Main tables:**
- `VATBusinessRecord` / `VATRegInfo` - VAT registration records
- `AsyncVATTasks` - Async task queue in RPA database
- `BusinessLicenseInfo`, `IdCardInfo`, etc. - Supporting document tables

## Common Commands

### Project Setup
```bash
# Install PHP dependencies
composer install

# Initialize directory structure and set up directories
php scripts/init_project.php

# Setup database (adjust password as needed)
sqlcmd -S localhost -U sa -P your_password -i database/database_schema.sql

# Install Python dependencies for advanced document processing
cd python && pip install -r requirements.txt
cd ..

# Install QR code dependencies (Windows)
scripts/install_qrcode_deps.bat
```

### Testing the System
```bash
# Full system component test (validates all dependencies)
php scripts/test_system.php

# Complete end-to-end workflow test
php scripts/test_complete.php

# Test specific components
php scripts/test_database.php          # Database connectivity
php scripts/test_ocr.php               # OCR functionality
php scripts/test_qr_code.php           # QR code generation
php scripts/test_utf8_logging.php      # UTF-8 logging support
php scripts/test_translate.php         # Translation functionality

# Feature-specific tests (100+ test scripts available)
php scripts/test_hague_complete.php    # Complete Hague document generation
php scripts/test_signature_converter.php # Signature processing
php scripts/test_vat_generate.php      # VAT document generation
```

### Generate PDF Documents
```bash
# ES 海牙文档生成 API（异步受理，接口文档见 docs/ES_HAGUE_API.md）
# POST to: http://localhost/public/es_hague_api.php with JSON payload

# 或按业务记录 id 触发 VAT 文档异步生成
# POST to: http://localhost/public/generate_api.php with JSON payload
```

### Development and Debugging
```bash
# Test with mock data
php scripts/test_with_mock_data.php

# Check specific document types
php scripts/test_credit_report_only.php
php scripts/test_id_card_simple.php
php scripts/test_business_license_format.php

# Test translation and OCR features
php scripts/test_translate.php
php scripts/test_ocr.php
php scripts/test_portrait_extraction.php

# Verify log encoding
php scripts/verify_utf8_log.php

# Python script testing
python python/qrcode.py --help
python/python/normalize_pdf.py input.pdf output.pdf
```

## System Dependencies

### Required Software
- **PHP 7.4+** with extensions: `sqlsrv`, `pdo_sqlsrv`, `zip`, `gd`, `pdo`
- **LibreOffice** for Word-to-PDF conversion
- **Ghostscript** or **PDFtk** for PDF merging
- **SQL Server** database

### External Services
- **Tencent Cloud OCR** for ID card processing and portrait extraction
- **Baidu OCR** for credit report processing and scanned PDF 查册文件 detection
- **Tencent COS** for cloud storage (optional)
- **Volcano Translate** (primary) / **DeepL** (fallback) for Chinese↔Spanish/English translation

### Composer Dependencies
Key packages:
- `endroid/qr-code` - QR code generation
- `tencentcloud/tencentcloud-sdk-php` - Tencent Cloud integration
- `qcloud/cos-sdk-v5` - COS storage
- `overtrue/pinyin` - Chinese name processing
- `setasign/fpdf` - PDF generation
- `overtrue/chinese-calendar` - Chinese calendar support

## Configuration

### Environment Configuration
The system uses environment variables through `.env` file:
- Database credentials for dev/prod environments
- External API keys (Tencent Cloud, COS)
- Path configurations

### Main Configuration File
`config/config.php` includes:
- Multi-environment database settings
- File paths (template, output, temp, upload directories)
- LibreOffice installation path
- PDF conversion quality settings
- External service configurations

### Template System
Word templates use `{{placeholder}}` format for data substitution. Key templates:
- Hague Power of Attorney (ES/EN)
- Letter Recipient Authorization (ES/EN)
- Credit Report Translation
- Business License Translation
- ID Card Translation

## API Usage

- **ES 海牙文档生成 API**: `public/es_hague_api.php` — **异步受理**（校验通过即返回 `{code:200, ProcessMode:'async', data:null, bizParam}`，文件由 queue_processor 后台生成；任务 ID 仅写服务端日志，调用方按 bizParam 定位任务记录）；字段/错误码/契约见 `docs/ES_HAGUE_API.md`，Data 字段定义同步维护于 `UNIFIED_API_DESIGN.md` §4.4
- **VAT 文档生成 API**: `public/generate_api.php` — 按业务记录 id 触发异步生成（任务 DataSource='source'）
- **异步队列处理器**: `task/queue_processor.php` — 后台处理 AsyncVATTasks 任务（'api' 与 'source' 统一排队）
- 已废弃（勿用）: `public/api.php`、`public/web_interface.php`、`scripts/example_usage.php`（DocumentGenerator 旧流程）

## Key Development Notes

- **Document Order**: The system generates documents in a specific legal order that must be maintained
- **Hong Kong Company Detection**: Check `CompanyCountry` field (香港/HK/Hong Kong) - affects document flow significantly
- **HagueType for HK Companies**: Determines if 查册文件 is generated (1/2 = yes, 3 = no)
- **查册文件 Detection** (`VATDataService::isCompanyParticularsPDF`): Two-phase detection — first tries PyMuPDF text extraction via `company_particulars_detector.py`; if PDF is scanned (no extractable text), falls back to Baidu OCR to extract text and match keywords (Company Particulars, 公司资料, etc.)
- **File Paths**: All paths use absolute paths for reliability across environments
- **Cleanup**: Temporary files are automatically cleaned up after processing
- **Security**: Database updates use prepared statements to prevent SQL injection
- **Logging**: Comprehensive logging system with different levels (info, warning, error) and UTF-8 encoding support for Chinese characters
- **Translation**: Supports Chinese, Spanish, and English with caching (Volcano API with DeepL fallback)
  - **查册文件 shareholder address & share_class**: English values kept as-is; Chinese values translated to Spanish via `translateShareholderFields()`
  - **查册文件 registered_office address**: Chinese addresses translated to English via `translateParticularsAddress()`
- **Async Processing**: Long-running tasks use RPA database task queue with `AsyncTaskManager`
- **API 字段文档同步（强制）**: ES 海牙等 API 业务字段有更新时，必须同步更新 `UNIFIED_API_DESIGN.md` 的 Data 字段说明表格（**§4.4 通用总表，字段只增不减**）与 `docs/ES_HAGUE_API.md` §3.1；**字段名不允许更改，只允许修改说明信息**；请求示例 json（`西班牙EPR海牙.json`，es_haiya 项目根目录）数据也需同步更新；**`E:\ou\meiou-app\app_withdrawn\docs\UNIFIED_API_DESIGN.md` 为原始文档**（§4.4.1=德国VAT示例、§4.4.2=西班牙海牙示例），两份 UNIFIED_API_DESIGN.md 必须保持内容一致。**关联操作流程（每次必做）**：
  1. **操作 `app_withdrawn` 前先 `git pull`**（`E:\ou\meiou-app\app_withdrawn` 是独立 git 仓库，master 分支；确保文档拉到最新再改，避免覆盖他人提交）
  2. 修改 es_haiya 侧 `UNIFIED_API_DESIGN.md` + `docs/ES_HAGUE_API.md` §3.1 + 请求示例 json（若涉及）
  3. 将 `UNIFIED_API_DESIGN.md` 同步覆盖到 `app_withdrawn\docs\UNIFIED_API_DESIGN.md`，`diff` 两份文件必须为空
  4. **`app_withdrawn` 仓库不做提交/推送处理**——只负责拉取使用（`git pull`）；同步后的文档改动留在该仓库工作区，由用户自行处理

## Async Processing Flow

1. **Synchronous Phase** (`generate()` method, generate_api 流程):
   - Validate input data
   - Check for existing async tasks
   - For non-HK companies: validate credit report file
   - Create async task record in RPA database
   - Return task ID to client

2. **Asynchronous Phase** (`generateFromCreditReport()` method):
   - Process documents based on company type (HK vs non-HK)
   - Generate Word documents using templates
   - Convert to PDF using LibreOffice
   - Merge all PDFs
   - Upload to COS (optional)
   - Update task status in database

3. **ES 海牙 API 异步受理**（`es_hague_api.php`，详见 `docs/ES_HAGUE_API.md`）:
   - 受理阶段：校验全部参数（字段错误**聚合返回**）→ **重复请求双向判重**（`BusinessSerialNumber` 查 API 来源 0/1 任务 + `BusinessId` 查任意来源 0/1 任务，命中返回 400；已完成/失败任务允许重新提交）→ 下载信用报告（非香港公司）→ 创建任务（DataSource='api'，TaskStatus=0，请求参数入 TaskData）→ 立即返回 `{code:200, ProcessMode:'async', data:null, bizParam}`
   - 生成阶段：queue_processor → `VATAsyncProcessor::processApiTask` 从 TaskData.request_data 重建 $dbData → 生成合并 PDF → 写 ResultData{file1, cos_key, cos_url}（TaskStatus=2）
   - 失败回调：重试至上限后 failApiTask（TaskStatus=3）；若配置 `ES_HAGUE_RESULT_CALLBACK_URL`（.env，可选），`AsyncResultNotifier` 向调用方 POST 失败回调（超时 `ES_HAGUE_CALLBACK_TIMEOUT`，默认 10），未配置不回调

## Important Method Signatures

```php
// VATDocumentGenerator.php - Line 1554
private function generateWordDocuments($templateData, $dbData, $isHongKongCompany = false, $hagueType = 0)

// VATDocumentGenerator.php - Line 310 area
// Document flow branching based on company type and HagueType
if ($isHongKongCompany) {
    // Always 海牙 flow, pass hagueType for 查册文件 decision
    $wordFiles = $this->generateWordDocuments($templateData, $dbData, true, $hagueType);
} else {
    // Non-HK: Check SpecsName for 海牙/免海牙
    if ($isApostilleNotRequired) {
        $wordFiles = $this->generateApostilleNotRequiredDocuments($templateData, $dbData, false);
    } else {
        $wordFiles = $this->generateWordDocuments($templateData, $dbData, false, 0);
    }
}
```

## Testing Strategy

The project includes 100+ test scripts in `scripts/test_*.php`:

### Core Tests
- `test_system.php` - Validates all system dependencies
- `test_complete.php` - Full end-to-end workflow
- `test_database.php` - Database connectivity and operations

### Feature-Specific Tests
- `test_ocr*.php` - OCR functionality tests
- `test_qr*.php` - QR code generation, extraction and management
- `test_translate.php` - Translation functionality
- `test_id_card*.php` - ID card processing variants
- `test_signature*.php` - Signature processing and insertion
- `test_utf8*.php` - UTF-8 encoding and logging tests
- `test_vat*.php` - VAT document generation tests
- `test_hague*.php` - Hague document generation
- `test_credit_report*.php` - Credit report processing
- `test_business_license*.php` - License document handling

## Troubleshooting

### Common Issues
1. **LibreOffice not found**: Check installation path in config
2. **Database connection failed**: Verify credentials in `.env`
3. **PDF merge errors**: Ensure Ghostscript is installed
4. **OCR failures**: Check Tencent Cloud API credentials
5. **Permission denied**: Verify write permissions for output/temp directories
6. **Python scripts not working**: Ensure Python 3.x is installed with required dependencies (opencv-python, PyPDF2, etc.)

### Debug Commands
```bash
# Check system requirements
php scripts/test_system.php

# View application logs with proper UTF-8 encoding
powershell "Get-Content 'logs\*.log' -Encoding UTF8 | Select-String 'ERROR'"

# Test database connection
php scripts/test_database.php

# Verify LibreOffice installation
libreoffice --version

# Test Python integration
python python/qrcode.py --help
```

## Logging and Monitoring

### Log File Management
The system generates detailed UTF-8 encoded logs in the `logs/` directory with automatic Chinese character support:

```bash
# View latest logs with proper UTF-8 encoding (Windows PowerShell)
powershell "Get-Content 'logs\*.log' -Encoding UTF8 | Select-String 'ERROR'"

# Search logs by Application ID
php -r "require_once 'src/Logger.php'; echo Haiya\Logger::searchByApplicationId('logs', 12345, 7);"

# Search logs by Request ID
php -r "require_once 'src/Logger.php'; echo Haiya\Logger::searchByRequestId('logs', '20251212123456_abc12345', 7);"

# Real-time log monitoring (PowerShell)
powershell "Get-Content 'logs\pdf_generator_$(date -Format yyyy-MM-dd).log' -Encoding UTF8 -Wait"
```

### Log Testing and Verification
```bash
# Test UTF-8 logging functionality
php scripts/test_utf8_logging.php

# Verify log file encoding
php scripts/verify_utf8_log.php
```

### Log Viewing Best Practices
- Use UTF-8 capable text editors (VS Code, Notepad++, modern editors)
- Set console encoding to UTF-8 on Windows before viewing
- New log files include UTF-8 BOM for proper encoding detection
- See `docs/日志编码说明.md` for detailed encoding guidance

## Documentation Structure

Project documentation is organized across several locations:

**`docs/` directory:**
- **AUTO_CLEANUP_IMPROVEMENTS.md** - Automatic temp file cleanup mechanism
- **PDF身份证支持说明.md** - PDF format ID card support guide
- **QUEUE_PROCESSOR_MONITORING.md** - Queue processor monitoring and heartbeat
- **WECHAT_NOTIFICATION.md** - Enterprise WeChat notification setup
- **PDF_FLOW_DIAGRAM.txt** - PDF processing flow diagram

**Other documentation:**
- `README.md` - Project overview and quick start (root)
- `python/README.md` - Python utility scripts reference
- `task/README.md` - Async task queue reference
- `.kiro/specs/hong-kong-company-document-generation/` - HK company document generation specs

### Python Scripts
The `python/` directory contains utility scripts for advanced document processing:
- **qrcode.py** - QR code detection and extraction from PDFs
- **normalize_pdf.py** - PDF normalization and processing
- **remove_blank_pages.py** - Automatic blank page removal
- **credit_report_detector.py** - Credit report identification and processing
- **company_particulars_detector.py** - HK company particulars document detection (PyMuPDF-based)

Python dependencies are managed in `python/requirements.txt` and include opencv-python, PyPDF2, and other image processing libraries.

### Environment Configuration Files
- `.env.example` - Template environment configuration (copy to `.env`)
- Environment variables support for database credentials, API keys, and file paths
- Multi-environment support (development/production) through config switching