docs(welfare): 明确不活跃清零的时间边界(北京自然日, 第16日0点)
补充清零日界定义:末次活跃日记为第1日,从末次活跃起「第16日0点」(北京)清零 = 北京 00:00 of (last_active_date + 15天),按自然日 0 点对齐,非从末次活跃时刻滚动 15×24h。 - 应清零 ⟺ (cn_today() − last_active_date).days ≥ RESET_DAYS - SQL cutoff = 北京 00:00 of (cn_today() − (RESET_DAYS−1)),新增 activity.reset_cutoff() 辅助 - 资格边界(第16日0点)与 worker 执行点 RUN_HOUR 解耦;inactive_days 改按北京自然日 - 同步更新 §4/§6/§8/§10 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
guke
@@ -64,7 +64,13 @@ last_active = max(
|
||||
max AnalyticsEvent.created_at WHERE event IN ACTIVE_EVENTS,
|
||||
max CouponPromptEngagement.created_at WHERE engage_type == "claim_started",
|
||||
)
|
||||
不活跃 ⟺ last_active < now - INACTIVITY_RESET_DAYS 天
|
||||
不活跃判定：按北京自然日、0 点对齐（非从末次活跃时刻滚动 15×24h）
|
||||
last_active_date = 北京(last_active).date() # 末次活跃的北京日，记为「第 1 日」
|
||||
清零边界 = 北京 00:00 of (last_active_date + RESET_DAYS 天) =「第 (RESET_DAYS+1) 日 0 点」 # 15 → 第16日0点
|
||||
应清零 ⟺ (cn_today() − last_active_date).days ≥ RESET_DAYS
|
||||
⟺ last_active < cutoff， cutoff = 北京 00:00 of (cn_today() − (RESET_DAYS−1)) # 供 SQL 比较
|
||||
inactive_days = (cn_today() − last_active_date).days # 清零当日恰 = RESET_DAYS
|
||||
例：末次活跃 1/1 → 1/16 00:00(第16日0点)清零，当日 inactive_days=15；1/15 及之前不清
|
||||
```
|
||||
|
||||
### 模块内容
|
||||
@@ -75,7 +81,8 @@ last_active = max(
|
||||
- `last_active_subqueries(db)` —— 复刻现 admin `queries._last_active_parts()`：两个按 `user_id` 的 `GROUP BY max(created_at)` 聚合子查询。
|
||||
- `last_active_expr(login_col, ev_sub, eng_sub, dialect)` —— 生成 `greatest`/`max`（PG 用 `func.greatest`，SQLite 用 `func.max`），保留现有 `coalesce(..., last_login_at)` 兜底写法。
|
||||
- `_norm_utc()` —— 沿用现 admin 的 naive→UTC 归一（SQLite naive / PG aware 混算保护）。
|
||||
- `select_inactive_users(db, *, cutoff, with_balance=True)` —— **worker 专用**：join `CoinAccount`，筛 `last_active < cutoff` 且（`coin_balance>0 OR cash_balance_cents>0 OR invite_cash_balance_cents>0`），返回 `(user, account, last_active, inactive_days)`。
|
||||
- `reset_cutoff(reset_days)` / `warn_cutoff(reset_days, k)` —— 生成**北京 0 点对齐**的边界 datetime（见口径）：`reset_cutoff = 北京 00:00 of (cn_today() − (reset_days−1))`，供下面查询按 `last_active < cutoff` 比较。
|
||||
- `select_inactive_users(db, *, cutoff, with_balance=True)` —— **worker 专用**：join `CoinAccount`，筛 `last_active < cutoff`（cutoff = 北京 0 点对齐边界，见口径）且（`coin_balance>0 OR cash_balance_cents>0 OR invite_cash_balance_cents>0`），返回 `(user, account, last_active, inactive_days)`。
|
||||
- `select_warn_targets(db, *, reset_days, warn_days_before)` —— **worker 专用**：返回 `(user, account, last_active, inactive_days, stage)` 元组——各"提前天数"窗口内、有余额、本 streak 未推过档 `stage` 的用户（去重结合 `notification_log`，逻辑见 §9）。
|
||||
|
||||
> **参考现状**：现口径散落在 `app/admin/repositories/queries.py:38,91-124,199-204`（`_ACTIVE_EVENTS`/`_last_active_parts`/`greatest`）与 `app/admin/repositories/stats.py:51-52,138-146`（`COMPARE_START_EVENT`/`COUPON_START_EVENT`/活跃用户集）。这些改为从 `activity.py` 导入（§12）。
|
||||
@@ -129,6 +136,7 @@ last_active = max(
|
||||
|
||||
- 每 `INACTIVITY_RESET_CHECK_INTERVAL_SEC` 秒醒一次；`last_run: date` 守卫**北京日**，保证每日只跑一轮。
|
||||
- 仅当 `cn_today() != last_run` 且当前北京小时 `>= INACTIVITY_RESET_RUN_HOUR` 时执行（启动补跑同 daily_exchange 语义）。
|
||||
- **清零资格边界 = 第 16 日 0 点（北京，见 §4），与 worker 执行点解耦**：worker 于当日 `RUN_HOUR`（默认 3 点）跑，把已过边界者一并清；若要严格 0 点触发可置 `RUN_HOUR=0`，但注意与 `daily_auto_exchange` 的 0 点任务错峰。
|
||||
- lifespan 里 `start_inactivity_reset_worker()` / `stop_...`（仿 `start_daily_exchange_worker` 在 `app/main.py` 的接线）。
|
||||
|
||||
### 一轮 `run_once(db)` 两阶段（同一次运行、各自逐用户独立 commit）
|
||||
@@ -143,7 +151,7 @@ for user, acc, last_active, inactive_days, stage in activity.select_warn_targets
|
||||
|
||||
**阶段 B — 清零**（`biz_type="inactivity_reset"`）
|
||||
```
|
||||
for user, acc, last_active, inactive_days in activity.select_inactive_users(db, cutoff=now-RESET_DAYS):
|
||||
for user, acc, last_active, inactive_days in activity.select_inactive_users(db, cutoff=activity.reset_cutoff(RESET_DAYS)): # 北京 00:00 of (今天−(RESET_DAYS−1))
|
||||
try:
|
||||
acc = wallet.get_or_create_account(db, user.id, commit=False, lock=True) # 行锁
|
||||
before = (acc.coin_balance, acc.cash_balance_cents, acc.invite_cash_balance_cents)
|
||||
@@ -195,7 +203,8 @@ INACTIVITY_RESET_CHECK_INTERVAL_SEC = 1800 # worker 唤醒间隔（可复用现
|
||||
```
|
||||
|
||||
- 清零范围（三桶）固定为常量，不做配置。
|
||||
- `INACTIVITY_WARN_DAYS_BEFORE` 语义：档位 `k` ⟹ 当 `inactive_days >= RESET_DAYS-k` 且 `< RESET_DAYS` 且本 streak 未推过档 `k` 时预警（漏跑某天时补发最紧急未推档，§9）。
|
||||
- `INACTIVITY_WARN_DAYS_BEFORE` 语义（`inactive_days` 为北京自然日，见 §4）：档位 `k` ⟹ 当 `inactive_days >= RESET_DAYS-k` 且 `< RESET_DAYS` 且本 streak 未推过档 `k` 时预警，即在北京日 `last_active_date + (RESET_DAYS−k)` 触发（漏跑某天时补发最紧急未推档，§9）。
|
||||
- `INACTIVITY_RESET_RUN_HOUR` 只决定 worker 每日执行点，**不改变**"第 16 日 0 点"这一资格边界（§4/§6）。
|
||||
|
||||
---
|
||||
|
||||
@@ -215,7 +224,7 @@ INACTIVITY_RESET_CHECK_INTERVAL_SEC = 1800 # worker 唤醒间隔（可复用现
|
||||
| 新用户 | 注册即登录（`last_login_at` 非空）→ 初始活跃；15 天不回归才清 |
|
||||
| 在途提现 | 提现申请时现金已扣入 `WithdrawOrder`，当前余额已不含在途；只清当前余额、不动提现单。提现失败退款到已清账户 = 用户的钱，正常 |
|
||||
| 与 `daily_auto_exchange` 并存 | 各自逐用户幂等；金币多已日结折现金，三桶全清正好覆盖 |
|
||||
| 时区 | 统一北京（`rewards.cn_today()`/`CN_TZ`）；流水 `created_at` 沿用北京 wall-clock naive |
|
||||
| 时区/日界 | 统一北京（`rewards.cn_today()`/`CN_TZ`）；**清零/预警按北京自然日 0 点对齐**（末次活跃记为第 1 日 → 第 16 日 0 点清零，见 §4），非滚动 24h；流水 `created_at` 沿用北京 wall-clock naive |
|
||||
| 误清防护 | 总闸默认关；先灰度只看预警/清零**名单**对不对，再开清零（§13） |
|
||||
|
||||
---
|
||||
|
||||
Reference in New Issue
Block a user