赞助功能横跨客户端与 user_manager：客户端负责「赞助」入口、弹窗与致谢名单， user_manager 拥有 donations 表以及 users 上的汇总字段。

​
为什么是「自行登记」

两条通道都在 RakuLL 之外完成支付，目前都拿不到可信的支付结果：
  • 微信：rakullapp_core/assets/imgs/payment.png 是个人收款码。纯个人身份没有商户号，也就没有订单体系和支付通知——线上收款属于持牌清算业务，监管要求经营主体资质。想拿到 notify_url 回调，最低门槛是个体工商户营业执照。
  • Ko-fi：嵌入的是 Ko-fi 自己的组件，跨域 iframe 不会告诉我们里面发生了什么。
因此付款完成后，由用户在弹窗里自行登记金额与方式，写入一条 status='pending' 的记录。这条记录立刻生效：入口静默、Dashboard 数字、致谢名单都随之更新—— 用户刚付完钱，不该再被要求等待审核。root 之后可以把记录改为 confirmed， 或对明显造假的记录 rejected（驳回会同时移出汇总与名单，并解除静默期）。
Ko-fi 服务端其实有 webhook（付款时向你配置的地址 POST 一次，用 verification_token 验真），所以这条通道将来是可以自动核验的。没有接是因为两个前置条件没满足：需要一个公网 可达的 HTTPS 端点，而且回调里只有付款人的邮箱与昵称——users 表没有邮箱字段，无法可靠 地对应到 RakuLL 账号，除非引导用户在 Ko-fi 留言里填用户名。status 字段就是为此留的： 接上 webhook 后只需把 pending 自动翻成 confirmed，不用改表。
这是一个致谢计数器，不是账务系统。donation_total_cny 用 DONATION_FX_TO_CNY 里刻意写死的近似汇率把混合币种折成一个数，不要拿它对账。

​
客户端组成

位置职责
lib/user_manager/api/donation_api.dart调用 /api/donations/*
lib/user_manager/models/donation_models.dartDonationMethod、DonationSummary、Supporter、SupporterWall 与 formatCny
lib/user_manager/widgets/donate_dialog.dart两步弹窗：选择方式 → 登记金额
lib/user_manager/widgets/supporters_dialog.dart致谢名单弹窗
lib/app/dashboard_screen.dart顶栏右上角的「赞助」按钮及其静默逻辑
lib/immersive_study/widgets/dashboard_overview.dartDashboard 上的赞助面板与「致谢」链接
lib/shared/widgets/web_embed.dart条件导入的 iframe 封装（见下）
Ko-fi 面板在 Web 上用 HtmlElementView 渲染 AppEnv.kofiEmbedUrl 的 iframe； 原生平台没有 iframe，web_embed_io.dart 退化为用 url_launcher 打开 AppEnv.kofiPageUrl。改 Ko-fi 账号只需 --dart-define=KOFI_USERNAME=...。

​
「赞助」按钮的静默期

按钮的可见性完全由服务端决定，客户端不做日期计算： DONATION_PROMPT_MUTE_DAYS 默认 30（即产品口径的「一个月」）。按钮只对已登录用户 渲染；汇总还没回来或接口失败时同样不显示——宁可少一次募捐，也不要让按钮闪进闪出， 或在 user_manager 异常时挡住页面其余部分。

​
致谢名单

GET /api/donations/supporters 是公开接口：它从每个用户的 Dashboard 都能点到， 返回内容只有用户名与日期。登记时勾选「匿名」的记录不进名单，但会计入 anonymous_count，因此名单里仍会显示「另有 N 位匿名赞助者」。

​
相关