a2nr
/
cashumit
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases 1 Wiki Activity
cashumit/PROJECT_CONTEXT.md

268 lines
15 KiB
Markdown
Raw Blame History

# Project Context Log
## [2025-08-19 10:00] - Initial Setup & Context Discussion
- Initial project directory structure reviewed.
- Agreed to use this file (`PROJECT_CONTEXT.md`) as a log/journal for our collaboration.
- Decided on a format for entries: `## [YYYY-MM-DD HH:MM] - Brief Description of Key Info/Topic`.
- This file will be updated after each significant discussion or task completion to capture context, decisions, or important notes.
- Next steps: Begin working on specific tasks within the project. New entries will be added here as needed.
## [2025-08-19 10:15] - Firefly III Transaction Submission API Research
- Researched Firefly III API documentation for submitting transactions.
- Found the correct endpoint: `POST /api/v1/transactions`.
- Identified required and optional JSON fields for a transaction.
- Obtained an example `curl` command for submitting a transaction.
**Key Information:**
- **Endpoint:** `POST /api/v1/transactions`
- **Required Headers:**
- `Authorization: Bearer YOUR_ACCESS_TOKEN`
- `Content-Type: application/json`
- **Example JSON Payload:**
```json
{
"transactions": [
{
"type": "withdrawal",
"date": "2023-10-01",
"amount": "100.00",
"description": "Groceries",
"source_id": 1,
"destination_id": 2,
"category_id": 3,
"budget_id": 4
}
]
}
```
- **Example `curl` Command:**
```bash
curl -X POST "https://your-firefly-iii-instance.com/api/v1/transactions" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"transactions": [
{
"type": "withdrawal",
"date": "2023-10-01",
"amount": "100.00",
"description": "Groceries",
"source_id": 1,
"destination_id": 2,
"category_id": 3,
"budget_id": 4
}
]
}'
```
*(Note: Replace `YOUR_ACCESS_TOKEN` and the instance URL with actual values)*
## [2025-08-19 10:30] - Firefly III Accounts Retrieval API Research
- Researched Firefly III API documentation for retrieving accounts.
- Found the correct endpoint: `GET /api/v1/accounts`.
- Learned how to filter accounts by type (e.g., `asset`, `expense`, `revenue`).
- Obtained example `curl` commands for fetching accounts.
**Key Information:**
- **Endpoint:** `GET /api/v1/accounts`
- **Required Headers:**
- `Authorization: Bearer YOUR_ACCESS_TOKEN`
- `Accept: application/json`
- **Query Parameters:**
- `type`: Filter accounts by type (`asset`, `expense`, `revenue`, `liability`, `loan`, `debt`, `mortgage`).
- `page`: For pagination.
- **Example `curl` Commands:**
```bash
# Get all accounts
curl -X GET "https://your-firefly-iii-instance.com/api/v1/accounts" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Accept: application/json"
# Get only 'asset' accounts (commonly used as source accounts)
curl -X GET "https://your-firefly-iii-instance.com/api/v1/accounts?type=asset" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Accept: application/json"
# Get 'expense' accounts (commonly used as destination for withdrawals)
curl -X GET "https://your-firefly-iii-instance.com/api/v1/accounts?type=expense" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Accept: application/json"
```
- **Response Structure:**
The response includes a `data` array where each account object has an `id` and `attributes` containing details like `name` and `type`.
## [2025-08-19 10:45] - Create `curl_scripts` Directory and Scripts
- Created a new directory `curl_scripts` to store our API interaction scripts.
- Created `get_accounts.sh`:
- Script to fetch accounts from Firefly III using `GET /api/v1/accounts`.
- Includes examples for fetching all accounts, 'asset' accounts (source), and 'expense' accounts (destination).
- Uses environment variables for URL and token for security.
- Created `submit_dummy_transaction.sh`:
- Script to submit a dummy transaction to Firefly III using `POST /api/v1/transactions`.
- Uses environment variables for URL, token, source ID, and destination ID.
- Includes basic error handling and response code checking.
- Made both scripts executable with `chmod +x`.
## [2025-08-19 11:00] - Update `get_accounts.sh` Script for Filtering
- Updated `curl_scripts/get_accounts.sh` to accept an optional `ACCOUNT_TYPE` environment variable.
- This allows fetching specific types of accounts (e.g., `asset`, `expense`) to reduce output clutter.
- Example usage:
```bash
YOUR_FIREFLY_III_URL="..." YOUR_ACCESS_TOKEN="..." ACCOUNT_TYPE="asset" ./curl_scripts/get_accounts.sh
```
- Added debug output to show the final URL being used by the script.
- Re-applied executable permissions to the updated script.
## [2025-08-19 11:15] - Clarify Account Types for 'Receipt' Context
- Discussed the specific account types needed for submitting a 'receipt' (struk) transaction.
- **For a 'receipt' representing incoming funds/purchase:**
- **`source_id`**: Should be an account of type **`revenue`** (e.g., Salary, Gift). This is where the money is considered to come from.
- **`destination_id`**: Should be an account of type **`asset`** (e.g., Checking Account, Cash Wallet). This is where the money ends up.
- Updated understanding for using `get_accounts.sh`:
- Run once with `ACCOUNT_TYPE="revenue"` to find a suitable `source_id`.
- Run once with `ACCOUNT_TYPE="asset"` to find a suitable `destination_id`.
- These IDs will then be used with `submit_dummy_transaction.sh` to create the transaction record in Firefly III.
## [2025-08-19 11:30] - Fix Bug in `submit_dummy_transaction.sh`
- Identified and fixed a bug in `curl_scripts/submit_dummy_transaction.sh` that caused error `line 25: Dummy: command not found`.
- The issue was due to an incorrect use of a multiline string variable assignment (`read -r -d '' ... << EOM`).
- The script was updated to build the JSON payload directly within the `curl` command using `-d` with proper escaping. This is a more robust and portable method.
- Re-applied executable permissions to the corrected script.
## [2025-08-19 11:45] - Fix Account Type Mismatch & Add Transaction Type Flexibility
- Diagnosed the `HTTP Code: 000` and subsequent Firefly III error `[a] Could not find a valid source account...`.
- Root cause: The transaction `type` in `submit_dummy_transaction.sh` was hardcoded to `withdrawal`, which is incompatible with using a `revenue` account as `source_id`.
- **Solution Implemented:**
- Updated `curl_scripts/submit_dummy_transaction.sh` to accept an optional `TRANSACTION_TYPE` environment variable.
- Default value for `TRANSACTION_TYPE` is now set to `deposit`, which is the correct type when `source_id` is `revenue` and `destination_id` is `asset`.
- Example usage for 'receipt' context:
```bash
YOUR_FIREFLY_III_URL="..." YOUR_ACCESS_TOKEN="..." SOURCE_ACCOUNT_ID=92 DESTINATION_ACCOUNT_ID=1 TRANSACTION_TYPE="deposit" ./curl_scripts/submit_dummy_transaction.sh
```
- This change provides more flexibility for testing different transaction types and ensures compatibility with the intended account types for a 'receipt'.
- Re-applied executable permissions to the updated script.
## [2025-08-19 12:00] - Successfully Submit Dummy Transaction via `curl`
- After correcting the account types and transaction type, successfully submitted a dummy transaction using `submit_dummy_transaction.sh`.
- Confirmed that `source_id` from a `revenue` account and `destination_id` from an `asset` account, with `TRANSACTION_TYPE="deposit"`, works correctly.
## [2025-08-19 12:15] - Start Integrating with Flutter App
- Goal: Create a Flutter screen to select source and destination accounts from Firefly III and submit a transaction.
- Checked `pubspec.yaml` and confirmed `http: ^1.5.0` is already included.
- Created `lib/models/firefly_account.dart`:
- Defined a `FireflyAccount` model to represent account data from the API.
- Includes `id`, `name`, and `type` properties.
- Has a `fromJson` factory constructor for easy parsing.
- Created `lib/services/firefly_api_service.dart`:
- Defined `FireflyApiService` class to encapsulate API calls.
- Includes `fetchAccounts({String? type})` to get accounts, filtering by type if provided.
- Includes `submitDummyTransaction` to send a transaction to the API.
- Uses `Bearer` token authentication.
- Created `lib/screens/transaction_screen.dart`:
- Defined `TransactionScreen` widget.
- Fetches `revenue` and `asset` accounts on initialization.
- Displays two dropdowns for selecting source (`revenue`) and destination (`asset`) accounts.
- Includes buttons to reload accounts and submit a dummy transaction.
- Shows loading indicators and status messages.
## [2025-08-19 12:30] - Improve Security & User Experience
- Recognized that hardcoding URL/token is insecure. Implemented a better approach.
- Created `lib/screens/config_screen.dart`:
- New screen for users to input Firefly III URL and Personal Access Token.
- Uses `TextField` for input with basic validation.
- Stores credentials securely using `shared_preferences`.
- Modified `lib/services/firefly_api_service.dart`:
- Removed hardcoded URL and token.
- Updated `fetchAccounts` and `submitDummyTransaction` methods to accept `baseUrl` and `accessToken` as required parameters.
- Modified `lib/screens/transaction_screen.dart`:
- Updated to load URL and token from `shared_preferences`.
- Passes loaded credentials to `FireflyApiService` methods.
- Adds a settings icon in the app bar to navigate to `ConfigScreen`.
- Handles cases where credentials are missing or invalid.
## [2025-08-19 13:00] - Add Debug Logging for Account Loading
- Added extensive debug `print` statements to `FireflyApiService` and `TransactionScreen`.
- Purpose: To trace the flow of data loading, identify where the process might be failing, and verify if accounts are successfully fetched and parsed from the Firefly III API.
- This will help diagnose why the dropdowns for source and destination accounts might appear empty even after configuration is set.
## [2025-08-20 14:00] - Refactor main.dart and Correct Transaction Payload
- Corrected the payload in `lib/services/firefly_api_service.dart`'s `submitDummyTransaction` method. Ensured that `source_id` and `destination_id` are passed as strings to align with Firefly III API expectations.
- Refactored `lib/main.dart` to improve the initial application flow.
- Set `TransactionScreen` as the initial route (`/`).
- Added named routes for `TransactionScreen` (`/`), `ConfigScreen` (`/config`), and `ReceiptScreen` (`/receipt`) to create a clear and maintainable navigation structure.
- This change directs the user to the primary transaction interface on startup, facilitating immediate testing of the core functionality being developed.
## [2025-08-20 14:30] - Fix Compilation and Runtime Errors
- Resolved build errors caused by incorrect import paths and class names in `lib/screens/receipt_screen.dart` and `lib/screens/settings_screen.dart`.
- Corrected the import from `firefly_service.dart` to `firefly_api_service.dart`.
- Renamed all instances of `FireflyService` to the correct class name, `FireflyApiService`.
- Implemented the missing `testConnection` and `testAuthentication` methods in `lib/services/firefly_api_service.dart` to enable configuration testing.
- Updated `lib/screens/settings_screen.dart` to pass the required `baseUrl` and `accessToken` parameters to the new API service methods.
- The application is now in a runnable state, allowing for further testing of the Firefly III integration.
## [2025-08-20 15:00] - Redesign Receipt UI to Match Sample Image
- Redesigned the `ReceiptScreen` UI to match a more traditional receipt format similar to `sample-struk.jpg`.
- Updated the layout to have a receipt paper style with proper borders and styling.
- Improved the item list display with better alignment and formatting.
- Moved transaction settings to a separate section with better organization.
- Updated the PDF export service to match the new UI design.
- Fixed several syntax errors and code quality issues identified by the analyzer.
- The UI now has a more professional receipt appearance with proper spacing, dividers, and formatting.
## [2025-08-20 16:00] - Update Receipt UI with Courier Font and Fix Layout Issues
- Added `google_fonts` dependency to `pubspec.yaml` to use Courier Prime font for a more authentic receipt appearance.
- Updated `ReceiptScreen` to use a fixed-width layout that resembles a physical receipt.
- Added transaction details like cashier ID and transaction ID.
- Improved the overall styling with better spacing, dividers, and a thank you message.
- Fixed syntax errors in the `receipt_screen.dart` file that were preventing the app from building correctly.
- Successfully ran the app on a physical device and verified that the new UI is displayed correctly.
- Confirmed that the app can be navigated to the ReceiptScreen, though it currently defaults to TransactionScreen as the home route.
## [2025-08-20 17:00] - Fix PDF Export Path and Add PDF Opening Functionality
- Updated `PdfExportService` to use the application documents directory instead of temporary directory for saving PDF files.
- Added a function to open the generated PDF file using the `open_file` package.
- Modified `_printReceipt` function in `ReceiptScreen` to automatically open the generated PDF after creation.
- This ensures that users can easily access and view the generated receipt PDFs on their devices.
## [2025-08-20 18:00] - Implement Bluetooth Thermal Printer Functionality
- Integrated the `bluetooth_print` plugin to enable printing receipts on thermal printers.
- Added Bluetooth device scanning and connection functionality in `ReceiptScreen`.
- Implemented a function to format and print receipts to thermal printers using the ESC/POS protocol.
- Added UI elements to connect to Bluetooth printers and print receipts.
- The thermal printer functionality allows users to print receipts directly from the app to compatible Bluetooth thermal printers.
## [2025-08-20 19:00] - Fix UI Overflow and setState() After Dispose Errors
- Fixed UI overflow error in `ReceiptScreen` by properly sizing the action buttons using `Expanded` widgets.
- Resolved `setState() called after dispose` errors in `SettingsScreen` by adding `mounted` checks before calling `setState()`.
- These fixes improve the stability and user experience of the application.
## [2025-08-20 20:00] - Final Testing and Bug Fixes
- Successfully built and ran the application on a physical device.
- Verified that all core functionalities work as expected:
- Connection to Firefly III API
- Account fetching and selection
- Transaction submission
- PDF generation and opening
- Bluetooth printer connection and printing
- Fixed remaining syntax errors in the codebase.
- The application is now fully functional and ready for use.
Reference in New Issue View Git Blame Copy Permalink