1553 lines
83 KiB
Markdown
1553 lines
83 KiB
Markdown
# DECISIONS — user rulings on the parity project
|
||
|
||
Binding decisions made by the user. They override defaults and survive context
|
||
loss. Referenced from `PROTECTED.md` and `PROGRESS.md`.
|
||
|
||
| Date | Phase | Decisions |
|
||
|---|---|---|
|
||
| 2026-09-21 | Phase 0 gate | D0–D5, D6–D8 (urgent), D9–D11, D12 (method change) |
|
||
|
||
---
|
||
|
||
## D0 — First name / last name: split the column (option **الف**)
|
||
|
||
**Ruling.** Add real `firstName` / `lastName` columns to `Customer` via an
|
||
**additive** migration.
|
||
|
||
Requirements:
|
||
|
||
1. Additive migration only — nothing dropped.
|
||
2. Backfill existing rows: **first token** of `fullName` → `firstName`, **the
|
||
rest** → `lastName`.
|
||
3. Rows whose `fullName` has **more than two tokens** must be written to a report
|
||
for manual review (they cannot be split safely).
|
||
4. **`fullName` is NOT removed.** It stays and is kept in sync as
|
||
`firstName + " " + lastName` so existing code keeps working.
|
||
5. `toRow()` must return the **real** `fname` / `lname`, not `fullName` / `''`.
|
||
6. Fix every consumer: `singleCustomer.vue`, `bulkCustomer.vue`,
|
||
`ReagentCustomer.vue`, and anywhere a name is displayed, searched or sorted.
|
||
**Remove the `split(' ')` fallback in `singleCustomer.vue`.**
|
||
7. Check the same defect on **`AdminUser`** (sales expert) and on
|
||
**registration / profile in `user-app` and `user-app-v2`**.
|
||
8. **Show the migration file and the command, and get approval, before running it.**
|
||
|
||
Evidence for the defect: reference has two columns
|
||
(`henza_server/database/migrations/2020_10_01_120430_customers_table.php:18-19`);
|
||
target collapses them (`apps/api/src/modules/admin-customers/admin-customers.service.ts:231-233`
|
||
returns `fname: c.fullName, lname: ''`).
|
||
|
||
## D1 — Admin auth: keep the target stricter
|
||
|
||
The reference leaves all ~215 admin routes unauthenticated
|
||
(`henza_server/routes/admin.php:12,272`). The target's JWT + 144-rid enforcement
|
||
**stands**, recorded as an accepted deviation.
|
||
|
||
**Additional requirement:** build a complete mapping matrix
|
||
**"every reference admin operation ↔ its permission key (rid) in the target"**,
|
||
so no operation is left without an equivalent permission. Explain the
|
||
**172 (reference) vs 174 (target) unique key** difference.
|
||
|
||
## D2 — Domain scope: audit only what the reference has
|
||
|
||
Confirmed. Do not manufacture rows for buy/sell gold, deposit, withdraw,
|
||
transfer, KYC levels, price sockets or payment callbacks — none exist in the
|
||
reference (`00-INVENTORY.md` §0).
|
||
|
||
Target-only capabilities (e.g. the dual-currency ledger, gram/rial debt) are
|
||
listed with status **➕** and **left untouched**. Ask when unsure.
|
||
|
||
## D3 — The 5 missing user-app screens: build them in Phase 2
|
||
|
||
`/report`, `/report/detail`, `/ChildOrder`, `/customerChoice`, `/complete_profile`
|
||
are built in **both** apps, each in its own design language, plus whatever backend
|
||
they need.
|
||
|
||
Also brought to reference behaviour in Phase 2:
|
||
- route analytics (`POST /log/create/{key}`, `GET /log/update/{id}`)
|
||
- the `isLoaded` guard
|
||
- the `sts_verify_step_two` guard on `completeProfile`
|
||
- guest behaviour: **toast «ابتدا وارد شوید» + redirect to `home`** (not a redirect to `/login`)
|
||
- **v2's missing cart stock ceiling (`capQty`/`maxQty`) must match v1 and the reference**
|
||
|
||
## D4 — Reference bugs: replicate behaviour, not breakage
|
||
|
||
- Broken or destructive reference behaviour is **not** ported — logged only.
|
||
- **Business behaviour, calculations, rounding and messages must match the
|
||
reference exactly.**
|
||
- Every deliberate non-replication gets a matrix note:
|
||
**«عمداً تکرار نشد — ISSUE #n»**.
|
||
- The price formula is the **live** version at
|
||
`henza_server/app/Models/ProductVariant.php:183-190` — *not* the commented-out
|
||
ones above it.
|
||
- Write a **unit test** for it with sample numbers and compare against the
|
||
reference formula computed by hand.
|
||
|
||
## D5 — Stray root folder: leave it for now
|
||
|
||
`gold-banking-monorepo/user-app-v2/` is logged in `ISSUES.md` (DEAD-03). At the
|
||
very end, after verifying nothing references it, delete it in **its own commit**.
|
||
|
||
---
|
||
|
||
## D6 — URGENT: OTP must be verified (exception to "log only", per `CLAUDE.md` §3)
|
||
|
||
The reference **does** verify the OTP, so the target accepting any code is a
|
||
**parity gap**, not just a security issue. Fix it to match the reference:
|
||
code matching, expiry, and attempt limits.
|
||
|
||
Reference implementation (`henza_server/app/Http/Controllers/Api/ApiMobileController.php:39-78`):
|
||
|
||
| Step | Reference behaviour | Line |
|
||
|---|---|---|
|
||
| Send | `userAuth` validates `username`, finds an **active** customer by mobile, generates `rand(1000,9999)`, stores it in `customer.send_password`, sends it by SMS | `:39-49` |
|
||
| Verify | `userVerfiy` validates `username` + `password`; if `faTOen(password) != customer.send_password` → **HTTP 422** | `:51-57` |
|
||
| Token | issues `api_token = Str::random(60)` only if the customer doesn't already have one | `:60-62` |
|
||
| Digits | the code is normalised through `Utility::faTOen()` (Persian → English digits) on **both** send and verify | `:42,56` |
|
||
|
||
⚠️ Note for the matrix: the reference has **no expiry and no attempt limit** —
|
||
`send_password` is a plain column that stays valid indefinitely. D6 asks for
|
||
expiry and attempt limits, which go **beyond** the reference. Recorded as a
|
||
deliberate, user-requested improvement; the parity row is the code match itself.
|
||
|
||
## D7 — URGENT: `@Public()` routes that write to the ledger
|
||
|
||
Show the exact list with file paths and what the reference did for each, then
|
||
protect them **after user approval**. See §"@Public audit" below.
|
||
|
||
## D8 — URGENT: the login customer-list leak
|
||
|
||
Identify whether it is reference or target, and what data leaks. See §"Login leak"
|
||
below.
|
||
|
||
---
|
||
|
||
## D9 — `percent`: trace before acting
|
||
|
||
Done — see `00-INVENTORY.md` and the trace summary delivered to the user.
|
||
**Key finding: the target's implementation is wrong.** `percent` is a real column
|
||
on the customer in the reference, not a derived value from the referring agent.
|
||
|
||
## D10 — Sales expert: the 5 missing fields
|
||
|
||
The move to `AdminUser` is **accepted**. For `ncode`, `phone`, `city_id`,
|
||
`gram_level`, `reagent_id`: find where the reference uses each for `type=1`
|
||
(list, filter, report, order, calculation). Fields that are genuinely used must
|
||
be added — **proposed shape: a `SalesExpertProfile` table related to `AdminUser`**.
|
||
Fields with no use are listed for the user to decide.
|
||
|
||
## D11 — `singleCustomer.vue`: migrate to the diff-send pattern
|
||
|
||
Bring it in line with `bulkCustomer.vue` and `ReagentCustomer.vue`. **Diff-send
|
||
is recorded as an accepted deviation** from the reference (which sends every
|
||
field on every save).
|
||
|
||
---
|
||
|
||
## D12 — METHOD CHANGE for Phase 1 (and Phase 2)
|
||
|
||
**1. The matrix is field-by-field, not page-by-page.** Every form field (name,
|
||
type, required, validation, message, default), every table column, every filter,
|
||
every button — and for each one, the **client field name ↔ API field name ↔ DB
|
||
column**, on **both** sides.
|
||
|
||
**2. A round-trip test is mandatory per entity:**
|
||
|
||
```
|
||
create with every field populated
|
||
→ open the edit form, assert every field is correctly populated
|
||
→ save with no changes, assert the DB row is byte-identical
|
||
→ change exactly one field, assert only that field changed
|
||
```
|
||
|
||
Run it for the sales expert too.
|
||
|
||
**3. Both rules are to be added to the `reference-parity-audit` skill**
|
||
(Step C and Step E) so Phase 2 inherits them.
|
||
|
||
---
|
||
|
||
## T1 — Customer authentication: a separate JWT strategy (option **الف**)
|
||
|
||
Approved. Conditions:
|
||
|
||
1. **Separate secrets** — customer tokens are signed with `JWT_CUSTOMER_SECRET`,
|
||
admin tokens with `JWT_SECRET`.
|
||
2. **A `typ` claim is checked in both guards** — `typ: 'admin'` vs `typ: 'customer'`.
|
||
3. **Mandatory cross-token tests:** a customer token on any admin route → 401;
|
||
an admin token on a customer route → rejected, unless deliberately allowed.
|
||
4. **Token lifetime and logout must be compared against the reference and
|
||
recorded here** (see below).
|
||
5. **No IDOR** — customer routes that return personal data derive the customer
|
||
from the **token**, never from an id in the request.
|
||
|
||
### Reference comparison — token lifetime and logout
|
||
|
||
| Aspect | Reference | Target (current) | Decision |
|
||
|---|---|---|---|
|
||
| Customer token | `api_token = Str::random(60)`, a random opaque string stored on the customer row (`ApiMobileController.php:60-62`) | none | new customer JWT |
|
||
| Expiry | **none** — the reference token never expires; it is reused on every login if already set | admin JWT `JWT_EXPIRES_IN`, default `12h` | customer JWT gets an explicit expiry (deliberate improvement over the reference) |
|
||
| Logout | the reference has **no logout endpoint**; the app drops the token client-side | apps clear `localStorage` | keep client-side clear; note that a stolen token stays valid until expiry |
|
||
| Rotation | the reference issues a new token **only if `api_token` is null** — logging in twice returns the same token forever | n/a | issue a fresh token on every verify |
|
||
|
||
The last three rows are **deliberate improvements over the reference**, approved
|
||
by the user in the same message that approved D6. Recorded so the matrix does not
|
||
later flag them as parity gaps.
|
||
|
||
## T2 — Uploaded files stay public
|
||
|
||
**Ruling:** `/uploads` is not touched. No allow-list, no signed URLs, and the
|
||
"private folder" stage is dropped.
|
||
|
||
**Recorded verbatim at the user's request:**
|
||
> «فایلهای آپلودی شامل مدارک عمداً عمومی هستند — تصمیم مالک پروژه»
|
||
> (Uploaded files, including identity documents, are deliberately public — the
|
||
> project owner's decision.)
|
||
|
||
### The light check the user asked for — result: ✅ already correct
|
||
|
||
| Check | Result | Evidence |
|
||
|---|---|---|
|
||
| Filenames unguessable? | **Yes.** `md5(Date.now() + originalname + randomUUID())` + the original extension | `src/modules/admin-uploads/admin-uploads.service.ts:53` |
|
||
| Sequential or original name on disk? | **No.** `originalName` is kept only as a DB column, never as the filename | `admin-uploads.service.ts:62` |
|
||
| Directory listing? | **No.** `PublicUploadsController` only resolves a single `:filename`, and `resolveStoredUpload()` rejects `.`/`..` and anything resolving outside the upload dir | `public-uploads.controller.ts:17`, `upload-path.ts:34-49` |
|
||
|
||
Nothing to change. No existing files were moved.
|
||
|
||
## T3 — Two-stage hotfix
|
||
|
||
Approved, with the condition that `GET /customers` be checked first.
|
||
|
||
**Check result:** the apps **are** dependent on it. Its only consumer is
|
||
`LoginView.vue:131` in both apps, and `CustomerSummary` is used nowhere else
|
||
(verified by grep). The fields actually read are `mobile`, `isActive`,
|
||
`isArchived`, then `session.login(id, mobile)` — four fields.
|
||
|
||
So per the ruling: stage 1 strips the sensitive fields and keeps the route; stage
|
||
2 removes the route when login moves to OTP.
|
||
|
||
---
|
||
|
||
# Urgent investigation results
|
||
|
||
## `percent` — full trace (D9)
|
||
|
||
### In the reference, `percent` is a real column on the customer
|
||
|
||
| Fact | Evidence |
|
||
|---|---|
|
||
| Column exists on `customers` | `database/migrations/2020_10_19_153228_customer_add.php:32` — `$table->double('percent')->default(0);` |
|
||
| Mass-assignable | `app/Models/Customer.php:31` |
|
||
| Defaulted to **3** for app-registered customers | `app/Http/Controllers/Adm/AdminController.php:338` — `$input['percent'] = 3;` |
|
||
| **Required** when an admin creates a wholesale customer | `AdminController.php:354` — `'percent'=>'required'` |
|
||
| Selected into the wholesale customer list | `Adm/MajorCustomerController.php:36` |
|
||
| Shown in a report column «درصد» | `Adm/ReportController.php:137` |
|
||
|
||
### What it actually does — it shifts the customer's making-charge filter
|
||
|
||
`app/Http/Controllers/Api/ApiMobileController.php:391-396`:
|
||
|
||
```php
|
||
if (sizeof($limit_percent) > 0 and auth('api-customer')->check()) {
|
||
$limit_percent[0] = $limit_percent[0] - auth('api-customer')->user()->percent;
|
||
$limit_percent[1] = $limit_percent[1] - auth('api-customer')->user()->percent;
|
||
$product->whereHas('variants', fn($q) => $q->whereBetween('percentage_pay', $limit_percent));
|
||
}
|
||
```
|
||
|
||
And it shifts the **filter bounds the app is told to display**, at login
|
||
(`ApiMobileController.php:76-77`):
|
||
|
||
```php
|
||
$customer['filterPercentPay'][] = strval(ProductVariant::min('percentage_pay') + $customer['percent']);
|
||
$customer['filterPercentPay'][] = strval(ProductVariant::max('percentage_pay') + $customer['percent']);
|
||
```
|
||
|
||
So `customer.percent` is a **per-customer making-charge offset**: the UI shows
|
||
`percentage_pay + percent`, and the filter subtracts it again before querying.
|
||
|
||
### What it does NOT do
|
||
|
||
**It is not part of the price formula.** The formula's extra percent comes from a
|
||
**global** config row, not from the customer:
|
||
|
||
- `app/Models/ProductVariant.php:50` — `ConfigStatic::where('key','product_price_extra_percent')->first()['val'] ?? 7`
|
||
- `app/Models/ProductVariant.php:183` — `($this->percentage_pay + static::$product_price_extra_percent)`
|
||
|
||
There is a **separate, unrelated** `ConfigStatic` key also called `percent`, used
|
||
for the cashback/wallet rule (`AdminController.php:903,994`; `Controller.php:203`) —
|
||
`value = total_weight * (percent/100)`. **Do not confuse the two.**
|
||
|
||
A **third** unrelated `percent` is a per-order-item field in wholesale orders
|
||
(`Adm/MajorOrderController.php:220`): `w = rash_weight + rash_weight * (percent/100)`.
|
||
That one comes from the request, not from the customer.
|
||
|
||
### The target is wrong
|
||
|
||
`apps/api/src/modules/admin-customers/admin-customers.service.ts:245`:
|
||
|
||
```ts
|
||
// legacy `percent` came from the referring agent's commission rate
|
||
percent: c.referredByAgent?.wagePercent ?? null,
|
||
```
|
||
|
||
That comment is **incorrect** — the reference reads `customer.percent`, its own
|
||
column. Consequences:
|
||
|
||
1. **Read is wrong** — it shows the agent's commission, not the customer's offset.
|
||
2. **Write is missing** — `update()` never handles `data.percent`
|
||
(`admin-customers.service.ts:600-658`), so editing the field in the admin form
|
||
does nothing.
|
||
3. **The create default is missing** — the reference sets `percent = 3` for
|
||
app-registered customers and **requires** it for admin-created wholesale
|
||
customers.
|
||
4. **The app-side effect is missing** — no `filterPercentPay` offset anywhere in
|
||
`user-app` / `user-app-v2`.
|
||
|
||
### Proposed reconstruction (needs user approval — it is a schema change)
|
||
|
||
1. Add `makingChargeOffsetPercent Decimal @default(0)` to `Customer` (additive
|
||
migration). Name it clearly so it is never confused with the two other
|
||
`percent`s; map it to the legacy key `percent` in `toRow()`.
|
||
2. `toRow()` returns that column, not `referredByAgent.wagePercent`. Remove the
|
||
incorrect comment.
|
||
3. `create()`: default **3** on the app-registration path; **require** it on the
|
||
admin wholesale path (reference `AdminController.php:354`).
|
||
4. `update()`: handle `data.percent`.
|
||
5. Catalogue filter: subtract the customer's offset from the `percentage_pay`
|
||
bounds before querying, and return shifted `filterPercentPay` bounds at login
|
||
— matching `ApiMobileController.php:391-396,76-77`.
|
||
6. The referring agent's `wagePercent` stays where it belongs (the agent), and is
|
||
**not** exposed through the customer form.
|
||
|
||
---
|
||
|
||
## `@Public()` audit (D7) — every unauthenticated route in the target
|
||
|
||
15 routes across 7 controllers. Verified by reading each controller.
|
||
|
||
### 🔴 Group A — ledger writes (the ones the user flagged)
|
||
|
||
`apps/api/src/modules/accounting/accounting.controller.ts` — `@Public()` on the
|
||
**whole controller** (`:7`), prefix `accounting` (`:8`):
|
||
|
||
| # | Route | Line | Effect | Reference equivalent |
|
||
|---|---|---|---|---|
|
||
| A1 | `GET accounting/customers/:customerId/balance` | `:12` | reads any customer's balance | `Adm/WalletController` — reference had auth **commented out** too (`routes/admin.php:12`) |
|
||
| A2 | `POST accounting/customers/:customerId/reconcile` | `:17` | **writes** — reconciles a balance | same: unauthenticated in reference |
|
||
| A3 | `POST accounting/repayments/gold` | `:22` | **writes** — records a gold repayment | same |
|
||
| A4 | `POST accounting/repayments/rial` | `:27` | **writes** — records a rial repayment | same |
|
||
| A5 | `POST accounting/entries/:entryId/confirm` | `:32` | **writes** — confirms a ledger entry | same |
|
||
|
||
**In the reference these were admin routes in `routes/admin.php`, and that whole
|
||
file's `auth:api` wrapper is commented out — so they were unauthenticated there
|
||
too.** The target faithfully reproduced that. Under **D1** the target is supposed
|
||
to be stricter, so these five are the clearest violation of D1 still standing.
|
||
|
||
**Recommendation:** A1–A5 are admin operations. Put them behind the admin JWT
|
||
guard with the matching rid (the wallet/document rids from `acl.constants.ts`).
|
||
**Awaiting your approval — this is the list you asked for.**
|
||
|
||
### 🟠 Group B — order writes
|
||
|
||
`apps/api/src/modules/orders/orders.controller.ts` — `@Public()` at `:7`, prefix `orders`:
|
||
|
||
| # | Route | Line | Note | Reference |
|
||
|---|---|---|---|---|
|
||
| B1 | `POST orders` | `:12` | customer places an order | `ApiMobileController::setOrder` — **was authenticated** via `auth('api-customer')`; it reads `auth()->id()` at `:533` |
|
||
| B2 | `GET orders/:id` | `:17` | reads any order by id | same guard in reference |
|
||
| B3 | `PATCH orders/:id/status` | `:22` | **changes order status**; DTO accepts a client-supplied `actorAdminUserId` | admin operation in reference |
|
||
|
||
**B1/B2 differ from the reference in kind:** the reference's customer endpoints
|
||
sat behind the `api-customer` guard and derived the customer from the token.
|
||
The target has **no customer session at all**, so it takes `customerId` from the
|
||
request body. That is why they are public. Fixing this properly means building
|
||
customer auth — which is exactly what **D6** starts.
|
||
|
||
**B3 is the worst of the three:** it lets an anonymous caller move an order's
|
||
status *and* attribute the action to any admin.
|
||
|
||
### 🟢 Group C — genuinely public reads (match the reference's public storefront)
|
||
|
||
| # | Route | File:line | Reference |
|
||
|---|---|---|---|
|
||
| C1 | `GET customers` | `customers/customers.controller.ts:10` | **see the leak below** |
|
||
| C2 | `GET customers/:id` | `:15` | — |
|
||
| C3 | `GET customers/:id/orders` | `:20` | — |
|
||
| C4 | `GET customers/:id/ledger-entries` | `:25` | — |
|
||
| C5 | `GET catalog/products` | `catalog/catalog.controller.ts:10` | reference storefront was public (`routes/site.php`) ✅ |
|
||
| C6 | `GET pricing/latest` | `pricing/pricing.controller.ts:10` | reference `/price` was public ✅ |
|
||
| C7 | `GET home/slider` | `admin-misc/public-slider.controller.ts:21` | reference `mobile_main_slider` config, public ✅ |
|
||
| C8 | `GET uploads/:filename` | `admin-uploads/public-uploads.controller.ts:17` | reference served uploads statically ✅ |
|
||
|
||
C5–C8 are legitimately public. **C1–C4 are not** — they expose customer records.
|
||
|
||
---
|
||
|
||
## Login leak (D8) — it is in the **target**, and it is worse than "a list"
|
||
|
||
**Where:** target only. `apps/user-app` and `apps/user-app-v2` both call
|
||
`GET /api/customers` at login and match the phone number **in the browser**.
|
||
|
||
**What leaks:** `GET /customers` is `@Public()`
|
||
(`customers/customers.controller.ts:10`) and returns **every active,
|
||
non-archived customer** with these fields
|
||
(`customers/customers.service.ts:6-23`, `:44-50`):
|
||
|
||
| Field | Sensitive? |
|
||
|---|---|
|
||
| `id`, `createdAt`, `updatedAt` | low |
|
||
| `fullName` | 🔴 **PII** |
|
||
| `mobile` | 🔴 **PII** |
|
||
| `nationalCode` | 🔴 **national ID number** |
|
||
| `cityId`, `referredByAgentId` | medium |
|
||
| `goldCreditLimitGrams`, `goldDebtGrams`, `fiatDebtRial` | 🔴 **financial position of every customer** |
|
||
| `verificationStep`, `isActive`, `isArchived` | medium |
|
||
| `nationalIdImageUrl`, `businessLicenseUrl`, `shopImageUrl` | 🔴 **URLs of ID-document scans** |
|
||
|
||
**`passwordHash` is correctly excluded** — the select list is explicit and the
|
||
source comment says so (`customers.service.ts:5`). So no password material leaks.
|
||
|
||
**Everything else does.** Any anonymous visitor can fetch the full customer book —
|
||
names, mobiles, national ID numbers, debts, and links to identity-document images
|
||
(and `GET uploads/:filename` is public too, so those links resolve).
|
||
|
||
**In the reference this was not possible.** Login was
|
||
`POST userAuth` → SMS code → `POST userVerfiy`
|
||
(`ApiMobileController.php:39-78`): the server looked the customer up by mobile
|
||
and returned **only that one customer** after the code matched. There was no
|
||
"download everyone and match on the client" step.
|
||
|
||
**Root cause:** the target has no customer authentication, so the client does the
|
||
lookup. **D6 (real OTP) is the fix for both problems at once** — once
|
||
`POST auth/otp/verify` returns the authenticated customer, `GET /customers` can
|
||
be taken off the public surface entirely.
|
||
|
||
---
|
||
|
||
# Stage 2 implementation record (2026-09-22)
|
||
|
||
## Deliberate improvements over the reference — user-approved
|
||
|
||
Recorded here so the Phase 1/2 matrices do not later flag them as parity gaps.
|
||
|
||
| # | Behaviour | Reference | Target | Approved in |
|
||
|---|---|---|---|---|
|
||
| 1 | OTP storage | plain text in `customer.send_password` | bcrypt hash in `CustomerOtp.codeHash` | D6 |
|
||
| 2 | OTP expiry | none — valid forever | 2 minutes | D6 |
|
||
| 3 | Attempt limit | none | 5 per challenge, then lockout | D6 |
|
||
| 4 | Replay | code stayed usable | single use (`consumedAt`) | D6 |
|
||
| 5 | Send throttle | none | 60s cooldown/number, 5 per number and 20 per IP per 10 min | user message of 2026-09-22 |
|
||
| 6 | Unknown number | `firstOrFail()` → 404, enumerable | identical `{sent:true}` | implied by 5; recorded here |
|
||
| 7 | Token rotation | `api_token` issued once, reused forever | fresh token on every verify | T1 |
|
||
| 8 | Token expiry | none | `JWT_CUSTOMER_EXPIRES_IN`, default 30d | T1 |
|
||
| 9 | Token secret | single opaque string | `JWT_CUSTOMER_SECRET`, separate from admin, plus a `typ` claim | T1 |
|
||
|
||
## New environment variables
|
||
|
||
| Name | Default | Purpose |
|
||
|---|---|---|
|
||
| `JWT_CUSTOMER_SECRET` | falls back to `JWT_SECRET`, then a dev string | signs customer tokens |
|
||
| `JWT_CUSTOMER_EXPIRES_IN` | `30d` | customer token lifetime |
|
||
|
||
Both fall back so local development keeps working, and both inherit the SEC-04
|
||
problem (an insecure default when unset) — tracked there, not re-logged.
|
||
|
||
## Known gap left open on purpose
|
||
|
||
`POST /orders` and `GET /orders/:id` are still `@Public()`. The customer token
|
||
now exists, so they can be closed, but `CreateOrderDto` carries `customerId` in
|
||
the body and changing that is an API-contract change touching both apps' cart
|
||
flow. Left for the Phase 2 apps work rather than widened into this hotfix.
|
||
Tracked as SEC-02 (B1/B2) in `ISSUES.md`.
|
||
|
||
---
|
||
|
||
# D13 — Retail storefront: preserved, but out of scope (2026-09-22)
|
||
|
||
**Owner's ruling.** The reference also contained a **retail storefront**
|
||
(single-customer / B2C shop). The **wallet**, **cashback** and
|
||
`ConfigStatic['percent']` belong to that storefront, not to the B2B gold
|
||
business this project is porting.
|
||
|
||
## The rule
|
||
|
||
1. **Nothing is deleted or disabled.** No code, table, column, endpoint, setting
|
||
or data belonging to the storefront may be removed or switched off — neither
|
||
in the target nor in the reference. Whatever exists in the target today stays
|
||
exactly as it is.
|
||
2. **No work is done on it.** No parity, no fixes, no refactoring.
|
||
3. **In the matrices** these items are listed with status
|
||
**⏸️ حفظشده — خارج از کار فعلی** (preserved — out of current scope) so they
|
||
remain visible, but **no gap row and no work row is created for them**.
|
||
4. **Shared surfaces need a heads-up.** If fixing something shared — product,
|
||
variant, price, order, customer — would affect the storefront, **ask the
|
||
owner before changing it**, so nothing in the storefront breaks.
|
||
5. **No guessing.** If it is unclear whether something is storefront-only or
|
||
shared, **list it and ask**.
|
||
|
||
## Status legend addition
|
||
|
||
| Symbol | Meaning |
|
||
|---|---|
|
||
| ⏸️ | Preserved — out of current scope (D13). Listed for visibility only; no gap row, no work row. |
|
||
|
||
## Endpoint classification — where the reference endpoints go
|
||
|
||
**The previously reported total of 369 was wrong; the real figure is 412.**
|
||
Recounting the live routes per file (excluding the 6 commented-out ones,
|
||
expanding `Route::resource` ×7 and `Route::match(['get','post'])` ×2) shows
|
||
`admin.php` has **151** explicit routes, not the 117 recorded in
|
||
`_inv-ref-server.md` §3.6 — so admin is **249**, not 215. Corrected in
|
||
`00-INVENTORY.md` §2.1.
|
||
|
||
| Surface | Route file(s) | Endpoints | In scope? |
|
||
|---|---|---|---|
|
||
| Admin panel — B2B | `admin.php` minus the storefront block below | **218** | ✅ in scope (Phase 1) |
|
||
| Admin panel — storefront management | `admin.php`: wallet 6, `single*` 8, comment 2, `get-analytics-tak` 1 explicit + `single` resource 7 + `comment` resource 7 | **31** | ⏸️ preserved, out of scope |
|
||
| B2B mobile app | `api.php` | **70** | ✅ in scope (Phase 2) |
|
||
| Retail storefront — customer API | `customer.php` | **48** | ⏸️ preserved, out of scope |
|
||
| Retail storefront — public site API | `site.php` | **30** | ⏸️ preserved, out of scope |
|
||
| Dev/ops closures, price cron, redirects | `web.php` | **15** | ⏸️ out of scope (dead/dev — see DEAD-\* in `ISSUES.md`) |
|
||
| **Total** | | **412** | |
|
||
|
||
**Result: 109 of the 412 endpoints belong to the retail storefront**
|
||
(48 `customer.php` + 30 `site.php` + 30 storefront management inside
|
||
`admin.php`), **15 more are dev/ops closures in `web.php`**, and
|
||
**288 remain in scope** (218 admin + 70 B2B app).
|
||
|
||
Evidence for the storefront classification:
|
||
|
||
| Block | Where | Why it is storefront |
|
||
|---|---|---|
|
||
| `routes/customer.php` (prefix `cu`) | whole file | guarded by `auth:api-singleCustomer`; cart, fav, address, comment, payment gateway, `customer/wallet` |
|
||
| `routes/site.php` (prefix `site`) | whole file | public shop front: `Site\SiteController`, `Site\CollectionController`, `Api\SiteController` |
|
||
| `admin/wallet/*` | `admin.php:186-191` | `Adm\WalletController` — cashback percent, charge, config |
|
||
| `admin/single*` | `admin.php:35,59,60,194-199` | `Adm\SingleCustomerController` — the retail customer's orders, transactions, wallet, report |
|
||
| `admin/comment*` | `admin.php:150-152` | `Adm\CommentController` — product reviews, a storefront feature |
|
||
|
||
The three unrelated `percent` meanings were already separated in
|
||
`MIGRATION-STATE.md`. D13 confirms that **`ConfigStatic['percent']` (wallet
|
||
cashback) is storefront and out of scope**, while **`customers.percent`
|
||
(→ `makingChargeOffsetPercent`) is B2B and stays in scope**.
|
||
|
||
---
|
||
|
||
# Report — SMS provider (parity investigation, 2026-09-22)
|
||
|
||
Requested before implementing. **Nothing was implemented yet; awaiting approval.**
|
||
|
||
## 1. Which provider does the reference use?
|
||
|
||
**Trez SMS panel** (`smspanel.trez.ir`), called directly with Laravel's `Http`
|
||
facade. There is **no package, no config file and no env var** — the endpoint and
|
||
the credentials are hardcoded in one model.
|
||
|
||
| Item | Value | Where |
|
||
|---|---|---|
|
||
| Class | `App\Models\Sms` | `henza_server/app/Models/Sms.php` |
|
||
| Live endpoint | `https://smspanel.trez.ir/SendMessageWithCode.ashx` | `Sms.php:69` (`Send`), `Sms.php:97` (`SendSms`) |
|
||
| Method | `POST`, form-urlencoded, 20s timeout | `Sms.php:71-78` |
|
||
| Form fields | `PhoneNumber` (sender line), `Username`, `Password`, `Mobile`, `Message` | `Sms.php:73-77` |
|
||
| Persistence | `Sms::set()` writes every message to the `messages` table | `Sms.php:80,120-129` |
|
||
| Queue | `SendSmsJob` / `SendSmsAfterCreate` exist, but `QUEUE_CONNECTION` defaults to `sync` (`config/queue.php:16`), so sends are inline | `app/Jobs/SendSmsJob.php:40` |
|
||
|
||
**A superseded provider is commented out above each call**: `0098sms.com`
|
||
(`sendsmslink.aspx`, GET, sender line `3000164545`). Not ported — dead code.
|
||
|
||
WARNING — **the reference has live production credentials committed to git**
|
||
(`Sms.php:74-76`: a panel username, a plaintext password, and a sender line).
|
||
They are **not** copied into the target and are **not** repeated here. Logged as
|
||
**SEC-12**. The owner should assume they are compromised and rotate them.
|
||
|
||
## 2. Message templates
|
||
|
||
`Sms::Send($to, $msg)` takes a fully-built string; there are no provider-side
|
||
template ids. Lines are separated by a newline.
|
||
|
||
### OTP — the one this project needs
|
||
|
||
`ApiMobileController.php:47`:
|
||
|
||
```
|
||
<#> code is {CODE}
|
||
رمز عبور یکبار مصرف شما جهت ورود به اپلیکشن هنزا گلد {CODE} می باشد
|
||
aMo6iFyUQaY
|
||
```
|
||
|
||
The first line and the trailing `aMo6iFyUQaY` are the **Android SMS Retriever**
|
||
hash — they must stay byte-identical or autofill breaks. This exact string is
|
||
already in the target at `customer-auth.service.ts:219-222`, built and held
|
||
ready, currently discarded via `void smsText`.
|
||
|
||
A second OTP variant exists for the web app (`WebApp/AuthController.php:21`),
|
||
ending with the site domain and a hash. Not used by the B2B app.
|
||
|
||
### The other B2B messages (all in scope)
|
||
|
||
| # | Trigger | Text | Where |
|
||
|---|---|---|---|
|
||
| 1 | Customer created by admin | `هنزا گلد` / `همکار گرامی {fname} {lname}` / `نام کاربری : {mobile}` | `AdminController.php:380-383` |
|
||
| 2 | Customer activated (`active == -1`) | `{name} عزیز ` / `حساب كاربري شما در اپليكيشن هنزا فعال شد.` / `هم اكنون مي توانيد محصولات جديد را بررسي و ثبت سفارش كنيد.` / `با مراجعه به لینک زیر می توانید وارد پروفایل کاربری خود شوید.` / `https://henzagold.com/customer/login` / `هنزا، راهكارهاي نوين تامين محصولات` | `AdminController.php:441-447` |
|
||
| 3 | Financial document approved | `هنزا گلد` / `سند مالی شما توسط مدیر سیستم تایید شد.` | `AdminController.php:465`, `CashController.php:141` |
|
||
| 4 | Financial document rejected | `هنزا گلد` / `سند مالی شما توسط مدیر سیستم رد شد.` | `CashController.php:144` |
|
||
| 5 | Order approved | `هنزا گلد` / `سفارش شما با شماره سند {oId}تایید شد.` (no space before «تایید» in the reference) | `AdminController.php:522` |
|
||
| 6 | Order placed — normal | `سفارش شما به شماره {id} به ثبت رسید. هنزا گلد` | `ApiMobileController.php:742` |
|
||
| 7 | Order placed — over `gram_level` | `سفارش شما به شماره {id} به ثبت رسید اما به دلیل عبور از سقف مجاز گرمی در حالت معلق قرار گرفت. هنزا گلد` | `ApiMobileController.php:739` |
|
||
| 8 | Order placed by the sales expert for a customer | `هنزا گلد` / `همکار گرامی {fname} {lname}` / `سفارشی به وزن {allGram} گرم توسط آقای {reagentName} برای شما در سیستم ثبت شده است.` / `در صورت مورد تایید بودن سفارش بر روی لینک زیر کلیک نمایید.` / `{confirmLink}` | `ApiMobileController.php:733` |
|
||
| 9 | To the customer's sales expert, on every order | `هنزا گلد` / `سفارشی توسط {fname} {lname} به شماره {id}و به وزن {allGram} به ثبت رسید.` | `ApiMobileController.php:749` |
|
||
| 10 | To four hardcoded admin numbers, on every order | `هنزا گلد` / `سفارشی توسط {fname} {lname}` / ` به وزن {round(allGram)}` / `در سیستم ثبت شد.` | `ApiMobileController.php:601-605` |
|
||
| 11 | To three hardcoded admin numbers, on findoc submit | `هنزا گلد` / `سندی توسط آقای / خانم {fname} {lname} در سیستم ثبت شد.لطفا نسبت به بررسی و تایید آن اقدام نمایید. ` | `ApiMobileController.php:154-158` |
|
||
| 12 | Admin free-text / batch | operator-supplied | `SmsController.php:56,151` |
|
||
|
||
Messages 10 and 11 go to **phone numbers hardcoded in the source**
|
||
(six different mobile numbers across `ApiMobileController.php:154-158,601-605`).
|
||
Porting those literals would be wrong — they belong in configuration. Proposal:
|
||
one env var holding a comma-separated list, defaulting to empty. Logged as
|
||
**STUB-05**.
|
||
|
||
**Storefront messages are excluded** per D13: the cashback/wallet texts
|
||
(`AdminController.php:921,951`), `Customer/OrderController.php:94,141-145`,
|
||
`SingleCustomerController.php:66`, `Site/SiteController.php:182`,
|
||
`birthdayCommand.php`, `SmsWalletCommand.php`.
|
||
|
||
## 3. Proposed env vars — names only, no values in code or git
|
||
|
||
| Name | Required | Purpose |
|
||
|---|---|---|
|
||
| `SMS_PROVIDER` | no, default `trez` | selects the driver; `none` keeps today's dev behaviour |
|
||
| `SMS_TREZ_URL` | no, defaults to the reference endpoint | provider endpoint |
|
||
| `SMS_TREZ_USERNAME` | **yes in production** | panel username |
|
||
| `SMS_TREZ_PASSWORD` | **yes in production** | panel password |
|
||
| `SMS_TREZ_SENDER_LINE` | **yes in production** | the `PhoneNumber` form field |
|
||
| `SMS_ADMIN_RECIPIENTS` | no, default empty | replaces the hardcoded admin numbers (STUB-05) |
|
||
|
||
Proposed behaviour, per the owner's instruction:
|
||
|
||
- **Key absent, `NODE_ENV !== 'production'`** — today's behaviour is unchanged:
|
||
the code is logged once by `Logger`, a redacted audit row is written.
|
||
- **Key absent, `NODE_ENV === 'production'`** — the server **fails to boot** with
|
||
an explicit error naming the missing variable. No silent no-op, because a
|
||
silent no-op means no customer can log in and nothing says why.
|
||
- Secrets are read from `process.env` only; nothing is written to the repo, and
|
||
`.env.example` carries the **names with empty values**.
|
||
|
||
**Awaiting approval before implementing.**
|
||
|
||
---
|
||
|
||
# Report — MON-08: where the pricing values come from (2026-09-22)
|
||
|
||
Requested: in `henza_pwa`, does the user type `wagePercent` / `discountPercent` /
|
||
`flatRialCharge`, or does the app compute them?
|
||
|
||
## Answer: the app computes all of them. The user types none of them.
|
||
|
||
The whole order payload is built in one place,
|
||
`henza_pwa/src/views/cart.vue:160-184` (`submitOrder`):
|
||
|
||
| Payload field | Target equivalent | Source | Evidence |
|
||
|---|---|---|---|
|
||
| `percent_pay` | `wagePercent` | `getWage(variant)` = `myStore.state.percent + variant.percentage_pay` | `cart.vue:173` -> `src/Mixins/product/index.ts:69-75` |
|
||
| `discount` | `discountPercent` | `getPromotion(product)?.discount_percent ?? 0` | `cart.vue:170` |
|
||
| `rial_pay` | `flatRialCharge` | **hardcoded `0`** — no UI writes it | `cart.vue:179` |
|
||
| `rash_weight` | (target reads from DB) | `cart.variant(cartItem).grams` — the variant's own weight | `cart.vue:178` |
|
||
| `qty` | `quantity` | the cart stepper — **the only genuine user input** | `cart.vue:177` |
|
||
|
||
Both computed inputs come from server-issued data:
|
||
|
||
- `variant.percentage_pay` — the variant's making charge, from the catalogue.
|
||
- `myStore.state.percent` — **`customers.percent`**, delivered by `POST /me-data`
|
||
and stored at `myDataStore.ts:29,59,122-127`. This is the same
|
||
`makingChargeOffsetPercent` field of D9, and it **confirms that trace from the
|
||
client side**: the offset is per-customer and it is added to the making charge.
|
||
- `promotion.discount_percent` — from the promotion the server returned.
|
||
|
||
Two fields are sent as **literal constants with a `// how to get?!` comment**
|
||
(`cart.vue:181-182`): `wage_weight: 5.7856000000000005` and
|
||
`weight: 6.303744000000001`. The server ignores both — `setOrder` recomputes the
|
||
weight from `rash_weight`, and the `wage_weight` use is commented out
|
||
(`ApiMobileController.php:549-551`). Dead payload fields; logged as **DEAD-06**.
|
||
|
||
## What the server does with them
|
||
|
||
`ApiMobileController.php:536-541` computes the customer's **gold debt** directly
|
||
from the numbers in the request:
|
||
|
||
```php
|
||
$percent = ($item['percent_pay'] ?? 0) - ($item['discount'] ?? 0);
|
||
$gram = ($item['rash_weight'] ?? 0) + (($item['rash_weight'] ?? 0) * ($percent / 100));
|
||
return $gram * ($item['qty'] ?? 0);
|
||
```
|
||
|
||
Nothing is re-read from the database and nothing is validated. A crafted request
|
||
sets its own making charge, its own discount and its own weight — so the
|
||
reference lets a customer decide how much gold they owe.
|
||
|
||
## Consequence — per the owner's ruling
|
||
|
||
The app computes these values, so the ruling applies:
|
||
|
||
> «اگر اپ حساب میکند: اولین کار Phase 2 این باشد که سرور همان مقادیر را با همان
|
||
> منطق از DB بخواند و مقادیر کلاینت را نادیده بگیرد، با تست مقایسهای که نشان
|
||
> دهد نتیجه برای کاربر عادی یکسان است.»
|
||
|
||
**Phase 2, item #1** (recorded in `PROGRESS.md`):
|
||
|
||
1. The server derives, per line:
|
||
`wagePercent = customer.makingChargeOffsetPercent + variant.percentagePay`,
|
||
`discountPercent` from the applicable promotion, `flatRialCharge = 0`.
|
||
2. Client-sent values are **ignored**, and a warning is logged when they differ —
|
||
the same pattern already used for `customerId` in `orders.service.ts`.
|
||
3. **A comparison test** proves that for an ordinary customer the server-derived
|
||
values equal what the app sends today, so the total is unchanged.
|
||
4. The formula, its ordering and its rounding are untouched (D4).
|
||
|
||
This depends on `makingChargeOffsetPercent` existing, so the percent migration
|
||
must land first.
|
||
|
||
## `rash_weight` — accepted deviation
|
||
|
||
The reference trusts the client's `rash_weight` (`ApiMobileController.php:538`);
|
||
the target already reads the weight from the variant in the database. **Per the
|
||
owner's ruling the target's behaviour stays.** Recorded here as a deliberate
|
||
security deviation from the reference. The visible result is identical whenever
|
||
the client sends the true variant weight, which the reference app always does
|
||
(`cart.vue:178`); it differs only for a forged request, which is the point.
|
||
|
||
---
|
||
|
||
# D14 — Migration workflow, and the `customer_sync_full_name` trigger (2026-09-22)
|
||
|
||
## Workflow
|
||
|
||
| Environment | Command | Rule |
|
||
|---|---|---|
|
||
| Development | `npx prisma migrate dev` | the only way schema changes are applied |
|
||
| Production | `npx prisma migrate deploy` | **only** this — never `migrate dev`, never `migrate reset` |
|
||
| Anywhere | `prisma db execute` | **no longer used for schema changes** |
|
||
|
||
If `migrate dev` reports drift and offers a reset: **stop, do not accept, report
|
||
it.** `_prisma_migrations` is never edited by hand.
|
||
|
||
### What actually happened on 2026-09-22
|
||
|
||
`migrate dev` **refused to run**: it is interactive by design and this shell is
|
||
not a TTY. That is a safety property, not a problem — a reset prompt could never
|
||
be auto-accepted here.
|
||
|
||
Before falling back, drift was checked read-only with `prisma migrate diff`. It
|
||
reported one pre-existing difference that has nothing to do with this work:
|
||
|
||
```
|
||
-- DropTable
|
||
DROP TABLE "_goldbank_migrations";
|
||
```
|
||
|
||
`_goldbank_migrations` is a **bespoke ledger from the earlier port**, holding 12
|
||
historical rows (`0001_init.sql`, `seed:initial`, …). It is not in
|
||
`schema.prisma`, so Prisma considers it foreign and would drop it. **It was not
|
||
dropped.** Dropping it is a destructive operation, it is unapproved, and the
|
||
rows are the only record of how the pre-Prisma port was applied. Logged as
|
||
**DEAD-07**; leave it until the owner decides.
|
||
|
||
The two new migrations were therefore applied with **`migrate deploy`**, which
|
||
applies exactly the pending files and touches nothing else — so the drift was
|
||
neither "fixed" nor acted upon. Result: `11 migrations found. Database schema is
|
||
up to date!`
|
||
|
||
## The `customer_sync_full_name` trigger
|
||
|
||
Created by `20260922120000_customer_name_parts`. **Prisma does not know it
|
||
exists**, so a write through Prisma Client can produce a row different from what
|
||
was written. Documented in three places so the next developer cannot miss it:
|
||
the migration header, the `Customer` model doc comment in `schema.prisma`, and
|
||
here.
|
||
|
||
| Write | Result |
|
||
|---|---|
|
||
| the parts only | `fullName` is rebuilt as `first + ' ' + last` |
|
||
| `fullName` only | the parts are re-derived (first token / the rest) |
|
||
| **both in one statement** | **THE PARTS WIN**; the submitted `fullName` is discarded |
|
||
|
||
**Why the parts win.** After D0 the parts are what the three forms edit, so they
|
||
carry the operator's intent; `fullName` is the derived, legacy-facing value.
|
||
The opposite precedence would silently undo an edit made in the two boxes the
|
||
operator actually typed into.
|
||
|
||
Verified live by `apps/api/scripts/test-name-trigger.cjs` — 9 assertions across
|
||
all three directions plus insert, a multi-token name, and a no-op update. It
|
||
creates one temporary row and deletes it, reporting the deletion.
|
||
|
||
---
|
||
|
||
# D15 — `_goldbank_migrations` is kept, and the UTF-8 testing rule (2026-09-22)
|
||
|
||
## The table stays, declared and ignored
|
||
|
||
**Owner's ruling:** keep `_goldbank_migrations`, delete no row from it, declare
|
||
it in `schema.prisma` with `@@ignore` so `migrate diff` stops proposing a drop,
|
||
and explain why it is there.
|
||
|
||
Done — `model goldbank_migrations` at the end of `schema.prisma`, mapped to the
|
||
real table name, with `@@ignore` so it never enters Prisma Client.
|
||
|
||
**Verification:**
|
||
|
||
```
|
||
npx prisma migrate diff --from-schema-datasource --to-schema-datamodel --script
|
||
→ -- This is an empty migration. (drift: ZERO)
|
||
npx prisma migrate status
|
||
→ 11 migrations found. Database schema is up to date!
|
||
Prisma Client exposes it? no (@@ignore)
|
||
```
|
||
|
||
## ⚠️ Correction to the earlier DEAD-07 assessment
|
||
|
||
The previous entry called this table a leftover from the pre-Prisma port. **That
|
||
was wrong**, and investigating the ruling is what surfaced it.
|
||
|
||
`_goldbank_migrations` is the tracking table of **the application's own
|
||
migration runner**, `apps/api/src/prisma/migrate.ts:5`. That runner exists for a
|
||
real reason, stated at `migrate.ts:7-13`: the Docker deploy image is copy-only
|
||
and ships **no Prisma CLI**, so `migrate deploy` cannot run in the container.
|
||
The runner executes the same `.sql` files through Prisma Client instead and
|
||
records them here.
|
||
|
||
So the project keeps **two ledgers, deliberately**:
|
||
|
||
| Ledger | Written by | Used |
|
||
|---|---|---|
|
||
| `_prisma_migrations` | the Prisma CLI | development (`migrate dev` / `migrate deploy`) |
|
||
| `_goldbank_migrations` | `src/prisma/migrate.ts` | the deployed container, at boot |
|
||
|
||
That runner also **already defended this table**: `migrate.ts:190-196` filters
|
||
out any `DROP TABLE "_goldbank_migrations"` statement, with a comment noting
|
||
that `migrate diff` had once emitted exactly that. The `@@ignore` model now
|
||
removes the cause rather than relying on that guard.
|
||
|
||
**Consequence for D14:** `migrate deploy` remains the rule for production *when
|
||
run by hand*, but the container applies migrations itself at boot through
|
||
`prepareDatabase()`. Any new migration must therefore be safe under **both**
|
||
paths — which is why idempotent SQL (`IF NOT EXISTS`, `CREATE OR REPLACE`)
|
||
matters here beyond ordinary caution.
|
||
|
||
### Row count went 12 → 14, and nothing was deleted
|
||
|
||
Starting the API for the round-trip test ran `prepareDatabase()`, which appended
|
||
the two new migrations to this ledger:
|
||
|
||
```
|
||
2026-09-22T04:29:14.085Z 20260922120000_customer_name_parts
|
||
2026-09-22T04:29:14.101Z 20260922120100_customer_making_charge_offset
|
||
```
|
||
|
||
All 12 original rows are present and unmodified. The runner's `$$`-aware
|
||
statement splitter handled the PL/pgSQL trigger body correctly — the trigger and
|
||
its function are both present in the database, and the 9 trigger assertions pass
|
||
against it.
|
||
|
||
## Testing rule — Persian input always comes from a file
|
||
|
||
**Owner's ruling:** the Windows shell mangles Persian text, so any test with
|
||
Persian input (names, addresses, messages, validation) must read its data from a
|
||
**file** — the test file itself or a UTF-8 JSON fixture — never from a
|
||
command-line argument. Any earlier result that was wrong because of this must be
|
||
re-run.
|
||
|
||
### Why, concretely
|
||
|
||
A `curl -d '{"fname":"محمد علی"}'` issued through the shell arrived at the API
|
||
with every Persian character replaced by `?` (codepoint `0x3f`). The first
|
||
round-trip attempt therefore "passed" its internal consistency checks while
|
||
storing `????` — the API and DB agreed with each other, and both were wrong.
|
||
|
||
### What was re-run
|
||
|
||
The customer round-trip test, with the payload written by Node as UTF-8 and sent
|
||
with `curl --data-binary @file`. It then passed on real Persian text:
|
||
create «محمد علی» + «احمدی» → edit form shows each part correctly → no-op save
|
||
leaves the row byte-identical → single-field edits touch only that field. The
|
||
three rows from both attempts were deleted and logged.
|
||
|
||
### The rule going forward
|
||
|
||
- Fixtures live in the test file or in a `.json` written with `utf8` encoding.
|
||
- HTTP bodies are sent with `--data-binary @file`, not `-d '<inline>'`.
|
||
- Assertions compare against literals **in the test file**, never against a
|
||
string that has passed through the shell.
|
||
- Console output of Persian is not evidence: the Windows console renders it as
|
||
`?` even when the data is correct. Verify by comparing values or codepoints in
|
||
Node, as `scripts/test-name-trigger.cjs` does.
|
||
|
||
---
|
||
|
||
# D16 — Price display is storefront; new work order (2026-09-22)
|
||
|
||
## 1. PRICE-01 is stopped — price belongs to the retail storefront
|
||
|
||
**Owner's ruling.** Computing and displaying `price` / `price_with_discount` is a
|
||
**retail storefront (تکفروشی)** concern. The B2B app works in **making charge
|
||
(اجرت)** only. So PRICE-01 falls under D13 and is marked **⏸️ preserved — out of
|
||
current scope**.
|
||
|
||
| Item | Ruling |
|
||
|---|---|
|
||
| `apps/api/src/modules/pricing/variant-price.ts` | **Kept, not deleted.** Simply not used. |
|
||
| `variant-price.spec.ts` (11 hand-checked tests) | **Kept** and still runs in CI. |
|
||
| Any code wiring price into the admin panel | **Revert.** — *None existed: `computeVariantPrice` was never called from anywhere outside its own file and spec, so there was nothing to revert. Verified by grep over `apps/api/src` and `apps/admin-panel/src`.* |
|
||
| Making-charge fields — `percentage_pay`, `makingChargeOffsetPercent`, wage display | **Still fully in scope.** |
|
||
|
||
PRICE-01 in `ISSUES.md` is re-marked ⏸️ rather than deleted, so the analysis and
|
||
its evidence stay available if the storefront is ever taken up.
|
||
|
||
**Why this matters beyond one row:** the reference's `ProductVariant::$appends`
|
||
carries `price`, `color_str` and `price_with_discount` together
|
||
(`ProductVariant.php:115-119`). Only the price pair is storefront; anything else
|
||
appended there is still judged on its own merits.
|
||
|
||
## 2. The gate stands: admin first, then the apps
|
||
|
||
### Phase 1 — admin, in this order
|
||
|
||
**(a) Persons (اشخاص)**
|
||
1. The **5 missing sales-expert fields** (`ncode`, `phone`, `city_id`,
|
||
`gram_level`, `reagent_id`): **report first** — where the reference uses each
|
||
one for `type=1` — then add according to what that shows. Standing proposal:
|
||
a `SalesExpertProfile` related to `AdminUser` (D10). Fields with no use are
|
||
**listed for the owner to decide**, not added speculatively.
|
||
2. `singleCustomer` migrates to **diff-send** (D11).
|
||
3. Field-by-field audit of every form and grid in Persons — retail customer,
|
||
wholesale customer, sales expert — per D12, each with its round-trip test.
|
||
|
||
**(b) Products, categories, variants, and order detail in the admin** — deep
|
||
field-by-field: every form field, column, filter and button (D12).
|
||
- The **variant image picker stays untouched** (PROTECTED, `PROTECTED.md` §B);
|
||
only genuine omissions are added.
|
||
- The **making charge of every variant and every order line must display and
|
||
persist exactly as the reference does.**
|
||
|
||
**(c) The rest of the admin, in order:** financial documents → users and
|
||
permissions → admin SMS templates → promotions / notifications / cities /
|
||
branches / workshops → reports.
|
||
|
||
**(d)** Full admin test pass, the Phase 1 report, then the gate question
|
||
**«ادمین کامل و تست شد. بریم سراغ اپها؟»** — and **stop and wait**.
|
||
|
||
### Phase 2 — apps (only after the owner approves)
|
||
|
||
**(a)** The 5 v2-behind-v1 logic gaps, most important the **cart stock ceiling
|
||
(`capQty`/`maxQty`)**, matching v1 and the reference exactly — v2's design fully
|
||
preserved, with a test proving v1 and v2 behave identically.
|
||
|
||
**(b)** The missing screens (`report`, `report/detail`, `ChildOrder`,
|
||
`customerChoice`, `complete_profile`) in **both** apps, each in its own design,
|
||
plus whatever backend they need.
|
||
|
||
**(c)** Field-by-field audit of products, categories, variants, cart and order in
|
||
the apps.
|
||
|
||
**(d)** The remaining Phase 2 items: MON-08, removing `customerId` from the order
|
||
DTO, route analytics, the `isLoaded` / `sts_verify_step_two` guards, guest
|
||
behaviour, app SMS templates, and the remaining screens.
|
||
|
||
## 3. Working method per section
|
||
|
||
**Implement the gaps first, then field-by-field test that same section.** Before
|
||
fixing any section, **show the owner a short summary of the gaps found** and wait.
|
||
|
||
This supersedes the "audit everything, then fix everything" reading of D12: the
|
||
field-by-field requirement is unchanged, but it is applied **per section**, with
|
||
a checkpoint before each one.
|
||
|
||
---
|
||
|
||
# D17 — Sales expert: `SalesExpertProfile`, and `reagent_id` deliberately not ported (2026-09-22)
|
||
|
||
## `reagent_id` — deliberately NOT replicated
|
||
|
||
**Owner's ruling, verbatim:**
|
||
|
||
> «`reagent_id` در فرم کارشناس مرجع، اثر جانبی فرم مشترک `customers` بوده و پر
|
||
> کردنش کارشناس را از لیست قابلانتخاب حذف میکرد (`queryReagent:420`). عمداً
|
||
> پورت نشد. منطق معرف روی `Customer.referredByAgentId` کامل پیاده شده است.»
|
||
|
||
### The evidence behind it
|
||
|
||
`reagent_id` carries real logic in the reference — but **every single use reads a
|
||
CUSTOMER's `reagent_id`** (which agent introduced them), never a sales expert's
|
||
own:
|
||
|
||
| Use | Reference | What it does |
|
||
|---|---|---|
|
||
| Scope "my customers" | `AdminController.php:271` | `->where('reagent_id', $auth->id)` |
|
||
| Set on customer create | `AdminController.php:326` | records the introducing agent |
|
||
| Commission / gram-sold rollup | `MajorOrderController.php:267-269,316-318` | `updateGramSell($customer->reagent_id)` |
|
||
| SMS to the customer's agent | `ApiMobileController.php:727,750` | notify the agent |
|
||
| Analytics rollup | `AdminController.php:550-552` | `whereNull('reagent_id')` roots + their children |
|
||
|
||
A `grep` for any code reading `reagent_id` on a `type=1` row returns **nothing**.
|
||
|
||
**The decisive line is `queryReagent` (`AdminController.php:415-424`):**
|
||
|
||
```php
|
||
Customer::select(['id', 'name as title'])->whereNull('reagent_id')
|
||
```
|
||
|
||
Only rows **without** a `reagent_id` may be chosen as an agent. So filling the
|
||
`reagent_id` field on a sales expert's own form (`ReagentCustomer.vue:139`)
|
||
**removes that expert from the selectable-agent list** — an unwanted side effect
|
||
of the shared `customers` form, not a feature. The same `whereNull` filter shapes
|
||
the analytics rollup.
|
||
|
||
**Therefore:** the field is not added to `SalesExpertProfile`. Adding it would
|
||
either do nothing or reproduce that defect. No new hierarchy logic is invented.
|
||
|
||
Matrix annotation: **«عمداً تکرار نشد — D17»**.
|
||
|
||
### Confirmed: no agent can be dropped from the referrer dropdown
|
||
|
||
The owner asked for explicit confirmation. The target's agent list is
|
||
`queryReagents()` (`apps/api/src/modules/admin-customers/admin-customers.service.ts:779-786`):
|
||
|
||
```ts
|
||
this.prisma.adminUser.findMany({
|
||
where: { role: 'SALES_EXPERT', isActive: true },
|
||
orderBy: { fullName: 'asc' },
|
||
select: { id: true, fullName: true },
|
||
})
|
||
```
|
||
|
||
It filters on **role and active only** — there is no `whereNull` equivalent, so
|
||
**every active sales expert appears and none can be accidentally excluded.**
|
||
This is strictly better than the reference, whose `whereNull('reagent_id')`
|
||
silently hid any agent whose own `reagent_id` had been filled in.
|
||
|
||
Wiring: `admin-customers.controller.ts:82` → `GET admin/customers-omde/query/reagent`,
|
||
mapped at `apps/admin-panel/src/api/endpoints.ts:77`, consumed by
|
||
`bulkCustomer.vue:436`.
|
||
|
||
## `SalesExpertProfile` — approved shape
|
||
|
||
A separate table rather than columns on `AdminUser`, because these fields are
|
||
meaningful only for `role = SALES_EXPERT` and would be permanently null for every
|
||
other admin.
|
||
|
||
| Column | Type | Reference origin | Why |
|
||
|---|---|---|---|
|
||
| `adminUserId` | unique FK → `AdminUser` | — | one profile per expert |
|
||
| `cityId` | FK → `City`, nullable | `ReagentCustomer.vue:111` | a filterable grid column (`ReagentListModel.js:14`) **and** it drives the commission autofill |
|
||
| `gramLevel` | `Decimal(14,4)`, default 0 | `ReagentCustomer.vue:158` | the «سطح اعتبار» column, filterable (`ReagentListModel.js:17`) |
|
||
| `phone` | text, nullable | `ReagentCustomer.vue:95` | stored in the reference; no reader — added on the owner's instruction |
|
||
| `nationalCode` | text, nullable | `ReagentCustomer.vue:31` | same |
|
||
|
||
`phone` and `nationalCode` keep the reference's validation exactly:
|
||
`required: false`, message `لطفا مقدار را وارد کنید`.
|
||
|
||
## City-driven commission autofill
|
||
|
||
Ported verbatim from `henza_admin/src/views/apps/customer/ReagentCustomer.vue:215-228`:
|
||
|
||
1. On city selection, look for `percent` on the already-loaded city row.
|
||
2. If it is absent or falsy, `GET cities/get-percent-aux/{id}` and use the response.
|
||
3. Write the result into the form's `percent` field.
|
||
|
||
Backend: `AdminController.php` behind `admin.php:225-226`
|
||
(`cities/get-percent/{id}` and `cities/get-percent-aux/{id}`), reading
|
||
`cities.percent` / `cities.percent_aux` — both already present on the target's
|
||
`City` model as `percent` / `percentAux` (`schema.prisma` `model City`).
|
||
|
||
## `firstName` / `lastName` on `AdminUser`
|
||
|
||
Closes D0 requirement 7. Same pattern as `Customer`, applied to **all**
|
||
`AdminUser` rows, not only sales experts: additive columns, backfill
|
||
(first token → `firstName`, the rest → `lastName`), a sync trigger where **the
|
||
parts win** when both change in one statement, and a multi-token review report.
|
||
|
||
Every `fname: fullName, lname: ''` site is corrected — starting with
|
||
`listReagents` (`admin-customers.service.ts:375-376`).
|
||
|
||
---
|
||
|
||
# D18 — Standing approval (owner decision, 2026-09-22)
|
||
|
||
To reduce round-trips, the owner granted a **standing approval**. From now on the
|
||
following are done **without stopping and without asking**, with only a short
|
||
report at the end of each section before moving straight to the next:
|
||
|
||
- Implementing gaps whose reference behavior is unambiguous — a field, column,
|
||
filter, validation, message, button or page.
|
||
- Fixing target/reference mismatches where the reference behavior is clear.
|
||
- **Purely additive** migrations (a new column or table) on the development DB,
|
||
provided a dry-run inside a transaction with rollback is clean first.
|
||
- Writing and running tests.
|
||
- Applying the same fix to other sites of the same pattern (as with the six
|
||
extra `fname: fullName, lname: ''` sites found during D17).
|
||
|
||
**STOP and ask** only for:
|
||
|
||
1. Deleting any data, column, table, file or capability.
|
||
2. Any change to a PROTECTED zone or to the storefront surfaces of D13.
|
||
3. Any place the reference behavior is ambiguous or open to two readings.
|
||
4. Any place a reference bug is NOT being ported and that affects business
|
||
logic (the D17 situation).
|
||
5. A migration that alters existing data (backfill or update), unless it only
|
||
touches test data.
|
||
6. The Phase 1 end gate.
|
||
|
||
Everything else in DECISIONS, PROTECTED, D13 and D15 stays in force. In
|
||
particular this approval does **not** loosen: the ban on `migrate reset` or
|
||
touching `_prisma_migrations`, the CHANGELOG entry required for every data
|
||
deletion, or the UTF-8-from-file rule for tests with Persian input.
|
||
|
||
---
|
||
|
||
# D19 — Delivery Mode (owner decision, 2026-09-22)
|
||
|
||
The owner has a **delivery tonight**. Until further notice:
|
||
|
||
1. **No more deep field-by-field auditing and no more questions.** Implement the
|
||
main gaps and make sure the project works.
|
||
2. **The "admin first, then apps" gate is lifted for tonight.** Work on admin and
|
||
both apps in the priority order below.
|
||
3. **Nothing is deleted or changed** in PROTECTED zones, storefront (D13) areas,
|
||
data, features or designs. All earlier security rules remain in force.
|
||
4. **When a decision is needed, pick the lowest-risk option that breaks nothing**,
|
||
continue, and record it here rather than stopping to ask.
|
||
|
||
## Answers that closed the Persons audit
|
||
|
||
| Q | Ruling |
|
||
|---|---|
|
||
| A — `singleCustomer` diff-send | **Do not touch it** (D13 wins). **D11 is CANCELLED.** |
|
||
| B — lock `mobile` on edit | **Not ported.** The target keeps its current editable behaviour. Logged in ISSUES. |
|
||
| Gap 2 — `faToEn` on admin mobile | **Implement** (create and update). |
|
||
| Gap 1 — welcome SMS | **Implement**, byte-identical text, but non-blocking per D20. |
|
||
| Gap 4 — province/city tree | **ISSUES only.** |
|
||
| Gap 5 — Jalali birth date | **ISSUES only.** |
|
||
|
||
**D11 is superseded by this decision and must not be acted on.**
|
||
|
||
---
|
||
|
||
# D20 — SMS boot rule reversed, and a master OTP for delivery (2026-09-22)
|
||
|
||
## 1. SMS must never block anything
|
||
|
||
The rule from D14 — *"in production, if the SMS key is missing the server must
|
||
fail to boot with a clear error"* — is **REMOVED**.
|
||
|
||
New behaviour, in every environment:
|
||
|
||
* Missing credentials → log a **warning** and **boot normally**.
|
||
* `send()` with no credentials → **silently declines and logs**; it never throws.
|
||
* **No SMS, including the welcome SMS, may ever stop an operation.** Customer
|
||
creation succeeds whether or not the message goes out.
|
||
|
||
The live send test to the owner's number is **cancelled**; the SMS panel is not
|
||
a priority for this delivery.
|
||
|
||
## 2. `OTP_MASTER_CODE` — a manual login code for the delivery
|
||
|
||
A temporary bypass so login works during the demo.
|
||
|
||
| Rule | Detail |
|
||
|---|---|
|
||
| Source | **`OTP_MASTER_CODE` env var only.** Never hardcoded in source. |
|
||
| Default | Unset or empty → **completely disabled**. |
|
||
| Effect | When set, it is accepted for **any active customer's** mobile, **alongside** the real code, which keeps working. |
|
||
| Unchanged | Active-customer check, throttling and attempt limits all still apply. |
|
||
| Boot | When enabled, print a clear warning: `OTP_MASTER_CODE فعال است — قبل از انتشار اصلی حذف شود`. |
|
||
| Audit | Every login through it is logged **with the customer's mobile**. |
|
||
|
||
Tests required: master code logs in; with the env var absent the same code is
|
||
rejected; the real code still works.
|
||
|
||
**Before the real release: remove `OTP_MASTER_CODE` from the environment and
|
||
configure the SMS credentials.** Recorded in `DELIVERY.md` and as a Critical
|
||
entry in `ISSUES.md`.
|
||
|
||
---
|
||
|
||
# D21 — Sales-expert login to the customer apps (owner decision, 2026-09-23)
|
||
|
||
The owner required that a sales expert be able to sign into the customer apps,
|
||
**without** reversing D17 (the expert stays an AdminUser, never a Customer).
|
||
|
||
## The problem
|
||
|
||
In the reference a sales agent WAS a Customer row (`customers.type = 1`), so:
|
||
|
||
* they logged in through the ordinary customer flow and got the whole app;
|
||
* `setOrder` did `Customer::findOrFail(auth()->id())` and read that row's
|
||
`gram_level` (`ApiMobileController.php:534-535`) — the agent's own order, own
|
||
credit limit, own ledger;
|
||
* `getChildOrder` filtered `where('reagent_id', auth()->id())`
|
||
(`:767`) and `myChild` the same (`:188`) — the logged-in customer's id.
|
||
|
||
Here the expert is an AdminUser, which has **no ledger and no credit limit** and
|
||
cannot be an `Order`'s subject (`Order.customerId` is a required FK).
|
||
|
||
## The design
|
||
|
||
**One token family, two principals.** The app token's `typ` claim is either
|
||
`'customer'` or `'sales-expert'`; `customer-jwt.strategy.ts` resolves both to
|
||
one shape whose `id` is **always a Customer id**. Every route already written
|
||
for a customer therefore works unchanged for an expert — which is exactly what
|
||
the reference gave them.
|
||
|
||
**A trading account.** Each expert gets **one** linked Customer row
|
||
(`SalesExpertProfile.tradingCustomerId`, additive migration
|
||
`20260923120000_sales_expert_trading_customer`), created lazily at their first
|
||
`request-otp`. It carries only their own trading position.
|
||
|
||
### Answering the owner's question — whose name, and from where
|
||
|
||
| Question | Answer | Source |
|
||
|---|---|---|
|
||
| An order the expert places is **whose**? | Their **own trading account** — not a customer's | Reference: the agent's order was their own row |
|
||
| Its **making charge**? | `AdminUser.wagePercent` → `makingChargeOffsetPercent` | Reference: the agent's `customers.percent` |
|
||
| Its **credit limit**? | `SalesExpertProfile.gramLevel` → `goldCreditLimitGrams` | Reference: `$customer->gram_level` (`:535`) |
|
||
|
||
Both numbers are the same two the reference read off the agent's own Customer
|
||
row, so the behaviour matches; only the storage location differs. Seeded at
|
||
creation and not resynchronised afterwards — an operator editing the expert's
|
||
commission changes it for their referred customers, and changing an existing
|
||
trading account's terms silently is a money change nobody asked for.
|
||
|
||
## Scope rules
|
||
|
||
* `Customer.referredByAgentId` points at the **AdminUser**, so "my customers"
|
||
and "my customers' orders" scope on `me.adminUserId`, taken from the token.
|
||
An expert can never see another expert's customers (tested, both directions).
|
||
* The trading account has `referredByAgentId = null` — an expert is not their
|
||
own referred customer.
|
||
* Child orders keep the reference's `sts = 5` filter as
|
||
`status = DELIVERED_TO_AGENT` — the same «تحویل مسئول فروش» point.
|
||
* Both expert routes 403 for an ordinary customer, and `expert/whoami` lets the
|
||
apps hide the menu entries. The server does not rely on the UI hiding them.
|
||
|
||
## Token boundaries (all tested)
|
||
|
||
| Token | On | Result |
|
||
|---|---|---|
|
||
| expert app token | admin route | **401** |
|
||
| customer token | admin route | **401** |
|
||
| admin token | expert route | **401** |
|
||
| expert token, after deactivation | expert route | **401**, immediately |
|
||
|
||
`jwt.strategy.ts` gained an explicit check that rejects any token carrying an
|
||
app `typ`. This matters because an expert's app token holds their **AdminUser
|
||
id** in `sub`: `JWT_CUSTOMER_SECRET` falls back to `JWT_SECRET` when unset, and
|
||
in that configuration the token would otherwise have validated as an admin and
|
||
been handed full panel permissions.
|
||
|
||
## Deliberately NOT ported
|
||
|
||
`myChild` minted an `api_token` for every listed customer as a side effect
|
||
(`ApiMobileController.php:197-201`), which let an agent act **as** that
|
||
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
|
||
the **expert wins**. Since `Customer.mobile` is unique, the code adopts the
|
||
existing customer row as the expert's trading account rather than failing the
|
||
login or creating a duplicate, and logs a warning.
|
||
|
||
---
|
||
|
||
## D22 — «تکمیل پروفایل» (complete_profile), 2026-09-23
|
||
|
||
Ports `POST /major/complete`
|
||
(henza_server `Major/CustomerController::complete`, reached from
|
||
`henza_pwa/src/views/user/src/completeProfile.vue`) as
|
||
`POST customer/me/complete-profile`.
|
||
|
||
**Reference behaviour kept**
|
||
- all three document ids required; a miss is rejected before anything is written
|
||
- the customer comes from the session, never from the body (D21)
|
||
- the verification step is set to the reference's **live** value 2 — approved
|
||
outright, not "waiting for an expert". The reference's own
|
||
`sts_verify_step_two = 1` line is commented out at `:83` in favour of `= 2`
|
||
at `:85`. That is `VerificationStep.VERIFIED` here.
|
||
- both SMS messages byte-identical, and non-blocking per D20
|
||
- the entry point is the **profile screen**, shown only while the documents are
|
||
missing (`profile.vue:96-102`), and the route redirects home once they are in
|
||
(`router/index.ts:266`)
|
||
|
||
**Reference behaviour deliberately NOT ported** (all in ISSUES.md)
|
||
- **SEC-14** — `$customer->update($request->all())` mass-assigned the whole
|
||
request body, letting the app write its own credit limit, making charge, gold
|
||
debt, active flag or mobile. Replaced with a three-field whitelist.
|
||
- **SEC-15** — four real personal mobiles hardcoded in the source. They come
|
||
from `PROFILE_ADMIN_MOBILES` instead; blank means nobody is notified.
|
||
- **APP-03** — `refresh()`'s unterminated `setInterval` page reload.
|
||
|
||
**One gap had to be closed first (UPL-01).** The reference let the app upload
|
||
through the same `file/create` the admin used, inside its `auth:api-customer`
|
||
group; the target's copy is admin-guarded. Added `POST customer/me/documents`,
|
||
reusing `AdminUploadsService` unchanged so both paths share one size limit,
|
||
MIME whitelist and naming scheme.
|
||
|
||
## D23 — `JWT_CUSTOMER_SECRET` warns loudly, 2026-09-23
|
||
|
||
`customerJwtSecret()` falls back to `JWT_SECRET`. When it does, app and admin
|
||
tokens are signed with the **same key**, leaving the `typ` check in
|
||
`jwt.strategy.ts` as the only barrier — and an expert's app token carries their
|
||
AdminUser id in `sub`. The owner asked for a refusal to boot **or** a very
|
||
clear warning; the lower-risk option was chosen (D19), since failing the boot
|
||
could take down a running deployment that has not set the variable yet. A
|
||
banner as loud as the master-OTP one now fires at boot, and DELIVERY.md lists
|
||
it as the **first** pre-release step (REL-03).
|
||
|
||
## D24 — «گزارش» (report + report/detail) on the internal ledger, 2026-09-23
|
||
|
||
**In the reference this feature computes nothing.** `Customer\TahesabController`
|
||
(henza_server `app/Http/Controllers/Customer/TahesabController.php`) forwards
|
||
every call to an external accounting system — `hesab.henzagold.com` and a bare
|
||
IP at `31.7.68.147:3030` — with `Http::withoutVerifying()` (TLS verification
|
||
off), a bearer token hardcoded in the source and a URL-embedded `sfx` secret,
|
||
keyed on `Customer.mcode`, the customer's id in that other system. The PWA
|
||
renders whatever comes back.
|
||
|
||
The target has no such system and no `mcode`. **The owner chose option الف:**
|
||
build the reference's UI and flow over our own ledger, with no external
|
||
connection. So `customer/me/report*` reproduces the statement's SHAPE — the
|
||
field names `henza_pwa/src/type/accounting.ts` declares, so the ported
|
||
components bind unchanged — from `LedgerEntry`.
|
||
|
||
**Honesty rule.** Every figure is computed from confirmed ledger entries.
|
||
Where the external system carried a column the target has no equivalent for
|
||
(foreign currency, وزن پلاستیک, نام کارساخته, جنس فلز and its internal
|
||
bookkeeping ids), the field is `null`/zero and the UI **omits the row** rather
|
||
than rendering a fabricated value. Recorded as REP-01.
|
||
|
||
**Two things the target does better, deliberately:**
|
||
- Only **confirmed** entries count, the same rule the cached
|
||
`Customer.goldDebtGrams` / `fiatDebtRial` follow — so the statement's closing
|
||
balance agrees with the figure shown everywhere else in the app. Asserted by
|
||
the test.
|
||
- **SEC-16:** the reference's `detail($id)` took the factor code from the URL
|
||
and performed **no ownership check whatsoever** — it never looks at `auth()`
|
||
— so any signed-in customer could read any other customer's document by
|
||
guessing a code. Here the id is only ever a filter on top of a `customerId`
|
||
scope, so someone else's id returns nothing. Tested in both directions.
|
||
|
||
The reference gated the page on `myStore.hasMCode()`; with no mcode in the
|
||
target the gate is simply a session, and the server scopes every row to the
|
||
token.
|
||
|
||
## D25 — blank env vars are treated as unset, 2026-09-23
|
||
|
||
Found by the pre-delivery compose run (DEPLOY-02): **admin login returned 500
|
||
for every user in Docker.** `docker-compose.yml` passes each optional variable
|
||
as `${X:-}`, so an unconfigured one arrives as `""`, not `undefined`. The code
|
||
read them with `process.env.X ?? 'default'`, which only falls back on
|
||
`undefined` — so the empty string won and `jsonwebtoken` threw on every sign.
|
||
|
||
Invisible to every existing suite, all of which ran against a local dev process
|
||
where the variable is genuinely absent.
|
||
|
||
`src/common/env.ts` now provides `envOr` / `envOrNull`, which treat blank as
|
||
unset, and every auth, port, upload and SMS read uses them. Three of those were
|
||
not merely cosmetic: a blank `UPLOAD_DIR` would have served static files from
|
||
the **filesystem root**, a blank `PORT` would have bound a random ephemeral port
|
||
(`Number('') === 0`), and a blank `JWT_SECRET` would have become the verifying
|
||
key. Pinned by `src/common/env.spec.ts`, which reproduces the original throw
|
||
against the real `jsonwebtoken` and asserts the reader can no longer produce it.
|
||
|
||
**Standing rule from here on:** read an environment variable with `envOr` /
|
||
`envOrNull`, never with `??`, unless an empty string is a meaningful value for
|
||
that specific variable.
|
||
|
||
## D26 — SMS through the owner's relay gateway, drivers per provider, 2026-10-05
|
||
|
||
The owner supplied the PHP client of their own SMS gateway — a relay at
|
||
`http://185.231.112.101/api/createsms` that handles SMS for several panels and
|
||
apps. Owner rulings:
|
||
|
||
| Topic | Ruling |
|
||
|---|---|
|
||
| Default | The relay **replaces Trez as the default**. Trez is **kept**, selectable with `SMS_PROVIDER=trez`; more providers may follow. |
|
||
| Secret | The `secret_key` **lives in source** as the default. The gateway has a second verification factor held elsewhere, so the owner does not treat it as sensitive. `SMS_RELAY_SECRET` overrides it. (Contrast SEC-12, where the Trez credentials stay env-only.) |
|
||
| Platform | **Every** message goes through Kavenegar (`platform: "kave"`). |
|
||
| Host | The server's own IP is correct, as in the PHP client; `SMS_RELAY_HOST` overrides it. |
|
||
| Address | The IP over HTTP is correct. HTTPS on that IP presents an expired `*.montpar.ir` certificate (checked 2026-10-05), so HTTPS is not usable on the IP; `SMS_RELAY_URL` can switch later. |
|
||
| Replies | Undocumented; left to the implementation. A 2xx counts as sent unless the JSON body says `status: false`, `success: false`, `ok: false`, `status: "error"`/`"failed"` or carries `error`. |
|
||
|
||
Implementation: `apps/api/src/modules/sms/drivers/` — one `SmsDriver` per
|
||
provider (`relay.driver.ts`, `trez.driver.ts`) registered in `drivers/index.ts`.
|
||
A new provider is one file plus one registry line. `SmsService` keeps the
|
||
cross-provider rules: trim, persist every message (SEC-11 for OTP unchanged),
|
||
log failures and never throw (D20). Plan: `docs/SMS-RELAY-PLAN.md`.
|
||
|
||
Consequence: with no SMS variables set, **every environment now sends real
|
||
SMS**, local development included. Set `SMS_PROVIDER=none` on a machine that
|
||
must not send.
|
||
|
||
## D27 — accounting integration (Tahesab / Zarrin), switchable from the admin panel, 2026-10-05
|
||
|
||
The owner wants the app connected to the shop's accounting software, and the
|
||
software differs per installation: **Tahesab** or **Zarrin**, picked with one
|
||
switch in the admin panel (`none | tahesab | zarrin`). Plan and the full API
|
||
survey: `docs/ACCOUNTING-INTEGRATION-PLAN.md`. Owner rulings:
|
||
|
||
| Topic | Ruling |
|
||
|---|---|
|
||
| Scope | Customer sync, balance sync, order documents, and ready-made items (کارساخته) ↔ products. **Everything else stays in the app** — repayment documents (melted gold, cash, cheque) are not sent. |
|
||
| Balance | The accounting balance is **shown to the customer**; the **credit-limit check stays on the internal ledger**. |
|
||
| Report | «گزارش» reads from the accounting software when the integration is on, so it agrees with the balance shown. Supersedes D24 for that case only; D24 remains the fallback. |
|
||
| Customers | Created in the accounting software when an admin marks them **VERIFIED**; existing ones are linked by **mobile**. Accounts that exist only in the accounting software are **created in the app**, keyed by mobile (national code falls back to the mobile, as elsewhere). |
|
||
| Documents | Sent at the debt-recognition point (`DELIVERED_TO_AGENT`) as **temporary** (موقت) documents for the accountant to finalise. Ready-made items only for now; gold/coin trading later. |
|
||
| Products | One accounting کارساخته = one app **Product**. Title, code and stock belong to the accounting software; images, description, variants, category and **making charge belong to the app**. |
|
||
| Visibility | **A product with no image is never shown in the app** — all products, automatically. |
|
||
| Stock | Accounting stock is shown in the admin panel; at zero the product is unavailable in the app (pre-order variants excepted). |
|
||
|
||
Security carried over from the reference's mistakes (SEC-06/16/17): TLS
|
||
verification is never disabled (a custom CA can be supplied instead), the
|
||
token is write-only and encrypted at rest with `ACCOUNTING_SECRET_KEY`, the
|
||
generic `const` settings routes refuse `accounting.*` keys, and statement
|
||
details are scoped to the token's own customer.
|
||
|
||
Later rulings, same day (plan §11–§12, ACC-08/09): sync is real-time (change
|
||
feed polled every 5 s, sends right after commit, order-time live stock that
|
||
falls back to the last known figure); sync buttons on the wholesale-customer
|
||
and product lists and a live balance on the app profile, all working whenever
|
||
a provider is connected regardless of the feature switches; and the order
|
||
status that posts the temporary document (پیشفاکتور) is an admin-chosen rule
|
||
(`documents.triggerStatus`, default «تحویل مسئول فروش»).
|
||
|
||
---
|
||
|
||
## D28 — ورود اپ باید خطای واقعی را بگوید (۲۰۲۶/۱۰/۱۲)
|
||
|
||
**گزارش مالک:** «اگر کاربری در اپ نبود خطا نمیدادی کاربر یافت نشد میبردیش توی
|
||
صفحه ارسال کد و واقعا نمیشد فهمید خطا از پروژه هست یا نه پیامک نمیاد یا نه واقعا
|
||
نیست میخوام خطا بدی کاربر یافت نشد»
|
||
|
||
**تصمیم:** مرحله اول ورود باید علت را بگوید.
|
||
|
||
| حالت | قبل | بعد |
|
||
|---|---|---|
|
||
| شماره ثبت نشده | `{ sent: true }` — کاربر به صفحه کد میرفت | **۴۰۴** «این شماره در سیستم ثبت نشده است…» |
|
||
| پیامک فرستاده نشد (درگاه خراب) | `{ sent: true }` | **۵۰۳** «ارسال پیام کوتاه در حال حاضر ممکن نیست…» |
|
||
| کارشناس فروش با حساب معاملاتی غیرفعال | `{ sent: true }` | **۴۰۳** «حساب شما غیرفعال است…» |
|
||
| کارشناس فروش بدون پروفایل | `{ sent: true }` | **۴۰۳** «حساب شما کامل نیست…» |
|
||
|
||
**نسبت با مرجع:** این همان کاری است که مرجع میکرد (`firstOrFail()` در
|
||
`ApiMobileController::userAuth:43` ⇒ ۴۰۴). پاسخ مبهم، انحراف ما بود نه این.
|
||
|
||
**معاوضه امنیتی، صریح:** پاسخ مبهم برای این بود که کسی از بیرون نتواند بفهمد چه
|
||
شمارههایی در سیستم ثبتاند. این محافظت در مرحله اول کاهش یافت، **عمداً و به
|
||
دستور مالک**، چون هزینهاش را کاربران واقعی و پشتیبانی میدادند. چیزی که سر جایش
|
||
ماند: سقف تعداد ارسال برای هر شماره و هر IP (`assertSendAllowed`) که مرجع
|
||
نداشت — پس شمارشکردن شمارهها محدود است نه آزاد؛ و مرحله دوم (`verifyOtp`) که
|
||
برای همه علتهای شکست یک پیام واحد میدهد.
|
||
|
||
**چرا D20 اینجا نقض نمیشود:** D20 میگوید پیامک ناموفق نباید یک *عملیات* را
|
||
خراب کند — سفارش باید ثبت شود حتی اگر پیامکش نرود. در ورود، پیامک **خودِ
|
||
عملیات** است، پس سکوت از چیزی محافظت نمیکند.
|
||
|
||
ثبت شده در `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.
|
||
|
||
## D30 — بخشهای «فقط سوپر ادمین» در پنل مدیریت (۲۰۲۶/۱۰/۱۴)
|
||
|
||
**خواسته مالک:** این بخشها فقط به سوپر ادمین (۰۹۱۲۸۰۸۱۳۹۲) نشان داده شوند و در
|
||
سطح دسترسیها هم نباشند: لیست مشتریان تک، لیست بنکداران، لیست مغازهداران حضوری،
|
||
شعب و کارگاه، تب «مشتری تک» در افزودن شخص، فیلد «سینی ها» در فرم محصول، ثبت
|
||
سفارش تک و لیست سفارشهای تک، «افزودن تخفیف تک»، و «مدیریت کیف پول».
|
||
|
||
**پاسخهای مالک:**
|
||
- سوپر ادمین = **فقط حساب با موبایل ۰۹۱۲۸۰۸۱۳۹۲**، نه هر ادمینی که نقش `SUPER_ADMIN` دارد.
|
||
- اعمال **کامل**: مخفی در پنل + بستن آدرس مستقیم صفحه + ۴۰۳ از API.
|
||
- «سینی ها» در **هر دو جا**: فیلد فرم محصول و تب «مدیریت ثابت ها».
|
||
- تخفیف تک: **افزودن + ویرایش + حذف**، و هر سه از سطح دسترسیها حذف.
|
||
|
||
**سازوکار.** `@SuperAdminOnly()` در `apps/api/src/modules/auth/guards.ts`، که
|
||
`PermissionsGuard` سراسری آن را اعمال میکند؛ شماره و فهرست rid ها در
|
||
`auth/super-admin.ts`. به سوپر ادمین rid های این بخشها همیشه داده میشود
|
||
(`withSuperAdminRids`) تا با ذخیرهی دوبارهی سطح دسترسیاش از دست نروند. در پنل:
|
||
`users.isSuperAdmin` (از `is_super_admin` در login و `users/show`)، `superAdminOnly`
|
||
روی منو و route، و حذف این rid ها از درخت صفحه دسترسیها برای غیر سوپر ادمین.
|
||
|
||
**تصمیمهای جانبی (برای نشکستن چیزهای دیگر):**
|
||
- **پنل شعبه** همان endpoint های مشتری تک و سفارش تک را صدا میزند؛ این endpoint ها
|
||
برای ادمینِ دارای `branchId` هم باز ماند (`allowBranch`). بدون این، کارکنان شعبه
|
||
قفل میشدند. پیامد: ادمینی که شعبه دارد از API به این چهار endpoint دسترسی دارد.
|
||
- **سوپر ادمین در درخت دسترسیها همه را میبیند** تا بتواند این rid ها را به سطح
|
||
دسترسی کارکنان شعبه بدهد. دیگران آنها را نمیبینند، و rid هایی که سطح از قبل
|
||
دارد هنگام ذخیره توسط آنها **حفظ** میشود (حذف بیصدا نمیشود).
|
||
- `admin/orders/:id`، `status` و `status-options` بین سفارش تک، عمده و تامین مشترکاند
|
||
و `order.list` میخواستند؛ حالا هر کدام از `order.list` / `order.omde` / `order.tamin`
|
||
کافی است (`RequirePermission` چند rid میپذیرد).
|
||
- لیست کارگاهها (`admin/workshops/list`) **باز ماند**: انتخاب کارگاه در «سفارش های
|
||
ساختنی» از آن است. بقیهی endpoint های کارگاه و همهی شعب بسته شدند.
|
||
- **تخفیف تک فقط در پنل بسته شد، نه در API**: API تک و عمده را از هم تشخیص نمیدهد
|
||
(PROMO-TAK-01).
|
||
- بنکداران/مغازهداران و سینیها rid مشترک با بخشهای دیگر دارند (`persons.list.client.omde`،
|
||
`collection.*`)؛ پس از درخت حذف نشدند و با `@SuperAdminOnly` / `isSuperAdmin` بسته شدند.
|