Voiced/scripts/erpnext-e2e/README.md

# ERPNext live end-to-end (podman)

Runs Voiced's ERPNext integration against real ERPNext v15 sites: one plain site and one with India Compliance.
Everything is rootless podman (`podman` and `podman-compose`, never docker). All names are prefixed `voiced-erp`.

| File | Purpose |
|---|---|
| `compose.yml` | Lean stack: MariaDB, one Redis, backend (gunicorn on `127.0.0.1:8088`), one worker. Project name `voiced-erp`. |
| `Containerfile.ic` | `frappe/erpnext:v15.121.6` plus the `india_compliance` app files (`version-15` branch). |
| `setup.sh` | Builds the image, starts the stack, creates both sites, prepares them, writes `.env.a` and `.env.b`. |
| `setup_site.py` | Runs inside the container: company, accounts, address, items, integration user and keys. |
| `../../src-tauri/src/integrations/erpnext/live_tests.rs` | The `#[ignore]` Rust tests. |

## Reproduce

```bash
cd scripts/erpnext-e2e
./setup.sh            # first run pulls ~2 GB of images and takes about 10 minutes
```

`setup.sh` creates two sites that one backend serves by Host header:

| Site | URL | Contents | Env file |
|---|---|---|---|
| `127.0.0.1` | `http://127.0.0.1:8088` | ERPNext only | `.env.a` |
| `localhost` | `http://localhost:8088` | ERPNext + India Compliance | `.env.b` |

Both get the company "Voiced Test Co" (abbreviation `VTC`, INR, India, fiscal year 2026-27), the output tax accounts
`Output Tax CGST|SGST|UTGST|IGST - VTC` (India Compliance creates its own with the same names), `TDS Receivable - VTC`,
the bank account `HDFC - VTC`, a company address, the UOMs Hour/Minute/Second, the items `VOICED-SERVICE` (stock UOM Nos)
and `VOICED-HOURLY` (stock UOM Hour), and an integration user with a fresh API key and secret.
`.env.*` files hold those keys; they are git-ignored (`.env.*` in the root `.gitignore`) and must never be committed.

Run the Rust tests (they only touch the site named by the sourced env file):

```bash
set -a; . scripts/erpnext-e2e/.env.a; set +a      # or .env.b for the India Compliance site
cargo test --manifest-path src-tauri/Cargo.toml live_ -- --ignored --test-threads=1
```

Environment variables the tests read:

| Variable | Meaning |
|---|---|
| `ERPNEXT_URL`, `ERPNEXT_KEY`, `ERPNEXT_SECRET` | Site address and the integration user's API key and secret. |
| `ERPNEXT_COMPANY` (`Voiced Test Co`), `ERPNEXT_ABBR` (`VTC`) | Company; account names derive from the abbreviation. |
| `ERPNEXT_IC` | `1` on the India Compliance site; the `live_ic_*` tests skip themselves otherwise. |
| `ERPNEXT_ROUNDING` | `banker` (ERPNext default) or `commercial`; decides what the half-paise test expects. |
| `ERPNEXT_BANK_ACCOUNT` (`HDFC - VTC`) | Account that receives payments. |

Each test builds its own in-memory Voiced database and a fresh invoice series (`L<time><n>/001`), so reruns never collide
with documents from earlier runs. Switch the rounding method of a site with
`podman exec -i voiced-erp-backend bash -c "cd /home/frappe/frappe-bench/sites && /home/frappe/frappe-bench/env/bin/python - 127.0.0.1 rounding=commercial" < setup_site.py`
(re-run `setup.sh` or copy the printed `ERPNEXT_*` lines if you need the new key; the key is regenerated on every run).

Tear down (touches only the `voiced-erp` project; the cached images stay):

```bash
podman-compose -p voiced-erp -f compose.yml down -v
podman volume rm voiced-erp_voiced-erp-db voiced-erp_voiced-erp-sites voiced-erp_voiced-erp-logs   # only if `down -v` left them
```

