docs(decisions): record 0029–0033

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Amiram_se 2026-10-08 22:36:22 +04:00
parent 3b8c95a94e
commit 381e01e030
6 changed files with 120 additions and 0 deletions

View File

@ -0,0 +1,23 @@
# 0029 Every payment ends on its result page
Status: Proposed · Area: architecture · Date: 2026-10-08 · Decided by: agent
## Context
U10 §۹ (Oct 2026) ends every payment on one result page. The API, not the front, verifies with the bank: its `/payments/callback` redirects the browser to `CHECKOUT_SUCCESS_URL`, `CHECKOUT_CANCEL_URL` or `CHECKOUT_PENDING_URL` with `?paymentId=&status=`.
## Decision
- Set those three API URLs to the site's `/payment/return` (`ROUTES.paymentReturn`). The page shows «در حال تأیید پرداخت...», reads the payment every 2 s until it is settled, then `router.replace`s itself with `/payment/result/[paymentId]` (`ROUTES.paymentResult`). After 30 s it moves on anyway, and the result shows «در حال بررسی».
- Subscribe, renew and reactivate all end there, including a development grant (no bank).
- Both pages render in the browser behind `AuthGuard role="investor"`; the return page's skeleton is the confirming screen itself.
## Alternatives
- Return straight to checkout or the channel with a toast (U9 ۵.۲, U10 ۱.۲): superseded by the design.
- Point the API at the result page: its callback appends a query string, not a path segment.
## Consequences
- Each deployment's API env must name the right site; bull and bear share the URL, and the edge routes by device.
- The in-sheet renew success and failure states (R3 03, 04) are not built: the result page replaces them.

View File

@ -0,0 +1,22 @@
# 0030 The last checkout's period and code survive the bank
Status: Proposed · Area: architecture · Date: 2026-10-08 · Decided by: agent
## Context
Back from the gateway and «تلاش دوباره» on a failed result must reopen checkout with the same period and invite code (U10 ۶.۳, ۹.۲). The browser leaves the app for the bank, so memory is lost unless bfcache keeps the page.
## Decision
- `stores/checkout-draft` is a persisted zustand store, `session.checkout-draft`, holding one `{ creatorId, tierId, referralCode, paymentId }`; `paymentId` is the payment sent to the bank, kept until it is settled (0033).
- `startCheckout` and `startRenewal` write it once a payment exists (redirect or grant); the result page clears it on success; checkout restores it once, for the same creator, when the form is untouched; logout clears it.
- A page restored from bfcache resets its pay button and reads its screen again (`pageshow`).
## Alternatives
- Period and code in the URL: an invite code would land in history, logs and shares.
- Ask the API to return the code with the payment: not available.
## Consequences
- The invite code sits in local storage until success or logout; it is a creator's shared invitation, not personal data.

View File

@ -0,0 +1,20 @@
# 0031 Renew and reactivate list periods as TierOption cards
Status: Proposed · Area: design · Date: 2026-10-08 · Decided by: agent
## Context
R3 01–06 draw the renew and reactivate sheet's periods as a two-column chip grid with the price under each name. U9 (Oct 2026) made island `TierOption` the one tier card, with the per-month line and the saving against monthly.
## Decision
The renew and reactivate sheet (and modal on desktop) lists the creator's periods as `TierOption` radio cards in one column, as checkout does; the dates panel, price-changed note, total and pay button follow them as drawn.
## Alternatives
- A new island chip-radio for the grid: a second way to show the same tier, with less information.
## Consequences
- The sheet is taller than R3 draws; it scrolls inside at 85% height.
- A live promotion applies to renew and reactivate as it does to subscribe (product rule, Oct 2026), so each card shows its discount tag and countdown, as R3 01 and the terms' §۵ do.

View File

@ -0,0 +1,21 @@
# 0032 The notification centre is a page on mobile and a panel on desktop
Status: Proposed · Area: architecture · Date: 2026-10-08 · Decided by: agent
## Context
U5 §۲ opens the centre from a bell in the top bar: a full-screen pushed page on mobile, a 400px side panel on desktop. Same URL tree in bull and bear (0001).
## Decision
- `ROUTES.notifications` (`/notifications`) is a `(main)` page in both apps; bull's bell links there, and bear renders it in the 640 column for a direct visit.
- bear's header bell opens `NotificationPanel` (island `Sheet placement="side"`), loaded with `next/dynamic` on the first click; it closes when an item leads to another page.
- The bell shows for a member of either role on tab bars and the desktop header, never on pushed bars; its count is a browser-only query, and opening the centre marks all read.
## Alternatives
- A panel on mobile too: the design asks for a page.
## Consequences
- Items render the server's Persian title and body; a creator link (`/traders/<profileId>`) is looked up before navigating.

