129 lines
12 KiB
Markdown
129 lines
12 KiB
Markdown
# readdata — 阅读统计
|
||
|
||
查看个人阅读数据统计，包含阅读时长、天数、读书排行、偏好分析等。
|
||
|
||
> **⚠️ 使用前必须阅读本文件字段说明。** 阅读统计字段容易因字段名产生误判，尤其是所有阅读时长字段的单位。调用 `/readdata/detail` 前必须先确认本文件中的参数、字段单位和统计口径；禁止凭字段名或数值大小推断单位。
|
||
|
||
## 接口
|
||
|
||
### `/readdata/detail` — 阅读统计详情
|
||
|
||
**请求参数：**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `mode` | string | 否 | 统计维度：`weekly`=本周, `monthly`=本月, `annually`=本年, `overall`=总计。默认 `monthly`。|
|
||
| `baseTime` | int | 否 | 基准时间戳（0=当前周期），此时服务端会归一化到周期起点：周一、月初、年初；`overall` 固定为 0。传历史时间戳可查看该时间戳所在周期的数据；`annually` 只返回 `baseTime` 所在自然年的数据，不会自动包含后续年份 |
|
||
|
||
**回包字段说明（字段按 `mode` 和数据条件可选返回）：**
|
||
|
||
| 字段 | 说明 |
|
||
|------|------|
|
||
| `baseTime` | 统计周期的基准时间戳：`weekly` 为周一 00:00，`monthly` 为月初 00:00，`annually` 为年初 00:00，`overall` 为 0 |
|
||
| `readTimes` | 分桶阅读/收听总时长（对象，key 为分桶起始时间戳，value 为秒数）。`weekly`/`monthly` 通常按天分桶，`annually` 按月分桶，`overall` 按年分桶 |
|
||
| `dailyReadTimes` | 年度模式可能返回的每日阅读时长明细（对象，key 为日期时间戳，value 为秒数）；用于日历明细展示，不应替代 `totalReadTime` 作为总量口径 |
|
||
| `readDays` | 有效阅读天数。服务端按有效阅读规则计算，当前规则为单日阅读满 1 分钟 |
|
||
| `totalReadTime` | 当前请求周期的总阅读/收听时长（**秒**）。统计总时长时优先使用该字段，`readTimes` 仅用于明细展示或交叉校验；**禁止误当成分钟或小时** |
|
||
| `dayAverageReadTime` | 日均阅读/收听时长（秒），分母是当前周期已过去的自然日数或历史完整周期自然日数，不是 `readDays` |
|
||
| `compare` | 与上一周期的日均时长对比比例；正数表示增长，负数表示下降。该字段只在当前周期且上一周期数据足够时返回，`0.2` 表示约增长 20% |
|
||
| `readLongest` | 读得最多的书/有声内容排行数组，最多 10 条，按 `readTime` 降序；低于 5 分钟的条目会被过滤 |
|
||
| `readLongest[].book` | 书籍信息对象（电子书/出版书），包含 `bookId`、`title`、`author`、`cover` 等 |
|
||
| `readLongest[].albumInfo` | 有声内容信息对象；当排行条目是有声书/专辑时返回 |
|
||
| `readLongest[].readTime` | 该书或有声内容在当前统计范围内的阅读/收听时长（秒） |
|
||
| `readLongest[].recordReadingTime` | 该书的朗读/记录类阅读时长（秒），存在时才返回 |
|
||
| `readLongest[].tags` | 标签数组，目前常见值包括 `笔记最多`、`单日阅读最久` |
|
||
| `readStat` | 阅读统计摘要数组 |
|
||
| `readStat[].stat` | 统计项名称，常见为 `读过`、`读完`、`阅读`、`笔记` |
|
||
| `readStat[].counts` | 统计值文案，如 `12本`、`45天`、`120条` |
|
||
| `readStat[].scheme` | 对应统计项的 App 跳转链接，可能为空 |
|
||
| `preferCategory` | 偏好阅读分类数组，最多 8 个；不足时可能补充默认分类占位 |
|
||
| `preferCategory[].categoryId` | 分类 ID |
|
||
| `preferCategory[].categoryTitle` | 分类名称 |
|
||
| `preferCategory[].parentCategoryId` | 父分类 ID |
|
||
| `preferCategory[].parentCategoryTitle` | 父分类名称 |
|
||
| `preferCategory[].val` | 分类偏好权重，按最高分类阅读时长归一化后的相对值，用于图表展示 |
|
||
| `preferCategory[].readingTime` | 该分类阅读时长（秒） |
|
||
| `preferCategory[].readingCount` | 该分类阅读本数 |
|
||
| `preferCategory[].categoryType` | 分类类型标记，普通分类为 0，部分特殊分类会返回 1 或 2 |
|
||
| `preferCategoryWord` | 偏好分类文案，如 `偏好阅读文学`；年度报告场景可能改为固定文案 `偏好阅读` |
|
||
| `preferTime` | 24 小时阅读时段分布数组，值为秒数。注意输出顺序从 6 点开始，依次到次日 5 点，不是从 0 点开始 |
|
||
| `preferTimeWord` | 偏好时段文案。总偏好时段数据不足 10 小时时可能不返回；常见文案如 `偏好上午阅读`、`偏好白天阅读`、`偏好夜间阅读`、`汲取新知，昼夜不倦` |
|
||
| `preferAuthor` | 偏好作者数组。只有作者数据达到展示阈值时返回 |
|
||
| `preferAuthor[].authorId` | 作者 ID |
|
||
| `preferAuthor[].name` | 作者名 |
|
||
| `preferAuthor[].count` | 阅读该作者的书本数 |
|
||
| `preferAuthor[].readTime` | 阅读该作者作品的时长，格式化字符串，如 `5小时30分钟`，不是秒数 |
|
||
| `preferAuthor[].user` | 作者关联用户信息，存在时返回 |
|
||
| `authorCount` | 符合统计条件的作者总数，不一定等于 `preferAuthor` 返回条数 |
|
||
| `preferPublisher` | 偏好出版社数组。至少 3 个出版社且最高出版社阅读本数达到阈值时返回 |
|
||
| `preferPublisher[].name` | 出版社名 |
|
||
| `preferPublisher[].count` | 阅读该出版社书籍的本数 |
|
||
| `preferCp` | 偏好版权方数组。满足展示阈值时返回 |
|
||
| `preferCp[].count` | 阅读该版权方书籍的本数 |
|
||
| `preferCp[].copyrightInfo` | 版权方信息，包括名称、用户 VID、头像、角色等 |
|
||
| `readRate` | 文字阅读占比百分比，计算口径约为 `wrReadTime / (wrReadTime + wrListenTime) * 100`。当总时长不足 1 小时或文字阅读占比过高时不返回 |
|
||
| `wrReadTime` | 文字阅读时长（秒），通常为 `totalReadTime - wrListenTime`；仅在 `readRate` 可展示时返回 |
|
||
| `wrListenTime` | 听书/TTS/有声内容时长（秒）；仅在 `readRate` 可展示时返回 |
|
||
| `rank` | 本周好友阅读排行信息；仅当前周且未隐藏排行时返回 |
|
||
| `rank.text` | 排行文案，如 `朋友中排第3名` |
|
||
| `rank.scheme` | 排行跳转链接 |
|
||
| `registTime` | 用户注册时间戳 |
|
||
| `medals` | 勋章数组；可展示勋章不少于 3 个时返回 |
|
||
| `preferBooks` | 偏好阅读书籍卡片数组，包含书籍、推荐理由和偏好类型等信息 |
|
||
| `yearReport` | 年度报告入口数组。`overall` 可能返回多年的入口，`annually` 可能返回当前年份入口；`times` 为该年 12 个月阅读/收听时长数组 |
|
||
| `recordReadingTime` | 总朗读/记录类阅读时长（秒），目前主要在 `overall` 模式下汇总返回 |
|
||
| `readRecordsWord` | 书籍分布模块标题文案，当前固定为 `书籍分布` |
|
||
| `readDistributionWord` | 点评分布模块标题文案，当前固定为 `点评分布` |
|
||
| `readTimeGears` | 阅读时长档位数组，当前为 `[60, 1800, 3600, 10800, 18000]`，用于前端展示分段 |
|
||
| `styleType` | 样式类型，常见为 `normal`；年度报告场景可能返回特殊样式 |
|
||
|
||
> 年度报告相关字段（如 `annualList2023`、`preferBooks2023`、2025 年报模块字段等）会随活动配置变化，不作为通用阅读统计字段依赖。
|
||
|
||
## 周期特点与区间组合
|
||
|
||
`/readdata/detail` 只支持按固定自然周期查询，不支持直接传任意起止日期。遇到"某天至今"、"某月中旬到现在"、"跨年区间"这类请求时，应通过多个固定周期结果组合计算。
|
||
|
||
| mode | 周期粒度 | baseTime 行为 | 适合用途 |
|
||
|------|----------|---------------|----------|
|
||
| `weekly` | 自然周 | 归一到该周周一 00:00 | 本周、某历史周 |
|
||
| `monthly` | 自然月 | 归一到该月 1 日 00:00 | 本月、某历史月、区间边界扣减 |
|
||
| `annually` | 自然年 | 归一到该年 1 月 1 日 00:00 | 某年全年、今年至今、跨年区间拼接 |
|
||
| `overall` | 全部历史 | 固定为 0 | 总计，不适合拆任意日期区间 |
|
||
|
||
**组合原则：**
|
||
|
||
1. 优先用较大周期减少调用次数：整年用 `annually`，整月用 `monthly`。
|
||
2. 跨年区间按自然年拆分：历史整年 + 当前年至今。
|
||
3. 起点落在年/月中间时，可用"大周期 - 起点之前的完整小周期"近似组合；如果接口返回 `dailyReadTimes`，可对边界日期做日级精确扣减。
|
||
4. **完整周期**使用该周期回包的 `totalReadTime`；**不完整边界周期**优先使用 `dailyReadTimes` 精确扣除起点前/终点后的日期。若没有日级明细，只能使用月级/年级近似，并在回答中说明口径。
|
||
5. 不要把截断展示的 `readTimes` 当作主结果；`readTimes` 仅用于明细展示或交叉校验。
|
||
|
||
**Few-shot：**
|
||
|
||
- 用户问："2024 年 1 月 31 日至今，我的总阅读时长是多少？"
|
||
- 推荐做法：查询 `2024` 至当前年份的 `annually`，累加年度 `totalReadTime`；再查询 `2024-01` 的 `monthly`，从总和中扣除 2024 年 1 月的 `totalReadTime`，得到近似的 `2024-02-01 至今` 口径。
|
||
- 若年度返回 `dailyReadTimes` 且需要精确到 1 月 31 日，则只扣除 `2024-01-01` 至 `2024-01-30` 的日级时长，保留 1 月 31 日。
|
||
- 用户问："2025 年以来读了多久？"
|
||
- 查询 `mode=annually`，`baseTime` 取 2025 年内任一时间戳；如果当前年份大于 2025，再继续查询后续每个自然年并累加。
|
||
- 用户问："去年 3 月到今年 2 月读了多久？"
|
||
- 查询去年 3-12 月各月 `monthly`，再查询今年 1-2 月各月 `monthly`，累加 `totalReadTime`。
|
||
|
||
## 工作流
|
||
|
||
1. **默认**：调 `/readdata/detail`，不传参数使用默认 `mode=monthly` 展示本月阅读数据。
|
||
2. **用户问本周/今年/总共**：对应传 `mode=weekly`/`annually`/`overall`。
|
||
3. **用户问历史数据**：如"上个月读了多少"，将上月某天的时间戳作为 `baseTime` 传入；如"2025 年读了多久"，传 `mode=annually` 且 `baseTime` 取 2025 年内任一时间戳。
|
||
4. **用户问跨年区间**：如"2024 年至今""2025 年以来"，必须按自然年逐年查询：从起始年份到当前年份分别调用 `mode=annually`，每次 `baseTime` 取该年份内时间戳；历史年份返回的是该自然年全年数据，当前年份返回的是本年至今数据。不要把 `2025` 年度结果标注为"2025 年至今"，也不要漏查当前年份。
|
||
5. **用户问任意起止日期区间**：先判断是否能拆成完整自然年/月/周；完整周期使用 `totalReadTime` 累加，不完整边界优先使用 `dailyReadTimes` 做日级扣减；如果没有日级明细，则使用月级近似并说明口径。例如"2024 年 1 月 31 日至今"可用 2024 年至今的年度数据合计，减去 2024 年 1 月月度数据，得到 `2024-02-01 至今` 口径；若有日级明细，则只扣除 1 月 1-30 日，保留 1 月 31 日。
|
||
6. **总时长口径**：单个完整周期优先采用回包 `totalReadTime`；跨周期区间按"完整周期 `totalReadTime` 累加/相减 + 边界周期 `dailyReadTimes` 日级修正"计算。不要手动把截断输出里的 `readTimes` 相加作为主结果；回答时明确标注使用了哪些完整周期，以及是否使用了日级边界扣减或月级近似。
|
||
7. **日均口径**：`dayAverageReadTime` 是按自然日平均，不是按阅读天数平均；如果需要“阅读日均”，必须说明该字段不是接口直接返回值，需要用 `totalReadTime / readDays` 另行计算。
|
||
8. 综合展示：总时长、阅读天数、自然日均时长、与上期对比，读得最多的书，偏好分类和作者。
|
||
|
||
## 输出格式
|
||
|
||
- **总览**：阅读天数、总时长（转为 x 小时 y 分钟）、自然日均时长、与上期对比（增长/下降百分比）
|
||
- **读书排行**：列出读得最多的书/有声内容，书名或专辑名 + 阅读/收听时长
|
||
- **阅读统计**：读过本数、读完本数、阅读天数、笔记数等
|
||
- **偏好分析**：偏好分类、偏好时段、偏好作者、偏好出版社/版权方（如有）
|
||
- 时长单位统一转换：所有阅读时长字段均按秒处理，秒 → "x 小时 y 分钟"格式；不得把 `totalReadTime` 当成分钟或小时
|