taxes_az/CLAUDE.md

# CLAUDE.md

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

## Project Overview

**taxes_az** is a Frappe/ERPNext application for managing Azerbaijan tax declarations and compliance. It integrates with Azerbaijan's E-Taxes system (new.e-taxes.gov.az) to automate tax filing, company profile management, and tax calculations.

## Development Environment

This is a Frappe app that must be developed within a Frappe bench environment.

### Common Commands

```bash
# Development server (run from bench directory)
cd /home/frappe/frappe-bench
bench start

# Database migrations
bench --site [site-name] migrate

# Install/reinstall app
bench --site [site-name] install-app taxes_az
bench --site [site-name] reinstall-app taxes_az

# Console access
bench --site [site-name] console

# Clear cache
bench --site [site-name] clear-cache

# Build assets (after JS/CSS changes)
bench build --app taxes_az

# Run tests
bench --site [site-name] run-tests --app taxes_az
```

### Post-migration Hook

The app automatically creates Item Groups after migration via:
```python
after_migrate = "taxes_az.create_item_group.create_item_groups"
```

## Architecture

### Core Integration Modules

#### 1. E-Taxes Authentication (`taxes_az/auth.py`)
- Handles authentication with Azerbaijan E-Taxes API
- Token management and renewal (endpoint: `https://new.e-taxes.gov.az/api/po/auth/public/v1/renew`)
- Activity tracking with 10-minute timeout
- Key functions:
  - `record_etaxes_activity()` - Tracks user activity for session management
  - Authentication state stored in "Asan Login" doctype

#### 2. Company E-Taxes Integration (`taxes_az/company_etaxes.py`)
- Fetches company profile data from E-Taxes
- Handles special gambling activity logic (codes: 92000, 9200003, 9200004, 9200001, 9200002, 9200005)
- Key functions:
  - `force_update_gambling_fields()` - Special handling for gambling companies
- Client-side counterpart: `taxes_az/client/company.js`

### DocTypes Structure

The app contains **199 doctypes** organized into main categories:

#### Tax Declarations (Main Documents)
- **Declaration of Value Added Tax** - VAT declarations with 10+ child tables for different sections (elave1-10, bolme, hesabat, etc.)
- **Declaration of Simplified Tax** - Simplified tax with calculation child tables
- **Declaration of Mining Tax** - Mining resource tax with wholesale pricing tables
- **Excise Declaration** - Excise tax with extensive child tables for different product categories
- **Income Tax Return** - Corporate income tax with 5+ child tables
- **Property Tax Return** - Property/land tax declarations
- **Export Declaration** - Export-related tax declarations
- **Withholding Tax declarations** - Various withholding tax types

#### Supporting Doctypes
- **Certificate on Non-Emergence of Tax Liability** - Tax clearance certificates (4 variations: tediyye, tediyye2, tediyye3, tediyye_4)
- **Company metadata** - Additional activity, affiliate organizations, business objects, non-resident services
- **Business Classification** - NACE-style activity codes
- **Main Type of Activity** - Primary business activity classifier
- **Agricultural Purpose Type** - Agricultural land use types
- **EQM Codes** - E-Taxes specific codes
- **Tax Article** - Tax article/clause definitions

#### Utility Doctypes
- **XML Mapping Tool** - Maps Frappe doctypes to E-Taxes XML formats
- **VAT Allocation** - VAT distribution logic
- **Tax Article Items Report** - Links items to tax articles

### XML Mapping System

The app includes a sophisticated XML mapping system (`taxes_az/public/js/xml_mapping/`) to convert Frappe documents to E-Taxes XML format:

- **xml_parser.js** - Parses E-Taxes XML templates
- **field_generator.js** - Generates mapping field UI
- **doctype_field_selector.js** - Selects Frappe fields for mapping
- **mapping_storage.js** - Stores mapping rules
- **xml_generator.js** - Generates final XML from mapped data

Usage: Create an XML Mapping Tool document, upload E-Taxes XML template, map fields to Frappe doctype fields, then generate XML for submission.

### Reports

Located in `taxes_az/taxes_az/report/`:

- **land_tax_report** - Land/property tax calculations by tax article
- **customer_outstanding_balance** - Outstanding customer balances
- **fuel_products_purchase_report** - Fuel/oil product purchases
- **mining_resources_stock_report** - Mining resources inventory
- **gaming_revenue_report** - Gaming/gambling revenue (for gambling companies)
- **sport_and_lottery_report** - Sports betting and lottery reporting
- **taxable_assets_report** / **tax_exempt_assets_report** - Asset tax status
- **tax_articles_revenue_report** - Revenue by tax article
- **sales_invoice_info_report** / **payment_entry_info_report** - Transaction reporting

