hedena_gold/DELIVERY.md

# DELIVERY — gold-banking-monorepo

Branch: **`release/delivery`** · Prepared 2026-09-23

Contains everything from `parity/security-hotfix` and `parity/phase-1-admin`.
Both merged with **no conflicts** (`phase-1-admin` already contained
`security-hotfix`, so the merge was a fast-forward). `main` was not touched.

---

## 0. Quick start — run these in order

Copy-paste, top to bottom. Nothing here needs a decision.

### Step 1 — fill in the environment

Create `.env` in the repo root. These **must** have a value:

```dotenv
# Database
POSTGRES_USER=postgres
POSTGRES_PASSWORD=<choose a strong password>
POSTGRES_DB=goldbank
DATABASE_URL=postgresql://postgres:<the same password>@db:5432/goldbank?schema=public

# Auth — two DIFFERENT random values. Generate each with:
#   node -e "console.log(require('crypto').randomBytes(48).toString('base64url'))"
JWT_SECRET=<random value 1, 32+ characters>
JWT_CUSTOMER_SECRET=<random value 2, 32+ characters, NOT the same as above>
# Every origin the panel and the two apps are opened from, comma-separated.
CORS_ORIGINS=https://adm.example.ir,https://app.example.ir,https://app2.example.ir
```

The API **refuses to start** in production until all three are right, and
prints every problem at once (REL-01, REL-03, SEC-04 —
docs/SERVER-SETUP-CHECKLIST.md). A random value:
`node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"`.

Inside Docker the database host is `db`, not `localhost`.

Everything else is optional and may be left blank. Two you may want now:

```dotenv
# Delivery only — a fixed OTP that signs in ANY active customer.
# Exactly 4 digits, or it cannot be typed into the apps. REMOVE before the
# real release (see "Before the real release" below). The production image
# refuses to start with it unless the server is marked as a test server:
OTP_MASTER_CODE=1379
TEST_SERVER_ALLOW_MASTER_CODE=yes

# SMS goes through the "relay" gateway with nothing to set (D26).
# SMS_PROVIDER=none turns sending off; the server still starts either way.
SMS_PROVIDER=
```

### Step 2 — build

```bash
pnpm install
pnpm build:release
```

**Do not skip `pnpm build:release`, and never run `docker compose build`
without it first.** The API image copies a bundle built here on the machine; it
does not build inside the image. Skipping this step produces an image from
**old code** and still reports success. This is real — it happened during this
delivery's own test run, with a bundle four days stale. (DEPLOY-03)

### Step 3 — start

```bash
docker compose up -d --build
```

Database migrations and seeding run **automatically inside the API container**
at boot. There is no manual migration step. Never run `prisma migrate reset`.

### Step 4 — check it came up

```bash
docker compose ps                 # db healthy, api up
docker compose logs api | tail -40
```

In the log you should see `Nest application successfully started`, and
`Applied migrations: …` (first run) or `No pending migrations` (later runs).

An `OTP_MASTER_CODE IS ACTIVE` banner is **expected** while that variable is
set — it is a reminder, not an error, and it disappears once you remove the
variable before the real release.

A `JWT_CUSTOMER_SECRET IS NOT SET` banner means **Step 1 was not done**. That
one is a real security problem, not a warning to ignore — go back and set it.

### Step 5 — prove the whole flow works

```bash
# Publishes the API on host port 3100 so the test can reach it.
docker compose -f docker-compose.yml -f docker-compose.delivery-test.yml up -d api
node apps/api/scripts/test-compose-e2e.cjs http://localhost:3100/api <OTP_MASTER_CODE>
```

Expect **32 passed, 0 failed**. It signs a sales expert and an ordinary
customer into the app, has both place an order, confirms both orders appear in
the admin panel, and re-checks the token boundaries — all against the real
container.

`docker-compose.delivery-test.yml` exists **only** for that check. The normal
deployment uses `docker-compose.yml` alone, where the API has no host port and
Dokploy/Traefik routes to it by domain.

---

## ⚠ Before the real release

Tonight's build is a **delivery build**. These are the things that must change
before it is a production release. The first three are blocking.

### A. Configuration — blocking

