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

3.3 KiB
Raw Blame History

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

# 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

# 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

# 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