Merge branch 'master' into extract-color-schema

docs/project-memory/shared-memory/decision-log.md

@@ -4057,10 +4057,31 @@
 ## 2026-07-13 公开作品资产使用派生精确读授权
 
 - 背景：资产 ACL 严格执行后，已登记为 `private` 的作品封面和正式资产不能再依赖 generated 前缀匿名读取；但公开作品仍需要允许访客读取它实际展示和运行的资产。
-- 决策：已登记 `asset_object` 继续保持 `private`，新增匿名派生 view `public_work_asset_read_grant`。view 只从 `Published + visible` 作品（`custom-world` 另要求未删除）正式发布快照中收集实际使用的资产，历史作品随 view 计算自动补齐；资产读取 procedure 在同一事务快照内组合 `asset_object` 与该 view，不从连接级长期订阅 cache 判断 ACL。
+- 决策：已登记 `asset_object` 继续保持 `private`，新增匿名派生 view `public_work_asset_read_grant`。view 只从 `Published + visible` 作品（`custom-world` 另要求未删除）正式发布快照中收集实际使用的资产，历史作品随 view 计算自动补齐；资产读取 procedure 在同一事务快照内先取资产 owner，再使用各玩法 owner 索引定向计算该作者的 grant，不为每张图片执行全站 view，也不从连接级长期订阅 cache 判断 ACL。
 - 授权边界：grant 携带作品 owner，API 只有在它与 `asset_object.owner_user_id` 一致，且 `asset_object_id` 或精确 `object_key` 命中时才允许匿名读取。隐藏、删除或取消发布会使 grant 自动消失；参考图、未选中候选图和 `generationInputs` 明确排除。Custom World 只遍历角色、地标、营地、章节和 opening CG 等已知正式根，不能递归 legacy payload 的未知预览 / 编辑字段。
 - 禁止项：不得通过放开 `generated-*` 前缀或批量把历史对象改为 `PublicRead` 修复公开作品，两种方式都会让作品可见性生命周期与资产授权脱节，并重新引入跨账号读取。
 - 影响范围：`module-assets` 公开资产授权判定、`spacetime-module` 跨玩法公开资产 view 与权威读取 procedure、`spacetime-client` facade 和 `api-server` 资产读取 ACL。
 - 权威查询：`asset_object` 不进入 client 长期订阅。API 通过仅 runtime service identity 可调用的 procedure，按主键或 `(bucket, object_key)` 服务端索引读取事务内 metadata；只有位置查询明确返回不存在时才允许进入 legacy curated 前缀兼容，procedure 失败、超时或重复位置一律失败关闭。
 - 一致性：隐藏、删除或取消发布提交后，后续读取 procedure 的事务快照立即按新状态判断，不等待任意池连接追上订阅水位。公开派生授权、`PublicRead` 和 legacy 兼容读取签名 URL 的有效期最多 600 秒，因此该能力仍不是对既有签名的瞬时吊销机制；owner / admin 读取保持原有效期口径。
 - 验证方式：公开可见作品的正式资产可匿名读取；未选候选图、参考图、跨 owner 伪造 key 仍返回不存在；隐藏、删除或取消发布后新的读取请求立即拒绝，再恢复公开可见时新的读取请求立即恢复；超长公开 `expireSeconds` 被截断为 600 秒。
