ae4b7aef07
## Summary Maps every code path in the API repo that creates an e-conomic draft invoice or sends draft lines, and documents which paths pick a layout, which one they pick, and how the planned **with-discounts / without-discounts** two-layout selection applies. **Key finding:** the two envelope creators already implement a discount-aware selector. No code change is required for the TRU-197 rollout — only the two `invoice*LayoutNumber` config variables need to be set in the `economic` module. ## Findings at a glance - **22** code paths in `services/nginx/app/` create or send draft invoices (2 envelope creators + 6 line-add paths + 14 caller/selector/helper paths) - **2** paths currently pick a layout — both already discount-aware - **0** paths need updating for the 2-layout rollout - **2** config variables drive the selection: `invoiceLayoutNumber` and `invoiceDiscountLayoutNumber` (already wired into `economic::$config` and the OpenAPI schema) ## The two selectors 1. `economic_invoice_draft_mo::resolveLayoutNumber()` at `services/nginx/app/modules/economic/invoices/draft/economic_invoice_draft_mo.php:115` — used by `createInvoiceDraftExample()` for the single-order draft flow. 2. `collected_order_invoices_o::resolveInvoiceLayoutNumber()` at `services/nginx/app/objects/collected_order_invoices_o.php:673` — used by `createInvoiceDraft()` for the collected-invoice flow. Both return `invoice_discount_layout` if any item has a non-zero discount, otherwise `invoice_layout`. They throw if the discount layout is required and `invoiceDiscountLayoutNumber` is unconfigured. ## Document `documentation/economic/layout-selection-flow.md` — full inventory table, current/desired state, and migration plan. ## Related - TRU-197 — `documentation/economic/invoice-template-audit.md` - TRU-193 — `documentation/economic/export-field-audit.md` - PR #391 — `economic_export_sanitizer` Refs: TRU-198 --------- Co-authored-by: openhands <openhands@all-hands.dev> Co-authored-by: OpenClaw <openclaw@copenhagentruckwash.io> Co-authored-by: TRU-198 Subagent <subagent@openhands.dev>
83 lines
3.4 KiB
Markdown
83 lines
3.4 KiB
Markdown
# GitHub Secrets for e-conomic Live Verification
|
|
|
|
This document explains which secrets need to be configured in the `copenhagentruckwash/api` GitHub repository for the **Verify e-conomic Live** workflow (`.github/workflows/live-verify-economic.yml`) to work.
|
|
|
|
## Required Secrets
|
|
|
|
| Secret | Description | Where to find it | Required? |
|
|
|---|---|---|---|
|
|
| `ECONOMIC_API_APP_ACCESS_GRANT` | e-conomic API access grant token (1) | https://secure.e-conomic.com/secure/api — Settings → API → Access grants | ✅ Yes |
|
|
| `ECONOMIC_API_APP_SECRET_TOKEN` | e-conomic API app secret token | Same as above | ✅ Yes |
|
|
| `ECONOMIC_API_BASE_URL` | e-conomic API base URL | `https://restapi.e-conomic.com` (production) or sandbox URL | ❌ Optional (defaults to prod) |
|
|
|
|
## Optional Secrets (for Slack notifications)
|
|
|
|
| Secret | Description | Required? |
|
|
|---|---|---|
|
|
| `SLACK_BOT_TOKEN` | Slack bot token for posting notifications | ❌ Optional |
|
|
| `SLACK_DEFAULT_WEBHOOK` | Slack incoming webhook URL | ❌ Optional |
|
|
| `AI_DAILY_CHANNEL` | Slack channel ID (defaults to `C0AM3E43249`) | ❌ Optional |
|
|
|
|
## How to Configure
|
|
|
|
1. Go to: https://github.com/copenhagentruckwash/api/settings/secrets/actions
|
|
2. Click **"New repository secret"**
|
|
3. Add each of the required secrets above
|
|
4. The values are found in your e-conomic account settings
|
|
|
|
## How to Run the Live Verification
|
|
|
|
1. Go to: https://github.com/copenhagentruckwash/api/actions/workflows/live-verify-economic.yml
|
|
2. Click **"Run workflow"**
|
|
3. Leave `customer_number` as `12345679` (default)
|
|
4. Set `dry_run` to **`false`** for a real test
|
|
5. Click **"Run workflow"**
|
|
6. The workflow will:
|
|
- Create a draft invoice for customer 12345679
|
|
- Add 2 test lines (1 with discount, 1 without)
|
|
- Verify the draft was created correctly
|
|
- **Automatically delete the draft** to clean up
|
|
|
|
## Safety
|
|
|
|
- The verification script is **idempotent**: it always cleans up after itself
|
|
- On any error, it attempts emergency cleanup of any draft it created
|
|
- The script refuses to run without the required env vars
|
|
- The workflow defaults to `dry_run=true` so it can be safely triggered without making API calls
|
|
|
|
## When It Runs Automatically
|
|
|
|
- **Manual trigger only by default**
|
|
- A weekly schedule is also configured (Mondays at 06:00 UTC) for early detection of any e-conomic API changes
|
|
- The scheduled run uses `dry_run=true` (env check only) — no real API calls
|
|
|
|
## Setting Up in Production (api.truckwash.io)
|
|
|
|
The same e-conomic credentials are also used by the live API. They're stored in:
|
|
- The production server's `.env` file (loaded by PHP)
|
|
- The deploy.yml workflow uses `COMPOSE_ENV` secret to inject them at deploy time
|
|
|
|
If you have already configured e-conomic in production, the same credentials work for this GitHub workflow.
|
|
|
|
## Troubleshooting
|
|
|
|
### "ECONOMIC_API_APP_ACCESS_GRANT is not set"
|
|
|
|
The secret is not configured. Follow the "How to Configure" steps above.
|
|
|
|
### "ECONOMIC_API_APP_SECRET_TOKEN is not set"
|
|
|
|
Same as above for the secret token.
|
|
|
|
### "Draft creation returned HTTP 401"
|
|
|
|
The credentials are wrong or expired. Check that the access grant is still active in your e-conomic account.
|
|
|
|
### "Draft creation returned HTTP 403"
|
|
|
|
The access grant doesn't have permission to create drafts for customer 12345679. Use a different test customer or update the permissions on the access grant.
|
|
|
|
### "Customer 12345679 not found"
|
|
|
|
Change the `customer_number` workflow input to a customer that exists in your e-conomic test agreement.
|