feat: implement account linking and management system
Add comprehensive account linking functionality to automatically match bank accounts to Firefly III accounts, with manual override options. This includes: - New LinkStore module for persistent storage of account links with auto-linking based on IBAN matching - Extended adapter traits with inspection methods (list_accounts, get_account_status, etc.) and discover_accounts for account discovery - Integration of linking into sync logic to automatically discover and link accounts before syncing transactions - CLI commands for managing account links (list, create, etc.) - Updated README with new features and usage examples This enables users to easily manage account mappings between sources and destinations, reducing manual configuration and improving sync reliability.
This commit is contained in:
@@ -63,26 +63,126 @@ COMMANDS:
|
||||
- All placeholder commands log appropriate messages for future implementation
|
||||
- Maintained all existing sync functionality and flags
|
||||
|
||||
### Phase 2: Core Port Extensions
|
||||
### Phase 2: Core Port Extensions ✅ COMPLETED
|
||||
|
||||
**Objective**: Extend ports and adapters to support inspection capabilities.
|
||||
|
||||
**Steps:**
|
||||
1. Add inspection methods to `TransactionSource` and `TransactionDestination` traits:
|
||||
1. ✅ Add inspection methods to `TransactionSource` and `TransactionDestination` traits:
|
||||
- `list_accounts()`: Return account summaries
|
||||
- `get_account_status()`: Return sync status for accounts
|
||||
- `get_transaction_info()`: Return transaction metadata
|
||||
- `get_cache_info()`: Return caching status
|
||||
2. Update existing adapters (GoCardless, Firefly) to implement new methods
|
||||
3. Define serializable response structs in `core::models` for inspection data
|
||||
4. Ensure all new methods handle errors gracefully with `anyhow`
|
||||
2. ✅ Update existing adapters (GoCardless, Firefly) to implement new methods
|
||||
3. ✅ Define serializable response structs in `core::models` for inspection data
|
||||
4. ✅ Ensure all new methods handle errors gracefully with `anyhow`
|
||||
|
||||
**Testing:**
|
||||
- Unit tests for trait implementations on existing adapters
|
||||
- Mock tests for new inspection methods
|
||||
- Integration tests verifying data serialization
|
||||
|
||||
### Phase 3: Adapter Factory Implementation
|
||||
**Implementation Details:**
|
||||
- Added `AccountSummary`, `AccountStatus`, `TransactionInfo`, and `CacheInfo` structs with `Serialize` and `Debug` traits
|
||||
- Extended both `TransactionSource` and `TransactionDestination` traits with inspection methods
|
||||
- Implemented methods in `GoCardlessAdapter` using existing client calls and cache data
|
||||
- Implemented methods in `FireflyAdapter` using existing client calls
|
||||
- All code formatted with `cargo fmt` and linted with `cargo clippy`
|
||||
- Existing tests pass; new methods compile but not yet tested due to CLI not implemented
|
||||
|
||||
### Phase 3: Account Linking and Management ✅ COMPLETED
|
||||
|
||||
**Objective**: Implement comprehensive account linking between sources and destinations to enable reliable sync, with auto-linking where possible and manual overrides.
|
||||
|
||||
**Steps:**
|
||||
1. ✅ Create `core::linking` module with data structures:
|
||||
- `AccountLink`: Links source account ID to destination account ID with metadata
|
||||
- `LinkStore`: Persistent storage for links, aliases, and account registries
|
||||
- Auto-linking logic (IBAN/name similarity scoring)
|
||||
|
||||
2. ✅ Extend adapters with account discovery:
|
||||
- `TransactionSource::discover_accounts()`: Full account list without filtering
|
||||
- `TransactionDestination::discover_accounts()`: Full account list
|
||||
|
||||
3. ✅ Implement linking management:
|
||||
- Auto-link on sync/account discovery (IBAN/name matches)
|
||||
- CLI commands: `banks2ff accounts link list`, `banks2ff accounts link create <source_account> <dest_account>`, `banks2ff accounts link delete <link_id>`
|
||||
- Alias support: `banks2ff accounts alias set <link_id> <alias>`, `banks2ff accounts alias update <link_id> <new_alias>`
|
||||
|
||||
4. ✅ Integrate with sync:
|
||||
- Always discover accounts during sync and update stores
|
||||
- Use links in `run_sync()` instead of IBAN-only matching
|
||||
- Handle unlinked accounts (skip with warning or prompt for manual linking)
|
||||
|
||||
5. ✅ Update CLI help text:
|
||||
- Explain linking process in `banks2ff accounts --help`
|
||||
- Note that sync auto-discovers and attempts linking
|
||||
|
||||
**Testing:**
|
||||
- Unit tests for auto-linking algorithms
|
||||
- Integration tests for various account scenarios (IBAN matches, name matches, no matches)
|
||||
- Persistence tests for link store
|
||||
- CLI tests for link management commands
|
||||
|
||||
**Implementation Details:**
|
||||
- Created `core::linking` with `LinkStore` using nested `HashMap`s for organized storage by adapter type
|
||||
- Extended traits with `discover_accounts()` and implemented in GoCardless/Firefly adapters
|
||||
- Integrated account discovery and auto-linking into `run_sync()` with persistent storage
|
||||
- Added CLI commands under `banks2ff accounts link` with full CRUD operations and alias support
|
||||
- Updated README with new account linking feature, examples, and troubleshooting
|
||||
|
||||
### Phase 4: CLI Output and Formatting
|
||||
|
||||
**Objective**: Implement user-friendly output for inspection commands.
|
||||
|
||||
**Steps:**
|
||||
1. Create `cli::formatters` module for consistent output formatting
|
||||
2. Implement table-based display for accounts and transactions
|
||||
3. Add JSON output option for programmatic use
|
||||
4. Ensure sensitive data masking in all outputs
|
||||
5. Add progress indicators for long-running operations
|
||||
6. Implement `accounts` command with `list` and `status` subcommands
|
||||
7. Implement `transactions` command with `list`, `cache-status`, and `clear-cache` subcommands
|
||||
8. Add account and transaction inspection methods to adapter traits
|
||||
|
||||
**Testing:**
|
||||
- Unit tests for formatter functions
|
||||
- Integration tests for CLI output with sample data
|
||||
- Accessibility tests for output readability
|
||||
- Unit tests for new command implementations
|
||||
- Integration tests for account/transaction inspection
|
||||
|
||||
### Phase 5: Status and Cache Management
|
||||
|
||||
**Objective**: Implement status overview and cache management commands.
|
||||
|
||||
**Steps:**
|
||||
1. Implement `status` command aggregating data from all adapters
|
||||
2. Add cache inspection and clearing functionality to `transactions cache-status` and `transactions clear-cache`
|
||||
3. Create status models for sync health metrics
|
||||
4. Integrate with existing debug logging infrastructure
|
||||
|
||||
**Testing:**
|
||||
- Unit tests for status aggregation logic
|
||||
- Integration tests for cache operations
|
||||
- Mock tests for status data collection
|
||||
|
||||
### Phase 6: Sync Logic Updates
|
||||
|
||||
**Objective**: Make sync logic adapter-agnostic and reusable.
|
||||
|
||||
**Steps:**
|
||||
1. Modify `core::sync::run_sync()` to accept source/destination traits instead of concrete types
|
||||
2. Update sync result structures to include inspection data
|
||||
3. Refactor account processing to work with any `TransactionSource`
|
||||
4. Ensure dry-run mode works with all adapter types
|
||||
|
||||
**Testing:**
|
||||
- Unit tests for sync logic with mock adapters
|
||||
- Integration tests with different source/destination combinations
|
||||
- Regression tests ensuring existing functionality unchanged
|
||||
|
||||
### Phase 7: Adapter Factory Implementation
|
||||
|
||||
**Objective**: Enable dynamic adapter instantiation for multiple sources/destinations.
|
||||
|
||||
@@ -98,7 +198,24 @@ COMMANDS:
|
||||
- Mock tests for adapter creation
|
||||
- Integration tests with real configurations
|
||||
|
||||
### Phase 4: File-Based Source Adapters
|
||||
### Phase 8: Integration and Validation
|
||||
|
||||
**Objective**: Ensure all components work together and prepare for web API.
|
||||
|
||||
**Steps:**
|
||||
1. Full integration testing across all source/destination combinations
|
||||
2. Performance testing with realistic data volumes
|
||||
3. Documentation updates in `docs/architecture.md`
|
||||
4. Code review against project guidelines
|
||||
5. Update `AGENTS.md` with new development patterns
|
||||
|
||||
**Testing:**
|
||||
- End-to-end tests for complete workflows
|
||||
- Load tests for sync operations
|
||||
- Security audits for data handling
|
||||
- Compatibility tests with existing configurations
|
||||
|
||||
### Phase 9: File-Based Source Adapters
|
||||
|
||||
**Objective**: Implement adapters for file-based transaction sources.
|
||||
|
||||
@@ -119,74 +236,6 @@ COMMANDS:
|
||||
- Integration tests with fixture files from `tests/fixtures/`
|
||||
- Performance tests for large file handling
|
||||
|
||||
### Phase 5: Sync Logic Updates
|
||||
|
||||
**Objective**: Make sync logic adapter-agnostic and reusable.
|
||||
|
||||
**Steps:**
|
||||
1. Modify `core::sync::run_sync()` to accept source/destination traits instead of concrete types
|
||||
2. Update sync result structures to include inspection data
|
||||
3. Refactor account processing to work with any `TransactionSource`
|
||||
4. Ensure dry-run mode works with all adapter types
|
||||
|
||||
**Testing:**
|
||||
- Unit tests for sync logic with mock adapters
|
||||
- Integration tests with different source/destination combinations
|
||||
- Regression tests ensuring existing functionality unchanged
|
||||
|
||||
### Phase 6: CLI Output and Formatting
|
||||
|
||||
**Objective**: Implement user-friendly output for inspection commands.
|
||||
|
||||
**Steps:**
|
||||
1. Create `cli::formatters` module for consistent output formatting
|
||||
2. Implement table-based display for accounts and transactions
|
||||
3. Add JSON output option for programmatic use
|
||||
4. Ensure sensitive data masking in all outputs
|
||||
5. Add progress indicators for long-running operations
|
||||
6. Implement `accounts` command with `list` and `status` subcommands
|
||||
7. Implement `transactions` command with `list`, `cached`, and `clear-cache` subcommands
|
||||
8. Add account and transaction inspection methods to adapter traits
|
||||
|
||||
**Testing:**
|
||||
- Unit tests for formatter functions
|
||||
- Integration tests for CLI output with sample data
|
||||
- Accessibility tests for output readability
|
||||
- Unit tests for new command implementations
|
||||
- Integration tests for account/transaction inspection
|
||||
|
||||
### Phase 7: Status and Cache Management
|
||||
|
||||
**Objective**: Implement status overview and cache management commands.
|
||||
|
||||
**Steps:**
|
||||
1. Implement `status` command aggregating data from all adapters
|
||||
2. Add cache inspection and clearing functionality to `transactions cached` and `transactions clear-cache`
|
||||
3. Create status models for sync health metrics
|
||||
4. Integrate with existing debug logging infrastructure
|
||||
|
||||
**Testing:**
|
||||
- Unit tests for status aggregation logic
|
||||
- Integration tests for cache operations
|
||||
- Mock tests for status data collection
|
||||
|
||||
### Phase 8: Integration and Validation
|
||||
|
||||
**Objective**: Ensure all components work together and prepare for web API.
|
||||
|
||||
**Steps:**
|
||||
1. Full integration testing across all source/destination combinations
|
||||
2. Performance testing with realistic data volumes
|
||||
3. Documentation updates in `docs/architecture.md`
|
||||
4. Code review against project guidelines
|
||||
5. Update `AGENTS.md` with new development patterns
|
||||
|
||||
**Testing:**
|
||||
- End-to-end tests for complete workflows
|
||||
- Load tests for sync operations
|
||||
- Security audits for data handling
|
||||
- Compatibility tests with existing configurations
|
||||
|
||||
## Architecture Considerations
|
||||
|
||||
- **Hexagonal Architecture**: Maintain separation between core business logic, ports, and adapters
|
||||
|
||||
Reference in New Issue
Block a user