后台充值订单实付口径、发放泥点列、用户累计充值与兑换码单位

- 新增 AdminRechargeOrderEntryPayload.paidAmountCents：只有 paid_at 存在的订单才有实付，未支付 / 已关闭 / 已过期固定为 0 - 充值管理列表把「金额 / 泥点」拆成「实付」「发放泥点」两列，未支付行实付显示「未支付」并附订单金额小字；退款面板「订单实付」改读同一字段 - 用户详情充值订单表新增「发放泥点」列，商品列只保留商品名，实付同样按 paidAmountCents 展示 - 用户详情新增 cumulativeRechargedCents：api-server 按 user_id 读取 profile_recharge_order，只累加 paid_at 存在的订单金额（退款不回减），单次上限 500 行，读取失败或命中上限返回 null - 用户详情身份区新增「累计充值」，读不到时显示「未知」，不用用户详情最多 20 条订单在 BFF 或前端近似重算 - 兑换码奖励单位收口为泥点：输入标签与列表列头改「奖励泥点」，单元格带「泥点」单位，避免被当成元 - 新增后端 2 条累计充值口径单测与前端 2 条用例（未支付不显示实付且发放泥点独立成列、累计充值未知态） - 同步后端架构数据契约（实付口径 / 累计充值来源与上限 / 兑换码奖励单位）与决策记录 - 验证：cargo check -p api-server；cargo test -p api-server --bin api-server admin（138 passed / 0 failed / 1 ignored）；npm run admin-web:typecheck；npx vitest run apps/admin-web/src（220 passed）；cargo fmt --all --check、check:encoding、check:doc-index、git diff --check 通过
2026-09-23 20:10:20 +08:00
parent 0dbd279dfc
commit 1b05a1d05e
11 changed files with 219 additions and 16 deletions
@@ -9277,3 +9277,14 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
 - 边界（本次不改）：用户详情「历史花费」（`profile_wallet_consumption_total` 投影与手动对账）维持既有「退款不冲减」决策，仍只累计负向消费流水；若要改成净额，必须单独走投影语义 + 对账口径变更，不能顺手改这一处。充值退款追回、余额重置、赠送和 hold 继续不计入消耗。
 - 影响范围：`server-rs/crates/api-server/src/admin.rs`、`server-rs/crates/shared-contracts/src/admin.rs`、`apps/admin-web/src/api/adminApiTypes.ts`、`apps/admin-web/src/pages/AdminDashboardPage.tsx`、对应用例与 `docs/technical/【后台管理】Dashboard运营看板方案-2026-06-23.md`。
 - 验证方式：`cargo test -p api-server --manifest-path server-rs/Cargo.toml --bin api-server dashboard_consumption`（新增 4 条净额用例全绿）；`cargo test -p api-server --manifest-path server-rs/Cargo.toml --bin api-server admin`（136 passed / 0 failed / 1 ignored）；`npm run admin-web:typecheck`；`npx vitest run apps/admin-web/src`（218 passed）；`npm run check:encoding`、`git diff --check`。
+
+## 2026-09-23 后台充值订单实付口径、发放泥点列、用户累计充值与兑换码单位
+
+- 背景：充值管理列表与用户详情把订单金额当实付展示，未支付订单也显示非 0 实付；发放泥点挤在「金额 / 泥点」一格或商品列小字里；用户详情看不到该用户累计充值额度；兑换码页的奖励数字没有单位，运营无法判断是元还是泥点。
+- 决策（实付只有支付过的订单才有）：`AdminRechargeOrderEntryPayload` 新增 `paidAmountCents`，由 api-server 按订单 `paid_at` 是否存在判定——存在才等于订单金额，未支付 / 已关闭 / 已过期固定为 0。后台前端实付列显示 `未支付`（并附订单金额小字），退款面板「订单实付」读同一字段；订单金额 `amountCents` 不再被当作实付。
+- 决策（发放泥点独立成列）：充值管理列表的表头由「金额 / 泥点」拆成「实付」与「发放泥点」两列，用户详情充值订单表同样新增「发放泥点」列，商品列只保留商品名；未支付订单发放为 0 泥点，与实付口径一致。
+- 决策（累计充值由后端算）：用户详情新增 `cumulativeRechargedCents`，api-server 按 `user_id` 读取 `profile_recharge_order`、只累加 `paid_at` 存在的订单金额（退款不回减），单次读取上限 500 行；读取失败或命中上限返回 `null`，前端显示「读取失败」，不用用户详情最多 20 条订单在 BFF 或前端近似重算。此次只新增 BFF 字段，未改 SpacetimeDB 表结构与 procedure。
+- 决策（兑换码奖励是泥点）：兑换码 `rewardPoints` 是奖励泥点（兑换成功按 `redeem_code_reward` 流水进钱包），后台输入标签改为「奖励泥点」、列表列头与单元格都带「泥点」单位。
+- 影响范围：`server-rs/crates/api-server/src/{admin.rs,admin_recharge.rs}`、`server-rs/crates/shared-contracts/src/admin.rs`、`apps/admin-web/src/api/adminApiTypes.ts`、`apps/admin-web/src/pages/{AdminRechargeOrderPage.tsx,AdminRedeemCodePage.tsx}`、`apps/admin-web/src/components/AdminUserDetailDialog.tsx`、对应三个用例文件与后端架构数据契约文档。
+- 验证方式：`cargo test -p api-server --manifest-path server-rs/Cargo.toml --bin api-server cumulative_recharge`（2 条新用例）与 `cargo check -p api-server`；`npm run admin-web:typecheck`；`npx vitest run apps/admin-web/src`（220 passed），其中三个定向文件 33 passed（新增「未支付订单不显示实付金额，发放泥点单独成列」与「累计充值读取不到时展示未知，不用订单列表近似」）。
+- 边界（未验证）：未连真实生产库核对历史订单的累计充值数值，也未跑真实栈 API smoke。