+
+## 2026-07-13 普通微信支付 V3 退款使用统一观察事务闭环
+
+- 背景：普通微信支付 V3 的退款申请响应、退款结果回调、主动查单和商户平台手工退款发现可能重复、乱序或只出现其中一种；原充值订单只有单一终态，无法表达多次部分退款、权益回收欠款和会员人工处理。
+- 退款事实：新增 `profile_recharge_refund`、`profile_recharge_refund_observation`、`profile_recharge_order_refund_settlement` 和 `profile_recharge_refund_bill_checkpoint`。所有已验签退款事实统一调用 `record_profile_recharge_refund_observation_and_return`；`out_refund_no` 是商户幂等键，微信退款单号保持唯一，重复 observation 必须核对原订单、微信支付单、金额、状态和事实指纹，不能仅按主键吞掉冲突。
+- 订单与权益：部分退款保持原充值订单 `paid`，累计成功退款等于订单金额时才改为 `refunded`；`paid_at` 永久保留，退款不恢复首充资格。泥点按累计退款比例计算目标回收量，全额时精确收口原 `points_delta`；自动回收只扣普通永久泥点，不动每日免费和会员周期泥点。永久泥点不足时记录 `shortfall` 并冻结正式钱包消费，流水来源为 `recharge_refund_recovery`；会员退款统一 `manual_review`，不自动猜测有效期、档位或周期泥点回滚。
+- 回调与现金事实：退款回调使用独立 `/api/profile/recharge/wechat/refund-notify`，不能复用支付 `WECHAT_PAY_NOTIFY_URL`。验签、解密、契约校验和 SpacetimeDB 持久化成功后返回 `204`；现金退款已成功但本地权益不足、订单冲突或会员待复核时仍先保存事实并 ACK，只有签解密、契约或持久化失败才让微信重试。诊断日志只保存脱敏结构化摘要和稳定引用。
+- 查单与账单：`WECHAT_PAY_REFUND_RECONCILIATION_ENABLED` 代码默认关闭，只有具备真实商户凭据和 runtime service identity 的 HTTP 角色可开启；生产 env 示例与 deploy 会补 `true`，真实支付显式关闭时发布失败。非终态退款按 1 / 5 / 10 / 20 / 30 分钟衰减查单；成功退款早于支付通知时只对 `order_missing / order_not_paid` 继续重试，其他人工复核不自动放行；候选列表按分钟轮转分页，失败日志不回显 provider URL。北京时间次日 10 点后按 30 个稳定分片轮转补扫微信 API 可查询的近 90 天 `bill_type=REFUND` 交易账单，每 30 分钟覆盖完整窗口。单行失败不阻塞其他行和日期，但当日不写完成 checkpoint；昨日 `NO_STATEMENT_EXIST` 至少延迟到次日 10 点后再确认。`PLATFORM-ORIGINAL / PLATFORM-BALANCE` 只用于发现商户平台退款，发现后仍必须主动查单取得当前状态；账单申请响应验签，GZIP 内容按 SHA1 验真并使用 CSV parser 和十进制定点金额解析。
+- 历史与入口边界：正式落账前已经 ACK 的旧退款通知不会因升级自动重放。已知商户退款单号通过受控服务端查单后进入统一事务，未知手工退款由 T+1 账单发现；超过微信 API 近 90 天窗口的历史数据需从商户平台导出核对后逐笔受控查单，禁止直接 SQL 写退款表。当前不开放匿名或普通用户退款、补录接口，退款申请只允许受控运维或后续管理员鉴权流程。
+- 影响范围：`module-runtime` 退款领域策略与钱包来源、`spacetime-module` 退款表和事务、`spacetime-client` facade、`platform-wechat` 退款 / 查单 / 交易账单协议、`api-server` 退款回调与 reconciliation worker。
+- 验证方式：退款相关 `module-runtime` / `platform-wechat` / `api-server` 定向测试，`npm run check:spacetime-schema`、`npm run check:spacetime-runtime-access`、`npm run check:server-rs-ddd`、`npm run check:encoding`、`git diff --check`；真实联调后只读核对退款单、observation、订单级 settlement 和账单 checkpoint。
+
+## 2026-07-13 后台充值退款使用钱包占用与统一用户详情
+
+- 背景：普通 V3 退款已经能从回调、查单和账单收口现金事实，但后台主动退款若先调微信再扣泥点，会在用户余额不足时产生本可避免的欠账；后台各页面也没有统一查询用户余额、绑定状态和充值订单的入口。
+- 决策：新增 `profile_recharge_refund_hold`，后台执行退款前按累计部分退款公式原子占用本次应追回的永久泥点，再使用客户端稳定 `requestId` 派生 `out_refund_no` 调微信。部分退款额外占用 1 泥点并发舍入缓冲，防止占用创建后到达的外部退款跨越累计 `floor` 边界；全额退款不加缓冲。`SUCCESS` 扣款并结算匹配占用，`CLOSED` 释放，`PROCESSING / ABNORMAL` 保持；结果未知时不擅自释放，至少等待 10 分钟并连续 3 次退款查单收到官方 `RESOURCE_NOT_EXISTS` 才由 worker 释放。普通消费必须排除全部活动占用。
+- 欠账与冻结：支付侧已经成功退款时不能回滚现金事实；永久泥点不足部分继续只写订单 settlement 的 `unrecovered_points`，限制普通消费，后续永久泥点优先自动偿还。每日免费和会员周期泥点不参与。人工冻结单独使用 `profile_wallet_manual_restriction`，解除人工冻结不解除退款欠账限制。
+- 人工复核：交易号或订单总额冲突只允许管理员确认退款归属，退款行追加不可变的管理员、原因、时间后重新运行标准结算；该操作不是“直接解冻”，余额不足仍形成欠账。会员退款、未知错误和非法结算计划不显示该入口，也不能复用泥点钱包冻结语义。
+- 后台边界：充值订单、预检、执行、应急退款号登记、用户详情和钱包冻结均只挂在管理员鉴权路由。用户详情由 `user_id` 或陶泥号经认证服务解析，返回头像、昵称、脱敏手机号、绑定状态、钱包分桶、占用、欠账和最近订单；后台语义明确的用户字段复用同一个图标按钮和弹窗，管理员主体及 `admin:*` 合成 ID 不打开用户详情。
+- 部分退款预检：微信支付查单 `trade_state=REFUND` 只表示已发生退款，不代表全额退款。刷新已登记退款后，本地累计成功退款大于 0 且小于订单总额、且不存在非终态退款、活动 hold、欠账或人工冻结时，可以继续退本地剩余额度；没有本地成功退款事实能解释 `REFUND` 时继续失败关闭并要求登记或账单对账。
+- 影响范围：`module-runtime`、`spacetime-module`、`spacetime-client`、`api-server` 管理员 BFF / refund worker、`shared-contracts` 与 `apps/admin-web`。

