guke
ece498876f
- 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>
36 lines
3.1 KiB
Markdown
36 lines
3.1 KiB
Markdown
# inactivity_reset_log — 15 天不活跃清零审计
|
|
|
|
> 模型 `app/models/inactivity.py` · 仓库 `app/repositories/inactivity.py` · worker `app/core/inactivity_reset_worker.py` · [← 索引](./README.md) · [总览](./OVERVIEW.md)
|
|
|
|
连续 15 天不活跃(北京自然日,活跃口径见 `app/repositories/activity.py`:`home_view` + 发起比价 + 发起领券,**不含登录**)的用户,worker 每日自动清零其**金币 + 折算现金**。每清一个用户写一行,记清零前三桶余额快照 + 原因 + 判定时的活跃时间/不活跃天数,供纠纷排查。清零同时另写 2 条钱包流水(`coin_transaction` / `cash_transaction`,`biz_type=inactivity_reset`,`ref_id=` 本表 `id`),资金流可逐笔回溯、人工恢复。**邀请奖励金(`invite_cash_balance_cents`)是产品红线、不清零**,本表 `invite_cash_balance_cents_before` 仅为清零时仍保留的邀请金快照(非被清金额)。append-only,不更新。
|
|
|
|
## 用在哪 / 增删改查
|
|
- **C(插入)**:`inactivity.clear_user` 逐用户清零(独立事务、行锁)时写一行,`db.flush()` 拿 `id` 作流水 `ref_id` 交叉链接。
|
|
- **U / D**:无(append-only 审计)。
|
|
- **R**:纠纷排查 / 对账(与 `coin_transaction` / `cash_transaction` 的 `ref_id` 交叉核对)。
|
|
|
|
## 字段
|
|
| 列 | 类型 | 约束 / 默认 | 说明(取值 / join) |
|
|
|---|---|---|---|
|
|
| `id` | Integer | **PK**, autoincrement | 主键;作 `ref_id` 写入两条清零流水 |
|
|
| `user_id` | Integer | NOT NULL, index | 被清零用户;只索引不设外键(同 `analytics_event`,避免删用户级联 / 留历史) |
|
|
| `coin_balance_before` | Integer | NOT NULL | 清零前金币余额(个数);= 对应 `coin_transaction.amount` 绝对值 |
|
|
| `cash_balance_cents_before` | Integer | NOT NULL | 清零前折算现金余额(分);= 对应 `cash_transaction.amount_cents` 绝对值 |
|
|
| `invite_cash_balance_cents_before` | Integer | NOT NULL | 清零时的**邀请奖励金**余额快照(分)——**不清、原封保留**,仅记录以证明"未动邀请金" |
|
|
| `last_active_at` | DateTime(tz) | nullable | 判定时的最近活跃时刻(UTC);无任何活跃信号时兜底为 `user.created_at` |
|
|
| `inactive_days` | Integer | NOT NULL | 判定时的不活跃天数(北京自然日) |
|
|
| `reason` | String(32) | NOT NULL | 清零原因,如 `inactive_15d` |
|
|
| `reset_at` | DateTime(tz) | server_default now(), index | 清零时刻 |
|
|
|
|
## 关系 / Join Key
|
|
- `user_id` → `user.id`(无外键直连,靠 `user_id` 关联)。
|
|
- `id` → `coin_transaction.ref_id` / `cash_transaction.ref_id`(`biz_type=inactivity_reset`):审计行 ↔ 资金流水交叉对账。
|
|
|
|
## 索引与约束
|
|
- PK `id`;`ix_inactivity_reset_log_user_id`(按用户查)、`ix_inactivity_reset_log_reset_at`(按时间查)。
|
|
|
|
## 注意
|
|
- **只清 2 桶**:金币 + 折算现金;**邀请现金不清**(两本账物理隔离,见 [`coin_account`](./coin_account.md) / `wallet.CoinAccount` 注释)。
|
|
- **天然幂等**:清完余额=0,次日不再匹配;worker 重启 / 多次唤醒 / 补跑都不会重复清零或重复流水。
|
|
- **总闸默认关**(`INACTIVITY_RESET_ENABLED=false`),灰度验证清零名单后再开。
|