UC_4.6.2: Settings — Profile & Preferences

---

Document References

Design asset note: the 7 frames above are not yet committed to References/Wireframe/Stage 2/Settings/; this document cites the Figma node until the BA commits them (Ref: QnA_init_docs.md A-19).

---

1. Overview

Design: Figma — Profile & Preferences, node 7878-116947

2. Trigger

• The trader clicks the user chip in the sidebar footer (displaying their initials + level, e.g. SD / Lvl 5) and selects Settings from the dropdown (Ref: UC_4.1.2 §2 Screen Description, row 6), then selects the Profile & Preferences tab (Ref: BR_4.6.2.1).

3. Pre-conditions

• The trader is authenticated and inside the Dashboard shell (Ref: UC_4.1.1 §1 Overview).
• A Users record exists for the trader, populated at checkout with email, full name, and phone_number (Ref: UC_2.8.3 — Phase 2 Account Claim).

4. Post-conditions

The two commit paths reach their own post-conditions independently (Ref: BR_4.6.2.14).

After a photo commit (Crop Image [Done], or a confirmed [Remove Photo]):

• The Users record reflects the new profile_photo_url — the new S3 object URL, or null after a removal. No other profile column is touched.
• The previously stored S3 object is hard-deleted; there is no image history to roll back to (Ref: BR_4.6.2.6).
• Every surface that renders the trader's avatar — the sidebar user chip and the My POD widget on the LIVE Community page — reflects the new photo, or the trader's initials if the photo was removed (Ref: BR_4.6.2.13).
• The form's dirty state is unchanged — a photo commit neither enables nor resets [Save Changes] / [Cancel] (Ref: BR_4.6.2.8).
• The trader has been told the write succeeded: the success toast Ref: TS-DASH-01 — "Changes saved successfully" — is shown once the overlay closes (Ref: BR_4.6.2.16).

After a phone commit ([Save Changes] returns HTTP 200):

• The Users record reflects the submitted phone_number; every other profile column is unchanged.
• The form returns to a clean (non-dirty) state — [Cancel] is hidden and [Save Changes] is Disabled (Ref: BR_4.6.2.8).

5. Basic Flow

