Files

T

s.esmaeiliandClaude Opus 5 ddcc8c5649 feat(apps): a sales expert can work inside their customer's account (D29)

Reported missing by the owner: in the reference an expert could open any
of their referred customers and use the app AS them — browse, see
balance and debt, place orders — «یکجورایی انگار با اکانت اون ها لاگین
کرده». D21 had deliberately left it out as a session-hijack primitive.
The owner asked for the capability back with the implementation left to
judgement, so the scope is the reference's and the mechanism is not.

Scope: everything, as the reference had it. Its axios interceptor
swapped the bearer token, so every request went as the customer,
document upload included. No route is closed in act-as mode.

Mechanism: the reference minted and handed over the customer's own
permanent api_token. Here the expert keeps their own token and sends
X-Act-As-Customer, resolved in one place — CustomerJwtStrategy
.validateExpert. That single point is why all 17 customer routes work
unchanged: validate() already returns a principal whose `id` is a
Customer id and every customer route reads it. It also fixes four real
defects of the original:

- ownership is re-checked on EVERY request, with referredByAgentId in
the same where clause as the id, so another expert's customer and a
non-existent id both answer 403, and a customer moved to another
expert loses access at once rather than at token expiry;
- nothing durable is handed out — the reference's token sat in
localStorage with no expiry and kept working after the expert left;
- adminUserId survives, so an order placed this way is attributable;
in the reference the request was literally the customer's;
- 403 rather than 401, so the app clears the act-as state instead of
logging a perfectly valid session out.

Performance: one findFirst on the primary key, only when the header is
present, and it replaces the trading-account lookup rather than adding
to it.

Three things the reference never needed, because it swapped the whole
session. queryCache's `me:` keys, favouritesStore and wageQuoteStore all
dropped their data on a TOKEN change, which act-as does not cause — so
an expert would have seen their own profile, orders, balance, ledger and
favourites inside the customer's account. The wage-quote one is the
money case: making charge is per customer, so the figure on screen would
not have been the one the order was priced at. And uploadDocument builds
its own headers, so an expert's upload would have been filed against
their own account, silently.

Added with no reference equivalent: a permanent «در حال مشاهده به‌عنوان
…» bar. There, impersonation was invisible once the token had been
swapped, and placing an order on the wrong customer's gold debt was one
tap away. It is also the exit — the reference's only way out was a
logout that ended the expert's own session too. The cart is cleared in
both directions.

CustomerJwtStrategy had no test coverage at all and is now where this
feature's whole authorisation boundary lives: act-as-customer.spec.ts
covers 11 cases, including the header being ignored on a customer token,
the no-header path asserting the extra query does not run, and a revoked
session short-circuiting before the header is read.

api: 308/308 tests, 28 suites; both apps vue-tsc clean.

اپ: کارشناس فروش می‌تواند وارد حساب مشتریان خود شود، وضعیتشان را ببیند و از طرفشان سفارش ثبت کند.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

2026-10-12 11:48:59 +03:30

22 KiB

Raw Blame History

PROGRESS — Reference Parity Project

Read this file FIRST at the start of every session and after every /compact. Rules live in CLAUDE.md (workspace root). Method lives in the reference-parity-audit skill. Neither is in this repository — see docs/GO-LIVE-PLAN.md §0.

New workstreams (2026-10-04) — plans only, nothing executed