docs/project-memory/shared-memory/pitfalls.md

@@ -47,6 +47,14 @@
 - 验证：`cargo check -p spacetime-client --manifest-path server-rs/Cargo.toml`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`npm run check:spacetime-schema`。
 - 关联：`server-rs/crates/spacetime-module/src/editor_project_storage.rs`、`server-rs/crates/spacetime-client/src/editor_project.rs`、`server-rs/crates/api-server/src/admin.rs`。
 
+## 后台素材缩略图不要在首次挂载时全量换签
+
+- 现象：后台“素材查询”首批缩略图正常，继续向下滚动或读取更多后长期显示占位图；api-server journald 中已到达的 `/admin/api/assets/read-url` 可能全部是 `200`。
+- 原因：列表一次挂载 80 条私有素材时，每个缩略图同时换签，会在同秒突发请求。production Nginx 的 `genarrative_admin_rps` 为 `30r/s burst=16`，超出部分在进入 api-server 前已返回 `429`，因此仅查 api-server 日志会漏掉失败请求。
+- 处理：缩略图使用 `IntersectionObserver` 在进入视口附近时再调用管理端换签；对 `429` 使用有上限的退避重试，并在条目卸载后停止更新状态和安排重试。不得为单页突发放大 Nginx 通用管理端限流，也不得在单次限流失败后永久保留无图占位。
+- 验证：前端定向测试覆盖首屏外的后续行进入可见区后才换签、“读取更多”追加行可继续显示缩略图、`429` 后有限重试恢复、卸载后不再重试；真实浏览器滚动验收时同时核对 Nginx access/error log、api-server journald 和 Network 面板，不以单一日志面判定成功。
+- 关联：`apps/admin-web/src/pages/AdminEditorAssetQueryPage.tsx`、`apps/admin-web/src/pages/AdminEditorAssetQueryPage.test.tsx`。
+
 ## 陶泥儿精选重复先查同源同媒体画布副本
 
 - 现象：每次从项目素材中把同一个生成素材拖到画布上，`陶泥儿精选` 都多出一张看起来相同的素材。
@@ -2120,6 +2128,30 @@
 - 处理：不要改成订阅完整 `profile_recharge_order` 历史表。后端订阅只保留活跃五分钟定时器的 `profile_recharge_order_expiration_timer`，监听 timer 删除后按 `order_id` 通过 procedure 读取订单，只处理当前状态为 `expired` 的记录；支付 / 关闭信号会被忽略，断线窗口继续由未检查过期订单 catch-up 补齐。这样既不依赖不受支持的枚举 SQL，也不会把充值历史常驻 API 客户端缓存。
 - 验证：运行 `cargo test -p spacetime-client profile_recharge_expiration --manifest-path server-rs/Cargo.toml`，发布后确认 API 日志不再出现订阅解析错误，并用真实 pending 订单验证 scheduled reducer 过期后写入 `expiration_checked_at`。
 
