---
schema: "hl-changelog/v2"
ticket: "7304"
title: "新增团期状态流水（时间线）只读端点 GB-ADM-096：GET /v3/admin/order/group-batch/:groupBatchId/status-logs"
consumer: "admin"
author: "jw(GIT)"
change_type: "新增接口"
backend_status: "deployed"
gateway_status: "verified"
frontend_status: "verified"
frontend_owner: "mmg"
frontend_ref: "51ca6946"
target_release: ""
verified_at: "2026-09-09"
status_note: "新增一个只读端点，把此前只写不可读的 group_batch_status_log 暴露给管理端。后端已部署 TEST 并经真实网关实测 AC-1~AC-6（含读回 #7283 的 BATCH_PRODUCT_CANCEL_FAILED 兜底留痕）。前端待接：团期详情加一个「操作记录/时间线」区块——STATUS 类画 fromStatusName→toStatusName 箭头，DATA 类只渲染 content；中文名一律用后端给的 eventTypeName/fromStatusName/toStatusName，不要自建映射表（枚举会继续新增）；operatorType 可能是 SYSTEM/MQ，此时 operatorId 为 null、operatorName 是「系统」之类固定文案。权限与团期看板/芯片同码 group-batch:view。"
updated_at: "2026-09-09"
base: "dev-v3"
---

# 团期状态流水（时间线）只读端点

## 一、给前端的一句话

团期的「操作记录 / 时间线」现在有接口了。**一次 GET 拿到该团期从建团到当前的全部事件**，按时间升序，中文名后端已经拼好，前端直接渲染即可。这是个纯新增端点，不动任何既有接口。

## 二、变更接口清单

| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
|---|---|---|---|---|---|
| 1 | 团期状态流水（时间线） | GET | `/v3/admin/order/group-batch/:groupBatchId/status-logs` | 新增 | 一次返回该团期全部状态流水，按时间升序；此前该表只写不可读 |

## 三、接口详情

### 1. 团期状态流水（时间线） `GET /v3/admin/order/group-batch/:groupBatchId/status-logs`

**VO**: `GroupBatchStatusLogItemVO`

#### 使用场景

团期详情页的「操作记录 / 时间线」区块。此前这张表只写不读——建团、成团、取消成团、流团、退单审批、转期、导出、合同保险十余条链路都往里写，但页面上一条也看不到。

#### 入参

| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|---|
| `groupBatchId` | path | Long | 是 | 雪花 ID，按字符串传 | 团期 ID |

无 query、无 body。**不分页**——单团期的流水条数由其生命周期事件数决定（量级几十条），不是无界列表。

#### 出参

`Result<List<GroupBatchStatusLogItemVO>>`，按 `changedAt` **升序**。

| 字段 | 类型 | 说明 |
|---|---|---|
| `logId` | String | 流水 ID（雪花） |
| `groupBatchId` | String | 团期 ID（雪花） |
| `changeType` | String | `STATUS`=状态流转 / `DATA`=状态内数据变更 |
| `eventType` | String | 事件类型值，如 `BATCH_GROUP` |
| `eventTypeName` | String | 事件类型中文名，如「成团」；枚举外的历史值为 `null` |
| `fromStatus` | String | 变更前团期状态；首次建团为 `null` |
| `fromStatusName` | String | 变更前状态中文名，如「招募中」 |
| `toStatus` | String | 变更后团期状态 |
| `toStatusName` | String | 变更后状态中文名，如「资源准备中」 |
| `content` | String | 展示文本，后端已拼好，前端直接渲染 |
| `reason` | String | 理由 / 备注，可为 `null` |
| `operatorType` | String | `USER` / `ADMIN` / `SYSTEM` / `MQ` |
| `operatorId` | String | 操作人 ID（雪花）；`SYSTEM` / `MQ` 场景为 `null` |
| `operatorName` | String | 操作人姓名快照；系统场景为「系统」之类固定文案 |
| `extra` | Object | 附加快照，**已解析成对象**（不是转义 JSON 字符串）；无附加数据时为 `null` |
| `changedAt` | String | `yyyy-MM-dd HH:mm:ss` |

#### 请求示例

```http
GET /v3/admin/order/group-batch/2097500233511362561/status-logs
Authorization: Bearer <admin token>
```

#### 响应示例

```json
{
  "code": 200,
  "message": "成功",
  "data": [
    {
      "logId": "2097500233519751171",
      "groupBatchId": "2097500233511362561",
      "changeType": "STATUS",
      "eventType": "BATCH_CREATE",
      "eventTypeName": "建团",
      "fromStatus": null,
      "fromStatusName": null,
      "toStatus": "RECRUITING",
      "toStatusName": "招募中",
      "content": "建团：秋日川西小环线",
      "reason": null,
      "operatorType": "ADMIN",
      "operatorId": "1001",
      "operatorName": "admin",
      "extra": null,
      "changedAt": "2026-09-09 09:40:00"
    },
    {
      "logId": "2097501083860418561",
      "groupBatchId": "2097500233511362561",
      "changeType": "DATA",
      "eventType": "BATCH_CONTRACT_ISSUE",
      "eventTypeName": "手动开合同/保险",
      "fromStatus": "RESOURCE_PREPARING",
      "fromStatusName": "资源准备中",
      "toStatus": "RESOURCE_PREPARING",
      "toStatusName": "资源准备中",
      "content": "手动开合同 · 张三（HL20260909094000073）",
      "reason": null,
      "operatorType": "ADMIN",
      "operatorId": "1001",
      "operatorName": "admin",
      "extra": {
        "orderId": "2097500234186702849",
        "orderNo": "HL20260909094000073",
        "kind": "合同",
        "schemeName": "标准国内电子签约方案"
      },
      "changedAt": "2026-09-09 09:43:23"
    }
  ]
}
```

