ali
/
taxes_az
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
taxes_az/CLAUDE.md

259 lines
9.5 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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 Azərbaycan tax declarations and compliance. It integrates with Azərbaycan'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 syncs Item Groups after migration via:
```python
after_migrate = "taxes_az.master_data.sync.sync_item_groups"
```
Item Groups ship as `master_data/item_group.json` and are applied with a
tree-aware hash-diff sync (insert/update only). See `master_data/sync.py`.
## Architecture
### Core Integration Modules
#### 1. E-Taxes Authentication (`taxes_az/auth.py`)
- Handles authentication with Azərbaycan 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 Azərbaycan 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 synced from `master_data/item_group.json` 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`)
- Azərbaycan 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 (Azərbaycan'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
│ ├── master_data/ # JSON master data + hash-diff sync
│ ├── 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
- **Azərbaycan** - DocType names, field labels, Item Group names
- **English** - Code, function names, technical terms
When adding new features, follow existing language conventions for each context.
Reference in New Issue View Git Blame Copy Permalink