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>
This commit is contained in:
s.esmaeili
co-authored by
Claude Opus 5
Claude Opus 5
parent
c518f9995b
commit
ddcc8c5649
@@ -991,3 +991,97 @@ apply in production. Full api suite **295/295, 27 suites**; both apps `vue-tsc`
|
||||
clean.
|
||||
|
||||
_No data was deleted in this entry._
|
||||
|
||||
---
|
||||
|
||||
## 2026-10-12 — Phase 2 — «ورود به حساب مشتری» restored (EXP-01/02/03, D29)
|
||||
|
||||
- **What:** A sales expert can again open one of their referred customers'
|
||||
accounts and use the whole app as them — browse, see balance, debt and
|
||||
reports, and place orders that land on the customer's account. Entered from
|
||||
the customer's card on «لیست مشتریان»; a permanent bar names whose account it
|
||||
is and exits.
|
||||
- **Why:** owner report — the reference had it («یکجورایی انگار با اکانت اون ها
|
||||
لاگین کرده … و این خیلی کاربردی بود ولی الان نیست») and D21 had deliberately
|
||||
left it out as a session-hijack primitive. The owner asked for the capability
|
||||
back, with the implementation left to judgement: «همان قابلیت هارو میخوام حالا
|
||||
هرجور که فکر میکنی از لحاظ امنیت و پرفورمنس بهتره».
|
||||
- **Reference:** `customerChoice.vue:155-167` → `myDataStore.ts:159-169` →
|
||||
`tokenManage.ts:8` → `plugins/axios.ts:18`; server
|
||||
`ApiMobileController.php:197-201`.
|
||||
- **Target:** `customer-auth/app-principal.ts`, `customer-jwt.strategy.ts`,
|
||||
`orders.controller.ts`, `orders.service.ts`, `sales-expert-app.controller.ts`;
|
||||
both apps' `stores/session.ts`, `api/client.ts`, `stores/queryCache.ts`,
|
||||
`stores/favoritesStore.ts`, `stores/wageQuoteStore.ts`,
|
||||
`views/expert/CustomerChoiceView.vue`, `components/expert/ActingAsBar.vue`,
|
||||
`App.vue`.
|
||||
- **Matrix row:** EXP-01, EXP-02, EXP-03 in `ISSUES.md`; D29 in `DECISIONS.md`;
|
||||
D21's "deliberately not ported" paragraph marked superseded.
|
||||
- **Commit:** see below.
|
||||
|
||||
**Scope is the reference's, in full.** Its axios interceptor swapped the bearer
|
||||
token, so *every* request went as the customer — including document upload. No
|
||||
route is closed in act-as mode. (The plan had proposed closing documents and
|
||||
logout; the owner asked for the reference's behaviour, so that was dropped.)
|
||||
|
||||
**The mechanism is not the reference's.** It minted a permanent `api_token` per
|
||||
customer and handed it over. Instead 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. Four consequences, each fixing a real defect of the original:
|
||||
|
||||
1. **Ownership is re-checked on every request**, with `referredByAgentId` in the
|
||||
same `where` as the id — so another expert's customer and a non-existent id
|
||||
give the same answer (403), and a customer moved to another expert loses
|
||||
access at once rather than at token expiry.
|
||||
2. **Nothing durable is handed out.** The reference's token sat in
|
||||
`localStorage` with no expiry and kept working after the expert left. Here
|
||||
the target is in `sessionStorage` and is only a hint; the authority is the
|
||||
expert's own token plus the per-request check.
|
||||
3. **The real actor survives.** `adminUserId` is kept, so an order placed this
|
||||
way is logged as `sales expert <id> acting as them`. In the reference the
|
||||
request was literally the customer's and nothing could be attributed
|
||||
afterwards.
|
||||
4. **403, not 401**, for a customer that is not theirs: the expert's own session
|
||||
is valid, so the app clears the act-as state instead of logging them out.
|
||||
|
||||
**Performance.** One `findFirst` on the primary key, and only when the header is
|
||||
present — it *replaces* the `tradingCustomer` lookup rather than adding to it, so
|
||||
the query count is unchanged in act-as mode and untouched for everyone else.
|
||||
|
||||
**Three things the reference did not need, because it swapped the whole session.**
|
||||
Found by reading the stores rather than assuming:
|
||||
|
||||
- `queryCache` (`me:` keys), `favoritesStore` and `wageQuoteStore` each dropped
|
||||
their data on a **token** change. Act-as changes whose data they hold without
|
||||
changing the token, so without this 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. Each
|
||||
watcher's own comment already stated the rule it was about to break.
|
||||
- `uploadDocument` bypasses `request()` and builds its own headers, so an
|
||||
expert's upload would have been filed against their own account, silently.
|
||||
`grep Authorization` on the client returning two call sites is what caught it.
|
||||
- The cart is in `localStorage`, so it is cleared in **both** directions —
|
||||
otherwise the expert's own basket follows them in and ends up on the
|
||||
customer's order.
|
||||
|
||||
**Added on purpose, with no reference equivalent:** the permanent «در حال مشاهده
|
||||
به‌عنوان …» bar. There, impersonation was invisible once the token had been
|
||||
swapped — the only way to tell whose account you were in was to notice the data
|
||||
looked wrong, 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 the logout button,
|
||||
which ended the expert's own session too.
|
||||
|
||||
**Verification.** `CustomerJwtStrategy` had **no test coverage at all** before
|
||||
this, and it is now where the whole authorisation boundary of the feature lives,
|
||||
so `act-as-customer.spec.ts` covers 11 cases: the happy path, the scoped query
|
||||
itself, another expert's customer, an inactive customer, a deactivated expert, a
|
||||
demoted expert, the header being **ignored** on a customer token, the no-header
|
||||
fallback (asserting the extra query does not run), blank and duplicated headers,
|
||||
and a revoked session short-circuiting before the header is read. Plus 2 cases on
|
||||
the order audit trail. Full api suite **308/308, 28 suites**; both apps
|
||||
`vue-tsc` clean.
|
||||
|
||||
_No data was deleted in this entry._
|
||||
|
||||
@@ -1249,6 +1249,12 @@ customer. That is a session-hijack primitive; every session here derives from
|
||||
the caller's own token. Not ported, and recorded here rather than silently
|
||||
dropped.
|
||||
|
||||
> ⚠️ **SUPERSEDED BY D29 (2026-10-12).** The owner asked for the capability
|
||||
> back, so acting as one's own customer now exists — with the reference's full
|
||||
> scope, but not its mechanism: no token is minted, the expert keeps their own,
|
||||
> and ownership is re-checked on every request. The paragraph above still
|
||||
> describes correctly what is **not** done (minting customer tokens). See D29.
|
||||
|
||||
## Ambiguity resolved the low-risk way
|
||||
|
||||
If one mobile ever belonged to both an expert and a customer, the owner ruled
|
||||
@@ -1451,3 +1457,59 @@ status that posts the temporary document (پیش‌فاکتور) is an admin-cho
|
||||
عملیات** است، پس سکوت از چیزی محافظت نمی‌کند.
|
||||
|
||||
ثبت شده در `ISSUES.md` به‌عنوان AUTH-01/02/03 و DOC-01.
|
||||
|
||||
---
|
||||
|
||||
## D29 — «ورود به حساب مشتری» برای کارشناس فروش (۲۰۲۶/۱۰/۱۲)
|
||||
|
||||
**خواسته مالک:** «کارشناس فروش میتونه از طریق اپ خودش وارد صفحه مشتری هاش بشه و
|
||||
از جانب اون ها ثبت سفارش کنه و وضعیت اون هارو ببینه و یکجورایی انگار با اکانت
|
||||
اون ها لاگین کرده همه چیز رو از دید اون مشتریش میدید و این خیلی کاربردی بود ولی
|
||||
الان نیست» و سپس: «همان قابلیت هارو میخوام حالا هرجور که فکر میکنی از لحاظ
|
||||
امنیت و پرفورمنس بهتره».
|
||||
|
||||
این **D21 را اصلاح می‌کند**: آنجا `changeUser` «عمداً پورت نشد» و به‌عنوان
|
||||
session-hijack رد شد. مالک قابلیت را خواست، پس بازگردانده شد — با همان دامنه
|
||||
کامل مرجع، ولی با سازوکار دیگر.
|
||||
|
||||
### دامنه: کامل، مثل مرجع
|
||||
|
||||
مرجع توکن را در interceptor سراسری axios عوض می‌کرد
|
||||
(`henza_pwa/plugins/axios.ts:18` ← `getUserToken()`)، پس **هر** درخواست از طرف
|
||||
مشتری می‌رفت: دیدن، ثبت سفارش، علاقه‌مندی، و آپلود مدارک. همان دامنه حفظ شد —
|
||||
هیچ مسیری در حالت act-as بسته نشد.
|
||||
|
||||
### سازوکار: هدر، نه توکن
|
||||
|
||||
| | مرجع | اینجا |
|
||||
|---|---|---|
|
||||
| چطور | توکن دائمی مشتری (`api_token`) به کارشناس داده می‌شد (`ApiMobileController.php:197-201`) | کارشناس توکن **خودش** را می‌فرستد + هدر `X-Act-As-Customer` |
|
||||
| کجا اعمال می‌شود | interceptor کلاینت | `CustomerJwtStrategy.validateExpert` — تنها نقطه |
|
||||
| بررسی مالکیت | یک‌بار، در لحظه گرفتن توکن | **هر درخواست**، با `referredByAgentId` در همان کوئری |
|
||||
| ماندگاری | `localStorage`، بی‌انقضا | `sessionStorage`؛ بستن تب = پایان |
|
||||
| ردّ حسابرسی | هیچ — درخواست عیناً مشتری بود | `adminUserId` حفظ می‌شود؛ سفارش لاگ می‌شود |
|
||||
| بعد از قطع همکاری کارشناس | توکن مشتری همچنان کار می‌کرد | ۴۰۱ فوری (نقش و `isActive` هر بار خوانده می‌شود) |
|
||||
|
||||
**چرا این نقطه:** `validate()` همیشه یک principal می‌سازد که `id` آن یک Customer
|
||||
id است و **هر ۱۷ مسیر مشتری** از آن می‌خوانند. پس تغییر در یک نقطه، همه مسیرها
|
||||
را از دید مشتری می‌کند — بدون تغییر در هیچ route.
|
||||
|
||||
**پرفورمنس:** یک `findFirst` روی کلید اصلی، **فقط** وقتی هدر هست؛ و جایگزین
|
||||
کوئریِ `tradingCustomer` می‌شود نه اضافه بر آن. مشتری عادی و کارشناس در حالت
|
||||
معمولی صفر هزینه اضافه.
|
||||
|
||||
**۴۰۳ و نه ۴۰۱** برای مشتریِ غیرمجاز: نشست خود کارشناس سالم است، پس اپ وضعیت
|
||||
act-as را پاک می‌کند و او را از سیستم بیرون نمی‌اندازد.
|
||||
|
||||
### چیزهایی که مرجع نداشت و اضافه شد
|
||||
|
||||
۱. **نوار همیشگی «در حال مشاهده به‌عنوان …» + دکمه خروج.** در مرجع، جابجایی
|
||||
نامرئی بود: راه فهمیدن اینکه در حساب کیستی، فقط دیدن داده‌های عجیب بود، و
|
||||
ثبت سفارش روی حساب اشتباه یک کلیک فاصله داشت. تنها راه خروج هم logout بود که
|
||||
نشست خود کارشناس را هم می‌بست (`Dashboard.vue:781-789`).
|
||||
۲. **پاک‌سازی حالت در جابجایی** (هر دو جهت): سبد، `queryCache` کلیدهای `me:`،
|
||||
علاقه‌مندی‌ها، و **اجرت‌های کش‌شده**. این آخری مالی است: اجرت هر مشتری
|
||||
متفاوت است، و بدون پاک‌سازی عددِ روی صفحه با عددِ ثبت سفارش یکی نمی‌بود.
|
||||
(در مرجع این مسئله وجود نداشت چون کل نشست با توکن عوض می‌شد.)
|
||||
|
||||
ثبت شده در `ISSUES.md` به‌عنوان EXP-01.
|
||||
|
||||
@@ -243,3 +243,25 @@ response for every unregistered number. `request-otp.spec.ts` now covers 9 cases
|
||||
— the happy path, the unknown number, Persian-digit input, a refused gateway, the
|
||||
dev no-gateway fallback, that the fallback does **not** apply in production, and
|
||||
the two sales-expert states.
|
||||
|
||||
## Sales expert — «ورود به حساب مشتری» restored (2026-10-12)
|
||||
|
||||
Reported by the owner: «کارشناس فروش میتونه از طریق اپ خودش وارد صفحه مشتری هاش
|
||||
بشه و از جانب اون ها ثبت سفارش کنه … انگار با اکانت اون ها لاگین کرده … و این
|
||||
خیلی کاربردی بود ولی الان نیست».
|
||||
|
||||
| ID | Severity | Where | Description | Evidence | Status |
|
||||
|---|---|---|---|---|---|
|
||||
| **EXP-01** | High (missing capability) | REF `henza_pwa` `customerChoice.vue:155-167` → `myDataStore.ts:159-169` → `tokenManage.ts:8` → `plugins/axios.ts:18`; REF server `ApiMobileController.php:197-201`. TGT both apps + `customer-jwt.strategy.ts` | A sales expert could open any of their referred customers' accounts and use the whole app as them — browse, see balance and debt, place orders. The reference did it by **minting and handing over the customer's own permanent `api_token`**, which its axios interceptor then used for every request. The target listed the customers but tapping one only opened a detail sheet; an expert's order always landed on their own trading account. | Read all five reference files and the target's view header, which recorded the omission (D21). | ✅ **RESTORED 2026-10-12 (D29)** with the reference's full scope — every customer route, including documents — but a different mechanism: `X-Act-As-Customer` alongside the expert's **own** token, resolved once in `CustomerJwtStrategy.validateExpert`, which is why all 17 customer routes work unchanged. Ownership (`referredByAgentId`) is re-checked **on every request** in the same query as the id, so another expert's customer and a non-existent id both answer 403. 11 tests. |
|
||||
| **EXP-02** | Medium (found while building EXP-01) | TGT both apps `stores/queryCache.ts`, `favoritesStore.ts`, `wageQuoteStore.ts` | All three drop their per-customer data when `session.token` changes — but act-as changes **whose** data they hold *without* changing the token. An expert entering a customer's account would have seen their own profile, orders, balance, ledger, favourites and **making-charge quotes**. | Read each watcher; each one's own comment stated the rule it was about to break. | ✅ Fixed with EXP-01: each watcher now also keys on `actingAs.id`. The wage-quote one is the money case — making charge is per customer, so a stale quote would have shown a figure that was not the one the order was priced at. |
|
||||
| **EXP-03** | Medium (same) | TGT both apps `api/client.ts` `uploadDocument` | The multipart upload bypasses `request()` and builds its own headers, so the act-as header had to be repeated there. Without it an expert uploading a customer's documents would have filed them against their **own** account, silently and with no error. | `grep Authorization` on the client returns two call sites, not one. | ✅ Both call sites send the header. |
|
||||
|
||||
**Deliberately different from the reference** (all in D29): no customer token is
|
||||
ever minted; the act-as target lives in `sessionStorage`, so closing the tab ends
|
||||
it, where the reference's `api_token` sat in `localStorage` forever and outlived
|
||||
the expert's employment; `adminUserId` survives the switch so an order placed
|
||||
this way is attributable (the reference's requests were indistinguishable from
|
||||
the customer's own); a permanent «در حال مشاهده به‌عنوان …» bar with an exit
|
||||
button, which the reference had no equivalent of — there, impersonation was
|
||||
invisible and the only way out was a logout that also ended the expert's own
|
||||
session; and the cart is cleared in both directions.
|
||||
|
||||
@@ -21,7 +21,7 @@ The "Current state" table below is the parity project's and was last updated 202
|
||||
|---|---|
|
||||
| **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 ✅**, plus the app-login error reporting the owner asked for (**AUTH-01/02/03**, **DOC-01**). **295/295** jest tests; both apps `vue-tsc` clean. |
|
||||
| **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 |
|
||||
@@ -143,6 +143,7 @@ All user rulings live there (D0–D17). Highlights that change how work is done:
|
||||
| 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
|
||||
|
||||
Reference in New Issue
Block a user