# 主动推送触发规则

## 概述

主动推送用于在合适的时间为家长提供个性化故事建议，提升使用频次与亲子阅读习惯。推送默认关闭，需家长开启并配置时间。

---

## 一、数据输入

- **孩子档案**: `child_profiles`（年龄、兴趣、成长主题）
- **故事数据**: `stories`（最近生成/阅读时间、主题标签）
- **推送配置**: `push_configs`（时间、周期、开关）
- **节日与生日**: 预置日历 + `birth_date`
- **行为事件**: 阅读/播放/跳过等行为埋点

---

## 二、触发类型与规则

### 2.1 时间触发（睡前）
- 条件：当前时间落在用户设定 `push_time` 附近（建议 ±30 分钟）。
- 频率：同一孩子每天最多 1 次。
- 示例：19:00-21:00 之间推送“今晚想听什么故事？”

### 2.2 事件触发（节日/生日）
- 条件：
  - 生日：`birth_date` 月日与当天一致。
  - 节日：命中节日清单（如儿童节、中秋节等）。
- 频率：当天仅推送 1 次，优先级高于时间触发。

### 2.3 行为触发（召回）
- 条件：最近 3 天无故事生成或阅读行为。
- 频率：每 3 天最多 1 次，避免频繁打扰。

### 2.4 成长触发（年龄变化）
- 条件：年龄跨越关键节点（如 4→5 岁）。
- 频率：每次年龄变化仅触发一次。
- 目的：推荐难度升级或新的成长主题。

---

## 三、优先级与抑制规则

**优先级顺序**（从高到低）:
1. 事件触发
2. 成长触发
3. 行为触发
4. 时间触发

**抑制规则**:
- 当天已推送则不再触发其他类型。
- 若在静默时间（21:00-09:00）触发，则延迟至下一个允许窗口。
- 用户关闭推送或未配置推送时间时，不触发。

---

## 四、个性化内容策略

- **兴趣标签**: 引用孩子的兴趣标签生成主题。
- **成长主题**: 优先匹配当前成长主题。
- **历史偏好**: 参考最近故事的标签与完成度。

**示例模板**:
- “今晚给{child_name}讲一个关于{interest}的故事，好吗？”
- “{child_name}最近在学习{growth_theme}，我准备了一个新故事。”

---

## 五、调度实现建议

使用 Celery Beat 每 5-10 分钟执行一次规则检查：

```python
@celery.task
def check_push_notifications():
    now = datetime.now(local_tz)
    configs = get_enabled_configs(now)

    for config in configs:
        if has_sent_today(config.child_profile_id):
            continue

        trigger = select_trigger(config, now)
        if trigger:
            send_push_notification(config.user_id, config.child_profile_id, trigger)
```

**关键点**:
- 需要记录每日推送日志用于去重。
- 优先级触发时应立即标记已发送。

---

## 六、日志与度量

建议增加 `push_events` 事件表用于统计与去重：

```sql
CREATE TABLE push_events (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id UUID NOT NULL,
    child_profile_id UUID NOT NULL,
    trigger_type VARCHAR(20) NOT NULL,  -- time/event/behavior/growth
    sent_at TIMESTAMP WITH TIME ZONE NOT NULL,
    status VARCHAR(20) NOT NULL,        -- sent/failed/suppressed
    reason TEXT
);
```

核心指标：
- Push 发送成功率
- 打开率（CTA 点击）
- 触发分布占比

---

## 七、安全与合规

- **默认关闭**，需家长显式开启。
- 支持一键关闭或设定免打扰时段。
- 遵循儿童隐私合规要求，最小化推送内容敏感信息。

---

## 八、相关文档

- [记忆智能系统 PRD](./MEMORY-INTELLIGENCE-PRD.md)
- [孩子档案数据模型](./CHILD-PROFILE-MODEL.md)