# CLAUDE.md

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

## Project Overview

Android banking POS terminal application built on Newland SDK (NSDK), implementing financial transactions (Sale, Refund, Void, Pre-Auth, QR payments, Settlement, etc.) for Morefun hardware devices.

- **ApplicationId:** `com.newland.template`
- **Min SDK:** 24, **Target SDK:** 31, **Compile SDK:** 34
- **Signing:** Both debug and release use `morefun.jks` (already configured in build.gradle)

## Build Commands

```bash
./gradlew assembleDebug          # Build debug APK
./gradlew assembleRelease        # Build release APK
./gradlew build                  # Build all modules
./gradlew clean                  # Clean build outputs
./gradlew test                   # Run unit tests
./gradlew lintDebug              # Run lint
./gradlew connectedAndroidTest   # Run instrumented tests on device
```

APKs are named: `{project}-{versionCode}-{versionName}-{buildType}-{timestamp}.apk`

Requires JDK 17. The path is set in `gradle.properties` — update `org.gradle.java.home` if your JDK location differs.

## Module Architecture

```
app/          - Entry point, UI fragments, MQTT integration
core/         - Transaction engine, all payment flows
base/         - Shared utilities, base classes, custom UI widgets, crypto helpers
database/     - Room ORM (transactions, merchants, reversal data)
sdk_helper/   - Newland NSDK wrapper and hardware abstraction
settings/     - Settings UI and configuration
message-tester/ - TCP/ISO8583 message testing utility
```

Dependency flow: `app → core → sdk_helper → base`, `app → database → base`

## Transaction Step-Chain Pattern

All payment flows (Sale, Refund, PreAuth, etc.) inherit from `AbstractTrans` and build a sequential step chain:

```java
chain.next(new PreCheckStep(true, false))
     .next(new InputAmountStep())
     .next(new ReadCardStep(...))
     .next(new InputPinStep())
     .next(new PackSaleStep())
     .next(new AddRecordStep())
     .next(new PrintReceiptStep())
     .proceed(callback);
```

`TransFactory` maps transaction type enums to their implementing classes. `TransActivity` executes them. To add a new transaction: create a class extending `AbstractTrans`, build its step chain, and register it in `TransFactory`.

## App Initialization Flow

```
App.onCreate()
  └─ SelfCheckHelper.initAppConfig()  [background thread]

MainActivity.onCreate()
  └─ SelfCheckHelper.initDevice()     [background thread]
    └─ MainFragment → ViewPager with menu pages
      └─ MenuFragment items → TransActivity → specific transaction
```

## Hardware Access (NSDK)

All hardware access goes through `ServiceHelper.getInstance()` (in `sdk_helper` module), which wraps the Newland NSDK AAR:

- Card readers: `BCardReader` (mag), `ContactReader` (chip), contactless readers
- PIN pad: `BPinpad` — handles PIN entry and encryption
- Printer: `BPrinter`
- Scanner: `BScanner`, `BHardScanner`
- Display/LED: `BLed`, `BSystem`

External PIN pad devices use `ExtServiceHelper`. The `ysdk_6.09.*.jar` provides Morefun device-specific extensions beyond standard NSDK.

## Key Utilities (base module)

- **Crypto:** AES, DES, DUKPT, RSA, SHA, MD5, PBKDF2, MAC, KCV helpers
- **ISO 8583:** Message packing/parsing for financial host communication
- **EMV:** TLV parsing utilities
- **Card:** Track2 parsing
- **Threading:** `CommonPoolExecutor`, `CommonScheduledPoolExecutor` — use these, not raw threads
- **UI:** `BaseActivity`, `BaseFragment`, `BaseDialog` — all screens extend these
- **Custom keyboards:** `NumberKeyboard`, `HexKeyboard`, `SimpleKeyboard`
- **Custom dialogs:** MessageDialog, CheckDialog, MenuDialog, AmountDialog, etc.

## Settings

Two password-protected settings levels:
- **Vendor settings:** password `201003`
- **Admin/Merchant settings:** password `000000`

## Database

Room ORM in `database` module. Access via service classes (not DAOs directly):
- `RecordService` — transaction history
- `MerchantService` — merchant configuration
- Reversal data service — pending reversals

## GitHub Access

The GitHub personal access token is available in the `GITHUB_TOKEN` environment variable. Use it with the GitHub API via `curl` when `gh` CLI is unavailable:

```bash
curl -s -H "Authorization: token $GITHUB_TOKEN" "https://api.github.com/repos/kasi1988/morefun_demo/pulls/70"
curl -s -H "Authorization: token $GITHUB_TOKEN" -H "Accept: application/vnd.github.v3.diff" "https://api.github.com/repos/kasi1988/morefun_demo/pulls/70"
```

## Communication

- **Host:** ISO 8583 over TCP socket (`SocketHelper`, SSL support included)
- **MQTT:** `MqttIntegration.java` for remote commands (Eclipse Paho client)
- **WebSocket:** Autobahn and Java-WebSocket libraries available
- **TOMS API:** `TOMSClientApi_V1.0.11.aar` for cloud platform receipt/parameter sync

## Implemented Transaction Types

Sale, Void Sale, Refund, Pre-Auth, Auth Complete, Installment, Void Auth Complete, Void Pre-Auth, Void Installment, QR Code, Alipay, WeChat, UPI QR, QR Refund, Settle, Settlement Reprint, Reprint Last Receipt, Reprint Receipt, Balance Query, Login, Master Key Injection, Print Detail.