+## 微信 Native 已入账但二维码弹窗不关闭
+
+- 现象：微信支付回调已经返回 `204`，本地充值订单为 `paid` 且泥点已到账，但网页仍停留在“微信扫码支付”，必须点击“我已支付”才刷新。
+- 原因：通用页面恢复确认逻辑在存在 `nativeWechatPayment` 时直接跳过，Native 分支创建二维码后也没有订阅订单 SSE，因此服务端回调发布的订单更新没有前端消费者。
+- 处理：Native 二维码出现后立即调用 `watchWechatRpgProfileRechargeOrder` 订阅当前订单；收到终态后更新充值中心、关闭二维码、清理 pending ref、刷新全局余额并只展示一次结果。SSE 超时或暂时失败时在二维码过期前重连，手动确认与 SSE 并发时以 pending order ref 保证只有首个终态生效。
+- 验证：`npm run test -- src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx` 覆盖不点击“我已支付”也会在 SSE 返回 `paid` 后自动关闭；再运行根级 `npm run typecheck`、`npm run check:encoding` 和 `git diff --check`。
+- 关联：`src/components/platform-entry/usePlatformProfileCenterController.ts`、`src/services/rpg-entry/rpgProfileClient.ts`、`server-rs/crates/api-server/src/runtime_profile.rs`。
+
+## 商户平台退款登记不要混淆 refund_id 与 out_refund_no
+
+- 现象：在“登记商户平台退款”里填写 `50000000000000000000000000000` 一类微信退款单号后提示找不到退款。
+- 原因：该编号是微信侧 `refund_id`；V3 单笔退款查询路径只接受商户退款单号 `out_refund_no`。把 `refund_id` 放进路径不会自动转换，退款查单会返回 `RESOURCE_NOT_EXISTS`。不过微信没有承诺 `refund_id` 固定为 `50` 开头的 29 位数字，合法 `out_refund_no` 也可能是纯数字，因此形状判断不能代替真实查单。
+- 处理：登记表单明确标注 `out_refund_no`，所有满足官方字符和长度约束的输入都交给服务端真实查询；只有查询确认不存在后，才把 `50` 开头的 29 位纯数字作为“疑似 refund_id”给出定向提示。只有 `refund_id` 时等待退款回调或 T+1 退款账单建立映射；不要调用异常退款申请接口冒充查询。`out_refund_no` 字符校验须覆盖官方允许的数字、大小写字母和 `_ - | * @`。
+- 验证：后台页面测试断言疑似编号仍交给服务端；平台适配器测试锁定 `RESOURCE_NOT_EXISTS` 映射和 `@` 字符，并确认真正的 `out_refund_no` 仍调用 `GET /v3/refund/domestic/refunds/{out_refund_no}`。
+- 关联：`apps/admin-web/src/pages/AdminRechargeOrderPage.tsx`、`server-rs/crates/api-server/src/admin_recharge.rs`、`server-rs/crates/platform-wechat/src/pay.rs`。
+
+## 微信支付查单的 REFUND 不等于已经全额退款
+
+- 现象：一笔 6 元充值在商户平台成功退 3 元并登记 `out_refund_no` 后，本地显示累计已退 3 元、剩余可退 3 元，但后台再次预检仍显示“未核验 / REFUND”并禁止退款。
+- 原因：微信支付订单查单的 `trade_state=REFUND` 只说明该支付订单发生过退款，不携带累计退款明细，也不表示已经全额退款。若后台把 `verified` 硬编码为 `trade_state == SUCCESS`，任何已成功部分退款的订单都会永久失去继续退款能力；反过来，仅看到 `REFUND` 就直接放行又可能漏掉未登记的商户平台退款。
+- 处理：预检先查支付订单并校验商户订单号、支付单号和总金额，再主动刷新全部已知 `out_refund_no` 并重读本地退款 settlement。`SUCCESS` 可继续预检；`REFUND` 仅在本地累计成功退款大于 0 且小于订单总额，并且没有 `PROCESSING / ABNORMAL` 退款、活动 hold、退款欠账或人工冻结时，允许继续退本地剩余额度。没有本地成功退款能解释 `REFUND` 时使用独立原因码阻止并要求登记或对账，不能冒充“订单未支付”。
+- 验证：后端策略测试覆盖 `SUCCESS + 0/600`、`REFUND + 0/600`、`REFUND + 300/600`、`REFUND + 600/600`；后台页面测试覆盖 `已核验 / REFUND` 时剩余额度可提交。真实联调核对累计退款、已追回泥点、活动占用和欠账均与退款明细一致。
+- 关联：`server-rs/crates/api-server/src/admin_recharge.rs`、`server-rs/crates/spacetime-module/src/runtime/profile.rs`、`apps/admin-web/src/pages/AdminRechargeOrderPage.tsx`。
+
 ## 抓大鹅历史草稿外部 Rodin GLB 链接必须转存后再试玩或发布
 
 - 现象：草稿页预览模型失败并报 `GL_INVALID_ENUM: Invalid cap.`，或结果页能看到历史生成记录但试玩、发布和正式运行态仍显示默认积木。
