From 91b0a2feb241a90d74fd9ddc4e124f91accfe993 Mon Sep 17 00:00:00 2001 From: argszero Date: Sun, 13 Sep 2026 12:35:42 +0800 Subject: [PATCH] docs(gift): drop the phantom "dashboard" trigger from the module doc The module header claimed the daily gift is lazily triggered by "wallet / dashboard / settle", but `ensure_daily_gift` is only called from `routes/wallet.rs` (the wallet endpoint) and `gateway.rs`'s forwarding balance prechecks (the forward / forward_stream paths that lead to settle). `/api/dashboard` never triggers it - it only reports whatever has already been recorded. Runtime proof: the same `GET /api/dashboard` returns `{"month":[],"net":-0.0}` on a fresh user, but `{"month":[{"pts":1.0,"type":"gift"}],"net":1.0}` once `GET /api/wallet` has run first. The author's own test comment (wallet.rs:682-686) states the gift is triggered by the first wallet fetch, i.e. the dashboard reflects rather than triggers. So the doc line, not the code, is wrong - and it has been wrong since the file was born in 889532d. Rewrite it as an invariant plus a pointer (the trigger sites are whatever calls `ensure_daily_gift`) instead of a roster that rots the next time a call site is added or removed. --- src/gift.rs | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/gift.rs b/src/gift.rs index f3b0472..146eade 100644 --- a/src/gift.rs +++ b/src/gift.rs @@ -3,7 +3,8 @@ //! P1（rant 2026-08-18T11:03:02）： //! - 新人赠送：注册（users.created_at）起连续 10 天内每天 1 点，当日有效 //! （expires_at = 当天 23:59:59）；第 11 天起不再赠送 -//! - 懒加载触发：wallet / dashboard / settle 前调用 ensure_daily_gift +//! - 懒加载触发：凡是需要「可用余额含当日赠送」的读取点，各自在读取前调用 `ensure_daily_gift` +//! （触发点即本函数的调用点，不在此列举）；只读报表（如 `/api/dashboard`）只反映已入账的赠送，不触发 //! - 防薅羊毛：每人每日仅一笔；过期未用自动失效（查询时惰性清理） //! - 消费扣减顺序：先扣最早到期的赠送点数，不足再扣永久 balance