multi-platform-media-manage/docs/xiaohongshu-work-note-statistics-field-mapping.md

小红书作品（笔记）每日统计数据导入逻辑与字段映射

接口信息

• 接口：GET https://creator.xiaohongshu.com/api/galaxy/creator/datacenter/note/base?note_id={noteId}
• 页面：https://creator.xiaohongshu.com/statistics/note-detail?noteId={noteId}
• 数据来源：返回体中的 data.day（日维度趋势数据）

导入流程

1. 遍历账号下所有作品：从 works 表查询该账号的所有小红书作品
2. 访问笔记详情页：打开 statistics/note-detail?noteId={noteId}
3. 监听接口响应：等待 note/base 接口响应（超时 30 秒）
4. 解析数据：
   • 提取 data.day 下的各 *_list 数组
   • 按 date（毫秒时间戳）合并为「按日一条」的数据
   • 使用 getChinaDateFromTimestamp 将时间戳转成中国时区日期
5. 过滤时间范围：默认只保留「作品发布后 14 天内」的数据（publishTime + 13 天）
6. 批量写入：调用 WorkDayStatisticsService.saveStatisticsForDateBatch 写入 work_day_statistics 表

字段映射表

数值型字段（每日增量，累加）

work_day_statistics 字段	data.day 来源	说明
record_date	各 list 项的 date（毫秒 → 中国时区当天 0 点）	按日期合并多条 list
play_count	view_list[].count	播放(阅读)量
exposure_count	imp_list[].count	曝光量/展现量
like_count	like_list[].count	点赞量
comment_count	comment_list[].count	评论量
share_count	share_list[].count	分享量
collect_count	collect_list[].count	收藏量
fans_increase	rise_fans_list[].count	涨粉数

比率类字段（百分比字符串，使用 coun 字段）

work_day_statistics 字段	data.day 来源	格式
cover_click_rate	cover_click_rate_list[].coun	"14%" 或 "0"
two_second_exit_rate	exit_view2s_list[].coun	"5%" 或 "0"
completion_rate	finish_list[].coun	"15%" 或 "0"

说明：比率类字段使用 item.coun（不是 count），如果值为 0 则存 "0"，否则存 ${n}%"。

时长/数值字符串字段（不加 %）

work_day_statistics 字段	data.day 来源	格式
avg_watch_duration	view_time_list[].count_with_double 或 count	保留两位小数的字符串，如 "12.34"

说明：优先使用 count_with_double，否则用 count，保留两位小数（四舍五入）。

数据汇总（同步到 works 表）

除了日统计，还会将 data 顶层的汇总指标同步到 works 表的 yesterday* 字段：

works 字段	data 来源	说明
yesterday_play_count	view_count	总播放数
yesterday_like_count	like_count	总点赞数
yesterday_comment_count	comment_count	总评论数
yesterday_share_count	share_count	总分享数
yesterday_collect_count	collect_count	总收藏数
yesterday_fans_increase	rise_fans_count	总涨粉数
yesterday_exposure_count	impl_count	总曝光数
yesterday_cover_click_rate	cover_click_rate	封面点击率（格式化为 "14%"）
yesterday_avg_watch_duration	view_time_avg_with_double 或 view_time_avg	平均观看时长（保留两位小数）
yesterday_completion_rate	full_view_rate	完播率（格式化为 "15%"）
yesterday_two_second_exit_rate	exit_view2s_rate	2秒退出率（格式化为 "5%"）

时区处理

• 接口返回的 date：中国时区（Asia/Shanghai）该日 0 点的 UTC 时间戳
• 解析方式：使用 getChinaDateFromTimestamp(ts) 函数，通过 Intl.DateTimeFormat 按中国时区解析年月日
• 存储：record_date 字段存为 DATE 类型，代表中国时区的日历日

时间范围限制

• 默认：只保留「作品发布后 14 天内」的数据
  • 计算方式：publishTime 的当天 + 13 天 = 共 14 天
  • 例如：2026-01-01 发布，则保留 2026-01-01 至 2026-01-14 的数据
• 首批补数据：可通过 ignorePublishTimeLimit: true 选项跳过此限制

错误处理

• 登录失效：检测到跳转到 login 页面时，抛出 XhsLoginExpiredError
  • 首次失效：尝试刷新账号 cookie
  • 刷新成功：用新 cookie 重试一次
  • 刷新失败或重试仍失效：标记账号为 expired 状态
• 接口超时：30 秒内未捕获到响应则跳过该作品，继续处理下一个
• 数据缺失：data.day 为空或不存在时返回空数组，不写入

调用方式

定时任务（批量同步所有账号）

await XiaohongshuWorkNoteStatisticsImportService.runDailyImport();

单账号同步

const svc = new XiaohongshuWorkNoteStatisticsImportService();
await svc.importAccountWorksStatistics(account);

指定作品（首批补数据）

await svc.importAccountWorksStatistics(account, false, {
  workIdFilter: [workId1, workId2],
  ignorePublishTimeLimit: true
});