### Item Groups

The app manages specialized item groups for Azerbaijan tax purposes:
- **Neft Məhsulları** (Oil Products) - Includes fuel types
- **Faydalı qazıntılar** (Mining Resources) - 20+ types of minerals with units
- **İdman, mərc və lotoreya oyunları** (Gaming) - Sports betting and lottery

These are created via `create_item_group.py` after migration.

## Frappe Framework Conventions

### DocType Structure
Each doctype folder contains:
- `{doctype_name}.json` - Field definitions
- `{doctype_name}.py` - Server-side controller
- `{doctype_name}.js` - Client-side controller
- `test_{doctype_name}.py` - Unit tests (optional)

### Naming Conventions
- Child table doctypes often have parent name + description (e.g., `declaration_of_value_added_tax_elave_1`)
- Azerbaijani terms used extensively in doctype names

### Hooks Registration

Hooks are defined in `taxes_az/hooks.py`:

```python
# Custom JS for doctypes
doctype_js = {
    "XML Mapping Tool": [
        "public/js/xml_mapping/xml_parser.js",
        "public/js/xml_mapping/field_generator.js",
        "public/js/xml_mapping/doctype_field_selector.js",
        "public/js/xml_mapping/mapping_storage.js",
        "public/js/xml_mapping/xml_generator.js"
    ],
    "Company": "client/company.js",
    "Item Group": "public/js/item_group.js"
}

# Document events
doc_events = {
    "Item Group": {
        "on_trash": "taxes_az.item_group.validate_item_group_deletion"
    }
}

# Fixtures (master data)
fixtures = [
    {"doctype": "Client Script", "filters": [["module", "=", "Taxes Az"]]},
    {"doctype": "Main type of activity"},
    {"doctype": "Business Classification"}
]
```

## Working with E-Taxes API

### Authentication Flow
1. User authenticates via ASAN Login (Azerbaijan's e-government system)
2. Tokens stored in "Asan Login" doctype with `is_default` flag
3. Activity tracked every API call to prevent timeout
4. Automatic token renewal via `RENEW_URL`

### API Integration Pattern
```python
# Always record activity before E-Taxes API calls
from taxes_az.auth import record_etaxes_activity
record_etaxes_activity()

# Make API call with proper headers
headers = {
    "Accept": "application/json, text/plain, */*",
    "Cache-Control": "no-cache",
    "Referer": "https://new.e-taxes.gov.az/eportal/az/login/asan"
}
```

## Special Business Logic

### Gambling Companies
Companies with main_activity in gambling codes must have either `seller` or `organizer` checkbox enabled. This is enforced in both Python (`company_etaxes.py`) and JavaScript (`client/company.js`).

### Tax Declaration Dependencies
Many tax declarations have complex child table structures. When modifying declarations:
1. Check all related child tables (elave, bolme, hisse, vergi_hesab, etc.)
2. Update calculation logic in parent doctype
3. Ensure XML mapping includes all child table fields if used for E-Taxes submission

## File Structure Reference

```
taxes_az/
├── taxes_az/                    # Main module
│   ├── auth.py                  # E-Taxes authentication
│   ├── company_etaxes.py        # Company integration
│   ├── create_item_group.py     # Item group creation
│   ├── item_group.py            # Item group validation
│   ├── hooks.py                 # Frappe hooks
│   ├── client/                  # Client scripts
│   │   └── company.js
│   ├── public/js/
│   │   ├── xml_mapping/         # XML mapping system
│   │   └── item_group.js
│   ├── data/                    # JSON data files
│   │   ├── industrial_land_data.json
│   │   └── cadastral_points_data.json
│   ├── fixtures/                # Master data
│   └── taxes_az/                # Nested module (doctypes/reports)
│       ├── doctype/             # 199 doctypes
│       ├── report/              # Custom reports
│       └── print_format/        # Print templates
├── convert-int-to-float.js      # Utility scripts
├── float-change.js
└── fixtures.json                # Fixture configuration
```

## Key Dependencies

- **Frappe Framework** (~=15.0.0) - Managed by bench
- **ERPNext** - Expected to be installed (uses Company, Item Group, Asset doctypes)
- Python 3.10+

## Testing

Run tests for specific doctypes:
```bash
bench --site [site-name] run-tests --doctype "Declaration of Value Added Tax"
```

## Language Note

The codebase uses a mix of:
- **Russian** - Comments and some internal documentation
- **Azerbaijani** - DocType names, field labels, Item Group names
- **English** - Code, function names, technical terms

When adding new features, follow existing language conventions for each context.