Notes on rootless podman: the compose file has no healthchecks (podman's healthcheck timers need systemd), and the
backend and worker are started by `setup.sh` after the configurator has exited.

## Integration user (feeds the main README)

Create a dedicated user in ERPNext (User list, type System User) with **the roles "Accounts User" and "Sales User"**.
Then open the user, "Settings" tab, "API Access", "Generate Keys", and copy the secret once.

Why both (verified live on plain ERPNext and with India Compliance; `setup_site.py` creates exactly this user):

- "Accounts User": create and submit Sales Invoices (draft, insert-and-submit, submit-later) and Payment Entries; read
  Accounts, Items, UOMs, Cost Centers, Price Lists, Item Groups, Company, the Sales Invoice naming series and (with
  India Compliance) GST Settings; attach a private PDF to the invoice.
- "Sales User": look up and create Customers and Addresses, read Customer Groups, Territories and the tax templates.
  With "Accounts User" alone a fresh site answers HTTP 403 on Customer.

No tax template is used (Voiced always sends explicit tax rows), so the tax-template list is only a convenience.
Do not use Administrator or System Manager keys. Roles on a user are cached by Frappe: after changing them run
`bench clear-cache` or the next request may still use the old set.

## Results (what was verified live)

Versions: Frappe 15.121.3, ERPNext 15.121.6, India Compliance 15.32.0 (the `version-15` branch; commit `db73b3e` at the time of this run, so a later image build may differ), MariaDB 11.8,
Redis 8.6, API v2 naming available (Frappe 15.73 or newer).

Verified on both sites unless marked IC (India Compliance site only):

- Connection test: user, frappe/erpnext/india_compliance versions, India Compliance detection, no warnings when the
  accounts match. Option lists load (companies, addresses, accounts, UOMs, cost centers, groups, series).
- Sales Invoice push in mirror mode (API v2, `name` = Voiced number): CGST+SGST, IGST, discount (`apply_discount_on:
  Net Total`), fractional hours, repeated descriptions on code-less rows, item-code rows from a preset, remarks. The
  grand total, the tax amounts per head and the posting date equal Voiced's; `disable_rounded_total` works.
- PDF attachment: uploaded through `upload_file`, `is_private` is 1.
- Idempotency: a second push is a no-op; with the local sync row deleted, the 409 path adopts the existing document
  (no duplicate, no second PDF).
- Submit: insert then submit in a second push (v2 `method/submit`), and series mode through the v1 `run_method` route.
- Series mode: ERPNext names the document, the Voiced number is in `remarks`, and a lost sync row is recovered by the
  remarks lookup.
- Payments: `get_payment_entry` plus overrides. `bank_account` is the Account name and lands in `paid_to`;
  `paid_amount = received_amount = cash`; the reference's `allocated_amount = cash + TDS`; TDS is one `deductions` row
  `{account, cost_center, amount: +TDS}`; the invoice's outstanding falls by cash + TDS; partial payments leave the rest.
- Customer and Address shape (IC: `gstin`, `gst_category` on both; state exact name; link to the Customer).
- IC: `place_of_supply` as `29-Karnataka`; Voiced's 38 state names equal India Compliance's `gst_state` list; HSN/SAC
  must be 6 or 8 digits (GST Settings `min_hsn_digits` was 6) and is enforced at submit; the 16-character name rule;
  GST-account warnings (mismatching CGST account, company without GST accounts, a too-long next number).

Defects found and fixed (each has a mock-based test in the normal suite):

1. `load_options`: the company-address list asked for the India Compliance-only `gstin` field and failed with HTTP 417
   on a plain site. It now retries without it.
2. Code-less rows with a fractional quantity of hours/minutes failed ("Quantity cannot be a fraction ... UOM Nos"):
   ERPNext defaults the row's stock UOM to Nos without an item. Such rows now also send `stock_uom` = the row UOM.
3. Rounding: ERPNext's default Rounding Method is Banker's Rounding; Voiced rounds half-paise up. On ties (for example
   9% of 10.50) the totals differ by 1 paise. A created document whose total differs is now a `conflict`: kept as a
   draft, never submitted, no PDF, with a message naming the fix (System Settings, Rounding Method, "Commercial
   Rounding"). The existing-document conflict message carries the same hint. With Commercial Rounding every case matched.
4. A lost link to a client's address created a new address on every first push. The customer's matching address (same
   first line and PIN) is reused. (`creation` in the order-by is ambiguous with a Dynamic Link filter and gives HTTP 500.)
5. A re-adopted document got a second copy of the PDF. A file of the same name is now looked up first.
6. IC refuses `is_reverse_charge = 1` unless the tax rows are negative amounts on separate "RCM" accounts, which would
   make ERPNext's total differ from Voiced's. It is sent as 0 and the push warns.
7. IC's 16-character rule is now checked before the POST in mirror mode (a readable, local refusal that points to series
   naming); ERPNext's own message is "Transaction Name must be 16 characters or fewer to meet GST requirements".
8. A TDS-only payment (no cash) got ERPNext's bare "Paid Amount is mandatory"; it is refused locally with the reason.
9. A fractional quantity on a whole-number UOM is refused by ERPNext with a readable message; Voiced appends what to
   change (unit mapping). No local pre-check: whether "Nos" is whole-number is a site setting.

Limits and notes:

- Rounding setting cannot be read by a restricted user, so it is detected by comparing the totals after creating the
  draft, not in the connection test.
- With India Compliance, an invoice with a missing or short HSN/SAC is created as a draft and fails at submit; the
  readable ERPNext message ("HSN/SAC must exist and should be 6 or 8 digits long for the following row numbers") is
  shown.
- A mirrored item row with an item code whose stock UOM differs from the row UOM works for whole quantities
  (`conversion_factor` 1); a fractional quantity needs the item's stock UOM to allow fractions.
- One intermittent failure was seen once in the half-paise test on the India Compliance site (the push of a non-tie
  case failed; three later full runs and a single-test run passed). The cause was not captured.

Not verified:

- ERPNext v14 and v16 (the v16 images that exist on some machines were not used), other India Compliance versions.
- Windows and WebView2; the Tauri commands and UI (the tests call the Rust push/payment functions directly).
- Overseas/SEZ customers, UTGST supplier states, multi-currency, GST Settings with "Round Off GST Values" on,
  reverse charge booked on RCM accounts, e-invoice/e-waybill (India Compliance API features), a TLS or reverse-proxied
  site (only plain `http://` on a loopback address), Frappe Cloud or any site with `allow_cors` or rate limits.