Files

T

ae4b7aef07 docs(economic): map draft-invoice layout code paths (TRU-198) (#395 )

## 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>

2026-08-17 13:05:13 +02:00

3.4 KiB

Raw Blame History

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

Go to: https://github.com/copenhagentruckwash/api/settings/secrets/actions
Click "New repository secret"
Add each of the required secrets above
The values are found in your e-conomic account settings

How to Run the Live Verification

Go to: https://github.com/copenhagentruckwash/api/actions/workflows/live-verify-economic.yml
Click "Run workflow"
Leave customer_number as 12345679 (default)
Set dry_run to false for a real test
Click "Run workflow"
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.

3.4 KiB Raw Blame History