98 lines
3.3 KiB
Markdown
98 lines
3.3 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Overview
|
|
|
|
Invoice Az is a Frappe application that integrates with Azerbaijan's e-taxes.gov.az system for uploading and downloading invoices. The app manages authentication via ASAN Login, handles token renewal, and provides mappings between Frappe ERPNext entities and e-taxes system entities.
|
|
|
|
## Development Commands
|
|
|
|
### Linting and Code Quality
|
|
```bash
|
|
# Run ruff for Python linting
|
|
ruff check invoice_az/
|
|
|
|
# Run ruff format
|
|
ruff format invoice_az/
|
|
|
|
# Run pre-commit hooks (includes ruff, eslint, prettier, pyupgrade)
|
|
pre-commit run --all-files
|
|
```
|
|
|
|
### Testing
|
|
```bash
|
|
# Run unit tests for a specific doctype
|
|
bench run-tests --app invoice_az --doctype "E-Taxes Item"
|
|
|
|
# Run all tests for the app
|
|
bench run-tests --app invoice_az
|
|
```
|
|
|
|
### Development
|
|
```bash
|
|
# Clear cache after making changes
|
|
bench clear-cache
|
|
|
|
# Restart workers after API changes
|
|
bench restart
|
|
|
|
# Watch logs
|
|
bench --site [site-name] console
|
|
```
|
|
|
|
## Architecture
|
|
|
|
### Core Components
|
|
|
|
1. **Authentication System** (`invoice_az/api.py`)
|
|
- ASAN Login integration for Azerbaijan government authentication
|
|
- Token management with automatic renewal every 4 minutes via cron job
|
|
- Activity tracking to prevent unnecessary token renewals
|
|
- Retry logic with exponential backoff for failed requests
|
|
|
|
2. **Document Integration**
|
|
- Extends Purchase Order and Purchase Invoice doctypes via hooks
|
|
- Client-side JavaScript files in `invoice_az/client/` directory
|
|
- Custom buttons for e-taxes operations
|
|
|
|
3. **Data Mapping System**
|
|
- E-Taxes Item/Party/Unit doctypes for storing e-taxes entities
|
|
- Mapping doctypes to link Frappe entities with e-taxes entities
|
|
- Automatic synchronization and search functionality
|
|
|
|
4. **API Integration** (`invoice_az/api.py`)
|
|
- RESTful API endpoints decorated with `@frappe.whitelist()`
|
|
- Request handling with retry logic
|
|
- Error logging and detailed error messages
|
|
|
|
### Key Features
|
|
|
|
- **Token Renewal**: Automatic token renewal via scheduler (every 4 minutes)
|
|
- **Activity Tracking**: Records user activity to optimize token renewals
|
|
- **Entity Mapping**: Maps ERPNext items, parties, and units to e-taxes equivalents
|
|
- **Bulk Operations**: Support for syncing multiple entities at once
|
|
- **Error Handling**: Comprehensive error logging and user-friendly error messages
|
|
|
|
### Database Schema
|
|
|
|
Custom Doctypes:
|
|
- **Asan Login**: Stores authentication credentials and tokens
|
|
- **E-Taxes Settings**: Global settings and status mappings
|
|
- **E-Taxes Item/Party/Unit**: Cached e-taxes entities
|
|
- **E-Taxes Item/Party/Unit Mapping**: Links between ERPNext and e-taxes entities
|
|
- **E-Taxes Purchase**: Purchase documents from e-taxes system
|
|
|
|
### Important Files
|
|
|
|
- `invoice_az/hooks.py`: App configuration, event hooks, and scheduler setup
|
|
- `invoice_az/api.py`: Main API logic for e-taxes integration
|
|
- `invoice_az/client/*.js`: Client-side functionality for UI enhancements
|
|
- `invoice_az/invoice_az/doctype/*/`: Custom doctype definitions
|
|
|
|
### Security Considerations
|
|
|
|
- All API endpoints are whitelisted with `@frappe.whitelist()`
|
|
- Token storage uses Frappe's password field type
|
|
- Activity tracking prevents unnecessary API calls
|
|
- Retry logic includes exponential backoff to prevent API flooding |