#### 空数据 / 降级响应

团期不存在、或该团期尚无任何流水，一律返回空列表，**不报错**：

```json
{ "code": 200, "message": "成功", "data": [] }
```

> 注意这一点与团期详情不同：`GET /v3/admin/order/group-batch/:groupBatchId` 对不存在的团期抛 `589500`，本端点回空数组。原因是这张表是 append-only 存证表，「查不到」在读语义上就等于「空时间线」。

单条记录的降级：`extra` 为空 / 空串 / 非法 JSON 时该条 `extra` 回 `null`，其余字段正常；事件类型或状态是枚举外的历史值时对应 `*Name` 回 `null`、code 原样返回。**一条脏数据不会让整条时间线查不出来。**

#### 错误响应

当前角色没有 `group-batch:view` 权限（失败关闭，与团期看板 / 芯片明细同码）：

```json
{ "code": 589507, "message": "无操作权限（非团期管理员 / 非本定制师名下）", "data": null, "success": false }
```

缺少或无效的 token 由网关拦截，返回 `401`。本端点不产生其它业务错误码。

#### 业务边界

- 只读端点，不改任何数据。
- 返回全量，不分页、不截断。
- 中文名由后端给：`eventTypeName` / `fromStatusName` / `toStatusName`；枚举外的历史值为 `null`。
- 团期不存在与无流水不区分，都回空数组。
- 权限码 `group-batch:view`，与团期看板、芯片逐户明细一致。

## 四、契约约束与正确调用方式

1. **中文名一律用后端返回的字段渲染，不要在前端自建 code→中文 映射表。** 团期事件类型会持续新增（#7283 刚加过 `BATCH_PRODUCT_CANCEL_FAILED`），后端给名字前端就零改动；自建映射表会漏。
2. **按 `changeType` 分叉渲染**：`STATUS` 画 `fromStatusName → toStatusName` 箭头；`DATA` 的 `fromStatus === toStatus`，只渲染 `content`。
3. **`operatorType` 可能是 `SYSTEM` / `MQ`**（AFTER_COMMIT 或异步链路写入），此时 `operatorId` 为 `null`，`operatorName` 是「系统」之类的固定文案，照常渲染即可，别按「一定有操作人」写死。
4. **`extra` 是对象或 `null`**，不是字符串，不要再 `JSON.parse`。不同事件的 `extra` 结构不同，按需取键、缺键要兜住。
5. **雪花 ID 一律按字符串处理**（`logId` / `groupBatchId` / `operatorId` 都以字符串下发）。
6. 名字字段可能为 `null`（库里存的是当前枚举外的历史值），此时前端兜底显示对应的 code。

## 六、边界行为

| 场景 | 行为 |
|---|---|
| 团期不存在 | `code=200`，`data=[]` |
| 团期存在但无流水 | `code=200`，`data=[]` |
| `extra` 为空 / 空串 / 非法 JSON | 该条 `extra` 回 `null`，其余字段正常，不影响整条时间线 |
| 事件类型 / 状态是枚举外的历史值 | 对应 `*Name` 回 `null`，`eventType` / `fromStatus` / `toStatus` 原样返回 |
| 无 `group-batch:view` 权限 | `589507` |

## 七、不影响范围

- 不改任何既有接口的路径、入参、出参、错误码。
- 不改团期状态流水的**写入**侧：十余条写入链路一行未动。
- 无表变更、无 Flyway、无数据迁移。
- 网关路由不新增（`/v3/admin/**` 已覆盖）。
- 只滚 `hl-order-service-v3` 一个服务。

## 八、测试环境已验证

TEST（`api.test.1814.love`）真实网关逐条取证：

| 验收项 | 实测 |
|---|---|
| 全量返回、按 `changedAt` 升序、条数与 `SELECT COUNT(*)` 一致 | ✅ |
| `STATUS` 与 `DATA` 两类各有实例，`DATA` 类 `fromStatus == toStatus` | ✅ |
| 能读回 #7283 的 `BATCH_PRODUCT_CANCEL_FAILED`，content 为「班期置不可售失败，请到产品后台手动取消该班期（班期 ID：…）」 | ✅ 本端点存在的直接理由 |
| `extra` 为结构化对象；空值 / 脏值回 `null` 不报错 | ✅ |
| 团期不存在 → `code=200, data=[]`（对照：团期详情同 id 抛 589500） | ✅ |
| `CUSTOMIZER` 角色 → `589507`，与 `chips/contract` 逐角色一致 | ✅ |

## 十、相关文档

- 实施单编号：GB-ADM-096（新增）
- 前序 #7283：本端点是它「同步失败只记时间线让运营看见」那条兜底的读回出口，解开其 AC-9 的阻塞

## 关联 / 联系人

- 工单：https://git.1814.love:8443/wx/HL/issues/7304
- PR：https://git.1814.love:8443/wx/HL/pulls/7359
- 后端：jw；前端：mmg