View File

@ -0,0 +1,29 @@
# 0033 A payment left at the bank is settled when the investor comes back
Status: Proposed · Area: architecture · Date: 2026-10-08 · Decided by: agent
## Context
An investor who backs out of the gateway (back button) never reaches `/payment/return`, so the payment stays `pending` and blocks a new one until the API reviews it (checkout answers `pending_review`, subscribe 409). U10 ۶.۳ expects checkout to be untouched. The API settles such a payment on request: `POST /subscriptions/payments/:id/abandon` asks the bank and answers `completed`, `abandoned`, `pending` or `closed`. A bank that has not been paid yet answers "not paid", so the request must never be sent while the bank's page may still be open.
## Decision
- The payment sent to the bank is kept as `paymentId` in the checkout draft (0030), only when the browser really leaves for a bank URL. `settleAbandonedPayment` is the one action that settles it, deduplicated while in flight, and it keeps each step in the store's in-memory `settlement`.
- Only the page that came back settles: a page restored from the back cache that sent the payment itself (`sentHere`, in memory), or a document opened from the history (`back_forward`). A new tab, a reload or a typed address never settles; that payment goes to the API's review.
- A `pending` answer is not asked again in the same page load.
- The app shell triggers the action for a signed-in investor outside `/payment/*`, once the draft is restored and again on a bfcache `pageshow`; moving between pages triggers nothing. When a settlement ends it invalidates checkout, channel, subscription and transaction queries.
- Checkout's screen read awaits the action before it reads, so the screen never shows a settled payment as in review. It shows a same-size skeleton with «در حال بررسی پرداخت قبلی شما با بانک…» while the store says settling. It goes to the result page when this creator's settlement is `completed`, before any other way out. It shows the pending state only when the bank has not answered.
- `/payment/return` forgets the draft's payment, once the draft is restored, when it is the one returned, so a bank answer is never settled twice.
## Alternatives
- Settle on every app load that finds a payment in the draft: a second tab or a reload while the bank's page is open would abandon a payment the investor may still pay.
- Remember the leaving tab in `sessionStorage`: more precise, but it needs a second storage lib for one flag. The history-load check covers backing out.
- Let the review run: the investor cannot retry for 15 minutes and may pay twice from another device.
- Settle only on the checkout page: the subscriptions and transactions tabs would show a stale pending payment.
## Consequences
- One extra request after a gateway round trip that did not come back; none otherwise.
- An investor who closes the bank's tab and opens the app fresh, rather than going back, waits for the API's review (15 minutes) before paying again.
- A payment the bank has not answered stays pending (`pending` outcome). The draft keeps it, and the next page opened from the history asks again.

View File

@ -30,3 +30,8 @@
- 0023 architecture: On desktop «پست جدید» is a dialog over the page through bear's `@modal` intercept of /compose/post; slots are emptied by explicit null pages, never a catch-all, and a hard load gets the full page. - 0023 architecture: On desktop «پست جدید» is a dialog over the page through bear's `@modal` intercept of /compose/post; slots are emptied by explicit null pages, never a catch-all, and a hard load gets the full page.
- 0025 architecture: The investor's داشبورد is a tabbed section, one route per tab in `dashboard/(investor)`, whose layout holds the top bar or heading and `DashboardTabs`; each tab has its own loading. - 0025 architecture: The investor's داشبورد is a tabbed section, one route per tab in `dashboard/(investor)`, whose layout holds the top bar or heading and `DashboardTabs`; each tab has its own loading.
- 0028 design: Landing-only island tokens: `tablet` (720px, the landing's grids only), `hero` and `section` type, `container-page` and `image-shade`. - 0028 design: Landing-only island tokens: `tablet` (720px, the landing's grids only), `hero` and `section` type, `container-page` and `image-shade`.
- 0029 architecture: End every payment on `/payment/result/[paymentId]`; the API's bank callback returns to `/payment/return`, which polls the payment until settled (30 s at most) and replaces itself.
- 0030 architecture: Keep the last checkout's period, invite code and bank payment in the persisted `session.checkout-draft` store from payment start until success, and restore them on the same creator's checkout.
- 0031 design: List renew and reactivate periods as island `TierOption` cards, as checkout does, instead of R3's chip grid.
- 0032 architecture: Serve the notification centre at `/notifications` on mobile and as a lazily loaded side panel from bear's header bell; opening it marks all read.
- 0033 architecture: Keep the payment sent to the bank in the checkout draft and settle it through `POST /subscriptions/payments/:id/abandon` only on the page that came back from the bank (bfcache or a history load), triggered by the app shell and awaited by checkout's screen read.