refactor: 收口平台钱包余额 delta

docs/technical/【前端架构】PlatformProfileWalletDeltaModel收口计划-2026-06-04.md

@@ -0,0 +1,32 @@
+# 【前端架构】Platform Profile Wallet Delta Model 收口计划
+
+## 背景
+
+`PlatformEntryFlowShellImpl.tsx` 仍内联维护个人钱包余额的本地 delta 规则：余额归一化、本地扣点 / 返还后的 dashboard 乐观更新，以及刷新服务端 dashboard 时如何抵消已经被服务端反映的本地 delta。
+
+这些规则是纯展示状态计算，但留在平台壳层会让壳层同时理解钱包余额边界、整数截断、负数保护和服务端快照对账。
+
+## 决策
+
+新增 `platformProfileWalletDeltaModel.ts`，收口钱包余额本地 delta 的纯规则：
+
+- `resolveProfileWalletBalance(...)` 负责把 dashboard 余额归一为非负整数。
+- `adjustProfileDashboardWalletBalance(...)` 负责把本地 delta 应用到 dashboard，并刷新 `updatedAt`。
+- `reconcileProfileWalletLocalDeltaWithServerDashboard(...)` 负责在拿到新服务端 dashboard 后扣除已被服务端反映的本地借贷变化。
+
+`PlatformEntryFlowShellImpl.tsx` 继续保留 API 请求、React ref、state 写入和刷新触发副作用。
+
+## 接口约束
+
+- 非数字、无穷值或空 dashboard 的余额按 `0` 处理。
+- 本地 delta 必须先 `Math.trunc`，余额不得低于 `0`。
+- 当服务端最新余额已经反映本地扣点时，剩余负 delta 应减少；已经全部反映时归零。
+- 当服务端最新余额已经反映本地返还 / 奖励时，剩余正 delta 应减少；已经全部反映时归零。
+- 服务端余额变化方向与本地 delta 相反时，不得错误抵消。
+
+## 验收
+
+- `npm run test -- src/components/platform-entry/platformProfileWalletDeltaModel.test.ts`
+- 针对新 Module 与 `PlatformEntryFlowShellImpl.tsx` 执行 ESLint。
+- `npm run typecheck`
+- `npm run check:encoding`