# redbook-server

**Repository Path**: phlio/redbook-server

## Basic Information

- **Project Name**: redbook-server
- **Description**: 小红书聚光数据采集，计划投放，发布素材
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-28
- **Last Updated**: 2026-08-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 小红书广告服务 - 接入文档

## 1. 项目概述

- 小红书 OAuth 授权与 Token 自动刷新
- 广告主配置管理
- 计划/创意/预算/离线数据同步
- 计划/笔记自动创建任务（从数据库读取待发布任务）
- 私信留资 Webhook 接收
- REST API 支持计划暂停、编辑、创意更新、笔记创建、级联创建等

### 高可用特性


| 能力      | 实现                                              |
| ------- | ----------------------------------------------- |
| 分布式调度   | XXL-Job 调度中心（默认），或 Spring @Scheduled + ShedLock |
| HTTP 重试 | Resilience4j Retry（指数退避）                        |
| 熔断降级    | Resilience4j CircuitBreaker                     |
| 连接池     | HikariCP                                        |
| 并行同步    | 可配置线程池 `redbook.sync.thread-pool-size`          |
| 健康检查    | `/actuator/health`、`/health`                    |
| 优雅停机    | `server.shutdown=graceful`                      |


---

## 2. 环境要求

- JDK 17+
- Maven 3.8+
- MySQL 8.0+

---

## 3. 快速启动

### 3.1 创建数据库

```sql
CREATE DATABASE redbook DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
```

Flyway 会在启动时自动执行 `db/migration/V1__init.sql` 建表。

### 3.2 配置环境变量

```bash
export DB_HOST=localhost
export DB_PORT=3306
export DB_NAME=redbook
export DB_USER=root
export DB_PASSWORD=your_password
export OAUTH_CALLBACK_HOST=your-server-ip:9030
export COS_SECRET_ID=your_cos_secret_id      # 笔记图片上传需要
export COS_SECRET_KEY=your_cos_secret_key
export COS_BUCKET=your-bucket-name
export ALERT_WEBHOOK=                        # 可选，告警 webhook
export XXL_JOB_ADMIN_ADDRESSES=http://127.0.0.1:8080/xxl-job-admin
export XXL_JOB_ACCESS_TOKEN=                 # 与 Admin 一致，无则留空
export XXL_JOB_EXECUTOR_PORT=9999
export SCHEDULER_MODE=xxl-job                # xxl-job | spring
```

### 3.3 编译运行

```bash
cd redbook-service
mvn clean package -DskipTests
java -jar target/redbook-service-1.0.0.jar --spring.profiles.active=dev
```

服务默认端口：**9030**

---

## 4. 数据库初始化

### 4.1 导入广告主配置

```sql
INSERT INTO rb_advertiser_config (app_id, app_secret, advertiser_id, name, auth_code, company_code, enabled)
VALUES
('12278', 'your_app_secret', '123456789', '账号名称', '授权码', 'zhiwu', 1);
```

### 4.2 导入 OAuth Token

```sql
INSERT INTO rb_oauth_token (app_id, access_token, access_token_expire, refresh_token, refresh_token_expire)
VALUES ('12278', 'token_value', 1787819470, 'refresh_value', 1790325070);
```

### 4.3 导入关键词包

```sql
INSERT INTO rb_keyword_package (company_code, package_name, keywords)
VALUES ('zhiwu', '默认词包', '关键词1,关键词2,关键词3');
```

### 4.4 创建计划发布任务

```sql
INSERT INTO rb_campaign_create_task (
  company_code, status, product_type_1, product_type_2, product_type_3,
  note_ids, app_id, advertiser_id, marketing_target, optimize_objective,
  placements, except_areas, keyword_packages, event_bid, search_bid_ratio,
  bar_content_user_list, comment_text
) VALUES (
  'zhiwu', '可发布', '家居', '灯具', '筒灯',
  'note_id_1,note_id_2', '12278', '123456789', '客资收集', '私信进线',
  '["信息流","搜索"]', '["浙江/金华"]', '["默认词包"]', 50.00, 1.2,
  '["立即咨询","免费领取"]', '置顶评论文案'
);
```

---

## 5. OAuth 授权

1. 在 `rb_advertiser_config` 中配置 `app_id`、`app_secret`
2. 访问授权链接（将 `APP_ID` 替换为实际值）：

```
https://ad-market.xiaohongshu.com/auth?appId=APP_ID&scope=["report_service","ad_query","ad_manage","account_manage"]&redirectUri=http://YOUR_HOST:9030/redbook/oauth&state=APP_ID
```

