growork 1.0.0

package/test/backend-api.md

@@ -0,0 +1,1236 @@
+# iOS 横幅推送与站内信方案
+
+## 整体架构
+
+### 系统分层架构
+
+
+```plaintext
+flowchart TB
+    subgraph Client[客户端]
+        iOS[iOS APP]
+        Admin[管理后台]
+    end
+    
+    subgraph Backend[bloomo-core 后端服务]
+        API[REST API]
+        Scheduler[定时调度器]
+        Service[站内信服务]
+        Cache[缓存服务]
+        Async[异步推送]
+    end
+    
+    subgraph Data[数据存储]
+        DB[(PostgreSQL)]
+        Redis[(Redis)]
+    end
+    
+    FCM[FCM 推送服务]
+    
+    Client --> API
+    API --> Service
+    Scheduler --> Service
+    Service --> Cache
+    Cache --> Redis
+    Service --> DB
+    Service --> Async
+    Async --> FCM
+    FCM -.->|推送通知| iOS
+```
+
+### 消息发送时序图
+
+
+
+```plaintext
+sequenceDiagram
+    autonumber
+    participant Admin as 管理后台
+    participant API as Admin API
+    participant TemplateService as 模板服务
+    participant TaskService as 任务服务
+    participant DB as PostgreSQL
+    
+    Note over Admin, DB: 1. 创建消息模板
+    Admin->>API: POST /admin/inbox/templates
+    API->>TemplateService: createTemplate(dto)
+    TemplateService->>DB: INSERT inbox_message_templates
+    DB-->>TemplateService: template_id
+    TemplateService-->>API: 模板创建成功
+    API-->>Admin: 返回 template_id
+    
+    Note over Admin, DB: 2. 创建发送任务
+    Admin->>API: POST /admin/inbox/tasks
+    API->>TaskService: createTask(dto)
+    TaskService->>DB: INSERT inbox_message_tasks
+    DB-->>TaskService: task_id
+    TaskService-->>API: 任务创建成功
+    API-->>Admin: 返回 task_id
+```
+
+### 定时任务执行时序图
+
+
+
+```plaintext
+sequenceDiagram
+    autonumber
+    participant Scheduler as 定时调度器
+    participant Redis as Redis缓存
+    participant DB as 数据库
+    participant Service as 站内信服务
+    participant FCM as FCM推送
+    
+    Note over Scheduler, FCM: 每小时整点执行
+    
+    Scheduler->>DB: 查询活跃任务
+    DB-->>Scheduler: 任务列表
+    
+    Scheduler->>Redis: 获取时区列表 + 已执行时区
+    Redis-->>Scheduler: 时区数据
+    
+    loop 遍历待执行时区
+        Scheduler->>Scheduler: 窗口匹配（过去60分钟）
+        
+        alt 匹配成功且未执行
+            Scheduler->>Redis: 获取该时区用户ID
+            Redis-->>Scheduler: 用户ID列表
+            
+            Scheduler->>DB: 分批查询用户详情
+            DB-->>Scheduler: 用户列表
+            
+            Scheduler->>Service: 发送消息
+            Service->>DB: 保存站内信记录
+            
+            opt 启用推送
+                Service->>FCM: 异步批量推送
+            end
+            
+            Scheduler->>Redis: 标记已执行
+            Scheduler->>DB: 保存执行记录
+        end
+    end
+```
+
+### 用户查看站内信时序图
+
+
+```plaintext
+sequenceDiagram
+    autonumber
+    participant iOS as iOS APP
+    participant API as User API
+    participant Service as 站内信服务
+    participant DB as PostgreSQL
+    
+    Note over iOS, DB: 获取消息列表（含 isRead、isExpired 字段）
+    iOS->>API: GET /inbox/messages
+    API->>Service: getMessages(userId, pageable)
+    Service->>DB: SELECT（包括过期消息）
+    DB-->>Service: Page of Message
+    Service-->>API: 返回列表（含 isExpired 标识）
+    API-->>iOS: 消息列表
+    iOS->>iOS: 前端计算未读数（isRead=false 的数量）
+    iOS->>iOS: 过期消息置灰不可点击
+    
+    Note over iOS, DB: 标记已读
+    iOS->>API: PUT /inbox/messages/{id}/read
+    API->>Service: markAsRead(userId, messageId)
+    Service->>DB: UPDATE SET is_read = true
+    Service-->>API: success
+    API-->>iOS: 200 OK
+```
+
+### 缓存预热时序图
+
+
+```plaintext
+sequenceDiagram
+    autonumber
+    participant App as 应用启动
+    participant CacheWarmer as 缓存预热组件
+    participant CacheService as 缓存服务
+    participant Redis as Redis
+    participant UserRepo as 用户Repository
+    participant DB as PostgreSQL
+    
+    Note over App, DB: 应用启动时预热缓存
+    App->>CacheWarmer: ApplicationRunner.run()
+    CacheWarmer->>CacheService: warmUpCache()
+    
+    CacheService->>Redis: 清除旧缓存 DEL inbox:tz:users:*
+    CacheService->>Redis: 清除旧缓存 DEL inbox:timezones
+    
+    CacheService->>UserRepo: 查询所有用户ID和时区
+    UserRepo->>DB: SELECT id, timezone FROM users
+    DB-->>UserRepo: List of [userId, timezone]
+    UserRepo-->>CacheService: List of [userId, timezone]
+    
+    loop 按时区分组
+        CacheService->>Redis: SADD inbox:tz:users:{timezone} userId
+        CacheService->>Redis: SADD inbox:timezones timezone
+    end
+    
+    CacheService-->>CacheWarmer: 预热完成
+    CacheWarmer-->>App: 启动继续
+    
+    Note over App, DB: 每日凌晨3点刷新缓存
+    CacheWarmer->>CacheService: warmUpCache()
+    Note right of CacheService: 重复上述流程
+```
+
+### FCM 推送流程时序图
+
+
+```plaintext
+sequenceDiagram
+    autonumber
+    participant iOS as iOS APP
+    participant FirebaseSDK as Firebase SDK
+    participant API as User API
+    participant UserService as 用户服务
+    participant CacheService as 缓存服务
+    participant Redis as Redis
+    participant DB as PostgreSQL
+    
+    Note over iOS, DB: APP 启动时通过登录接口上报 FCM Token 和时区
+    iOS->>FirebaseSDK: 获取 FCM Token
+    FirebaseSDK-->>iOS: fcm_token
+    iOS->>API: POST /user/login 包含 fcmToken、timezone 字段
+    API->>UserService: login 或 updateClientInfo
+    UserService->>DB: UPDATE users SET fcm_token, timezone
+    DB-->>UserService: success
+    
+    alt 时区变更
+        UserService->>CacheService: moveUserTimezone(userId, old, new)
+        CacheService->>Redis: SREM inbox:tz:users:{old} userId
+        CacheService->>Redis: SADD inbox:tz:users:{new} userId
+        CacheService->>Redis: SADD inbox:timezones {new}
+    end
+    
+    UserService-->>API: success
+    API-->>iOS: 200 OK
+```
+
+## 数据库设计
+
+### 站内信模板表 `inbox_message_templates`
+
+存储站内信模板配置，支持灵活的内容定义。
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| id | BIGSERIAL | 主键 |
+| template_code | VARCHAR(64) | 模板编码（唯一标识） |
+| title | VARCHAR(256) | 标题（支持变量占位符） |
+| content | TEXT | 内容（支持富文本/Markdown） |
+| content_type | VARCHAR(20) | 内容类型：TEXT / RICH_TEXT / TEMPLATE |
+| image_url | VARCHAR(512) | 可选图片 URL |
+| action_type | VARCHAR(32) | 点击动作类型：NONE / DEEP_LINK / WEB_URL |
+| action_url | VARCHAR(512) | 动作链接 |
+
+| variables | JSONB | 模板变量定义（如 `{"username": "string"}`) |
+
+| status | SMALLINT | 状态：0-禁用 1-启用 |
+
+| create_time | TIMESTAMPTZ | 创建时间 |
+
+| update_time | TIMESTAMPTZ | 更新时间 |
+
+### 站内信任务表 `inbox_message_tasks`
+
+存储定时/重复通知任务配置。支持固定模板或从 Remote Config 随机选择模板。
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| id | BIGSERIAL | 主键 |
+| task_name | VARCHAR(128) | 任务名称 |
+| template_id | BIGINT | 关联模板 ID（必填，定义消息格式和变量占位符） |
+
+| variable_values | JSONB | 固定模板变量值（如 `{"title": "Hello"}`），与 remote_config_key 二选一 |
+
+| remote_config_key | VARCHAR(128) | Remote Config 中的 key（存储文案列表，每天随机选一组），与 variable_values 二选一 |
+
+| target_type | VARCHAR(20) | 目标类型：ALL / USER_GROUP / INDIVIDUAL |
+
+| target_user_ids | TEXT[] | 目标用户 ID 列表（INDIVIDUAL 时使用） |
+
+| target_conditions | JSONB | 目标用户条件（USER_GROUP 时使用，如 `{"is_vip": true}`) |
+
+| inbox_enabled | BOOLEAN | 是否存储到站内信列表（默认 true） |
+
+| push_enabled | BOOLEAN | 是否发送推送（默认 false） |
+
+| silent_push | BOOLEAN | 是否静默推送（默认 false，仅发送 data 用于 APP 内弹窗，pushEnabled=true 时生效） |
+
+| push_title | VARCHAR(128) | 推送标题（可选，默认用模板标题） |
+
+| push_body | VARCHAR(256) | 推送内容摘要（可选，默认截取模板内容） |
+
+| schedule_type | VARCHAR(20) | 调度类型：IMMEDIATE / SCHEDULED / CRON |
+
+| scheduled_date | DATE | 定时发送日期（SCHEDULED 类型，用户当地日期） |
+
+| scheduled_local_time | TIME | 定时发送时间（SCHEDULED 类型，用户当地时间） |
+
+| cron_expression | VARCHAR(64) | Cron 表达式（CRON 类型，按用户时区执行） |
+
+| start_date | DATE | 任务生效开始日期 |
+
+| end_date | DATE | 任务生效结束日期（可选） |
+
+| valid_hours | INT | 消息有效时长（小时，从发送时算起，为空则永不过期） |
+
+| priority | SMALLINT | 消息优先级：0=普通, 1=重要, 2=紧急（默认 0） |
+
+| is_pinned | BOOLEAN | 是否置顶（默认 false） |
+
+| status | SMALLINT | 状态：0-禁用 1-启用 2-已完成 |
+
+| create_time | TIMESTAMPTZ | 创建时间 |
+
+| update_time | TIMESTAMPTZ | 更新时间 |
+
+### 任务执行记录表 `inbox_task_executions`
+
+追踪每个任务按时区的执行状态，用于支持按用户时区分批发送。
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| id | BIGSERIAL | 主键 |
+| task_id | BIGINT | 任务 ID |
+| timezone | VARCHAR(64) | 时区（如 Asia/Shanghai） |
+| execute_date | DATE | 执行日期 |
+| execute_time | TIMESTAMPTZ | 实际执行时间 |
+| user_count | INT | 发送用户数 |
+| push_count | INT | 推送数量 |
+| status | VARCHAR(20) | 状态：SUCCESS / FAILED / PARTIAL |
+| error_message | TEXT | 错误信息（失败时） |
+| create_time | TIMESTAMPTZ | 创建时间 |
+
+**索引**：
+
+- `UNIQUE (task_id, timezone, execute_date)` 防止同一时区同一天重复执行
+- `(task_id, execute_date)` 用于查询当天已选中的模板（确保同一天所有用户收到相同消息）
+### 用户站内信表 `user_inbox_messages`
+
+存储发送给每个用户的站内信记录。
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| id | BIGSERIAL | 主键 |
+| user_id | BIGINT | 用户 ID |
+| task_id | BIGINT | 来源任务 ID（可选） |
+| title | VARCHAR(256) | 标题 |
+| content | TEXT | 内容 |
+| content_type | VARCHAR(20) | 内容类型 |
+| image_url | VARCHAR(512) | 图片 URL |
+| action_type | VARCHAR(32) | 点击动作类型 |
+| action_url | VARCHAR(512) | 动作链接 |
+| priority | SMALLINT | 消息优先级：0=普通, 1=重要, 2=紧急（从任务继承） |
+| is_pinned | BOOLEAN | 是否置顶（从任务继承） |
+| is_read | BOOLEAN | 是否已读 |
+| read_time | TIMESTAMPTZ | 阅读时间 |
+| push_sent | BOOLEAN | 是否已发送推送 |
+| push_sent_time | TIMESTAMPTZ | 推送发送时间 |
+| expire_time | TIMESTAMPTZ | 过期时间（发送时根据任务配置计算） |
+| is_deleted | BOOLEAN | 是否已删除（软删除，默认 false） |
+| delete_time | TIMESTAMPTZ | 删除时间 |
+| create_time | TIMESTAMPTZ | 创建时间 |
+
+### User 表新增字段
+
+在现有 `users` 表中新增 FCM Token 相关字段（单设备模式）：
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| fcm_token | VARCHAR(512) | FCM 推送 Token |
+| fcm_token_update_time | TIMESTAMPTZ | Token 更新时间 |
+
+## Redis Key 清单
+
+[嵌入表格: PjaBsB4aAh4jPZtVSl2lraKJgBg_HssoHe]
+
+### Key 用途说明
+
+### 1. inbox:timezones
+
+- 用途：定时任务遍历所有时区，判断是否需要发送消息
+- 维护：应用启动预热 + 每日凌晨 3 点刷新
+### 2. inbox:tz:users:{timezone}
+
+- 用途：快速获取某时区的所有用户，避免数据库查询
+- 维护：应用启动预热 + 用户登录实时更新
+### 3. inbox:exec:{taskId}:{date}
+
+- 用途：防止同一任务在同一时区同一天重复执行
+- 维护：任务执行后写入； 48h TTL 自动清理
+### 4. inbox:content:{taskId}:{date}
+
+- 用途：Remote Config 随机文案场景，确保同一天所有用户看到相同文案
+- 维护：首次选中时写入； 48h TTL 自动清理
+
+## Firebase Remote Config 随机文案配置
+
+当任务配置了 `remote_config_key` 时，系统会从 Firebase Remote Config 读取**文案变量列表**，每天随机选择一组变量值填充到模板中发送（当天所有用户收到相同消息）。
+
+### 变量来源选择逻辑
+
+```plaintext
+if (task.remoteConfigKey != null) {
+    // 从 Remote Config 每天随机选一组变量
+    variables = selectRandomFromRemoteConfig(remoteConfigKey);
+} else {
+    // 使用固定变量
+    variables = task.variableValues;
+}
+```
+
+### 设计思路
+
+```plaintext
+┌─────────────────────────────────────────────────────────────┐
+│  数据库模板 (template_id)                                    │
+│  ┌─────────────────────────────────────────────────────┐   │
+│  │  title: "{{title}}"                                  │   │
+│  │  content: "{{content}}"                              │   │
+│  │  actionUrl: "bloomo://reading/daily"                 │   │
+│  └─────────────────────────────────────────────────────┘   │
+└─────────────────────────────────────────────────────────────┘
+                           │
+                           ▼ 填充变量
+┌─────────────────────────────────────────────────────────────┐
+│  Remote Config 文案列表 (每日随机选一组)                      │
+│  ┌─────────────────────────────────────────────────────┐   │
+│  │ [0] title: "Trust Your Intuition"                    │   │
+│  │     content: "Today, trust your inner voice..."      │   │
+│  ├─────────────────────────────────────────────────────┤   │
+│  │ [1] title: "Embrace New Beginnings"                  │   │
+│  │     content: "A fresh start awaits you..."           │   │
+│  ├─────────────────────────────────────────────────────┤   │
+│  │ [2] title: "Love is All Around"                      │   │
+│  │     content: "The universe is sending love..."       │   │
+│  └─────────────────────────────────────────────────────┘   │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Remote Config 配置格式
+
+在 Firebase Console 的 Remote Config 中配置一个 JSON 参数，Key 与任务的 `remote_config_key` 对应：
+
+**Key**: `daily_inspiration_contents`
+
+**Value**:
+
+```json
+[
+  {
+    "title": "Trust Your Intuition",
+    "content": "Today, the cards suggest you trust your inner voice. Let your intuition guide your decisions.",
+    "pushTitle": "Daily Inspiration",
+    "pushBody": "Trust your intuition today"
+  },
+  {
+    "title": "Embrace New Beginnings",
+    "content": "A fresh start awaits you. Be open to new opportunities and let go of what no longer serves you.",
+    "pushTitle": "Daily Inspiration",
+    "pushBody": "Embrace new beginnings"
+  },
+  {
+    "title": "Love is All Around",
+    "content": "The universe is sending you love today. Open your heart to receive and give love freely.",
+    "pushTitle": "Daily Inspiration",
+    "pushBody": "Love is all around you"
+  }
+]
+```
+
+### 配置字段说明
+
+[嵌入表格: PjaBsB4aAh4jPZtVSl2lraKJgBg_Nfp8ec]
+
+## 推送类型完整对照表
+
+### 后端配置 vs 推送效果
+
+[嵌入表格: PjaBsB4aAh4jPZtVSl2lraKJgBg_6MomZZ]
+
+> *客户端需自行实现前台弹窗逻辑*
+
+### APP 状态 vs 用户体验
+
+[嵌入表格: PjaBsB4aAh4jPZtVSl2lraKJgBg_DJ6gjN]
+
+### 使用场景推荐
+
+[嵌入表格: PjaBsB4aAh4jPZtVSl2lraKJgBg_xWFS2o]
+
+### FCM 消息结构对比
+
+[嵌入表格: PjaBsB4aAh4jPZtVSl2lraKJgBg_q0LTHT]
+
+
+
+## 核心服务设计
+
+### FCM 推送 `FcmPushClient`
+
+#### 横幅推送（Notification + Data）
+
+使用 Firebase Admin SDK 的 `FirebaseMessaging` 类：
+
+#### 静默推送（仅 Data，用于 APP 内弹窗）
+
+静默推送不携带 `notification`，只发送 `data`。客户端在 APP 前台时自行展示弹窗，APP 不在前台时忽略。
+
+#### 推送模式对比
+
+[嵌入表格: PjaBsB4aAh4jPZtVSl2lraKJgBg_XAH36h]
+
+### 站内信服务 `InboxMessageService`
+
+### 通知任务调度器 `InboxMessageTaskScheduler`
+
+**按用户时区发送**：SCHEDULED 和 CRON 类型的任务都按用户时区分批发送，确保用户在本地时间收到通知。
+
+## API 设计
+
+### 管理端 API（Open API 认证）
+
+| 方法 | 路径 | 说明 |
+| --- | --- | --- |
+| POST | /admin/inbox/templates | 创建消息模板 |
+| PUT | /admin/inbox/templates/{id} | 更新消息模板 |
+| GET | /admin/inbox/templates | 查询模板列表 |
+| POST | /admin/inbox/tasks | 创建发送任务 |
+| PUT | /admin/inbox/tasks/{id} | 更新任务 |
+| GET | /admin/inbox/tasks | 查询任务列表 |
+| POST | /admin/inbox/send | 即时发送消息（创建 IMMEDIATE 类型任务） |
+
+### 用户端 API（Firebase 认证）
+
+| 方法 | 路径 | 说明 |
+| --- | --- | --- |
+| GET | /inbox/messages | 获取站内信列表（分页） |
+| PUT | /inbox/messages/{id}/read | 标记已读 |
+| PUT | /inbox/messages/read-all | 全部标记已读 |
+| DELETE | /inbox/messages/{id} | 删除消息 |
+| - | （通过现有登录接口上报 fcmToken，与 appInstanceId 一致） | -  |
+
+## 用户体验
+
+勿扰时段只对 **Banner 推送** 生效，**静默推送（站内弹窗）** 保持正常发送。
+
+[嵌入表格: PjaBsB4aAh4jPZtVSl2lraKJgBg_TRiRk4]
+
+**场景示例**：
+
+```plaintext
+凌晨 2:00 发送 Banner 推送：
+├── 站内信 → 存入数据库 ✅
+├── 推送 → 只更新角标（不弹系统通知）
+└── 用户第二天看到 App 图标有红点 → 打开查看
+
+凌晨 2:00 发送静默推送（站内弹窗）：
+├── 站内信 → 存入数据库 ✅
+├── 推送 → 正常发送静默推送
+└── 用户在 App 内 → 显示站内弹窗
+    用户在后台/锁屏 → 不显示（符合预期）
+```
+
+## iOS 客户端配置说明
+
+### 推送配置链路
+
+
+```plaintext
+flowchart LR
+    Backend[后端 FCM API] --> FCM[Firebase Cloud Messaging]
+    FCM --> APNs[Apple Push Notification]
+    APNs --> iOS[iOS 设备]
+```
+
+要使推送正常工作，需要 **Firebase 配置** 和 **iOS 客户端配置** 两部分。
+
+### Firebase Console 配置（一次性）
+
+| 步骤 | 操作 |
+| --- | --- |
+| 1 | 登录 Firebase Console，进入项目设置 |
+| 2 | 点击 Cloud Messaging 标签页 |
+
+| 3 | 在 Apple app configuration 中上传 **APNs Auth Key**（推荐）或 APNs 证书 |
+
+APNs Auth Key 获取方式：
+
+1. 登录 Apple Developer 后台
+1. 进入 Certificates, Identifiers & Profiles → Keys
+1. 创建新 Key，勾选 Apple Push Notifications service (APNs)
+1. 下载 .p8 文件，上传到 Firebase
+### iOS 客户端配置
+
+#### 2.1 处理静默推送（APP 内弹窗）
+
+静默推送只发送 data，不带 notification。客户端需要自行判断并展示弹窗。
+
+#### 2.2 静默推送与横幅推送的区别
+
+[嵌入表格: PjaBsB4aAh4jPZtVSl2lraKJgBg_QzIaaW]
+
+### 配置清单
+
+| 项目 | 负责方 | 状态 |
+| --- | --- | --- |
+| 上传 APNs Key 到 Firebase | iOS 开发者 | 待完成 |
+| Xcode 启用 Push Notifications | iOS 开发者 | 待完成 |
+| 集成 Firebase/Messaging SDK | iOS 开发者 | 待完成 |
+| 获取并上报 FCM Token | iOS 开发者 | 待完成 |
+| 实现站内信列表 UI | iOS 开发者 | 待完成 |
+| 后端 FCM 推送实现 | 后端开发者 | 待完成 |
+
+## 操作配置说明
+
+### 模板配置（Template）
+
+模板定义消息的格式和内容结构，是创建任务的前提。
+
+#### 基本信息
+
+**templateCode**（必填）
+
+- 模板的唯一标识符，用于区分不同模板
+- 建议使用 snake_case 命名，如 `daily_reminder`、`christmas_2026`
+- 创建后不可修改
+**title**（必填）
+
+- 消息标题，支持变量占位符 `{{变量名}}`
+- 示例：`Hello {{username}}` 或固定文本 `Daily Tarot Reading`
+**content**（必填）
+
+- 消息正文内容
+- 支持变量占位符 `{{变量名}}`
+- 根据 contentType 可以是纯文本或富文本
+**contentType**（必填）
+
+- `TEXT` - 纯文本，适用于简短通知
+- `RICH_TEXT` - 富文本，支持 HTML 格式，适用于图文消息
+#### 交互配置
+
+**actionType**
+
+- `NONE` - 无点击动作（默认）
+- `DEEP_LINK` - 深度链接，点击后跳转到 APP 内指定页面
+- `WEB_URL` - 网页链接，点击后打开外部浏览器
+**actionUrl**
+
+- actionType 为 `DEEP_LINK` 时：填写 APP 深度链接，如 `bloomo://reading/daily`
+- actionType 为 `WEB_URL` 时：填写完整网址，如 `https://bloomo.com/promo`
+**imageUrl**
+
+- 可选的消息图片 URL
+- 适用于节日祝福、活动通知等需要配图的场景
+#### 变量定义
+
+**variables**
+
+- JSON 对象，定义模板中使用的变量及其类型
+- 用于文档说明和校验，非强制
+- 示例：`{"username": "string", "date": "string"}`
+### 任务配置（Task）
+
+任务定义消息的发送策略，包括发送对象、发送时间、推送方式等。
+
+#### 基本信息
+
+**taskName**（必填）
+
+- 任务名称，用于后台管理识别
+- 建议包含日期或用途，如 `Daily Reading Reminder`、`Christmas 2026 Greeting`
+**templateId**（必填）
+
+- 关联的模板 ID
+- 必须是已存在且启用的模板
+#### 变量值配置
+
+以下两个字段**二选一**：
+
+**variableValues**
+
+- 固定的变量值，JSON 对象
+- 用于填充模板中的 `{{变量名}}` 占位符
+- 示例：`{"title": "Today's Reading", "content": "Your daily inspiration..."}`
+**remoteConfigKey**
+
+- Firebase Remote Config 中的参数 Key
+- 系统每天从该 Key 对应的文案列表中随机选择一组变量值
+- 适用于每日灵感、随机祝福等需要变化的场景
+- 示例：`daily_inspiration_contents`
+#### 目标配置
+
+**targetType**（必填）
+
+- `ALL` - 发送给所有用户
+- `USER_GROUP` - 发送给符合条件的用户群组
+- `INDIVIDUAL` - 发送给指定的用户列表
+**targetUserIds**
+
+- targetType 为 `INDIVIDUAL` 时必填
+- 用户 UID 数组
+- 示例：`["uid_123", "uid_456"]`
+**targetConditions**
+
+- targetType 为 `USER_GROUP` 时使用
+- JSON 对象，定义筛选条件
+- 示例：`{"is_vip": true}` 或 `{"country": "US"}`
+#### 站内信配置
+
+**inboxEnabled**
+
+- 是否将消息存储到站内信列表
+- 默认 `true`
+- 设为 `false` 时消息只发推送不存储
+#### 推送配置
+
+**pushEnabled**
+
+- 是否发送 FCM 推送
+- 默认 `false`
+- 设为 `true` 时会向用户设备发送推送通知
+**silentPush**
+
+- 是否静默推送（仅在 pushEnabled=true 时生效）
+- 默认 `false`（横幅推送）
+- 设为 `true` 时发送静默推送，用于 APP 内弹窗
+[嵌入表格: PjaBsB4aAh4jPZtVSl2lraKJgBg_53y29u]
+
+**pushTitle**
+
+- 推送通知的标题
+- 不填则使用模板 title（变量替换后）
+- 可被 Remote Config 中的 `pushTitle` 字段覆盖
+**pushBody**
+
+- 推送通知的内容摘要
+- 不填则截取模板 content 前 100 字符
+- 可被 Remote Config 中的 `pushBody` 字段覆盖
+#### 调度配置
+
+**scheduleType**（必填）
+
+- `IMMEDIATE` - 立即发送，任务创建后马上执行
+- `SCHEDULED` - 定时一次性发送，在指定日期时间发送
+- `CRON` - 按 Cron 表达式重复发送
+**scheduledDate** + **scheduledLocalTime**
+
+- scheduleType 为 `SCHEDULED` 时必填
+- `scheduledDate`：发送日期，格式 `2026-01-28`
+- `scheduledLocalTime`：发送时间，格式 `09:00:00`
+- 按用户时区执行：东京用户在东京时间收到，纽约用户在纽约时间收到
+**cronExpression**
+
+- scheduleType 为 `CRON` 时必填
+- 标准 6 位 Cron 表达式：`秒 分 时 日 月 周`
+- 按用户时区执行
+常用表达式：
+
+[嵌入表格: PjaBsB4aAh4jPZtVSl2lraKJgBg_ZsXfIg]
+
+**startDate**
+
+- 任务生效开始日期
+- CRON 类型任务在此日期之前不会执行
+**endDate**
+
+- 任务生效结束日期（可选）
+- 不填则永久有效
+- CRON 类型任务在此日期之后不再执行
+#### 消息有效期
+
+**validHours**
+
+- 消息有效时长（小时），从发送时刻算起
+- 不填则消息永不过期
+- 示例：`24` 表示 24 小时后消息过期，用户无法查看
+
+**priority**
+
+- 消息优先级，控制消息在列表中的排序位置
+- 取值范围：
+  - `0`：普通（默认）
+  - `1`：重要
+  - `2`：紧急
+- 优先级高的消息排在前面
+- 不填则默认为 `0`
+**isPinned**
+
+- 是否将消息置顶显示
+- 取值：`true` / `false`（默认）
+- 置顶消息始终显示在列表最前面，多条置顶消息按优先级和时间排序
+- 适用于重要公告、紧急通知等需要用户优先看到的场景
+**排序规则**
+
+用户站内信列表的排序规则为：
+
+1. 置顶消息（`isPinned=true`）优先
+1. 同等置顶状态下，按优先级（`priority`）降序
+1. 同等优先级下，按创建时间（`createTime`）降序
+```plaintext
+置顶紧急 > 置顶重要 > 置顶普通 > 非置顶紧急 > 非置顶重要 > 非置顶普通
+```
+
+### 配置组合示例
+
+#### 每日定时推送（横幅通知）
+
+```json
+{
+  "taskName": "Daily Reading Reminder",
+  "templateId": 1,
+  "targetType": "ALL",
+  "inboxEnabled": true,
+  "pushEnabled": true,
+  "silentPush": false,
+  "scheduleType": "CRON",
+  "cronExpression": "0 0 9 * * ?",
+  "startDate": "2026-01-28",
+  "validHours": 24,
+  "priority": 0,
+  "isPinned": false
+}
+```
+
+#### 紧急公告（置顶 + 高优先级）
+
+```json
+{
+  "taskName": "Urgent Announcement",
+  "templateId": 3,
+  "targetType": "ALL",
+  "inboxEnabled": true,
+  "pushEnabled": true,
+  "scheduleType": "IMMEDIATE",
+  "validHours": 48,
+  "priority": 2,
+  "isPinned": true
+}
+```
+
+#### APP 内实时弹窗（静默推送）
+
+```json
+{
+  "taskName": "Reading Complete Alert",
+  "templateId": 2,
+  "targetType": "INDIVIDUAL",
+  "targetUserIds": ["user_123"],
+  "inboxEnabled": true,
+  "pushEnabled": true,
+  "silentPush": true,
+  "scheduleType": "IMMEDIATE"
+}
+```
+
+#### 仅站内信（无推送）
+
+```json
+{
+  "taskName": "System Announcement",
+  "templateId": 3,
+  "targetType": "ALL",
+  "inboxEnabled": true,
+  "pushEnabled": false,
+  "scheduleType": "IMMEDIATE"
+}
+```
+
+#### 仅推送（不存站内信）
+
+```json
+{
+  "taskName": "Flash Sale",
+  "templateId": 4,
+  "targetType": "ALL",
+  "inboxEnabled": false,
+  "pushEnabled": true,
+  "silentPush": false,
+  "scheduleType": "IMMEDIATE"
+}
+```
+
+## 使用指南
+
+### 场景一：发送即时通知（如紧急公告）
+
+**步骤 1：创建消息模板**
+
+```http
+POST /admin/inbox/templates
+Content-Type: application/json
+
+{
+  "templateCode": "urgent_notice",
+  "title": "Important Notice",
+  "content": "Dear user, we will perform system maintenance on {{date}}. Please save your work in advance.",
+  "contentType": "TEXT",
+  "actionType": "NONE",
+  "variables": {
+    "date": "string"
+  }
+}
+```
+
+**响应：**
+
+```json
+{
+  "code": 200,
+  "data": {
+    "id": 1,
+    "templateCode": "urgent_notice"
+  }
+}
+```
+
+**步骤 2：创建即时发送任务**
+
+```http
+POST /admin/inbox/tasks
+Content-Type: application/json
+
+{
+  "taskName": "System Maintenance Notice 2026-01-28",
+  "templateId": 1,
+  "variableValues": {
+    "date": "January 28, 2026 10:00 PM UTC"
+  },
+  "targetType": "ALL",
+  "inboxEnabled": true,
+  "pushEnabled": true,
+  "pushTitle": "System Maintenance",
+  "pushBody": "We will perform maintenance tonight",
+  "scheduleType": "IMMEDIATE",
+  "validHours": 24,
+  "priority": 2,
+  "isPinned": true
+}
+```
+
+**响应：**
+
+```json
+{
+  "code": 200,
+  "data": {
+    "id": 1,
+    "taskName": "System Maintenance Notice 2026-01-28",
+    "status": 1
+  }
+}
+```
+
+系统会立即开始发送消息给所有用户。
+
+### 场景二：配置每日提醒（如签到提醒）
+
+**步骤 1：创建模板**
+
+```http
+POST /admin/inbox/templates
+Content-Type: application/json
+
+{
+  "templateCode": "daily_reminder",
+  "title": "Daily Tarot Reading",
+  "content": "Start your day with a tarot reading! See what the cards have in store for you today.",
+  "contentType": "TEXT",
+  "actionType": "DEEP_LINK",
+  "actionUrl": "bloomo://reading/daily"
+}
+```
+
+**步骤 2：创建每日定时任务**
+
+```http
+POST /admin/inbox/tasks
+Content-Type: application/json
+
+{
+  "taskName": "Daily Reading Reminder",
+  "templateId": 2,
+  "targetType": "ALL",
+  "pushEnabled": true,
+  "scheduleType": "CRON",
+  "cronExpression": "0 0 9 * * ?",
+  "startDate": "2026-01-28",
+  "validHours": 24
+}
+```
+
+说明：
+
+- `cronExpression`: `0 0 9 * * ?` 表示每天 9:00
+- 系统会按用户时区发送，东京用户在东京时间 9:00 收到，纽约用户在纽约时间 9:00 收到
+- `validHours`: 24 小时后消息过期
+### 场景三：配置节日通知（如圣诞祝福）
+
+**步骤 1：创建节日模板**
+
+```http
+POST /admin/inbox/templates
+Content-Type: application/json
+
+{
+  "templateCode": "christmas_2026",
+  "title": "Merry Christmas!",
+  "content": "Wishing you a magical Christmas filled with love and joy! Here's a special holiday reading just for you.",
+  "contentType": "RICH_TEXT",
+  "imageUrl": "https://cdn.bloomo.com/images/christmas-2026.png",
+  "actionType": "DEEP_LINK",
+  "actionUrl": "bloomo://reading/holiday/christmas"
+}
+```
+
+**步骤 2：创建每年定时任务**
+
+```http
+POST /admin/inbox/tasks
+Content-Type: application/json
+
+{
+  "taskName": "Christmas Blessing",
+  "templateId": 3,
+  "targetType": "ALL",
+  "pushEnabled": true,
+  "scheduleType": "CRON",
+  "cronExpression": "0 0 9 25 12 ?",
+  "startDate": "2026-12-25"
+}
+```
+
+说明：
+
+- `cronExpression`: `0 0 9 25 12 ?` 表示每年 12 月 25 日 9:00
+- 任务会每年自动触发
+### 场景四：纯 Push 消息（不存储站内信）
+
+适用于短时提醒、促销弹窗等不需要保存历史的场景：
+
+```http
+POST /admin/inbox/tasks
+Content-Type: application/json
+
+{
+  "taskName": "Flash Sale Reminder",
+  "templateId": 10,
+  "targetType": "ALL",
+  "inboxEnabled": false,
+  "pushEnabled": true,
+  "pushTitle": "Flash Sale!",
+  "pushBody": "50% off for the next 2 hours!",
+  "scheduleType": "IMMEDIATE"
+}
+```
+
+说明：
+
+- `inboxEnabled: false` - 不存储到站内信列表
+- `pushEnabled: true` - 只发送横幅推送
+- 用户收到推送后点击进入 APP，但站内信列表中没有这条消息
+### 场景四-B：APP 内弹窗通知（静默推送）
+
+适用于用户正在使用 APP 时的实时提醒，如新消息到达、状态变更等：
+
+```http
+POST /admin/inbox/tasks
+Content-Type: application/json
+
+{
+  "taskName": "New Reading Available",
+  "templateId": 11,
+  "targetType": "INDIVIDUAL",
+  "targetUserIds": ["user_123"],
+  "inboxEnabled": true,
+  "pushEnabled": true,
+  "silentPush": true,
+  "pushTitle": "Your reading is ready!",
+  "pushBody": "Tap to view your personalized tarot reading",
+  "scheduleType": "IMMEDIATE"
+}
+```
+
+说明：
+
+- `pushEnabled: true` + `silentPush: true` - 发送静默推送
+- 静默推送只发送 data，不显示系统通知栏
+- 客户端在 APP 前台时自行展示弹窗
+- APP 不在前台时忽略（不会打扰用户）
+**推送模式对比：**
+
+[嵌入表格: PjaBsB4aAh4jPZtVSl2lraKJgBg_uHbqDO]
+
+### 场景五：针对特定用户发送消息
+
+**发送给 VIP 用户：**
+
+```http
+POST /admin/inbox/tasks
+Content-Type: application/json
+
+{
+  "taskName": "VIP Exclusive Offer",
+  "templateId": 4,
+  "targetType": "USER_GROUP",
+  "targetConditions": {
+    "is_vip": true
+  },
+  "inboxEnabled": true,
+  "pushEnabled": true,
+  "scheduleType": "IMMEDIATE"
+}
+```
+
+**发送给指定用户：**
+
+```http
+POST /admin/inbox/tasks
+Content-Type: application/json
+
+{
+  "taskName": "Personal Welcome Message",
+  "templateId": 5,
+  "targetType": "INDIVIDUAL",
+  "targetUserIds": ["user_123", "user_456"],
+  "pushEnabled": false,
+  "scheduleType": "IMMEDIATE"
+}
+```
+
+### 场景六：每日随机文案推送（基于 Remote Config）
+
+适用于每日灵感、每日运势等需要随机变化的消息场景。使用同一个模板格式，每天从 Remote Config 配置的文案列表中随机选择一组变量值填充，所有用户当天收到相同的消息。
+
+**步骤 1：创建带变量的模板**
+
+创建一个包含变量占位符的模板：
+
+```http
+POST /admin/inbox/templates
+Content-Type: application/json
+
+{
+  "templateCode": "daily_inspiration",
+  "title": "{{title}}",
+  "content": "{{content}}",
+  "contentType": "TEXT",
+  "actionType": "DEEP_LINK",
+  "actionUrl": "bloomo://reading/daily",
+  "variables": {
+    "title": "string",
+    "content": "string"
+  }
+}
+```
+
+**响应：**
+
+```json
+{
+  "code": 200,
+  "data": {
+    "id": 10,
+    "templateCode": "daily_inspiration"
+  }
+}
+```
+
+**步骤 2：在 Firebase Remote Config 配置文案列表**
+
+在 Firebase Console 中创建 Remote Config 参数：
+
+- **Key**: `daily_inspiration_contents`
+- **Value**:
+```json
+[
+  {
+    "title": "Trust Your Intuition",
+    "content": "Today, the cards suggest you trust your inner voice. Let your intuition guide your decisions.",
+    "pushTitle": "Daily Inspiration",
+    "pushBody": "Trust your intuition today"
+  },
+  {
+    "title": "Embrace New Beginnings",
+    "content": "A fresh start awaits you. Be open to new opportunities and let go of what no longer serves you.",
+    "pushTitle": "Daily Inspiration",
+    "pushBody": "A fresh start awaits"
+  },
+  {
+    "title": "Love is All Around",
+    "content": "The universe is sending you love today. Open your heart to receive and give love freely.",
+    "pushTitle": "Daily Inspiration",
+    "pushBody": "Love is all around you"
+  }
+]
+```
+
+**步骤 3：创建每日随机推送任务**
+
+```http
+POST /admin/inbox/tasks
+Content-Type: application/json
+
+{
+  "taskName": "Daily Inspiration - Random",
+  "templateId": 10,
+  "remoteConfigKey": "daily_inspiration_contents",
+  "targetType": "ALL",
+  "inboxEnabled": true,
+  "pushEnabled": true,
+  "scheduleType": "CRON",
+  "cronExpression": "0 0 9 * * ?",
+  "startDate": "2026-01-28",
+  "validHours": 24
+}
+```
+
+说明：
+
+- `templateId: 10` - 指定使用的模板（定义格式和变量占位符）
+- `remoteConfigKey` - 指向 Firebase Remote Config 中的文案列表 Key（有此字段则从远程随机选文案）
+- 每天 9:00（用户当地时间）执行时，系统会：
+  1. 检查 Redis 缓存中当天是否已选择过文案（`inbox:content:{taskId}:{date}`）
+  1. 如果没有，从 Remote Config 读取文案列表并随机选择一组
+  1. 将选中的索引缓存到 Redis（48h 过期）
+  1. 使用选中的变量值填充模板，发送给所有用户
+  1. 当天所有时区的用户都会收到相同内容的消息
+### Cron 表达式快速参考
+
+| 场景 | Cron 表达式 | 说明 |
+| --- | --- | --- |
+
+| 每天 9:00 | `0 0 9 * * ?` | 每日定时提醒 |
+
+| 每周一 10:00 | `0 0 10 ? * MON` | 周报推送 |
+
+| 每月 1 号 9:00 | `0 0 9 1 * ?` | 月初提醒 |
+
+| 每年 1/1 0:00 | `0 0 0 1 1 ?` | 新年祝福 |
+
+| 每年 12/25 9:00 | `0 0 9 25 12 ?` | 圣诞祝福 |
+
+| 每周一三五 9:00 | `0 0 9 ? * MON,WED,FRI` | 隔日提醒 |
+
+| 每 2 小时 | `0 0 */2 * * ?` | 定期检查 |
+
+**Cron 格式说明：**
+
+```plaintext
+秒 分 时 日 月 周
+0  0  9  *  *  ?
+│  │  │  │  │  └── 周（? 表示不指定）
+│  │  │  │  └───── 月（* 表示每月）
+│  │  │  └──────── 日（* 表示每日）
+│  │  └─────────── 时（9 表示 9 点）
+│  └────────────── 分（0 表示 0 分）
+└───────────────── 秒（0 表示 0 秒）
+```
+