# 小红书作品自动分页逻辑说明

## 页数计算逻辑

### 1. 页数统计变量

在 `get_all_works` 方法中，有两个关键的计数变量：

- **`iters`**: 总请求次数（包括失败的请求）
  - 初始值：0
  - 每次循环：`iters += 1`
  - 最大限制：800 次（`max_iters = 800`）

- **`page_count`**: 成功获取到的页数（只统计有作品的页面）
  - 初始值：0
  - 只有当 `notes` 不为空时：`page_count += 1`
  - 这是**实际成功获取到的页数**，不是总页数

### 2. 总页数计算

总页数可以通过以下方式计算：

```python
总页数 = ceil(总作品数 / 每页大小)
```

其中：
- **总作品数** (`total`): 从 API 返回的声明总数，可能来自：
  - `tags` 中的 `special.note_time_desc` 的 `notes_count`
  - `tags` 中其他 tag 的 `notes_count` 最大值
  - `data.total` 或 `data.total_count`
  - `data.page.total` 或 `data.page.totalCount`
  
- **每页大小** (`api_page_size`): 固定为 20

### 3. 分页流程

```
开始循环 (最多 800 次)
  ↓
iters += 1 (总请求次数)
  ↓
调用 API: fetch_notes_page(cursor)
  ↓
检查响应是否成功
  ├─ 失败 → 如果是第一次请求，切换到滚动模式
  └─ 成功 → 继续
      ↓
检查 notes 是否为空
  ├─ 为空 → 停止分页
  └─ 不为空 → page_count += 1 (成功页数+1)
      ↓
解析作品并去重
  ↓
检查是否获取完所有作品
  ├─ 累计作品数 >= 总数 → 停止分页
  └─ 继续 → 更新 cursor，继续下一页
```

### 4. 分页统计输出

在分页完成后，会输出以下统计信息：

```
分页统计: 总请求次数={iters}, 成功获取页数={page_count}, 累计作品数={len(works)}, 声明总数={total}
```

示例：
- 总请求次数：20（包括所有请求，即使某些请求返回空）
- 成功获取页数：18（只有返回作品的页面才计数）
- 累计作品数：360（实际获取到的作品总数）
- 声明总数：368（API 声明的总作品数）

### 5. 页数计算示例

假设账号有 368 个作品：

```
总作品数 = 368
每页大小 = 20
理论总页数 = ceil(368 / 20) = 19 页

实际执行：
- 第 1-18 页：每页 20 个作品，共 360 个
- 第 19 页：8 个作品
- page_count = 19（成功获取的页数）
- iters = 19（总请求次数，如果都成功的话）
```

## 日志输出位置

### Python 服务日志

Python 服务的日志通过 `print(..., flush=True)` 输出到**控制台**（标准输出）。

要查看完整的分页日志，需要：

1. **确保 Python 服务正在运行**
   ```bash
   cd server/python
   python app.py
   ```

2. **查看 Python 服务的控制台输出**
   - 日志会实时输出到运行 Python 服务的终端窗口
   - 所有 `print` 语句都会立即输出（因为使用了 `flush=True`）

3. **关键日志标识**
   - `========== 开始自动分页获取作品 ==========`: 分页开始
   - `第 {iters} 次请求 (cursor={cursor})`: 每次请求
   - `✅ 第 {page_count} 页获取成功`: 成功获取的页
   - `📊 分页统计`: 分页完成后的统计信息

### Node.js 日志

Node.js 端的日志会输出到：
- **控制台**（开发环境）
- **日志文件**（生产环境）：
  - `server/logs/combined.log` - 所有日志
  - `server/logs/error.log` - 错误日志

## 调试建议

如果 Python API 返回 0 个作品，可能的原因：

1. **Cookie 格式问题**
   - 检查 Node.js 传递给 Python 的 Cookie 格式是否正确
   - Python 期望 JSON 格式的 Cookie 数组

2. **登录状态失效**
   - 检查账号的 Cookie 是否过期
   - 查看 Python 日志中是否有 "Cookie 已过期" 的错误

3. **API 调用失败**
   - 查看 Python 日志中的错误信息
   - 检查网络连接和 API 响应

4. **页面加载问题**
   - 检查是否成功访问笔记管理页面
   - 查看是否有导航超时的错误

## 查看日志的方法

### 方法 1: 直接查看 Python 服务控制台

运行 Python 服务的终端窗口会显示所有日志。

### 方法 2: 重定向日志到文件

```bash
python app.py > python.log 2>&1
```

然后查看 `python.log` 文件。

### 方法 3: 使用测试脚本

运行测试脚本时，Python 服务的日志会输出到运行 Python 服务的终端窗口：

```bash
# 终端 1: 运行 Python 服务
cd server/python
python app.py

# 终端 2: 运行测试脚本
cd server
pnpm exec tsx src/scripts/test-xhs-works-sync.ts 35
```

Python 服务的日志会在终端 1 中显示。