@@ -3012,7 +3044,39 @@
 - 现象：资产 ACL 收紧后，公开页面读取其他作者作品资产集中返回 `404`；对象在 OSS 中真实存在，但已登记 `asset_object.access_policy = private`。
 - 原因：“作品公开”不等于“作者账号下所有 generated 对象永久公开”。只按 profile / session 关联也会误公开同会话的未选候选图、参考图或生成输入；批量改 `PublicRead` 则无法随作品隐藏、删除或取消发布自动撤销。
 - 处理：已登记对象继续保持 `private`，通过 `public_work_asset_read_grant` 只派生 `Published + visible`（`custom-world` 还必须未删除）正式发布快照实际使用资产的匿名读授权。API 必须同时校验 grant owner 与资产 owner 一致，以及 `asset_object_id` 或精确 `object_key` 命中；明确排除参考图、未选候选图和 `generationInputs`。Custom World 只能扫描角色、地标、营地、章节和 opening CG 等正式根，不能遍历 legacy payload 的未知根。历史作品交给 view 现算补齐，不做永久 ACL 数据补丁。
-- 权威查询边界：不能从 `asset_object` 或 `public_work_asset_read_grant` 的连接级订阅 cache 推断当前 ACL；池连接水位不一致会让刚撤销的 grant 继续签发 URL，也会让刚公开的作品短暂 404。资产定位和公开授权必须通过受 runtime service identity 限制的 procedure 在同一事务快照中计算，失败时拒绝读取；同时不要在每个池连接订阅复制全量 private 资产表。公开派生授权、`PublicRead` 和 legacy 兼容读取的签名 URL 最长 600 秒，owner / admin 不受该公开上限影响。
+- 权威查询边界：不能从 `asset_object` 或 `public_work_asset_read_grant` 的连接级订阅 cache 推断当前 ACL；池连接水位不一致会让刚撤销的 grant 继续签发 URL，也会让刚公开的作品短暂 404。资产定位和公开授权必须通过受 runtime service identity 限制的 procedure 在同一事务快照中计算，失败时拒绝读取；procedure 先按 asset owner 使用各玩法 owner 索引缩小到该作者作品，再匹配候选 `asset_object_id` / 精确 key，不能每张图都执行全站公开 view，也不要在每个池连接订阅复制全量 private 资产表。公开派生授权、`PublicRead` 和 legacy 兼容读取的签名 URL 最长 600 秒，owner / admin 不受该公开上限影响。
 - Remix 边界：拼图、Custom World 和大鱼现有 Remix 会把源资产引用复制到新 owner，但没有持久化不可伪造的资产来源。不得因此放宽跨 owner grant；源作品隐藏后仍公开的 Remix 资产，需要后续通过 Remix 时复制资产或持久化 provenance 解决。
 - 验证：资产 owner 本人仍可读；公开可见作品的正式资产可匿名读；跨 owner、只命中前缀、参考图、未选候选图和 `generationInputs` 仍返回不存在；作品隐藏、删除或取消发布后 grant 消失。
 - 关联：`server-rs/crates/spacetime-module/src/public_asset_access.rs`、`server-rs/crates/spacetime-client/src/assets.rs`、`server-rs/crates/api-server/src/assets.rs`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`。
+
+## iOS 退款问询的 result_code 不是 debug 状态
+
+- 现象：为了先观察真实 iOS 退款通知，回调返回 `ErrCode=0 + IosRefundQueryResponse.result_code=1`，并把 evidence 写成“调试阶段不执行自动退款决策”，看起来像安全 ACK，实际已经向微信建议拒绝退款。
+- 原因：`xpay_subscribe_ios_refund_query_notify` 只有 `result_code=0`（建议退款）和 `1`（建议拒绝）两种正式决策；`evidence` 必须是可审计的履约或消耗事实，不存在中立调试值。与此同时，解密后的完整 payload 含 OpenID、Apple 交易号、退款原因和票据，不能为了排障直接落日志。
+- 处理：未接入真实履约决策时返回非零 `ErrCode` 让微信重试，不携带 `IosRefundQueryResponse`；所有事件只写脱敏结构化摘要，payload、未知事件/字段、标识符和字符串值使用消息 Token 加用途域派生的稳定 HMAC 引用，自由文本只写长度和 HMAC 引用。Android 订阅成功和普通 goods 通知可能同形，payload marker 只能快速分流；只有存在同号 `wechat_mp_virtual` 本地充值订单，并在 2.5 秒内通过 `/xpay/query_order` 校验订单号、金额、`order_type=0/7`、支付状态和权威 `paid_time`，才允许入账。Apple 通知缺少 `WeChatPayInfo.PaidTime` 时走查单，绝不能用本机时间补齐。
+- 验证：`cargo test -p platform-wechat virtual_payment_debug_summary --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server virtual_payment_debug_routing --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server virtual_payment_ios_refund_query_has_no_fake_decision_response --manifest-path server-rs/Cargo.toml`。
+- 关联：`server-rs/crates/platform-wechat/src/pay.rs`、`server-rs/crates/api-server/src/wechat/pay.rs`、`docs/【技术方案】微信虚拟支付接入-2026-05-26.md`。
+
+## 微信支付 V3 的支付 notify_url 不会自动接收退款结果或发现全部手工退款
+
+- 现象：普通微信支付成功回调已经配置并可达，但在商户平台或代码里发起退款后，`/api/profile/recharge/wechat/notify` 收不到退款单状态变化；商户平台手工退款也可能没有请求本系统的退款回调入口。
+- 原因：V3 支付成功通知与退款结果通知是不同契约；代码发起退款时，退款通知地址来自每次 `POST /v3/refund/domestic/refunds` 请求里的 `notify_url`，支付下单使用的 `WECHAT_PAY_NOTIFY_URL` 不会自动复用。商户平台手工退款不能假设会携带本系统按 API 请求传入的回调地址；退款接口返回成功也只表示受理，不能当成退款终态。
+- 处理：代码退款显式传入公网 `https://<API 域名>/api/profile/recharge/wechat/refund-notify`，并用稳定 `out_refund_no` 串联申请、重复通知和主动查单。回调先用原始 body 验签、检查正负 5 分钟时间窗，再用 APIv3 密钥解密；校验事件、资源类型、商户号和退款状态后，将 callback observation 写入统一 SpacetimeDB 事务，持久化成功才返回 `204`。正式链路不再是“debug 只记日志”：部分 / 全额退款、泥点回收、欠款冻结和会员人工复核均由事务收口；未知事件、校验或持久化失败返回微信 `FAIL` 响应。另开启 `WECHAT_PAY_REFUND_RECONCILIATION_ENABLED=true`，对 `order_missing / order_not_paid` 继续等待晚到支付通知，候选退款按分钟轮转分页且错误日志不回显 provider URL；次日 10 点后按分片补扫微信 API 可查询的近 90 天 `bill_type=REFUND` 交易账单，并在落账前再主动查单。单行失败不能阻塞其他行或日期，也不能提前写完成 checkpoint；昨日 `NO_STATEMENT_EXIST` 至少延迟到次日 10 点后再确认；不要为联调开放未鉴权公网退款或补录接口。
+- 验证：`cargo test -p platform-wechat v3_refund_notify --manifest-path server-rs/Cargo.toml`、`cargo test -p platform-wechat v3_transaction_notify --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server v3_refund_notify_failure --manifest-path server-rs/Cargo.toml`；真实联调后只读核对 `profile_recharge_refund`、`profile_recharge_refund_observation`、`profile_recharge_order_refund_settlement` 和 `profile_recharge_refund_bill_checkpoint`。
+- 关联：`server-rs/crates/platform-wechat/src/pay.rs`、`server-rs/crates/api-server/src/wechat/pay.rs`、`server-rs/crates/api-server/src/app.rs`、`docs/【技术方案】微信虚拟支付接入-2026-05-26.md`。
+
+## 已 ACK 的历史退款通知不会因正式落账上线而自动重放
+
+- 现象：微信侧退款已经是 `SUCCESS`，旧 debug 回调也曾返回 `204`，但部署正式退款表和权益回收事务后，本地充值订单仍为 `paid`，退款表没有记录。
+- 原因：微信收到成功应答后会把该次通知视为已送达；服务升级不会让已经 ACK 的历史通知自动重放。主动 reconciliation 只能继续查询本地已经知道 `out_refund_no` 的非终态退款，不能凭空枚举所有历史退款。
+- 处理：已知 `out_refund_no` 时，由持有真实商户凭据的受控服务端先调用单笔退款查询，验微信响应签名后写入统一 observation 事务；未知的商户平台退款等待 T+1 `REFUND` 交易账单发现，再查单落账。自动账单按分片补扫微信 API 可查询的近 90 天，超过窗口的数据需从商户平台导出候选后逐笔受控查单。禁止用 SQL 直接把订单改为 `refunded`，也禁止直接插入退款表或按账单 CSV 状态扣泥点，这些做法会绕过不可变字段冲突校验、累计部分退款和权益结算。
+- 验证：核对退款 observation 的 `source`、`resolution_code` 与金额，再核对订单级 settlement 的累计退款、`recovery_status`、`unrecovered_points` 和 `wallet_frozen`；全额退款应保留原订单 `paid_at`，防止错误恢复首充资格。
+- 关联：`server-rs/crates/api-server/src/profile_recharge_refund_reconciliation.rs`、`server-rs/crates/spacetime-module/src/runtime/profile.rs`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。
+
+## 退款请求结果未知时不能立即释放钱包占用
+
+- 现象：后台调用微信退款超时或连接中断，页面提示状态未知；如果服务端立即释放泥点占用，用户可以继续消费，而微信稍后仍可能完成退款，最终形成可避免的退款欠账。反过来，永久保留占用又会让一次明确未创建的退款长期冻结余额。
+- 原因：HTTP 错误只能说明客户端没有拿到确定响应，不能证明微信没有受理；单次退款查单 `RESOURCE_NOT_EXISTS` 也可能处于短暂传播窗口。只有使用原 `out_refund_no` 主动查单才能继续判定。
+- 处理：网络结果未知时保留活动 hold，页面把原 `requestId`、订单、金额、原因和已知 `out_refund_no` 保存到当前后台标签页、当前管理员会话隔离的 `sessionStorage`，有效期 2 小时；刷新后必须与后端 active hold 的金额、原因和退款号对账一致才允许直接复用原请求，服务端明确拒绝时清理上下文。没有原请求上下文、上下文过期或管理员会话已切换时只开放预填 `out_refund_no` 的安全查单登记，不生成新 ID 硬撞活动 hold。worker 在占用创建至少 10 分钟后查同一退款号，查到退款就将验签事实写入统一 observation，只有连续 3 次查单收到官方 `RESOURCE_NOT_EXISTS` 才释放。进程重启清空连续次数并重新观察；超时、签名、配置、解析等错误一律重置次数并继续占用。
+- 补充：退款查单适配器必须保留微信 `RESOURCE_NOT_EXISTS` 业务码，并兼容同类 `ORDER_NOT_EXIST`，不能把所有非 2xx 都抹平成通用上游错误；签名有效的退款申请/查询响应仍须与本次 `out_refund_no`、订单号、交易号和金额做关联校验。已释放 hold 复用旧 `requestId` 时必须在调用微信前拒绝，并要求重新预检生成新的请求 ID。
+- 关联：`server-rs/crates/api-server/src/admin_recharge.rs`、`server-rs/crates/api-server/src/profile_recharge_refund_reconciliation.rs`、`profile_recharge_refund_hold`。