1. 授权成功后回调 `/redbook/oauth`，`auth_code` 自动写入数据库
2. 定时任务每 3 分钟刷新 Token（可通过 `redbook.scheduler.refresh-token-cron` 配置）

---

## 6. REST API 接口

所有接口支持 `POST`，Content-Type: `application/json`

### 6.1 计划暂停/开启

**POST** `/campaign/pause`

```json
{
  "app_id": "12278",
  "advertiser_id": "123456789",
  "campaign_id": 168656688,
  "status": 2
}
```

`status`: 1=开启, 2=暂停（默认2）

### 6.2 计划编辑

**POST** `/campaign/edit`

```json
{
  "app_id": "12278",
  "advertiser_id": "123456789",
  "campaign_id": 168656688,
  "campaign_day_budget": 500,
  "time_type": 0,
  "marketing_target": "客资收集"
}
```

### 6.3 创意状态更新

**POST** `/creativity/update`

```json
{
  "app_id": "12278",
  "advertiser_id": "123456789",
  "creativity_id": 987654321,
  "status": 2
}
```

### 6.4 创建广告笔记

**POST** `/ad_material_note/create`

```json
{
  "app_id": "12278",
  "advertiser_id": "123456789",
  "note_type": 1,
  "image_paths": ["/data/images/1.jpg", "/data/images/2.jpg"],
  "note_title": "标题",
  "note_desc": "正文内容",
  "user_id": "可选"
}
```

### 6.5 级联创建计划

**POST** `/cascade/create`

```json
{
  "app_id": "12278",
  "advertiser_id": "123456789",
  "product_type": "家居-灯具-筒灯",
  "optimize_objective_name": "私信进线",
  "marketing_target": "客资收集",
  "placements": ["信息流", "搜索"],
  "target_area_code": "251#252",
  "keywords": ["筒灯推荐"],
  "event_bid": 50,
  "search_bid_ratio": 1.2,
  "bar_content_user_list": ["立即咨询"],
  "comment": "置顶评论",
  "note_ids": ["note_id_1", "note_id_2"],
  "campaign_group_id": 12345
}
```

### 6.6 计划创建排队（写数据库）

**POST** `/campaign/create/task`

```json
{
  "account": "账号名",
  "template": "计划模版",
  "note_id": "笔记ID",
  "owner_id": "负责人ID"
}
```

### 6.7 私信留资 Webhook

**POST** `/webhook`

```json
{
  "data": {
    "id": "线索ID",
    "type": 0,
    "time": "2026-08-27 10:00:00",
    "c_user_id": "用户UID",
    "advertiser_id": "123456789",
    "campaign_id": "168656688"
  }
}
```

数据写入 `rb_private_message` 表，不再写入飞书。

---

## 7. 定时任务配置

支持两种调度模式，通过 `redbook.scheduler.mode` 切换：


| 模式                   | 说明                                      |
| -------------------- | --------------------------------------- |
| `xxl-job`（**默认，推荐**） | 接入 XXL-Job 调度中心，可视化管理、失败重试、分片、日志        |
| `spring`             | 内置 `@Scheduled` + ShedLock，无需额外部署 Admin |


```yaml
redbook:
  scheduler:
    mode: xxl-job    # 或 spring
    enabled: true
```

---

### 7.1 XXL-Job 接入

#### 7.1.1 部署调度中心