1. The trader lands on the Account screen and selects the Profile & Preferences tab.
2. Frontend calls GET /profile and receives {profile_photo_url, email, phone_number, ui_preferences}.
3. The General section renders: the avatar (the stored photo, or the trader's initials when profile_photo_url IS NULL — Ref: BR_4.6.2.7), the read-only Email, and the Phone field split into dial code + number. ui_preferences from the response is not consumed by this screen (Ref: BR_4.6.2.11).
4. The form starts clean: [Cancel] is hidden and [Save Changes] is Disabled (Ref: BR_4.6.2.8).
5. The trader edits the phone number. The form becomes dirty → [Cancel] appears and [Save Changes] becomes Enabled.

   Changing or removing the photo is a separate, self-committing path that runs outside this flow — Ref: §6 Alternative Flow A / Alternative Flow B and BR_4.6.2.14. A photo-only change leaves the form clean and [Save Changes] Disabled.

6. On the phone field's out-click, the frontend runs, in order: format/length check (Ref: BR_4.6.2.3) → same-as-current check (Ref: BR_4.6.2.5) → uniqueness check (Ref: BR_4.6.2.4). The first failing check renders its inline error and re-Disables [Save Changes].
7. The trader clicks [Save Changes].
8. Frontend calls PATCH /profile with {user_id, phone_number}. profile_photo_url is never part of this payload — the photo has its own endpoint (Ref: BR_4.6.2.15, §6 Alternative Flow A step 4).
9. On HTTP 200: success toast Ref: TS-DASH-01 is displayed and the form resets to clean per §4 Post-conditions.

6. Alternative Flows

Alternative Flow A — Change Photo

1. The trader clicks [Change Photo] → the browser's native file picker opens.
2. The frontend validates the selected file against BR_4.6.2.6. On failure, the matching error from Ref: CR-07 §7.2 is shown and the flow stops here — the avatar is unchanged and the form does not become dirty.
3. On success, the Crop Image modal opens with a fixed 1:1 crop frame; the trader may pan and zoom the image within the frame (no rotate).
4. The trader clicks [Done] → the photo is committed immediately, with no involvement from [Save Changes]:
   1. The modal closes and the blocking loading overlay Ref: OV-09 — "Updating avatar..." — covers the screen.
   2. The frontend requests a signed upload URL from the backend and PUTs the cropped binary directly to S3 (Ref: BR_4.6.2.6).
   3. The frontend calls PATCH /profile-photo with {user_id, profile_photo_url} — a photo-only endpoint; any phone edit currently staged in the form is not sent and is not affected (Ref: BR_4.6.2.15).
   4. On HTTP 200 the backend hard-deletes the previously stored S3 object (Ref: BR_4.6.2.6).
   5. The overlay closes, the new avatar is rendered on this screen and on every other avatar surface (Ref: BR_4.6.2.13), and the success toast Ref: TS-DASH-01 — "Changes saved successfully" — is shown (Ref: BR_4.6.2.16). [Remove Photo] becomes visible if it was hidden.
   6. The form's dirty state is untouched — if the trader had not edited the phone, [Save Changes] stays Disabled and [Cancel] stays hidden (Ref: BR_4.6.2.14).
5. The trader clicks [Cancel] instead → the modal closes and the selection is discarded. Nothing is uploaded, the previously displayed avatar is retained, and the form's dirty state is left exactly as it was before the modal opened.

Alternative Flow B — Remove Photo

1. [Remove Photo] is rendered only when the trader currently has a photo (profile_photo_url IS NOT NULL); it is hidden entirely otherwise.
2. The trader clicks [Remove Photo] → the confirmation popup Ref: CF-03 is shown. Because the removal commits immediately and is not reversible via [Cancel], an explicit confirmation is required (BA decision, 2026-08-21). The popup shows the title "Remove your photo?" with no body text, and two vertically stacked buttons: [Confirm] on top (Primary), [Cancel] below (Secondary).
3. The trader clicks [Cancel] in the popup → the popup closes and nothing happens; the avatar and the form's dirty state are unchanged.
4. The trader clicks [Confirm] → the removal is committed immediately:
   1. The blocking loading overlay Ref: OV-09 covers the screen.
   2. The frontend calls PATCH /profile-photo with {user_id, profile_photo_url: null} — the photo only; a staged phone edit is not sent (Ref: BR_4.6.2.15).
   3. On HTTP 200 the backend hard-deletes the stored S3 object (Ref: BR_4.6.2.6).
   4. The overlay closes, the avatar reverts to the trader's initials (Ref: BR_4.6.2.7) on this screen and every other avatar surface (Ref: BR_4.6.2.13), the success toast Ref: TS-DASH-01 is shown (Ref: BR_4.6.2.16), and [Remove Photo] is hidden.
   5. The form's dirty state is untouched (Ref: BR_4.6.2.14).
5. The removal cannot be undone from the UI — the previous image is gone from S3 and the trader must upload a new one.

7. Exceptional Flow

8. Business Rules

BR_4.6.2.1: Screen Entry Point and Tab Context

The Account screen is reached only through the sidebar footer user chip → dropdown → Settings (Ref: UC_4.1.2 §2 Screen Description, row 6). The chip renders the trader's avatar plus their current level — collapsed (avatar over Lvl 5) or expanded (avatar · Full Name · Level 15). The avatar is the saved profile photo, falling back to initials when none is set (Ref: BR_4.6.2.7, BR_4.6.2.13).

On entry, the default active tab is Connections & Credentials — the first entry in the tab list. Profile & Preferences becomes active only when the trader selects it. The full tab list and its owning UCs:

Note on the UC_4.6.x range: the WBS assigns only UC_4.6.1 – UC_4.6.4 to STAGE 2: DASHBOARD - COMMON / Settings, and UC_4.6.4 is Controls (AI chat & Reduce motion) (SRS published) — Ref: BR_4.6.2.11. There is no UC_4.6.5, and Account Actions no longer sits in the common range at all. The containing folder has been renamed UC_4.6.1-4.6.5 → UC_4.6.1-4.6.4 to match the WBS; every link in the repo was remapped accordingly.

BR_4.6.2.2: Field Editability Matrix

The General section exposes exactly the three items below. No other profile attribute is rendered on this screen.

Full Name is likewise immutable, and is not rendered on this screen at all. It is still read from the Users record to derive the avatar initials (Ref: BR_4.6.2.7).

BR_4.6.2.3: Phone Format Validation — Reuses the Checkout Block

The phone field reuses the checkout validation block verbatim: two-part input (dial code selector, default +1, scroll-only country list) + digits-only number input, E.164 length of 6–15 digits excluding the dial code, leading zeros auto-trimmed on out-click, validated on out-click and on submit. Ref: CR-09 §9.2.

There is no geo-blocking by region on this field — any country dial code is accepted (Source: QnA from clients — Settings, Profile & Preferences Definition row).

There is no deviation from CR-09 §9.2 — including the error copy. The field renders the shared strings verbatim; Settings has no phone strings of its own (BA instruction, 2026-08-24):

This reverses the 2026-08-11 decision recorded in QnA_init_docs.md A-09 / A-10 / A-12, which created the Settings-only strings IN-08 and IN-09. Both are now retired in list-toast-popup.md v3.13 and must not be referenced. IN-08's copy — "Invalid phone number format. Please check and try again" — is no longer used anywhere in the system. CR-09 §9.2 itself is unchanged: this UC conforms to it rather than editing it, so UC_2.8.3 (checkout) is behaviourally unaffected (BA instruction, 2026-08-24).

BR_4.6.2.4: Phone Uniqueness Across the System

A phone number may be associated with only one account. The check is the same one the checkout flow applies (Source: QnA from clients — Settings, Profile & Preferences Business logic row — Q: "Should we apply the same phone number validation logic here as well?" → A: "Yes").

• Trigger: phone field out-click, and again on submit.
• Authority: the backend is the final arbiter. The out-click check is only the first line of defence — a number that passes on out-click can still be claimed by another account before the trader clicks [Save Changes], in which case PATCH /profile returns HTTP 409 (Ref: §7 row 5).
• Error display: inline error Ref: IN-06 under the Phone field — "This phone number is already registered to another account."; [Save Changes] stays Disabled until the value is edited to one that clears the check.

This is the same rule and the same string as the checkout rule BR_2.8.3.4: Phone Number Uniqueness (Ref: UC_2.8.3 §6) — both render Ref: IN-06. The Settings-only duplicate string IN-09 is retired (Ref: BR_4.6.2.3). Checkout behaviour is unchanged; only IN-06's trigger description was widened to name both screens.

BR_4.6.2.5: New Phone Number Must Differ From the Current One

The submitted phone number must not be identical to the one currently stored on the account.

• Comparison basis: the fully normalised E.164 string — dial code plus number, with all display formatting characters stripped. Changing only the dial code while keeping the same digits (e.g. +1 5551234567 → +44 5551234567) therefore counts as a valid change, not a duplicate.
• Where enforced: client-side, on out-click and on submit — no backend round trip is required.
• Error display: inline error Ref: IN-10 — "The new phone number cannot be the same as your current one". [Save Changes] stays Disabled until the value differs.
• Why this one string stays Settings-specific: the checkout phone field is filled for the first time and has no "currently saved" value, so neither CR-09 §9.2 nor the checkout block defines a counterpart to reuse (Ref: BR_4.6.2.3).

BR_4.6.2.6: Profile Photo — Upload Constraints, S3 Signed-URL Flow, and Old-Object Deletion

Upload constraints (the values CR-07 §7.1 requires this UC to specify):

Both constraints are enforced client-side before the Crop Image modal opens; violations use the standard messages in Ref: CR-07 §7.2.

Upload mechanics — the image never transits the application backend (Source: RFQ_ Stack Trading Prop Tech V7.pdf §Page 36 — "Supports image uploads via S3 signed URL execution before submission"):

1. The frontend requests a short-lived signed upload URL from the backend.
2. The frontend PUTs the cropped image binary directly to S3 using that URL.
3. The resulting S3 object URL is sent as profile_photo_url to PATCH /profile-photo — a photo-only endpoint that carries no other field (Ref: BR_4.6.2.15).

When these steps run. Steps 1–3 fire the moment the trader clicks [Done] in the Crop Image modal — not on [Save Changes] (Ref: §6 Alternative Flow A step 4, BR_4.6.2.14). The whole sequence runs behind the blocking overlay Ref: OV-09.

On "upload and submission are one step". The RFQ describes the upload as running "before submission" — i.e. as a preparatory step ahead of a separate, trader-initiated save. That separation no longer exists: [Done] is the only trader action, and steps 1–3 run as one uninterruptible sequence behind OV-09 with no intermediate state the trader can see, cancel, or leave un-submitted. The three network hops are an internal implementation detail of a single logical operation. The signed-URL mechanism itself is retained — the image binary still never transits the application backend (BE team decision, 2026-08-21 — Ref: BR_4.6.2.15).

Old-object deletion. A trader has exactly one profile image at any time; the system keeps no history. Once the PATCH /profile-photo write returns HTTP 200, the backend hard-deletes the previously stored S3 object in the same operation — on replacement (Alternative Flow A) and on removal (Alternative Flow B) alike (BA instruction, 2026-08-21). Consequences:

• Deletion is conditional on the write succeeding. If the upload or the write fails, the old object is left intact and remains the trader's avatar (Ref: §7 rows 2 and 4).
• A replaced or removed photo is unrecoverable from the UI. There is no undo and no [Cancel] path — the trader must upload the image again. This is why [Remove Photo] is gated by the confirmation popup Ref: CF-03.
• An object uploaded to S3 for a commit whose PATCH /profile-photo then failed is orphaned; reclaiming it is a backend housekeeping concern with no user-facing effect and is out of scope for this UC.

BR_4.6.2.7: Avatar Fallback to Initials

Whenever profile_photo_url IS NULL — a brand-new account that never uploaded a photo, or an account whose photo was removed — the avatar renders the trader's initials derived from the Full Name held in the Users record. It never renders a generic placeholder figure (BA instruction, 2026-08-11 — Ref: QnA_init_docs.md A-04).

Derivation rule, applied to the Full Name captured at checkout:

The same derivation applies on every surface that renders a trader avatar, not just this screen — see BR_4.6.2.13 for the full consumer list. It is applied per displayed user, so a POD member with no photo of their own shows their own initials (e.g. Marcus Chen → MC) regardless of whether the viewing trader has a photo.

BR_4.6.2.8: Dirty-State Control of [Save Changes] and [Cancel]

The Phone field is the only input that makes this form dirty. The dial code and the phone number are the sole participants; the profile photo is not, because it commits on its own (Ref: BR_4.6.2.14).

Clicking [Cancel] reverts the staged phone value and dial code back to the last successfully saved state and returns the form to clean. It does not — and cannot — revert a photo change, which was already persisted at the moment it was made. No confirmation popup is shown, because nothing about the phone has been persisted yet.

A change to the Controls panel toggles never affects this dirty state either (Ref: BR_4.6.2.11).

BR_4.6.2.9: Unsaved-Changes Navigation Warning

While the form is dirty — i.e. the phone has been edited (Ref: BR_4.6.2.8) — the trader is warned before their staged changes would be discarded. A committed photo change never triggers this warning, because there is nothing staged left to lose (Ref: BR_4.6.2.14):

• Switching to another Settings tab, or navigating to another sidebar destination → confirmation popup Ref: CF-01, per CR-05. Choosing Leave discards the staged changes and completes the navigation; choosing Cancel keeps the trader on the tab with the form untouched.
• Closing or reloading the browser tab → the browser's own native unload prompt. Its copy is controlled by the browser and cannot be customised, so CF-01 does not apply to this case.

BR_4.6.2.10: Profile Is Global Per User — No SIM/LIVE Branching

This screen behaves identically for SIM (Evaluation) and LIVE (funded) accounts: same fields, same editability, same validation, same endpoints. The profile is a property of the user, not of the trading environment (Source: QnA from clients — Settings, Profile & Preferences Definition row, LIVE column: "Same as SIM - the profile is global per user, no SIM/LIVE distinction").

Consequently no rule in this UC is gated on account status, level, or environment.

BR_4.6.2.11: Controls Panel Is Out of Scope

The Controls panel (Desk Manager and Reduce Motion toggles) is rendered next to the tab list on every Settings tab, including this one, but it is not owned by this UC. It belongs to UC_4.6.4 — Controls (AI chat & Reduce motion). The Desk Manager toggle writes through its own dedicated endpoint POST /ai-preference; the Reduce Motion toggle writes nothing to the backend at all — it is frontend-only, persisted per device, and POST /accessibility-preference is withdrawn (client answer 2026-08-24, Ref: BR_4.6.4.2).

Two consequences for this UC:

• Toggling either switch saves immediately on flip. It does not route through this screen's [Save Changes] button and does not mark this form dirty (Ref: BR_4.6.2.8).
• The ui_preferences object returned by GET /profile is not read by this screen, and ui_preferences is never sent to either of this screen's write endpoints — even though the RFQ endpoint signature lists it as an optional parameter (BA decision, 2026-08-11 — Ref: QnA_init_docs.md A-18). This boundary is unchanged by the 2026-08-24 client answer; note only that ui_preferences no longer has a consumer in UC_4.6.4 either, since Reduce Motion left the database and the Desk Manager uses the dedicated users.ai_enabled column. ✅ Re-confirmed 2026-09-03 — the client states the field has "no active parameters to parse… today" and exists "strictly as a future-proofing measure", so having no reader and no writer is the intended state, not an omission (Ref: BR_4.6.2.15, [CTRL-EP-05]).

BR_4.6.2.12: Change Frequency and Downstream Effects of a Phone Change

For launch, a phone number change is a plain field update with no additional ceremony:

• No rate limit and no cool-down — the trader may change their phone number any number of times. Confirmed for launch 2026-08-27 ("ở bản launch, trader có thể thay đổi số điện thoại tự do mà không bị khóa thời gian"). Note the status of the source: the client's QnA row is still marked "STILL OPEN: no rate limit / cool-down was specified" — so this is a build decision taken in the absence of a client limit, not a limit the client has ruled out. If they later specify one, it lands here.
• No security constraint of any kind — confirmed for launch 2026-08-27. A phone change passes exactly two gates and is then written straight to PostgreSQL: the checkout regex format check (Ref: BR_4.6.2.3) and the system-wide uniqueness check (Ref: BR_4.6.2.4). Nothing else stands between the trader and the write.
• No OTP verification of the new number. Dashboard authentication is Auth0 passwordless over email, so the phone number is not currently an authentication factor.
• No security-notification email to the previous address, and no audit-log entry beyond the Users record's own updated_at timestamp.
• No propagation to Auth0, Rithmic, MT5, or TraderEvolution — the number lives only in the StackTrading Users table.

These four points define launch scope only. The phone number was originally collected at checkout to "enable Two-Factor Authentication (2FA) and coordinate emergency Drawdown Defense protocols" (Ref: UC_2.8.3 §7). If either capability is activated later, an unverified self-service phone change becomes an account-takeover vector and this rule must be revisited.

BR_4.6.2.13: Avatar Propagation — Consumer Surfaces

The photo saved on this screen is the single source for the trader's avatar across the whole Dashboard. There is no second avatar setting anywhere else (BA instruction, 2026-08-11 — Ref: QnA_init_docs.md A-20). Once PATCH /profile-photo returns HTTP 200, the new profile_photo_url is what every consumer surface below renders.

Mechanics of the propagation:

• Read-through, not a push. Each surface reads the profile_photo_url of the user it is displaying, straight from the Users record. This UC writes one column and pushes nothing — there is no sync job, no fan-out event, and no per-surface copy of the image to keep consistent.
• Fallback is per displayed user. Any surface showing a user whose profile_photo_url IS NULL renders that user's own initials per BR_4.6.2.7 — which is why POD member rows can show initials (MC) and a photo side by side in the same list.
• Refresh timing. The sidebar user chip refreshes immediately on the photo commit's HTTP 200 (Ref: §6 Alternative Flow A step 4.5 / Alternative Flow B step 4.4), because it is part of the shell the trader is already on. Every other surface picks the new value up on its own next data fetch; this UC does not force a re-render of screens the trader is not currently viewing.
• Level and name are not owned here. The level (Lvl 5, Level 15), the title/track label (Senior trader, Associate), and the Full Name shown next to the avatar all come from each consumer surface's own data contract. This UC contributes the image only.

Dashboard avatar vs. Discord avatar — closed 2026-08-27. The two are fully independent; Discord is never read.

The precedence question is resolved by removing the contest: StackTrading never pulls an avatar or a name from the Discord API, on any surface, as a primary value or as a fallback.

• Rationale, stated by the client: pulling Discord's CDN image invites broken images and expired CDN links — Discord avatar URLs are not stable third-party assets, and a dead link on the sidebar chip or a POD member row would be a visible defect StackTrading could not fix.
• A trader will therefore often show two different pictures — one on the Dashboard, one in Discord — and that is the intended outcome, not a sync gap to be closed later.
• Consequence for UC_4.14.2 (Pod Mentorship, LIVE): the My POD widget's data contract is now constrained, not open. It renders profile_photo_url with an initials fallback like every other surface; a Discord-sourced secondary fallback is excluded, so that branch does not need designing there. Adding one would be a change request against this rule.
• The same rule applies to names: the Full Name beside an avatar comes from the Users record, never from a Discord nickname or global display name (Ref: BR_4.5.2.6 — StackTrading does not manage Discord display names).

⚠️ Amendment — CR-20260903-001, 2026-09-03. The one-way boundary above is no longer absolute in the Discord direction.

Live-broadcast chat messages sent from the Dashboard now leave through a Discord Webhook that overrides username and avatar_url per payload, so that they render in Discord as the trader rather than as a bot transcript. Two clauses of this BR are affected:

Clause as closed 2026-08-27	Status after the CR
"StackTrading neither reads nor influences" the Discord surface	🔴 Superseded. profile_photo_url is now pushed to Discord on every Dashboard-sent chat message (Ref: BR_4.14.1.12)
"StackTrading never pulls an avatar or a name from the Discord API, on any surface, as a primary value or as a fallback"	🔴 Superseded in principle — the CR's avatar priority 2 (Discord photo when profile_photo_url IS NULL) requires exactly such a read. ⚠️ Not yet confirmed by the client as a deliberate reversal, and the 2026-08-27 rationale ("expired CDN links... a dead link would be a visible defect") still stands technically. Tracked as UC_4.14.1 §10 item 12
Everything governing Dashboard surfaces — this screen, the sidebar chip, My POD, the initials fallback of BR_4.6.2.7, and the My POD constraint on UC_4.14.2	🟢 Unchanged. No Dashboard surface reads Discord, and none renders a chat avatar

New constraint this creates on PATCH /profile-photo: the stored profile_photo_url must be publicly fetchable by Discord's servers, since Discord retrieves avatar_url itself. A private bucket or a signed URL with a TTL silently degrades every trader to the webhook's default image. BE confirmation pending — UC_4.14.1 §10 item 13.

BR_4.6.2.14: Photo and Phone Are Two Independent Commit Paths

The General section looks like one form but behaves as two unrelated transactions. This is the governing rule of the screen; BR_4.6.2.6 and BR_4.6.2.8 are its consequences (BA instruction, 2026-08-21).

Rules that follow from this split:

1. A photo-only session never lights up [Save Changes]. If the trader opens the tab, changes their avatar and changes nothing else, [Save Changes] stays Disabled and [Cancel] stays hidden for the whole session — there is nothing left to save.
2. The two payloads never merge. They cannot — they are different endpoints (Ref: BR_4.6.2.15). profile_photo_url is never sent by [Save Changes], and phone_number is never sent by a photo commit. A phone value staged in the form is simply not part of the photo call, and survives it untouched.
3. A failure on one path does not roll back the other (Ref: §7 rows 4 and 6).
4. Order does not matter. The trader may commit a photo before, after, or in the middle of editing the phone; each path is evaluated on its own.
5. The unsaved-changes guard covers the phone only. Navigating away with a committed photo but an untouched phone triggers no warning, because the form is clean (Ref: BR_4.6.2.9).

BR_4.6.2.15: API Contract — Endpoint Split and Verb

This screen talks to three endpoints. The write side deliberately deviates from the single Update User Profile operation described in RFQ_ Stack Trading Prop Tech V7.pdf §Page 36 (Sotatek BE team decision, API review 2026-08-21).

The three deviations from the RFQ, and why:

Naming. Singular /profile and /profile-photo — this is a singleton resource scoped to the authenticated trader, so the plural form would be wrong. GET /profile keeps its existing name and shape; UC_4.6.4 also reads from it and is unaffected by this change.

✅ [PP-EP-01] closed 2026-08-27. The BE team's proposal is adopted in full — "Chuyển đổi toàn bộ sang chuẩn RESTful sử dụng PATCH /profile" and "Nhất trí với quyết định phân tách này". All three deviations above are confirmed as the built behaviour: PATCH on both write endpoints, the two-endpoint split, and the merged crop → signed URL → S3 → PATCH /profile-photo chain behind a single [Done]. The competing names are formally retired: the WBS's PUT /profile and the RFQ's POST Update User Profile are both superseded and must not be cited as the contract. WBS row 174 still carries PUT /profile and needs correcting.

✅ ui_preferences — discrepancy resolved the same day; the payload is phone_number only. An earlier answer on 2026-08-27 had described PATCH /profile as updating "số điện thoại (phone_number) và cấu hình giao diện (ui_preferences)". The follow-up answer on UC_4.6.4 settles it the other way: because the Desk Manager keeps its own dedicated endpoint ("POST /ai-preference — không gộp chung vào profile nữa"), PATCH /profile is reduced to "Chỉ dùng để cập nhật số điện thoại" with the payload given as {"phone_number": "+84901234567"}. This document's payload therefore stands, for two reasons that both post-date the field's last live use:

• A-18 (2026-08-11) drew the boundary explicitly: UC_4.6.2 does not read or write ui_preferences; it belongs to UC_4.6.4 (Ref: BR_4.6.2.11).
• The client answer of 2026-08-24 left the column with no consumer at all. Reduce Motion is stored locally per device and never server-side; Desk Manager uses its own boolean users.ai_enabled via POST /ai-preference. So ui_preferences is not written by UC_4.6.4 either — writing it from this screen would resurrect a dead field and give it a writer but still no reader.

The column remains in the Zapier Users schema and in the GET /profile response shape, which is unchanged. ui_preferences now has neither a reader nor a writer anywhere in the Settings module — it is a dormant column, not a live field.

✅ Confirmed by the client on 2026-09-03 — the column is dormant by design, and this is not a documentation gap. Asked directly what the field is for, the client answered: "There are currently no active parameters to parse for this field today. It is intentionally included in the schema strictly as a future-proofing measure. Please maintain this column as an optional JSON object. This ensures the frontend team can easily save arbitrary cross-device layout preferences in future updates without requiring structural database schema changes later." (Source: [CTRL-EP-05], QnA STAGE 2 — Settings §9 Controls & Concierge.) Three build consequences:

• Keep the column and keep it in the contract. users.ui_preferences is JSONB, nullable / optional. GET /profile returns it as-is; a write endpoint that accepts it treats it as an optional pass-through with no validation of its inner shape. Nothing on the backend parses it in this release.
• This screen still never sends it. The payload of PATCH /profile stays {user_id, phone_number} — the client's own answer scopes that endpoint to the phone number, and the field has no reader to serve.
• The earlier "future use = change request" note is superseded. Adding a frontend-only, cross-device layout key later is explicitly pre-authorised by this answer — no DB migration and no CR. A key that carries backend logic or cost (anything a worker or a Zapier flow must read) is a different matter and does need a CR, because it makes the column live.

✅ user_id stays in the payload — confirmed 2026-08-28. The 2026-08-27 payload examples omitted it ({"phone_number": …}, {"profile_photo_url": …}) while POST /ai-preference in the same answer carried it. The inconsistency is resolved in favour of keeping user_id on all three write endpoints — PATCH /profile, PATCH /profile-photo and POST /ai-preference — "để đảm bảo tính nhất quán cao nhất với tài liệu đặc tả RFQ gốc". The payload table above stands as written; the omission in those examples was shorthand, not a contract change.

This is a consistency decision, not an authorisation one: the endpoints remain authenticated, and user_id in the body must never be trusted as the authority for whose record is written. BE resolves the acting trader from the session and rejects a mismatch — a payload user_id that differs from the authenticated trader is an error, never an instruction to write someone else's row.

BR_4.6.2.16: Photo Commit — Success Confirmation Toast

A profile-photo commit ends with the same success toast as every other Settings save: Ref: TS-DASH-01 — "Changes saved successfully" (BA instruction, 2026-08-28).

• When it fires. On HTTP 200 from PATCH /profile-photo — on both commit triggers: Crop Image [Done] (Ref: §6 Alternative Flow A step 4.5) and [Confirm] in Ref: CF-03 (Ref: §6 Alternative Flow B step 4.4). The two triggers share one endpoint and one commit model, so they share one confirmation.
• Sequence. The blocking overlay Ref: OV-09 closes first, then the toast is raised. The two are never on screen together: OV-09 reports work in progress, the toast reports work finished.
• Copy. Identical to the phone save — the string is not specialised per field. TS-DASH-01 is the single Settings-wide success toast (Ref: BR_4.6.2.14).
• On failure, no success toast is shown. The failure branches raise their own error toast and restore the previous avatar (Ref: §7 rows 2 and 4).
• This does not change the commit model. The toast is confirmation only: the photo path still commits on its own trigger, still never marks the form dirty, and still never involves [Save Changes] (Ref: BR_4.6.2.14).

9. Screen Description

9.1 Account screen — Profile & Preferences tab

9.2 Crop Image modal

9.3 Remove photo confirmation popup — Ref: CF-03

Layout note. This popup stacks its two buttons vertically with the affirmative action on top, unlike CF-01 / CF-02, which place them side by side with Cancel first. The design set is the authority here (BA design frame, 2026-08-21).

---

Changelog