KNA-3366/feat: Basic tests and general order logic improvements

.github/workflows/tests.yml

@@ -0,0 +1,36 @@
+name: Module Tests
+
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  test:
+    name: PHP ${{ matrix.php-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        php-version: ["8.2", "8.3"]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: ${{ matrix.php-version }}
+          coverage: none
+
+      - name: Syntax check test files
+        run: |
+          php -l twopayment.php
+          php -l controllers/front/payment.php
+          php -l tests/bootstrap.php
+          php -l tests/OrderBuilderTest.php
+          php -l tests/run.php
+
+      - name: Run offline test suite
+        run: php tests/run.php

AGENTS.md

@@ -0,0 +1,75 @@
+# AGENTS.md — Two Payment Module (PrestaShop)
+
+Project-specific instructions for AI coding agents working in this repository.
+
+## Scope
+
+These rules apply to all files under this module directory.
+
+## Mission
+
+Build and maintain a robust B2B payment module where Two provider behavior and PrestaShop order state stay consistent, auditable, and safe.
+
+## Hard Constraints
+
+1. Never create a local PrestaShop order if Two rejects/fails order creation.
+2. Apply rejection/rollback protections globally (not by country-specific exception).
+3. Preserve provider-first flow and retry idempotency.
+4. Do not weaken server-side validation in favor of frontend checks.
+5. Keep tax/amount formulas consistent with existing test expectations.
+6. Never expose secrets in logs or code.
+7. Never default to insecure transport behavior.
+
+## Required Verification Before Claiming Done
+
+Run from module root:
+
+```bash
+php -l twopayment.php
+php tests/run.php
+```
+
+If you edited additional PHP files, lint each one:
+
+```bash
+php -l path/to/file.php
+```
+
+## i18n Requirements
+
+For every user-facing string change:
+- Update PHP/Smarty translation surfaces (`$this->l`, `{l ...}`)
+- Update JS i18n dictionary in `twopayment.php` when used by frontend modules
+- Update `translations/es.php` with natural Spanish
+- Avoid hardcoded English UI fallback where module i18n is available
+
+## File Ownership Reference
+
+- `twopayment.php`: hooks, settings, API interactions, payload and i18n map
+- `controllers/front/payment.php`: checkout confirmation + order creation safety
+- `controllers/front/orderintent.php`: order intent API and gating data
+- `views/js/modules/*.js`: checkout UX logic and client validation
+- `views/templates/hook/*.tpl`: admin and checkout rendering
+- `tests/OrderBuilderTest.php`: tax/amount/order payload invariants
+
+## Change Quality Rules
+
+- Keep diffs targeted; avoid unrelated refactors in payment-critical paths.
+- Preserve backward compatibility unless change request is explicit.
+- Add or update tests for behavior changes in payload, validation, or flow control.
+- Update `CHANGELOG.md` for functional changes.
+
+## Release Consistency Rules
+
+When bumping/releasing versions, keep these in sync:
+- `twopayment.php` version
+- `config.xml` version
+- `CHANGELOG.md`
+
+## Common Failure Patterns to Avoid
+
+- Reintroducing local order writes before provider success.
+- Losing idempotency on retries/timeouts.
+- Country-specific tax/error branching that bypasses global safeguards.
+- Admin UI showing invoice actions too early in order lifecycle.
+- Updating JS messages without adding corresponding translation keys.

AI_CONTEXT.md

@@ -0,0 +1,162 @@
+# Two Payment Plugin for PrestaShop
+
+AI agent operating manual for the `twopayment` module.
+
+## 1) Current Truth
+
+| Item | Value |
+| --- | --- |
+| Module | `twopayment` |
+| Version | `2.4.0` |
+| PrestaShop support | `1.7.6` to `9.x` |
+| Core model | Provider-first checkout (Two first, PrestaShop order second) |
+| Main file | `twopayment.php` |
+
+Canonical version sources:
+- `twopayment.php` (`$this->version`)
+- `config.xml` (`<version>`)
+- `CHANGELOG.md` top entry
+
+These must stay aligned.
+
+## 2) Product Goal
+
+Reliable B2B invoice checkout via Two, with:
+- No phantom local orders when provider-side creation/review fails
+- Accurate tax/amount payload parity with PrestaShop totals
+- Safe retry behavior (idempotency)
+- Clear admin observability of Two order lifecycle
+
+## 3) Non-Negotiable Invariants
+
+1. Never create a local PrestaShop order if Two order creation/verification fails.
+2. Apply the rejection/rollback rule for all countries, not Spain-only logic.
+3. Keep provider-first flow intact: Two acceptance/verification gates local order creation.
+4. Keep idempotency on provider order creation paths.
+5. Do not weaken server-side validation gates even if frontend checks exist.
+6. Preserve tax math integrity (`tax_amount = net_amount * tax_rate`, within rounding constraints).
+7. Do not expose secrets or disable SSL verification by default.
+8. If user-facing text changes, update all required i18n surfaces (PHP, JS i18n map, translations).
+
+## 4) Core Flow (High Level)
+
+### Checkout and Order Creation
+1. Buyer enters/selects company details.
+2. Order intent check runs (frontend + server-side persistence/validation).
+3. Two order is created first.
+4. Only after provider-side success, local PrestaShop order is finalized.
+
+### Retry/Idempotency
+- Repeated submit/callback paths must not duplicate provider orders.
+- Attempt tracking table + idempotency headers are part of the safety model.
+
+### Admin Order View
+- Show stable stored identifiers and state info.
+- Where available, refresh/fetch current provider metadata for accuracy.
+- Invoice links/actions should only be shown when lifecycle state permits (for example after fulfillment).
+
+## 5) File Ownership Map
+
+### Core Module
+- `twopayment.php`
+  - Hooks, config fields, API wrappers, payload building, i18n JS dictionary
+  - Main place for business rules and invariants
+
+### Front Controllers
+- `controllers/front/payment.php`
+  - Provider-first payment orchestration and final local order safety
+- `controllers/front/orderintent.php`
+  - Ajax order intent, company context, guardrails
+- `controllers/front/confirmation.php`
+  - Post-checkout result handling
+- `controllers/front/cancel.php`
+  - Cancellation/error paths
+
+### Frontend Checkout Modules
+- `views/js/modules/TwoCheckoutManager.js`
+  - Payment-option behavior, approval/decline UX, terms UI
+- `views/js/modules/TwoOrderIntent.js`
+  - Order intent polling and UI messaging
+- `views/js/modules/TwoCompanySearch.js`
+  - Company discovery and selection
+- `views/js/modules/TwoFieldValidation.js`
+  - Account/company field validation behavior
+
+### Admin UI
+- `views/templates/hook/displayAdminOrderLeft.tpl`
+- `views/templates/hook/displayAdminOrderTabContent.tpl`
+
+### Tests
+- `tests/OrderBuilderTest.php`
+- `tests/run.php`
+
+### Upgrades
+- `upgrade/upgrade-*.php`
+
+## 6) i18n Rules
+
+When adding/changing user-facing strings:
+1. Wrap PHP strings with `$this->l(...)`.
+2. For JS, expose keys via `Media::addJsDef(... 'i18n' => [...])` in `twopayment.php`.
+3. Consume keys in JS; avoid raw English literals for user-facing errors/messages.
+4. Add/update `translations/es.php` with natural Spanish, not literal machine phrasing.
+5. Re-check template `{l s=... mod='twopayment'}` coverage.
+
+## 7) Tax and Amount Safety
+
+Before changing payload builders:
+- Verify line-item formulas and rounding behavior.
+- Ensure product-level, shipping, and discount lines reconcile to order totals.
+- Validate behavior for mixed rates and tax-exempt contexts.
+- Keep fallback tax-derivation logic deterministic.
+
+Always run the order-builder test suite after tax/amount edits.
+
+## 8) Verification Commands (Minimum)
+
+Run from module root:
+
+```bash
+php -l twopayment.php
+php -l controllers/front/payment.php
+php -l controllers/front/orderintent.php
+php tests/run.php
+```
+
+For broader edits, lint any touched PHP files and re-run tests.
+
+## 9) Logging and Debugging
+
+- Use `PrestaShopLogger::addLog` with actionable context (`order_id`, `two_order_id`, endpoint/action).
+- Never log API keys, tokens, or sensitive customer data.
+- Use debug mode only for targeted diagnosis; keep normal logs concise.
+
+## 10) Common Regression Risks
+
+1. Reintroducing local order writes before provider acceptance.
+2. Country-specific error branching that bypasses global rejection guardrails.
+3. Broken idempotency on retries/timeouts.
+4. Silent mismatch between frontend i18n keys and PHP-provided dictionary.
+5. Admin view showing invoice actions before provider invoice lifecycle is ready.
+6. Version mismatch across `twopayment.php`, `config.xml`, `CHANGELOG.md`.
+
+## 11) Release Hygiene Checklist
+
+Before release/tag:
+1. Version synchronized across module files.
+2. Upgrade script exists and is referenced where needed.
+3. Changelog entry accurate and merged cleanly.
+4. Tests green.
+5. No temporary debug code/messages.
+6. Translation updates included for changed user-facing text.
+
+## 12) Working Style for Agents
+
+- Prefer minimal, targeted diffs over broad rewrites.
+- Preserve backward compatibility unless explicitly changing behavior.
+- Document any behavior-changing decision in `CHANGELOG.md` and relevant docs.
+- If a rule here conflicts with code behavior, update this file in the same change.
+
+## Revision Notes
+
+- 2026-02-26: Rewritten for v2.4.0 architecture and provider-first safeguards.