Skip to content

API_CONTRACT_REVIEW.md

Latest commit

 

History

History
309 lines (230 loc) · 11 KB

API_CONTRACT_REVIEW.md

File metadata and controls

309 lines (230 loc) · 11 KB
Raw

API Contract Consistency Review Report

Generated: $(date) Status: READY FOR RELEASE (with critical fixes needed)

Executive Summary

The batch-file-processor project has been reviewed for API contract consistency across 5 critical areas. 3 major issues and 3 minor issues were identified that could cause runtime errors. These must be addressed before release.

1. PIPELINE INTERFACE CONSISTENCY ✅ PASS

Assessment

All pipeline steps in dispatch/pipeline/ properly implement their respective protocols and have required methods.

Details

  • EDIValidationStep (validator.py): ✅ Implements ValidatorStepInterface

    • Methods: validate(), should_block_processing(), execute(), get_error_log(), clear_error_log()

  • EDIConverterStep (converter.py): ✅ Implements ConverterInterface

    • Methods: convert(), get_supported_formats(), execute()

  • EDISplitterStep (splitter.py): ✅ Implements SplitterInterface

    • Methods: split(), execute()

  • EDITweakerStep (tweaker.py): ✅ Implements TweakerInterface

    • Methods: tweak(), execute()

Verdict

✅ PASS - All pipeline steps are consistent and fully implemented. No runtime errors expected from this area.

2. PLUGIN SYSTEM ✅ PASS

Assessment

All plugins in interface/plugins/ properly inherit from ConfigurationPlugin and implement all required methods.

Details

Verified plugins:

  • CSVConfigurationPlugin ✅
  • FintechConfigurationPlugin ✅
  • JolleyCustomConfigurationPlugin ✅
  • StewartCustomConfigurationPlugin ✅
  • SimplifiedCSVConfigurationPlugin ✅
  • ScannerwareConfigurationPlugin ✅
  • ScansheetTypeAConfigurationPlugin ✅
  • EStoreEInvoiceConfigurationPlugin ✅
  • EStoreEInvoiceGenericConfigurationPlugin ✅
  • YellowdogCSVConfigurationPlugin ✅

Required Methods (All Present)

  • Class methods: get_name(), get_identifier(), get_description(), get_version()
  • Configuration methods: get_format_name(), get_format_enum(), get_config_fields()
  • Lifecycle methods: initialize(), activate(), deactivate()
  • Implementation methods: validate_config(), create_config(), serialize_config(), deserialize_config(), create_widget()

Verdict

✅ PASS - All plugins properly inherit and implement the ConfigurationPlugin interface. No inconsistencies found.

3. DATABASE SCHEMA CONSISTENCY ⚠️ CRITICAL ISSUES FOUND

Issue #1: Column Mismatch Between schema.py and Database

Severity: HIGH Type: Schema Inconsistency

The schema.py defines columns that don't exist in the actual database, and vice versa.

Missing from database (defined in schema.py but not in DB):

- backend_copy_destination
- convert_format
- edi_output_folder
- error_message
- filename
- original_path
- process_edi_output
- processed_path
- sent_to
- split_edi_filter_categories
- split_edi_filter_mode
- status
- upc_padding_pattern
- upc_target_length

Extra in database (exist in DB but not in schema.py):

- edi_converter_scratch_folder
- email_origin_address
- email_origin_password
- email_origin_smtp_server
- email_origin_username
- email_smtp_port
- report_email_address
- report_email_password
- report_email_smtp_server
- report_email_username
- reporting_smtp_port

Risk: Code referencing missing columns will fail at runtime when trying to access split_edi_filter_categories, split_edi_filter_mode, upc_target_length, or upc_padding_pattern.

Files Affected:

  • schema.py - Lines 133-207 (folders table definition)
  • migrations/add_plugin_config_column.py - Attempts to add split_edi_filter_categories and split_edi_filter_mode

Issue #2: Plugin Configuration Column Naming Mismatch

Severity: MEDIUM Type: Column Naming Inconsistency

  • schema.py defines: plugin_config TEXT (lines 113, 196)
  • schema.py migration attempts to add: plugin_configurations TEXT (line 408)
  • Actual database has: plugin_config (column 65)
  • Code references: plugin_configurations in interface/models/folder_configuration.py

Risk: Code using plugin_configurations field will not find the plugin_config column in the database, causing mapping errors.

Files Affected:

  • schema.py - Lines 408-418
  • migrations/add_plugin_config_column.py - Lines 6-30
  • interface/models/folder_configuration.py - Uses plugin_configurations field

Issue #3: Migration Adds Columns Never Defined in ensure_schema()

Severity: MEDIUM Type: Missing Schema Definition

migrations/add_plugin_config_column.py adds columns via ALTER TABLE that are never defined in ensure_schema():

  • split_edi_filter_categories (migration line 35-40)
  • split_edi_filter_mode (migration line 43-49)

Risk: If ensure_schema() is called after the migration (e.g., on a new database), these columns won't be created, causing inconsistency.

Recommendations

  1. Update schema.py to match actual database schema

    • Add missing columns: edi_converter_scratch_folder, email_origin_*, report_email_*, etc.
    • Remove or mark as deprecated columns that only exist in schema but not in DB

  2. Standardize plugin column naming

    • Choose ONE name: either plugin_config or plugin_configurations
    • Update migration to match schema.py
    • Update folder_configuration.py to use the correct name

  3. Update ensure_schema() to include migration columns

    • Add split_edi_filter_categories and split_edi_filter_mode to the folders table creation
    • Ensure these are also added to administrative table for consistency

