cn-rdms/rdms-project/2026-04-23-product-activity-timeline-api-design.md

产品动态时间线后端接口需求说明

日期：2026-04-23

1. 背景

当前产品对象首页中的“产品动态时间线”模块，用户期望不是展示几条前端拼装的摘要，而是一个可以在首页内直接查询的正式动态模块。

本轮已确认的目标能力包括：

• 首页内直接展示产品动态时间线
• 默认查询最近 30 天
• 支持自定义起止时间筛选
• 支持事件类型多选筛选
• 支持分页
• 第一版事件范围收敛在产品对象与团队关系，不混入需求池事件

2. 当前前端现状

当前前端可直接使用的真实接口只有：

• GET /project/product/get
• GET /project/product/{id}/settings
• GET /project/product/{id}/members

这些接口目前只能提供：

• 产品当前状态
• 最近一次状态原因
• 产品经理
• 成员加入时间
• 成员退出时间
• 当前成员角色

它们可以勉强拼出少量“最近动态摘要”，但不足以支撑正式时间线查询模块。

3. 当前接口为什么不够

如果继续只依赖现有接口，前端存在以下硬缺口：

1. 没有统一的产品动态分页接口
2. 没有事件类型维度，无法支持类型筛选
3. 没有统一发生时间字段集合，无法稳定支持时间筛选
4. 没有事件操作人字段，无法明确展示“谁做了什么”
5. 没有统一的事件摘要字段，前端只能自己硬拼文案
6. 没有产品状态变更前后值，无法展示“从什么状态变更为什么状态”
7. 没有产品经理变更前后值，无法展示交接关系
8. 没有分页总数字段，无法做首页内翻页

因此，现有接口只适合做“概览摘要”，不适合做“可查询产品动态时间线”。

4. 后端接口交付要求

后端必须新增一条专用分页接口：

GET /project/product/{id}/activities/page

这条接口只服务“产品动态时间线”能力，不承担需求池动态，不承担首页其它概览指标。

前端要求后端单独提供这条接口，原因如下：

• 语义清晰，前后端都容易维护
• 首页时间线可直接消费
• 后续如果要做独立的产品动态页，也可以继续复用这条接口
• 不需要继续让前端从多个接口里拼装事件

5. 第一版事件范围

第一版事件类型确认收敛为 5 类：

• product_created：产品创建
• product_status_changed：产品状态变更
• product_manager_changed：产品经理变更
• product_member_joined：成员加入
• product_member_removed：成员移出

第一版明确不纳入：

• 成员角色调整
• 需求新增
• 需求状态流转
• 需求关闭
• 里程碑事件
• 风险点事件

6. 查询参数要求

接口必须支持以下查询参数：

• pageNo：页码
• pageSize：每页数量
• startTime：开始时间
• endTime：结束时间
• types：事件类型数组，多选

补充要求：

• 当前端未传时间范围时，后端默认按最近 30 天 返回
• 返回结果按 occurredAt desc 倒序排列
• types 支持多选，不要求前端单选

示例：

GET /project/product/1001/activities/page?pageNo=1&pageSize=10&startTime=2026-03-24 00:00:00&endTime=2026-04-23 23:59:59&types=product_status_changed&types=product_manager_changed

7. 返回结构要求

接口返回必须支持分页，分页结构至少应满足：

{
  "total": 128,
  "list": [
    {
      "id": "act_001",
      "type": "product_status_changed",
      "title": "产品状态变更",
      "operatorId": "10001",
      "operatorName": "张敏",
      "occurredAt": "2026-04-23 10:32:15",
      "summary": "产品状态由暂停变更为启用",
      "reason": "测试恢复",
      "beforeStatus": "paused",
      "afterStatus": "active"
    }
  ]
}

分页顶层字段至少包括：

• total
• list

如果后端已有统一分页模型，可以沿用现有分页结构，但前端必须能稳定拿到总数和列表。

8. 事件通用字段要求

无论哪种事件类型，后端都应统一返回以下字段：

• id：事件唯一 ID
• type：事件类型编码
• title：事件标题
• operatorId：操作人 ID
• operatorName：操作人名称
• occurredAt：发生时间
• summary：事件摘要
• reason：原因或备注，可为空

这些字段是首页时间线最小可展示集合。

9. 各事件类型的专属字段要求

9.1 产品创建 product_created

必须补充：

• creatorUserId
• creatorUserName

9.2 产品状态变更 product_status_changed

这是当前最关键的一类事件，后端必须返回：

• beforeStatus
• afterStatus
• reason

前端需要用这组字段明确表达：

• 变更前状态
• 变更后状态
• 本次变更原因

例如：

• 暂停 -> 启用
• 启用 -> 归档

9.3 产品经理变更 product_manager_changed

必须返回：

• beforeManagerUserId
• beforeManagerUserName
• afterManagerUserId
• afterManagerUserName
• reason

否则前端无法准确展示交接关系，只能看到当前经理，不能看到变更前后关系。

9.4 成员加入 product_member_joined

必须返回：

• memberUserId
• memberUserName
• roleId
• roleName
• remark

9.5 成员移出 product_member_removed

必须返回：

• memberUserId
• memberUserName
• roleId
• roleName
• reason

10. 前端展示口径

前端首页时间线模块第一版会直接基于这条接口支持：

• 默认最近 30 天
• 自定义时间范围筛选
• 事件类型多选筛选
• 分页切换

每条记录最少展示：

• 事件类型
• 事件标题
• 操作人
• 发生时间
• 变更摘要
• 原因/备注

其中“产品状态变更”需要明确体现：

• 变更前状态
• 变更后状态
• 变更原因

11. 为什么不建议继续让前端拼装

如果继续沿用当前前端拼装方案，会有这些问题：

• 产品状态变更前后值无法补齐
• 产品经理变更前后值无法补齐
• 无法支持分页
• 无法支持统一时间筛选
• 无法支持统一类型筛选
• 不同事件文案会在前端散落拼装，长期维护成本高

因此这里的前后端边界应明确为：

• 后端提供统一产品动态分页接口
• 前端负责筛选条件组织、分页交互和时间线展示

12. 本轮需求结论

本轮给后端的结论可以直接收敛为：

1. 当前前端已有接口不满足正式产品动态时间线需求
2. 后端新增 GET /project/product/{id}/activities/page
3. 接口必须支持分页、默认最近 30 天、自定义时间范围、事件类型多选
4. 第一版事件类型只做：
   • 产品创建
   • 产品状态变更
   • 产品经理变更
   • 成员加入
   • 成员移出
5. 产品状态变更必须提供前后状态和原因
6. 产品经理变更必须提供前后经理信息

这条接口交付后，前端才能把当前“产品动态时间线”从拼装摘要升级成正式可查询模块。