# Lessons

## 2026-03-25 — Branch hygiene
- If the user asks to work on the current branch, do not create a new branch.
- If a new branch was created by mistake, immediately switch back to the requested branch and delete the accidental branch after confirming changes are preserved.

## 2026-03-30 — Clarify before removing UI filters
- When the user asks to “remove” a filter, confirm whether they mean: remove entire filter UI, remove an option, or limit options.
- Prefer changing filter options first (e.g., keep only store/haraj) rather than deleting the whole filter.

## 2026-07-24 — Preserve requested dashboard labels
- Use the exact concise label requested by the user; do not add domain qualifiers such as “الطلب” unless requested.

## 2026-07-25 — Product attribute linking
- Product links Attribute via `attributes` and AttributeValue via `variants.size` / `variants.color` (plus `variants.attribute`).
- Do not put AttributeType on Product — size/color come from AttributeValue.kind, not AttributeType.
- Do not keep a flat `attributeValues` array; variants already own those refs.

## 2026-07-26 — Provider Home contract
- Prefer `/provider/home` over legacy `/home-provider` when the Figma home is order-centric.
- When the user asks to remove sliders, omit the `sliders` key entirely from the response and OpenAPI schema.

## 2026-07-26 — Product attributes populate
- After removing Product.attributes, also remove `{ path: 'attributes' }` from Product pre(/^find/) and post('save') populate lists, or StrictPopulateError breaks every Product.find.
- For existence checks in Favorites, prefer `countDocuments` over `findOne` to avoid heavy auto-populate.

## 2026-07-26 — Preserve Swagger grouping
- Adding pagination or Figma metadata must not move an existing endpoint to a different Swagger tag.
- Keep `/intros` under `Common`; only its contract and design links should change.

## 2026-07-26 — Dual-auth Swagger style
- Any endpoint that accepts both client and provider tokens must follow the `/profile` pattern:
  - security OR: `{ SecretKeyAuth + ClientBearerAuth }` | `{ SecretKeyAuth + ProviderBearerAuth }`
  - description bullets stating bearer actor type and that credentials are never mixed
  - `419` unauthorized example
  - preferably separate `examples.client` / `examples.provider` when the payload can differ by actor

## 2026-07-26 — Legacy location title/description strings
- Older provider/client locations store `title`/`description` as plain strings; current Auth writes `{ ar, en }`.
- Nested `{ ar, en }` schema paths cast-fail on strings (`Cannot create property 'ar' on string`) and Mongoose drops the whole `location` subdoc on Document/populate reads.
- Aggregation / `.lean()` hide the bug; Document `.populate()` surfaces empty location DTOs.
- Keep `location.title`/`description` as `Mixed` (normalize strings on set) so Document reads keep coordinates + text.

## 2026-07-26 — Push notification title is the project name
- `objSendNotify` intentionally prefers settings `siteName` over any supplied `title`; keep it that way.
- Provider broadcast accepts only `message`; the title is read from `Setting.siteName` so the brand name always shows.

## 2026-07-26 — Request filters do not imply response metadata
- When a query parameter selects data (such as ratings `type`), do not add it to the response unless explicitly requested.
- Apply omitted query defaults internally; never invent sentinel response values such as `all`.

## 2026-07-26 — Split Rate list DTOs by type
- Provider `GET /rates` uses `toUserRateDto` (`providerRate`) and `toProductRateDto` (`productRate`).
- List card DTO matches Figma only: `id`, `name`, `date`, `rate`, `comment` — not the full Rate model tree.
- Do not add empty `product` or `provider` objects when the design does not display them.
- Keep full `ratings` for create/detail and client-owned lists.

## 2026-07-29 — Verify persisted cron rows and notification interpolation
- A scheduled in-memory timer is not proof that the CronJob row was persisted; make `addCronJobToDB` return the upserted row and propagate database errors.
- New timeout settings on old Settings documents need an operational Mongoose default, otherwise a zero fallback silently disables the requested cron.
- In `objSendNotify`, avoid duplicate object keys: the later `orderNumber` key previously overwrote the correctly resolved nested value with an empty string.
- Verify notification text and payload against the real nested shape (`data.data.orderNumber`), not only the sender-side object.

## 2026-07-29 — Auto-cancel notification names the assigned store
- For a store-order approval timeout, identify the assigned store in the message instead of using legacy “nearby providers” wording.
- When adding `{{providerName}}` to i18n copy, pass `order.provider.name` in the notification data and test the fully interpolated Arabic sentence.

## 2026-07-29 — Restore order work from the final chat state
- If order files are deleted or reverted, recover the latest intended state from the transcript and existing contract tests, not from an older intermediate implementation.
- Verify route → controller → helper method names together, plus order timeout hooks and OpenAPI/Postman grouping.

## 2026-07-30 — Order route files are the final contract
- Treat the approved `OrderRoute.js` and `ReturnRequestRoute.js` shapes as the source of truth when documentation or older tests disagree.
- Final delivery paths are `/order/delivered`, `/order/received`, `/return-request/delivered`, and `/return-request/received`; identifiers are query parameters, never path parameters.

## 2026-07-30 — Design links require explicit user input
- Add design links only when the user supplies them for the current endpoint or feature.
- For every supplied link, verify it already exists in the relevant source and generated documentation; add it only when missing.
- Never infer, reuse, or invent a Figma/design link when the user did not provide one.

## 2026-07-30 — Add only user-supplied design links
- When the user sends Mobile/Web design links, verify whether they already exist in both the OpenAPI source and the served documentation artifact; add only any missing links.
- Never infer, reuse, or invent a design link for an endpoint when the user has not supplied one.