Plan	What	Waiting on
`docs/GO-LIVE-PLAN.md`	Stack upgrade, release isolation, data migration and cutover from the live henza system. §0 explains how to continue on another machine.	Owner go-ahead per step
`docs/PWA-PORT-PLAN.md`	Third user app `apps/user-app-classic`: a pixel-exact port of `henza_pwa@b171fff` onto the new API.	Owner rulings on its tensions 1–5 and Q1–Q9
`docs/ACCOUNTING-INTEGRATION-PLAN.md`	Tahesab / Zarrin integration, switchable in the admin panel (D27). Implemented 2026-10-05, off until switched on; progress in its §10.	Zarrin trial on a real install (ACC-01); ACC-03 ruling
`docs/DATA-MIGRATION-MAP.md`	Column-by-column map of the live henza MySQL schema (`oapi-struncture.sql`, 80 tables) onto Prisma, checked against real row counts via the read-only `docs/migration-precheck.sql`. Branch `migration/legacy-data`. 2026-10-07:* additive prep migration applied (nullable `nationalCode`, `birthDate`, rejection trail + `REJECTED`, `CustomerFavorite`), bcrypt guard, REJECTED consumer audit. ⚠ On this machine a file in `prisma/migrations` is applied by the watch-mode dev server on the next `src/` edit — see its §10.5.5.	`precheck-2` (where the ledger amount lives) and `precheck-3` output; two `verify()` rulings

The "Current state" table below is the parity project's and was last updated 2026-09-22.

Current state

Field	Value
Phase	Phase 2 — apps parity — items #1 and #2 done (Phase 1 closed, `83e5d28`)
Branch	`main` (the parity branches were merged; see git log 2026-10-08..10-12)
Status	Phase 1: all in-scope sections closed (§2 §4 §5 §6 §7 §8 §9 ✅ · §3 ⏸️ by D16). Phase 2: #1 MON-08 ✅, #2 D3 ✅, app-login error reporting (AUTH-01/02/03, DOC-01), and «ورود به حساب مشتری» restored (EXP-01/02/03, D29 — supersedes D21's omission). 308/308 jest tests; both apps `vue-tsc` clean.
Next step	Build `02-APPS-MATRIX.md` — the field-by-field apps matrix (D12), which Phase 2 has been running without. Then the remaining app rows it turns up.
Blocked on	nothing. Awaiting an owner ruling when convenient: PERM-02. Deferred by the owner: ANLY-01 (route analytics, lowest priority).
Last updated	2026-10-12

Phase 1 close-out (2026-10-12)

The two items that were still genuinely unfinished:

Item	Result
§2 — the D1 rid matrix (stood as (pending) all phase)	✅ filled: 163 rid-guarded routes, 68 distinct rids, 176 tree keys, mapped per module. 66/68 grantable from the UI; the 2 that are not are PERM-02.
Order-placement SMS	✅ SMS-03 — the matrix had logged one missing message; in fact all four were missing and `OrdersService` had no `SmsService`. Fixed with 6 tests.

What is NOT done, by decision rather than by omission:

	Why
§3 — product price display (PRICE-01)	⏸️ retail storefront, out of scope by D13/D16. `variant-price.ts` + 11 tests kept but unused.
Firebase push beside each SMS (PUSH-01)	⏸️ deferred to the PWA port.
«سفارش ویرایش شد» admin SMS	«عمداً تکرار نشد» (D4) — no target path edits a placed order.
PERM-02 (2 ungrantable rids)	additive, changes the permission vocabulary → awaits the owner, as PERM-01 did.
`02-APPS-MATRIX.md`	Phase 2's file; not created yet.

⚠️ Not verified in a browser. Every ✅ above rests on reading both sides, unit tests and smoke scripts. The prior port's note still stands: no admin view has been visually checked in a browser. A full click-through is the honest remaining risk on Phase 1.

Security hotfix — final result

Route	Was	Now
`GET accounting/customers/:id/balance`	public	admin, rid `wallet.list`
`POST accounting/customers/:id/reconcile`	public write	admin, rid `wallet.charge`
`POST accounting/repayments/gold`	public write	admin, rid `document.create`
`POST accounting/repayments/rial`	public write	admin, rid `document.create`
`POST accounting/entries/:id/confirm`	public write	admin, rid `document.list.confirm`
`PATCH orders/:id/status`	public write	admin, rid `order.list.sts.submit`
`GET customers`	every customer, 18 fields	route deleted
`GET customers/:id`	public	route deleted → `GET customer/me` (token)
`GET customers/:id/orders`	public	route deleted → `GET customer/me/orders` (token)
`GET customers/:id/ledger-entries`	public	route deleted → `GET customer/me/ledger-entries` (token)
—	—	new `POST customer/auth/request-otp` · `verify-otp`