| # | Do this | Why it matters |
|---|---|---|
| **1** | **Set `JWT_CUSTOMER_SECRET` to its own random value**, different from `JWT_SECRET`. | Not a cosmetic default. Unset, the API signs customer and sales-expert **app** tokens with `JWT_SECRET` — *the same key admin tokens use* — and the two token realms stop being cryptographically separate. The only remaining barrier is the `typ` check in `jwt.strategy.ts`, and a sales expert's app token carries their **AdminUser id** in `sub`. Two independent defences collapse into one. A loud boot banner fires while it is missing. **REL-03 (Critical).** |
| **2** | **Remove `OTP_MASTER_CODE` and `TEST_SERVER_ALLOW_MASTER_CODE` from the environment.** The API now refuses to start with the code set unless that flag says this is a test server. | While set, **any active customer signs in with that one fixed code**. Unset or empty disables it completely; the API prints a banner at boot for as long as it is armed. **REL-01 (Critical).** |
| **3** | **Set real `JWT_SECRET` and `CORS_ORIGINS`.** The API refuses to start without them. | Without the key anyone could forge an admin token; without the origin list any website could call the API from a visitor's browser. |
| **4** | **Confirm SMS is going out.** The default `relay` gateway needs no credentials (D26); check `docker compose logs api` for `SMS provider: relay` and send yourself a login code. | If the gateway refuses the `host` value (inside Docker it is the container's IP), set `SMS_RELAY_HOST`. A failed send is only a log line — the server still boots (D20). **REL-02.** |

| **5** | **Accounting integration (D27), only if it will be switched on:** set `ACCOUNTING_SECRET_KEY`; count products with no image (they disappear from the app — query in ISSUES ACC-05) and photograph them first; for Zarrin, run the trial on temporary documents first (ACC-01). | The integration itself is off until an admin turns it on in «اتصال حسابداری»; nothing changes before that except the no-image rule, which applies to every product. |

After changing any of these: `docker compose up -d --build` and confirm the
`OTP_MASTER_CODE` banner is **gone** from `docker compose logs api`.

### B. Credentials to rotate — the reference leaked them

These are committed in plaintext in `henza_server` and must be assumed
compromised by anyone who has ever had repo access. None were copied into this
repository, but they are **the same live accounts**.

- **SMS panel** username + password + sender line (`app/Models/Sms.php:73-77`) — **SEC-12 (Critical)**
- PayPing bearer token, Tahesab bearer token + IP allowlist, wallet hash pepper — **SEC-06**

### C. Parity work not finished

Phase 1 stopped after the Persons section when delivery mode began (D19). The
**Phase 1 gate still stands** as the next milestone.

**Admin — not yet audited field-by-field.** Each has had only the breakage scan
(`scan-admin-b2b.cjs`, 34 endpoints, 0 broken), not a parity audit:

- **Financial documents** (اسناد) — the money path; highest priority of the three
- **Users & permissions** (کاربران و دسترسی‌ها) — includes **PERM-01**, still
  open: the database holds **178** distinct permission ids against the UI's
  **174**. Unresolved because fixing it means **deleting rows**, which needs
  your approval.
- **Reports** (گزارش‌ها)
- Also untouched: products/categories/variants, SMS templates, promotions,
  cities, branches, workshops.

**Apps — known gaps.**

| ID | What |
|---|---|
| **MON-08** | `wagePercent`, `discountPercent` and `flatRialCharge` are taken from the **client** on order creation, so a caller can set their own making charge. `rashWeightGrams` is correctly read from the variant. The reference is *worse* (it trusts client `rash_weight` too), so this is already a partial improvement — but it is still a money path trusting client input. **Fix this first in Phase 2.** |
| **STUB-05** | Admin SMS recipients are hardcoded mobile numbers scattered across six places in the reference. Port as `SMS_ADMIN_RECIPIENTS` (comma-separated), the way `PROFILE_ADMIN_MOBILES` already works — not by copying the literals. Staff changes should not need a deploy. |
| **STUB-04** | Live gold price is **pull-on-mount only** — no socket, no polling. `quotedAt` renders as a Jalali **date**, so a stale rate looks current. |
| **STUB-03** | All list filtering and paging is **client-side** over one flat `GET /catalog/products`; no server `page`/`limit`. |
| **Analytics** | The reference PWA calls `useCustomAnalytics` on every route change (`henza_pwa/src/router/index.ts:249`); neither target app has any analytics. Deliberate — it needs a provider decision from you, not a port. |

**`docs/parity/ISSUES.md`** holds the full list with evidence and file
references — currently **40+ entries**, including everything above plus the
reference bugs deliberately not ported (SEC-14, SEC-16, APP-03, and the two
D21 items). Phase 3 is the pass over that file.

---

## 1. Environment variables

Names only — no values here, and none are committed. The full annotated list is
in `.env.example`; `docker-compose.yml` passes each one through to the API
container.

### Required

| Variable | Purpose |
|---|---|
| `DATABASE_URL` | PostgreSQL connection string. Inside Docker the host is `db`. |
| `POSTGRES_USER`, `POSTGRES_PASSWORD`, `POSTGRES_DB` | Credentials for the bundled `db` service. |
| `JWT_SECRET` | Signs **admin** tokens. Without it the API falls back to a well-known development string — set it. |
| `JWT_CUSTOMER_SECRET` | Signs **customer and sales-expert app** tokens. Must be its own value — see the warning at the top of this file. Unset, it falls back to `JWT_SECRET` and the two token realms merge. |

### Optional

| Variable | Default | Purpose |
|---|---|---|
| `PORT` / `API_PORT` | `3000` | API listen port. |
| `JWT_EXPIRES_IN` | `12h` | Admin token lifetime. |
| `JWT_CUSTOMER_EXPIRES_IN` | `30d` | Customer token lifetime. |
| `UPLOAD_DIR` | `<api>/storage/uploads` | Where uploaded files are written. |
| `ADMIN_PANEL_PORT`, `USER_APP_PORT`, `USER_APP_V2_PORT` | 5180–5182 | Dev servers only. |
| `RUN_MIGRATIONS` | `true` | Set `false` to skip the boot-time migration run. |
| `RUN_SEED` | `true` | Set `false` to skip seeding. |
| `ACCOUNTING_SECRET_KEY` | *(derived from `JWT_SECRET`)* | Encrypts the accounting-software token the admin enters (D27). Set its own long random value; changing it later means re-entering the token. |
| `ACCOUNTING_WORKER` | `on` | `off` keeps this instance out of the accounting background sync. |
| `PROFILE_ADMIN_MOBILES` | *(blank)* | Comma-separated admin mobiles told when a customer completes their profile. The reference hardcoded four numbers; blank means nobody is notified and the upload still succeeds. |

### SMS — all optional

`SMS_PROVIDER`: `relay` (default), `trez`, or `none` (D26).

- **relay**: `SMS_RELAY_URL`, `SMS_RELAY_SECRET` (both have built-in
  defaults), `SMS_RELAY_HOST` (blank = the machine's first external IPv4).
  No `platform` is sent; the gateway picks the line.
- **trez**: `SMS_TREZ_URL`, `SMS_TREZ_USERNAME`, `SMS_TREZ_PASSWORD`,
  `SMS_TREZ_SENDER_LINE`.

The server **always starts**; a misconfigured provider is a warning, and a
failed or skipped SMS never blocks an operation, including customer creation.

### ⚠ `OTP_MASTER_CODE` — delivery only

A fixed OTP accepted for **any active customer**, alongside the real code.

- Read only from the environment; never hardcoded.
- Unset or empty → completely disabled.
- **Must be exactly 4 digits.** Both apps' login box is four single-character
  inputs and only submits at four, so a longer code works over the API but
  cannot be typed into either app.
- Every login through it is logged with the customer's mobile.
- The real OTP keeps working unchanged while it is armed.

---

## 2. Running it

### Development

```bash
pnpm install
pnpm dev                 # all apps via turbo
```

Ports come from the repo-root `.env` (single source of truth):
API 3000, admin-panel 5180, user-app 5181, user-app-v2 5182.

### Build

```bash
pnpm build               # all workspaces
pnpm build:release       # the production/Docker build
```

### Deploy (Docker)

```bash
pnpm build:release        # ⚠ REQUIRED FIRST — see below
docker compose up -d --build
```

> **⚠ `pnpm build:release` must be run before `docker compose build`.**
> The API image is `COPY release/ ./` — it ships a bundle built on the
> developer machine, not one built inside the image. So `docker compose build`
> will happily produce an image from a **stale** `release/app.js` and report
> success. During this delivery's compose run that bundle was four days old and
> the container was missing every route added since. Tracked as **DEPLOY-03**.

Services: `db` (Postgres 15), `api` (port 3000), `admin-panel`, `user-app`,
`user-app-v2` (each nginx on port 80). The apps expose no host ports —
Dokploy/Traefik routes to them by domain. Uploads persist in the `api_uploads`
volume; without it every previously uploaded image 404s after a redeploy.

---

## 3. How migrations run

**Automatically, inside the API container, at boot.** No manual step.

`src/prisma/bootstrap.ts` calls `runMigrations()` before Nest starts. That
runner (`src/prisma/migrate.ts`) applies the `.sql` files from
`prisma/migrations` and records each one in its own tracking table,
**`_goldbank_migrations`**, so every file runs exactly once.

It exists because **the deploy image is copy-only and ships no Prisma CLI**, so
`prisma migrate deploy` is not available there. This is why the database has two
migration ledgers — `_prisma_migrations` (written by the Prisma CLI in
development) and `_goldbank_migrations` (written by the runtime runner). Both
are intentional. `_goldbank_migrations` is declared in `schema.prisma` with
`@@ignore` so drift checks do not propose dropping it.

**Never** run `prisma migrate reset`, and never edit either table by hand.
In development, migrations are created with `prisma migrate dev`; in production
the container runner applies them.

Seeding runs once after migrations, gated on a marker row, and is skipped when
no seed script is present.

---

## 4. What was verified on this branch

All green on `release/delivery`:

| Suite | Result |
|---|---|
| `pnpm build` (5 workspaces) | ✅ all pass |
| jest (api unit) | **54/54** |
| `smoke-admin.cjs` — admin flows | **43/43** |
| `smoke-apps.cjs` — customer flows, both apps | **43/43** |
| `scan-admin-b2b.cjs` — every B2B read endpoint | **34 ok, 0 broken** |
| `smoke-admin-b2b-writes.cjs` — order + document writes | **25/25** |
| `auth-smoke.sh` — permissions/401/403 | **32/32** |
| `test-sales-expert-roundtrip.cjs` | **33/33** |
| `test-sales-expert-app-login.cjs` — expert app login (D21) | **36/36** |
| `test-complete-profile.cjs` — «تکمیل پروفایل» | **38/38** |
| `test-report.cjs` — «گزارش» | **40/40** |
| `test-compose-e2e.cjs` — **the whole flow inside Docker Compose** | **32/32** |
| `test-name-trigger.cjs` | **9/9** |
| typecheck (api, admin-panel, user-app, user-app-v2) | ✅ clean |

### Verified inside Docker Compose, not just locally

The whole delivery flow was run against the **built container**, which is what
actually ships: `test-compose-e2e.cjs` signs a **sales expert** and an
**ordinary customer** into the app with the master code, has **both place an
order**, and confirms **both orders appear in the admin panel** and open there.
It also re-checks the three token boundaries in the deployed image. **32/32.**
The three page suites were re-run against the container too — complete-profile
38/38, report 40/40, expert login 36/36.

That run found two deployment problems that no local test could have caught:

- **DEPLOY-02 (fixed):** admin login returned **500 for every user in Docker**.
  Compose passes optional variables as `${X:-}`, so an unconfigured one arrives
  as `""`, not `undefined`; the code used `?? 'default'`, which only falls back
  on `undefined`, so the empty string reached `jsonwebtoken` and it threw on
  every sign. Fixed with `src/common/env.ts`, applied to every auth, port,
  upload and SMS read, and pinned by a test that reproduces the original throw.
- **DEPLOY-03 (process):** the API image ships a **pre-built** bundle, so
  `docker compose build` can silently produce an image from stale code. See the
  warning in the deploy section above.

Flows walked end to end: admin login, customer creation, sales-expert
create/edit, product and variant create/edit, order list/detail/status change,
wholesale order placement from the admin panel, cash document creation +
confirm + un-confirm; and in **both** customer apps: OTP login with the master
code, product browsing, cart, order placement, order history.

Money paths were checked against the reference's own formulas, not just for a
200: making charge `rash × (1 + (wage − discount)/100)` reproduced exactly, and
the cash-document conversion `price / (price_per_gram / 4.331802)` moved the
customer's gold debt by the expected amount and restored it exactly on
un-confirm.

Every test script deletes only the rows it created; the write test also asserts
the customer's balances end exactly as they started.

---

## 5. Known issues — not done tonight

Nothing here blocks the delivery. Full detail in `docs/parity/ISSUES.md`.

### Missing app pages

**None.** Every page the reference PWA has now exists in both apps.


### Delivered tonight

| Feature | State |
|---|---|
| **Sales-expert app login (D21)** | ✅ Done. An expert signs into both apps with their AdminUser account and the ordinary OTP flow; the master code works for them too. They get the whole app — browsing, cart, ordering, order history — plus their own two screens. |
| **«سفارش مشتریان» (ChildOrder)** | ✅ Done in both apps. Their referred customers' orders at «تحویل مسئول فروش», searchable, infinite-scrolled. |
| **«مشتریان من» (customerChoice)** | ✅ Done in both apps. Their referred customers, searchable, with a read-only detail sheet. |
| **APP-02 — admin home slider in v2** | ✅ Fixed. v2 now prefers admin-configured slides and keeps its category-derived hero as the fallback. |
| **«تکمیل پروفایل» (complete_profile)** | ✅ Done in both apps. Three document uploads (جواز کسب، سردر مغازه، کارت ملی), then the profile is marked verified. Reached from the profile screen, and only while the documents are missing — exactly the reference's condition. |
| **«گزارش» (report + report/detail)** | ✅ Done in both apps. Two tabs («کلیات حساب» / «جزئیات حساب»), a running gold and rial balance per document, and a per-document detail sheet. Built on the **internal ledger** (owner's option الف) — no connection to the external accounting system the reference proxied. See D24. |

An expert's own order lands on their **own trading account**, with the making
charge from `AdminUser.wagePercent` and the credit limit from
`SalesExpertProfile.gramLevel` — the same two numbers the reference read off
the agent's own customer row. See D21.

**Two reference behaviours were deliberately not ported**, both money/session
risks and both recorded in D21:
1. `myChild` minted an `api_token` per listed customer so the agent could act
   **as** them — a session-hijack primitive.
2. The child-order edit drawer (`PUT /order/child/{id}`) recalculated an
   order's weights and prices from client-sent values. The card opens a
   read-only summary instead.

### Behavioural gaps

| ID | What |
|---|---|
| **APP-02** | `user-app-v2` has no `getHomeSlider`, so slides configured in the admin panel appear in **user-app only**; v2 always derives its hero from categories. Not fixed because v2's home is its own design and rewiring it during a delivery risks the page being demonstrated. |
| **PERS-02** | The reference's cities are a province → city **tree** (provinces not selectable); the target flattened this to a `province` string and a flat select on all three Persons forms. The city itself is still captured correctly. |
| **PERS-03** | The reference collects a Jalali **birth date** on the customer forms; the target has no column for it. |
| **PERS-01** | The reference makes a customer's **mobile immutable on edit**; the target allows editing it. Owner ruled this NOT ported — the target keeps its current behaviour. |
| **PERF-01** | `listReagents()` runs one aggregate per row (N+1) for the per-agent sales total. Harmless at the current agent count. |

### Parity work not reached

Phase 1 was not completed: the field-by-field audit stopped after the Persons
section, and products/categories/variants, financial documents, users and
permissions, SMS templates, promotions, cities, branches, workshops and reports
have had only the breakage scan above, not a full parity audit. The
**Phase 1 gate was lifted for tonight only** (D19) and still stands as the next
milestone.

`PERM-01` (the database holds 178 distinct permission ids against the UI's 174)
is still awaiting a decision, because resolving it means deleting rows.

---

## 6. Decisions that shaped this build

Recorded in `docs/parity/DECISIONS.md`:

- **D13** — the retail storefront (`single*`, wallet, comments, `customer.php`,
  `site.php`) is **preserved but out of scope**. Nothing there was changed.
- **D19** — delivery mode: implement the main gaps, do not stop to ask, choose
  the lowest-risk option, change nothing protected.
- **D20** — SMS can never block a boot or an operation; `OTP_MASTER_CODE` for
  the delivery.
- **D26** — SMS goes through the owner's `relay` gateway by default; Trez is
  kept as a selectable driver.
- **D11 is cancelled** — superseded by D13.