docs(welfare): 不活跃清零 设计/计划对齐"邀请金不清" + inactivity 两表字典
- spec/plan:清零范围改两桶、run_warn 逐用户隔离不阻塞清零、stats 增 warn_failed - docs/database:新增 inactivity_reset_log / inactivity_notification_log 条目 + README 索引 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
guke
@@ -2,7 +2,9 @@
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
|
||||
**Goal:** 连续 15 天不活跃(北京自然日、第 16 日 0 点对齐)的用户,自动清零金币+折算现金+邀请现金,清零前按可配置节奏预警,全程留审计。
|
||||
**Goal:** 连续 15 天不活跃(北京自然日、第 16 日 0 点对齐)的用户,自动清零金币+折算现金(**邀请现金不清**——产品红线),清零前按可配置节奏预警,全程留审计。
|
||||
|
||||
> **更新(2026-07-18):** 邀请现金(invite_cash_balance_cents)由"三桶全清"改为**不清**——遵循 wallet.CoinAccount 的"物理隔离/产品红线"、与另一实现分支对齐。**以 `inactivity.clear_user` 现码为准**;下方 Task 7 的历史代码片段仍写三桶归零,阅读时以现码为准。
|
||||
|
||||
**Architecture:** 活跃口径抽成共享模块 `app/repositories/activity.py`(worker 与 admin 共用,单一真源);业务逻辑在 `app/repositories/inactivity.py`(纯同步、可单测);进程内每日 asyncio worker `app/core/inactivity_reset_worker.py`(仿 `daily_exchange_worker`,文件锁 + 北京日守卫 + 总闸)。预警走可插拔 `InactivityNotifier`,v1 为日志占位。审计双写:`inactivity_reset_log` 专表 + 钱包流水 `biz_type=inactivity_reset`。
|
||||
|
||||
|
||||
@@ -40,7 +40,7 @@
|
||||
|---|---|---|
|
||||
| **活跃口径** | 与"用户管理"一致：`max(home_view, 比价, 领券)`，**不含 last_login_at**；无任何信号时以 `created_at` 为非空基线 | 比价可从**浮窗**触发、不进首页；`last_login_at` 只在登录/换绑动作更新（re-login 也算），代表不了"在用 App"，故彻底排除 |
|
||||
| **"进首页"信号落地** | **方案 A：前端上报 `home_view` 埋点**（复用 `/analytics/events`），非新接口 | 三个活跃信号统一为同类埋点事件；零新接口零新列；与 admin 口径天然一致。B（鉴权接口 + 列）"更权威"的优势是假的——比价/领券仍是端上报事件，最弱环决定整体可信度 |
|
||||
| **清零范围** | **金币 + 折算现金 + 邀请现金** 三桶全清 | 对应"账户里的金币和现金" |
|
||||
| **清零范围** | **金币 + 折算现金**（**邀请现金不清**——产品红线，仅快照入审计） | 对应"账户里的金币和现金"；邀请奖励金与金币现金物理隔离、不可累加，见 `wallet.CoinAccount` 注释 |
|
||||
| **预警推送** | **可插拔通知器 + 日志占位**（v1），后续接 JPush/短信 | 现状无真实推送能力；先把清零主流程 + 审计做扎实，不阻塞 |
|
||||
| **预警时机** | **完全可配置**（提前天数列表 + 次数 + 执行点 + 通道） | R5 |
|
||||
| **触发方式** | **进程内每日 worker**，仿 `daily_exchange_worker` | 与项目最新模式一致，无需外部 cron |
|
||||
@@ -82,7 +82,7 @@ last_active = max(
|
||||
- `last_active_expr(base_col, ev_sub, eng_sub, dialect)` —— 生成 `greatest`/`max`（PG `func.greatest`／SQLite `func.max`）；子聚合缺失时 `coalesce(子聚合, User.created_at)` 兜底（注册基线恒非空，**替代原 last_login_at**）。
|
||||
- `_norm_utc()` —— 沿用现 admin 的 naive→UTC 归一（SQLite naive / PG aware 混算保护）。
|
||||
- `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_inactive_users(db, *, cutoff, with_balance=True)` —— **worker 专用**：join `CoinAccount`，筛 `last_active < cutoff`（cutoff = 北京 0 点对齐边界，见口径）且（`coin_balance>0 OR 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）。
|
||||
@@ -155,21 +155,21 @@ for user, acc, last_active, inactive_days in activity.select_inactive_users(db,
|
||||
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)
|
||||
if before == (0,0,0): continue
|
||||
if acc.coin_balance == 0 and acc.cash_balance_cents == 0: continue # 邀请现金不清,不算可清余额
|
||||
log = InactivityResetLog(user_id=user.id, coin_balance_before=before[0],
|
||||
cash_balance_cents_before=before[1], invite_cash_balance_cents_before=before[2],
|
||||
cash_balance_cents_before=before[1], invite_cash_balance_cents_before=before[2], # 邀请现金仅快照
|
||||
last_active_at=last_active, inactive_days=inactive_days, reason=f"inactive_{RESET_DAYS}d")
|
||||
db.add(log); db.flush() # 拿 log.id 作 ref_id 交叉链接
|
||||
if acc.coin_balance: wallet.grant_coins(db, user.id, -acc.coin_balance, biz_type="inactivity_reset", ref_id=str(log.id), remark="15天不活跃清零")
|
||||
if acc.cash_balance_cents: wallet.grant_cash(db, user.id, -acc.cash_balance_cents, biz_type="inactivity_reset", ref_id=str(log.id), remark="15天不活跃清零")
|
||||
if acc.invite_cash_balance_cents: wallet.grant_invite_cash(db, user.id, -acc.invite_cash_balance_cents, biz_type="inactivity_reset", ref_id=str(log.id), remark="15天不活跃清零")
|
||||
# 邀请现金(invite_cash_balance_cents)不清:产品红线、两本账物理隔离,仅快照记入审计。
|
||||
db.commit()
|
||||
except SQLAlchemyError:
|
||||
db.rollback(); stats["failed"] += 1
|
||||
```
|
||||
|
||||
- `grant_*` 负数出账、`balance_after=0`、写三条流水；`grant_coins` 负数**不**动 `total_coin_earned`（历史累计保留）。
|
||||
- 逐用户独立 commit：一个失败不影响其余。返回 `stats = {scanned, warned, cleared, failed}` 并 `logger.info`。
|
||||
- `grant_*` 负数出账、`balance_after=0`、写**两条**流水（金币 + 折算现金；**邀请现金不清**）；`grant_coins` 负数**不**动 `total_coin_earned`（历史累计保留）。
|
||||
- 逐用户独立 commit：一个失败不影响其余。返回 `stats = {warned, warn_skipped, warn_failed, scanned, cleared, failed}` 并 `logger.info`。**预警逐用户 try/except 隔离、且预警整段异常也绝不阻塞清零**（清零是不可逆资金操作，不能被通知故障拖住）。
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user