参考 [XXL-Job 官方文档](https://www.xuxueli.com/xxl-job/) 部署 `xxl-job-admin`（可用 Docker）：

```bash
docker run -d \
  -p 8080:8080 \
  -e PARAMS="--spring.datasource.url=jdbc:mysql://host:3306/xxl_job?useUnicode=true&characterEncoding=UTF-8 --spring.datasource.username=root --spring.datasource.password=xxx" \
  xuxueli/xxl-job-admin:2.4.2
```

首次登录：账号 `admin` / 密码 `123456`

#### 7.1.2 配置执行器

在 `application.yml` 或环境变量中配置：

```bash
export XXL_JOB_ADMIN_ADDRESSES=http://your-admin-host:8080/xxl-job-admin
export XXL_JOB_ACCESS_TOKEN=          # 与 Admin 配置的 accessToken 一致，无则留空
export XXL_JOB_EXECUTOR_PORT=9999     # 多实例时每台机器用不同端口
```

#### 7.1.3 在 Admin 控制台注册任务

1. **执行器管理** → 新增执行器，AppName 填 `redbook-service`（与配置一致），注册方式选「自动注册」
2. **任务管理** → 为每个 JobHandler 新建任务：


| JobHandler              | 说明       | 建议 Cron             |
| ----------------------- | -------- | ------------------- |
| `refreshAccessTokenJob` | Token 刷新 | `0 */3 * * * ?`     |
| `campaignSyncJob`       | 计划实时数据同步 | `0 */30 * * * ?`    |
| `creativitySyncJob`     | 创意实时数据同步 | `0 0 */1 * * ?`     |
| `offlineSyncJob`        | 离线数据同步   | `0 0 6,12,18 * * ?` |
| `groupListSyncJob`      | 广告组列表同步  | `0 0 9 * * ?`       |
| `budgetSyncJob`         | 预算快照     | `0 0 * * * ?`       |
| `createCampaignJob`     | 自动创建计划   | `0 */30 * * * ?`    |
| `createNoteJob`         | 自动创建笔记   | `0 */30 * * * ?`    |


> JobHandler 名称必须与代码中 `@XxlJob("xxx")` 完全一致。

#### 7.1.4 多实例部署

- 同一 AppName 的多台机器会自动注册到同一执行器组
- XXL-Job 路由策略选「第一个」或「轮询」均可；**同一任务同一时刻只在一台机器执行**
- 每台机器 `XXL_JOB_EXECUTOR_PORT` 需不同（如 9999、10000、10001）

---

### 7.2 Spring 内置调度（备选）

无需 XXL-Job Admin，适合本地开发：

```yaml
redbook:
  scheduler:
    mode: spring
```

Cron 在 `application.yml` 中配置：

```yaml
redbook:
  scheduler:
    refresh-token-cron: "0 */3 * * * ?"
    campaign-sync-cron: "0 */30 * * * ?"
    creativity-sync-cron: "0 0 */1 * * ?"
    offline-sync-cron: "0 0 6,12,18 * * ?"
    budget-sync-cron: "0 0 * * * ?"
    create-campaign-cron: "0 */30 * * * ?"
    create-note-cron: "0 */30 * * * ?"
```

多实例时 ShedLock 保证同一任务只执行一次。

---

## 8. 数据表说明


| 表名                        | 说明          |
| ------------------------- | ----------- |
| `rb_advertiser_config`    | 广告主账号配置     |
| `rb_oauth_token`          | OAuth Token |
| `rb_report_data`          | 计划/创意/预算等报表 |
| `rb_campaign_create_task` | 计划创建任务      |
| `rb_note_create_task`     | 笔记创建任务      |
| `rb_keyword_package`      | 关键词包        |
| `rb_private_message`      | 私信留资        |
| `rb_campaign_queue_task`  | API 提交的计划排队 |
| `rb_quota_snapshot`       | 配额小时快照      |


查询报表示例：

```sql
-- 查询今日计划数据
SELECT biz_id, account_name, metrics
FROM rb_report_data
WHERE biz_type = 'campaign'
  AND stat_date >= UNIX_TIMESTAMP(CURDATE()) * 1000
ORDER BY updated_at DESC;
```

---

## 9. 地域/营销配置

地域编码、营销诉求、优化目标等映射配置在 `area-config.yml`，可按需扩展，无需改代码。

---

## 10. 多实例部署建议

```bash
# 实例 1
java -jar redbook-service-1.0.0.jar --server.port=9030

# 实例 2
java -jar redbook-service-1.0.0.jar --server.port=9031
```

- 共用同一 MySQL 数据库
- **XXL-Job 模式**：调度中心统一管理，执行器自动注册，无需 ShedLock
- **Spring 模式**：ShedLock 协调多实例定时任务
- 前面加 Nginx/SLB 做 API 负载均衡
- 通过 `/actuator/health` 做存活探针

---

## 12. 常见问题

**Q: Token 获取失败？**  
检查 `auth_code` 是否过期，重新走 OAuth 授权流程。

**Q: 定时任务不执行？**  
确认 `redbook.scheduler.enabled=true`，检查 ShedLock 表是否存在。

**Q: 图片上传失败？**  
配置 COS 相关环境变量 `COS_SECRET_ID`、`COS_SECRET_KEY`、`COS_BUCKET`。

**Q: 如何关闭飞书告警？**  
默认 `redbook.alert.enabled=false`，仅写日志，不发送 webhook。