57 lines
3.2 KiB
Markdown
57 lines
3.2 KiB
Markdown
|
# Agent Instructions: PSP Project
|
||
|
|
|
||
|
|
This document provides essential context and guidelines for AI agents working on the PSP (Payment Service Provider) project.
|
||
|
|
|
||
|
|
## Project Purpose
|
||
|
|
A multi-module Android application for specialized POS (Point of Sale) hardware, providing a bridge between a Web-based POS interface and native hardware features (Thermal Printing & Payment Terminal).
|
||
|
|
|
||
|
|
## Architecture Overview
|
||
|
|
The project follows **Dependency Inversion** principles. Features are defined as interfaces in `:core` and implemented in hardware-specific modules like `:p3` or `:ps4`.
|
||
|
|
|
||
|
|
### Key Modules
|
||
|
|
- **`:core`**: Shared domain models (`PrintEntity`, `PaymentResultEntity`) and interfaces (`PspService`, `Printer`).
|
||
|
|
- **`:design_system`**: Contains `PspWebView` and the `PspJavaScriptInterface` (Web-Native Bridge).
|
||
|
|
- **`:p3` / `:ps4`**: Hardware SDK integrations.
|
||
|
|
- **`:app` / `:tis_app` / `:stage_app`**: Application entry points and Hilt dependency configuration.
|
||
|
|
|
||
|
|
## Critical Classes & Interfaces
|
||
|
|
|
||
|
|
### 1. Web-Native Bridge
|
||
|
|
- **`PspWebView.kt`**: The core component. Uses a `WebViewManager` for pooling and is highly optimized for weak hardware.
|
||
|
|
- **`PspJavaScriptInterface.kt`**: Defines the methods exposed to JavaScript (`pay`, `print`, `reload`, `uuid`).
|
||
|
|
- **Important**: Methods must be annotated with `@JavascriptInterface` and `@Keep`.
|
||
|
|
- **Note**: Numbers from JS arrive as `Double`.
|
||
|
|
|
||
|
|
### 2. Printer Implementation (`:p3`)
|
||
|
|
- **`P3Printer.kt`**: Implements the `Printer` interface.
|
||
|
|
- **`POIPrinterManager`**: The vendor SDK class.
|
||
|
|
- **Font Handling**: Use `getFontPath(resourceName: String)` to copy fonts from `res/font` to internal storage before passing the path to the SDK.
|
||
|
|
- **Logo Rendering**: Use `drawableToBitmap()` to handle VectorDrawables correctly.
|
||
|
|
|
||
|
|
### 3. Payment Service (`:p3`)
|
||
|
|
- **`Ps3Service.kt`**: Implementation of `PspService`.
|
||
|
|
- **`IapPosService.kt`**: Handles communication with the underlying POS payment application.
|
||
|
|
|
||
|
|
## Common Agent Tasks
|
||
|
|
|
||
|
|
### Adding a new Bridge Method
|
||
|
|
1. Add the method to `PspJavaScriptInterface.kt` with `@JavascriptInterface` and `@Keep`.
|
||
|
|
2. Update the constructor of `PspJavaScriptInterface` to take a lambda.
|
||
|
|
3. Update `PspWebView.kt` to pass the lambda from the UI layer.
|
||
|
|
|
||
|
|
### Optimizing for Weak Hardware
|
||
|
|
When performance issues arise in the WebView:
|
||
|
|
1. Check `WebViewManager.kt` settings.
|
||
|
|
2. Ensure `setLayerType(View.LAYER_TYPE_HARDWARE, null)` is set.
|
||
|
|
3. Keep `setOffscreenPreRaster(false)` for very weak hardware to save RAM.
|
||
|
|
4. Ensure `loadUrl` is NOT called in the `AndroidView.update` block (use `LaunchedEffect` instead).
|
||
|
|
|
||
|
|
## Development Rules
|
||
|
|
- **RTL Support**: The printer uses Persian/Arabic text. Always ensure numbers are converted to Persian digits using `toPersianDigits()` where appropriate.
|
||
|
|
- **Dependency Injection**: Use Hilt for all service injections. Do not instantiate implementation classes (`P3Printer`, `Ps3Service`) directly in the app modules.
|
||
|
|
- **WebView Lifecycle**: Always release WebViews back to the `WebViewManager` in `onDispose`.
|
||
|
|
|
||
|
|
## Mocking in `:stage_app`
|
||
|
|
- Use `StageViewModel` to return success/failure mocks for payment results without requiring physical hardware.
|
||
|
|
- Use the `PaymentResultEntity.success()` or `PaymentResultEntity.failure()` factory methods.
|