Still public by design: catalog/products, pricing/latest, home/slider, uploads/:filename (ruling T2), and POST /orders + GET /orders/:id — the last two are logged as SEC-02/B1-B2 and want a customer-token pass of their own.

Tests

apps/api/scripts/auth-smoke.sh (live server): 46 passed, 0 failed. Run it with API=http://localhost:3000/api CODE_LOG=/path/to/api.log.
pnpm test in apps/api (jest, newly installed): 7 passed.
Typecheck: api ✅ · user-app ✅ · user-app-v2 ✅. Both apps build ✅.

⚠️ Correction worth remembering

Stage 1 reported the customer-book leak as "mitigated" after narrowing the GET /customers field list. That was wrong: the response still returned every customer id, and the three /customers/:id* routes were still public, so the full data was still two requests away. The user caught it. Stage 2 deleted the whole id-bearing surface instead. Narrowing a response is not closing a leak while the id and the id-addressed routes remain.

⚠️ Read `DECISIONS.md` before doing anything

All user rulings live there (D0–D17). Highlights that change how work is done:

D12 — the matrix is FIELD-BY-FIELD, not page-by-page, and a 4-step round-trip test per entity is mandatory. Both rules were added to the reference-parity-audit skill (Step C rule C0, Step E rule E0).
D0 — split fullName into firstName/lastName via an additive migration; show the migration and get approval before running it.
D4 — never port broken behaviour, but match calculations/rounding/messages exactly; annotate each non-replication «عمداً تکرار نشد — ISSUE #n».
D2 — target-only features get status ➕ and are left alone.
D13 — the retail storefront (48 customer.php + 30 site.php + 31 storefront-management admin routes = 109 of the reference's 412 endpoints) is preserved but out of scope: status ⏸️, no gap row, no work row, nothing deleted or disabled. 288 endpoints stay in scope (218 admin + 70 B2B app). Note: the reference total is 412, not 369 — admin.php was undercounted in Phase 0; corrected in 00-INVENTORY.md §2.1. Ask before changing shared surfaces (product, variant, price, order, customer).

Phase checklist

P0.1 — All 3 reference folders readable (henza_server, henza_admin, henza_pwa)
P0.2 — Branch parity/phase-0 + docs/parity/ created
P0.3 — Inventory all 7 projects → _inv-*.md (8111 lines total) → consolidated in 00-INVENTORY.md
P0.4 — Mapping tables, missing list, extra list (00-INVENTORY.md §2–4)
P0.5 — Draft PROTECTED.md
P0.6 — GATE passed — PROTECTED.md confirmed, D0–D12 recorded
P0.7 — Urgent traces delivered: percent, @Public list, login leak
P0.8 — Skill updated with rules C0 (field-by-field) and E0 (round-trip test)
P1.0 — approved and DONE: 5 ledger routes protected, percent column added, D0 migration applied, SMS provider implemented
Phase 1 — Admin parity (01-ADMIN-MATRIX.md) — all in-scope sections closed 2026-10-12
GATE ← HERE — asked 2026-10-12: "Admin parity is complete and tested. Shall we move on to the apps (user-app & user-app-v2)?"
Phase 2 — Apps parity (02-APPS-MATRIX.md, both user apps)
Phase 3 — Work through ISSUES.md (only when user asks)

Answered — see `DECISIONS.md` for the full text

#	Ruling
D0	Split `fullName` → `firstName`/`lastName`, additive migration, backfill, sync, report multi-token rows. Approval needed before running.
D1	Target's stricter auth stands. Build the "reference operation ↔ rid" matrix; explain 172 vs 174.
D2	Audit only what the reference has. Target-only features → ➕, untouched.
D3	Build the 5 missing screens in Phase 2, both apps, plus analytics, `isLoaded`/`sts_verify_step_two` guards, guest toast+home, and v2's cart ceiling.
D4	Don't port breakage; do match calculations/rounding/messages. Unit-test the price formula.
D5	Leave the stray folder; delete last, own commit.
D6	OTP must verify — parity gap, fix it (plus expiry + attempt limits, which exceed the reference).
D7	`@Public` ledger routes: list delivered, awaiting approval to protect.
D8	Login leak: target, full customer book incl. national IDs and debts.
D9	`percent`: trace delivered — the target's implementation is wrong.
D10	Sales expert: keep `AdminUser`; investigate the 5 missing fields; propose `SalesExpertProfile`.
D11	`singleCustomer.vue` → diff-send.
D12	Field-by-field matrix + mandatory round-trip test. Added to the skill.
D13	Retail storefront (wallet, cashback, `ConfigStatic['percent']`) preserved but OUT OF SCOPE. Nothing deleted or disabled; no parity work; matrices list it ⏸️ with no gap/work row; ask before touching shared surfaces.
D14	`migrate dev` in development, `migrate deploy` in production and nowhere else. Never `migrate reset`; never edit `_prisma_migrations`. On drift + a reset offer: stop and report.
D15	`_goldbank_migrations` is KEPT — it is the tracking table of the app's own migration runner (`src/prisma/migrate.ts`), needed because the Docker image has no Prisma CLI. Declared `@@ignore`d; drift is zero. Persian test input must come from a FILE, never a shell argument.
D16	PRICE-01 STOPPED — price display is retail-storefront (⏸️ D13); the B2B app works in making charge only. `variant-price.ts` + tests kept but unused. Making charge stays in scope. New work order: Persons → Products/variants/order-detail → the rest of the admin → gate → apps. Per section: implement gaps, then field-by-field test, and show a gap summary BEFORE fixing.
D17	SalesExpertProfile (cityId, gramLevel, phone, nationalCode) + firstName/lastName on all AdminUsers. `reagent_id` deliberately NOT ported — in the reference it was a side effect of the shared customers form and filling it removed the expert from the selectable-agent list (queryReagent:420); the referrer logic lives on `Customer.referredByAgentId`.
D29	«ورود به حساب مشتری» restored (2026-10-12) — a sales expert can work inside any of their referred customers' accounts with the reference's full scope (every customer route, documents included). Mechanism deliberately not the reference's: no customer token is minted; `X-Act-As-Customer` rides the expert's own token and is authorised in `CustomerJwtStrategy.validateExpert`, re-checking `referredByAgentId` on every request. Supersedes D21's "deliberately not ported".
D28	App login step 1 must say what went wrong (2026-10-12): an unregistered number → 404, a failed SMS send → 503, an unusable sales-expert account → 403, each with its own Persian message. Restores the reference's `firstOrFail()`. Trades away part of the anti-enumeration protection, deliberately — the per-mobile/per-IP send throttles still bound it and `verifyOtp` stays single-message. See D28 for the full reasoning and why D20 is not violated.

Open — awaiting user approval

Nothing. The 5 ledger routes, the percent column and the D0 migration are all done and verified (see CHANGELOG 2026-09-22).

Key context (survives context loss)

Domain correction: the reference is a gold-jewellery B2B/B2C e-commerce system, not a gold bank. No buy/sell order book, no spread, no deposit/withdraw, no P2P transfer, no KYC levels, no daily limits (only gram_level), no payment callback route, no cron, no websockets. See 00-INVENTORY.md §0.
The gold price formula (Phase 1 row #1) — henza_server/app/Models/ProductVariant.php:183-190: +extra% → +7% margin → +9% VAT on the non-metal portion only → ×grams → floor(/1000)*1000. Three superseded commented-out variants above it apply VAT to the whole price — do not port those.
A large prior port already happened — see docs/ADMIN-PORT-PLAN.md and docs/CHANGELOG-PORT-HISTORY.md (80 views, 25 Nest modules, 29 Prisma models, 154 admin routes, 144/144 rids). Prior port notes no view was ever visually verified in a browser.
Stack changed across the port: Laravel→NestJS/Prisma, Vue2/Vuesax→Vue3/antd. Port behaviour, not code style.
Reference scale is inflated: 541 admin .vue files but only ~69 reachable (rest are Vuexy template demos); 9 reference router files are dead (not imported); ~28 legacy Django-era DB tables have no migrations.
v1 ⇄ v2 logic gaps (5, all v2 behind v1) are parity work, not design: ISSUES.md MON-01, V2-01..05.

Inventory files (Phase 0 working files)

File	Scope	Lines
`_inv-ref-server.md`	henza_server	1313
`_inv-tgt-api.md`	apps/api	1179
`_inv-ref-admin.md`	henza_admin	1705
`_inv-tgt-admin.md`	apps/admin-panel	1261
`_inv-ref-pwa.md`	henza_pwa	1178
`_inv-tgt-userapp.md`	apps/user-app	612
`_inv-tgt-userappv2.md`	apps/user-app-v2	700

Consolidated into 00-INVENTORY.md. Issues found: ISSUES.md (26 entries).

Standing rules added 2026-09-22

Migrations run only via the standard Prisma workflow (migrate dev in development). prisma db execute is not used for schema changes.
Every data deletion is logged in CHANGELOG.md — including throwaway rows created during a session.
D13 — the retail storefront is preserved but out of scope; see DECISIONS.md §D13 and PROTECTED.md §H.

Phase 2 — item #1 (MON-08) — ✅ DONE 2026-10-12

All four steps of the ruling are in place; see ISSUES.md §"Phase 2 — item #1". Steps 1, 3 and 4 had landed with the wage-formula work; step 2 — logging the client figures that get discarded — was added 2026-10-12, along with the comparison test the ruling asked for («تست مقایسه‌ای»), which step 3 had not actually had: the suite only covered a tampered request, not an honest one. orders.service.spec.ts is now 16 tests.

An operator ordering from the panel still keeps the numbers they typed — only an app order is re-priced by the server.

Phase 2 — item #2 (D3) — ✅ DONE 2026-10-12

D3 was ten items, not one. Seven were already built — all five screens (/report, /report/detail, /ChildOrder, /customerChoice, /complete_profile) exist in both apps, as do the sts_verify_step_two guard and v2's cart stock ceiling. Checked in the code, not read off a checkmark.

Outstanding item	Result
guest toast «ابتدا وارد شوید»	✅ both apps (APP-03). The destination stays the target's `/login?redirect=…`, better than legacy's `home` — owner's call, logged as «عمداً تکرار نشد — D3/الف».
`isLoaded` router guard	⏹️ not ported (APP-04) — guards a bootstrap request the target does not have; would only bounce a shared product link to `home` (D4). Owner agreed.
route analytics	⏸️ deferred, lowest priority (ANLY-01) — design parked in `docs/PHASE2-D3-PLAN.md`, with the two reference defects not to copy and the two retention/privacy questions still open.

⚠️ Phase 2 is running without its matrix. 02-APPS-MATRIX.md still does not exist, so "what else do the apps miss" rests on the earlier survey rather than a field-by-field comparison (D12). That is the next item.

The original requirement, for the record:

Before anything else in Phase 2: the server must derive wagePercent, discountPercent and flatRialCharge from the DB and ignore the client's values, because henza_pwa computes them rather than asking the user (cart.vue:170-179, Mixins/product/index.ts:69-75). A comparison test must show the total is unchanged for an ordinary customer. Depends on makingChargeOffsetPercent existing. Full reasoning: DECISIONS.md §"Report — MON-08".

Done 2026-09-22 (was: waiting on the owner)

#	Item	What is ready
1	Run the D0 and percent migrations	✅ Applied with `migrate deploy` (`migrate dev` is interactive-only and this shell is not a TTY). Drift checked read-only first — the only difference is the pre-existing `_goldbank_migrations` table, which was NOT dropped (DEAD-07). Service layer, all three forms, trigger test and the full round-trip test done.
2	Implement the SMS provider (Trez)	✅ `SmsModule`/`SmsService` live, OTP wired, text byte-identical, boot check fails in production on a missing key, `.env.example` has names only. The 12 B2B templates land per flow in their own phase. SEC-12: the owner is rotating the credentials and setting them in `.env`.

⚠️ Standing rules added 2026-09-22 (D14)

migrate dev in development, migrate deploy in production and nowhere else. Never migrate reset, never edit _prisma_migrations by hand. If drift is reported and a reset is offered: stop and report, do not accept. prisma db execute is no longer used for schema changes.
Every data deletion is logged in CHANGELOG.md, including throwaway rows a session creates itself.

⚠️ `customer_sync_full_name` is a DATABASE TRIGGER

Prisma knows nothing about it, so writing Customer can store something different from what you wrote:

Write	Result
the parts only	`fullName` is rebuilt
`fullName` only	the parts are re-derived (first token / the rest)
both at once	THE PARTS WIN; the submitted `fullName` is discarded

Re-read after writing if you need the stored value. See DECISIONS.md §D14 and the doc comment on the Customer model in schema.prisma.

⚠️ Two migration ledgers, on purpose (D15)

Ledger	Written by	Used
`_prisma_migrations`	the Prisma CLI	development
`_goldbank_migrations`	`apps/api/src/prisma/migrate.ts`	the deployed container, at boot

The Docker deploy image is copy-only and ships no Prisma CLI, so the app applies migrations itself at startup. Every new migration must be safe under both paths — keep the SQL idempotent (IF NOT EXISTS, CREATE OR REPLACE).

⚠️ Persian test input comes from a FILE (D15)

The Windows shell replaces Persian characters with ?. A test that passes its data inline can "pass" while storing ????. Write fixtures in the test file or a UTF-8 JSON file and send bodies with curl --data-binary @file. Console output of Persian is never evidence — compare values in Node.

⚠️ Phase 1 work order (D16 — supersedes the earlier ordering)

(a) Persons (اشخاص) ← current

The 5 missing sales-expert fields (ncode, phone, city_id, gram_level, reagent_id): report first where the reference uses each for type=1, then add accordingly (proposal: SalesExpertProfile related to AdminUser, D10). Unused fields are listed for the owner, not added speculatively.
singleCustomer → diff-send (D11).
Field-by-field audit of every Persons form and grid (retail, wholesale, sales expert) per D12, each with its round-trip test.

(b) Products, categories, variants, admin order detail — deep field-by-field. The variant image picker is PROTECTED (§B) — additive only. Making charge on every variant and order line must display and persist exactly as the reference.

(c) The rest, in order: financial documents → users & permissions → admin SMS templates → promotions / notifications / cities / branches / workshops → reports.

(d) Full admin test pass → Phase 1 report → gate question → STOP and wait.

Method per section (D16)

Implement the gaps first, then field-by-field test that same section. Show the owner a short gap summary BEFORE fixing each section.

✅ SEC-02 — verified complete (re-tested 2026-09-22)

Check	Result
`POST /orders` without a token	401 (was `@Public`)
Body `customerId: "customer-2"` with a `customer-dev-test` token	order landed on customer-dev-test; spoof blocked and warn-logged
`GET /orders/:id` own order	200
`GET /orders/:id` another customer's order	404, not 403 — ids stay unenumerable
`GET /orders/:id` unknown id	404, identical response
`GET /orders/admin/:id` with a customer token	401

9/9 passed live, plus 32/32 in auth-smoke.sh. The server derives the customer from the token only (orders.controller.ts:26-29, orders.service.ts createOrder(dto, customerId)).

Client-supplied wagePercent / discountPercent / flatRialCharge remain — that is MON-08, scheduled as Phase 2 item #1 per the owner's ruling.

22 KiB Raw Blame History Unescape Escape