82 lines
3.4 KiB
Markdown
82 lines
3.4 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
Kapital Bank is a Frappe app integrating BIRBank B2B API with ERPNext. It imports bank accounts, cards, and transactions as Payment Entries, with fuzzy matching of counterparties and purpose-based GL account mapping.
|
|
|
|
## Development Commands
|
|
|
|
```bash
|
|
# Start development server (from bench directory)
|
|
bench start
|
|
|
|
# Install/reinstall the app
|
|
bench install-app kapital_bank
|
|
|
|
# Run migrations after doctype changes
|
|
bench migrate
|
|
|
|
# Run tests
|
|
bench --site <site-name> run-tests --app kapital_bank
|
|
|
|
# Linting and formatting (from app directory)
|
|
pre-commit run --all-files
|
|
pre-commit run ruff --all-files # Python only
|
|
pre-commit run eslint --all-files # JavaScript only
|
|
```
|
|
|
|
## Code Style
|
|
|
|
- **Python**: Ruff linter/formatter — tabs, double quotes, line-length 110, target Python 3.10
|
|
- **JavaScript**: ESLint + Prettier — tabs, indent size 4
|
|
- **Indentation**: Tabs everywhere (spaces only in JSON, indent size 1)
|
|
|
|
## Architecture
|
|
|
|
### Core Modules
|
|
|
|
| File | Purpose |
|
|
|---|---|
|
|
| `kapital_bank/auth.py` | JWT auth: login, token refresh, scheduled renewal (cron every 4 min) |
|
|
| `kapital_bank/api.py` | `BIRBankClient` — HTTP wrapper with auto token refresh on 401 |
|
|
| `kapital_bank/bank_api.py` | Main business logic: registry loading, fuzzy matching, transaction import (~1400 lines) |
|
|
| `kapital_bank/hooks.py` | Frappe hooks: doctype_js, scheduler_events, doc_events |
|
|
| `kapital_bank/client/payment_entry.js` | Frontend: Payment Entry form/list customization |
|
|
|
|
### Data Flow
|
|
|
|
1. **Auth**: Credentials in `Kapital Bank Login` → JWT tokens stored as encrypted Password fields
|
|
2. **Registry**: API data fetched into local doctypes (Account, Card, Customer, Supplier)
|
|
3. **Mapping**: Settings tables link bank entities to ERPNext records (Bank Account, Customer, Supplier, GL Account)
|
|
4. **Import**: Statement transactions → fuzzy match party/purpose → create Payment Entry + tracking record
|
|
5. **Cleanup**: Doc events on Payment Entry (on_trash, on_cancel) auto-delete associated transaction records
|
|
|
|
### Matching Algorithm
|
|
|
|
Three-tier party matching with configurable similarity thresholds:
|
|
1. Exact VÖEN (tax ID) match
|
|
2. Name similarity via `SequenceMatcher` (defaults: customer 90%, supplier 80%, purpose 70%)
|
|
3. Optional Azerbaijani character normalization (Ə→E, ə→e, etc.)
|
|
|
|
### DocTypes
|
|
|
|
- **Single doctypes**: `Kapital Bank Login` (credentials), `Kapital Bank Settings` (central config hub with mapping child tables)
|
|
- **Registry doctypes**: Account, Card, Customer, Supplier — local copies of bank data
|
|
- **Child tables**: Account Mapping, Card Mapping, Customer Mapping, Supplier Mapping, Transaction Mapping
|
|
- **Tracking**: `Kapital Bank Transaction` — tracks imported Payment Entries by reference_no for deduplication
|
|
- **Utility**: `Kapital Bank API Test` — manual API testing
|
|
|
|
### Key Patterns
|
|
|
|
- All `@frappe.whitelist()` functions use `ignore_permissions=True` for system-level operations
|
|
- Bulk imports run as background jobs via `frappe.enqueue()` with 10-min timeout
|
|
- Progress published via `frappe.publish_realtime()` over Socket.IO
|
|
- Sensitive data (tokens, passwords) stored in Password-type fields (encrypted in DB)
|
|
- Error logging via `frappe.log_error()` with masked account numbers in debug output
|
|
|
|
## API Documentation
|
|
|
|
BIRBank B2B API documentation PDFs are in `birbank_docs/`. The base URL is `https://my.birbank.business/api/b2b`.
|