tehran_tala/docs/parity/DECISIONS.md

# 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`.