tehran_taj/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.

---

⚠ Before the real release — do these three things

1. Set JWT_CUSTOMER_SECRET to its own random value. This one is a real security boundary, not a default. If it is unset, the API signs customer and sales-expert app tokens with JWT_SECRET — the same key admin tokens use — so the two token realms stop being cryptographically separate. The only thing still keeping an app token off the admin routes is the typ check in jwt.strategy.ts, and a sales expert's app token carries their AdminUser id in sub. Two independent defences become one. The API prints a loud banner at boot while it is missing. Tracked as REL-03 (Critical).
2. Remove OTP_MASTER_CODE from the environment. While it is set, any active customer can sign in with that one fixed code. Unset or empty disables it completely, and the API prints a warning banner at boot for as long as it is armed. Tracked as REL-01 (Critical) in docs/parity/ISSUES.md.
3. Configure the SMS credentials (SMS_TREZ_*). Until then no customer can receive a real login code — messages are written to the log instead of sent. Tracked as REL-02.

---

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.
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; blank means "log, do not send"

SMS_PROVIDER (trez default, or none), SMS_TREZ_URL, SMS_TREZ_USERNAME, SMS_TREZ_PASSWORD, SMS_TREZ_SENDER_LINE.

With these unset the server still starts normally and logs a warning; 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

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

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

Deploy (Docker)

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.
• D11 is cancelled — superseded by D13.