Verdict

⚠️ CRITICAL - Schema inconsistencies must be fixed before release to prevent runtime errors when accessing missing columns.

4. IMPORT CONSISTENCY ⚠️ ISSUE FOUND

Assessment

The batch_file_processor/__init__.py shim exports modules that no longer exist or cannot be imported.

Issue: Missing Module Export

Severity: MEDIUM Type: Import Error

File: batch_file_processor/__init__.py line 42

  • Exports: "dispatch_process"
  • Status: ❌ Module does not exist at repository root

Risk: Callers using import batch_file_processor.dispatch_process will get ModuleNotFoundError.

Tested Imports

  • ✅ dispatch - Works
  • ✅ core - Works
  • ✅ backend - Works
  • ✅ interface - Works
  • ✅ utils - Works
  • ✅ create_database - Works
  • ❌ dispatch_process - FAILS (module not found)

Recommendations

  1. Option A: Remove from __all__ if no longer needed

    • Line 42: Remove "dispatch_process",

  2. Option B: Create stub or proper module

    • If functionality moved, create appropriate re-export
    • Update documentation for migration path

Verdict

⚠️ MINOR - Will cause import errors for callers using dispatch_process. Easily fixed by removing or providing the module.

5. DISPATCHCONFIG FIELDS COMPLETENESS ⚠️ ISSUE FOUND

Assessment

Not all DispatchConfig fields defined in the dataclass are used in orchestrator.py, and vice versa.

Issue: Unused Configuration Fields

Severity: LOW Type: Dead Code / Potential API Inconsistency

Unused fields in DispatchConfig:

- database: Optional[DatabaseInterface] = None
- file_processor: Optional[Any] = None  
- version: str = "1.0.0"

These fields are defined but never referenced in orchestrator.py:

  • database - Not used anywhere in orchestrator
  • file_processor - Not used anywhere in orchestrator
  • version - Not used anywhere in orchestrator

Used fields (verified):

✅ validator, error_handler, settings, backends
✅ file_system, upc_service, upc_dict
✅ progress_reporter
✅ validator_step, splitter_step, converter_step, tweaker_step

Risk Assessment

  • ❌ No immediate runtime error - unused fields don't cause failures
  • ⚠️ API confusing - Developers may provide these fields expecting them to work
  • ⚠️ Maintenance burden - Unclear if these should be removed or if they're reserved for future use

Recommendations

  1. Remove unused fields OR add usage

    • If truly unused: Remove database, file_processor, and version from DispatchConfig
    • If reserved for future: Add clear documentation explaining their purpose
    • If moved elsewhere: Update docstring to indicate that

  2. Document purpose of each field

    • Add comments explaining what each field is used for
    • Clarify if some fields are reserved for extensibility

Verdict

🟡 MINOR - Inconsistency creates API confusion but doesn't cause runtime errors. Should be cleaned up for clarity.

SUMMARY TABLE

Area Status Issues Severity
Pipeline Interface ✅ PASS 0 -
Plugin System ✅ PASS 0 -
Database Schema ❌ FAIL 3 CRITICAL
Import Consistency ⚠️ MINOR 1 MEDIUM
DispatchConfig Fields ⚠️ MINOR 1 LOW
OVERALL ⚠️ CONDITIONAL 5 1 CRITICAL

REQUIRED ACTIONS BEFORE RELEASE

🔴 CRITICAL (MUST FIX)

  1. Reconcile database schema with schema.py

    • Decide which columns are authoritative
    • Add missing columns to schema.py or remove from database
    • Ensure split_edi_filter_* columns exist in both

  2. Fix plugin configuration column naming

    • Standardize on one name (recommend plugin_configurations)
    • Update schema.py, migrations, and FolderConfiguration model
    • Test database queries with correct column name

🟡 IMPORTANT (SHOULD FIX)

  1. Remove or implement dispatch_process export

    • Delete from batch_file_processor/__init__.py if unused
    • Or create proper module/re-export if needed

  2. Clean up DispatchConfig

    • Document or remove unused fields (database, file_processor, version)
    • Add docstring comments for each field explaining usage

📝 TESTING RECOMMENDATIONS

  • Test new database creation with ensure_schema()
  • Test migration from old schema to new schema
  • Test plugin configuration persistence and retrieval
  • Test module imports from batch_file_processor package
  • Test orchestrator initialization with full config
  • Verify no AttributeError when accessing configuration columns

FILES REQUIRING CHANGES

CRITICAL:

  • /workspaces/batch-file-processor/schema.py (lines 113, 196, 408-427)
  • /workspaces/batch-file-processor/migrations/add_plugin_config_column.py (lines 1-78)
  • /workspaces/batch-file-processor/interface/models/folder_configuration.py (if using plugin_configurations)

IMPORTANT:

  • /workspaces/batch-file-processor/batch_file_processor/__init__.py (line 42)
  • /workspaces/batch-file-processor/dispatch/orchestrator.py (DispatchConfig docstring)

CONCLUSION

The API contracts are generally well-designed, with excellent consistency in the pipeline and plugin systems. However, critical database schema inconsistencies must be resolved before release to ensure reliable field access and migration safety.

Recommendation: Fix the schema issues, update imports, and clean up DispatchConfig documentation. Once these are resolved, the system is ready for release.