# 06-产品主数据 API 接口文档

## 0. 文档说明

本文档用于提供“产品主数据最小闭环”当前已完成接口的标准联调口径，供前端直接调试。

当前文档只覆盖以下 6 个接口：

- `GET /project/product/page`
- `GET /project/product/get`
- `POST /project/product/create`
- `PUT /project/product/update`
- `POST /project/product/change-status`
- `POST /project/product/delete`

说明：

- 本文档以当前代码实现为准。
- 本文档不覆盖产品团队、产品需求、关联项目、最近动态、产品上下文等未完成能力。
- 本文档中的返回示例为标准结构示例，不代表数据库中的真实数据。
- 当前仅做静态对齐，未执行编译、启动和联调验证。

## 1. 接口基础信息

### 1.1 访问前缀

当前 Controller 暴露前缀为：

```text
/project/product
```

### 1.2 认证与权限

默认沿用当前系统 OAuth2 / Token 认证链路。

请求头建议：

```http
Authorization: Bearer {accessToken}
Content-Type: application/json
```

各接口所需权限如下：

| 接口 | 权限码 |
|---|---|
| `GET /project/product/page` | `project:product:query` |
| `GET /project/product/get` | `project:product:query` |
| `POST /project/product/create` | `project:product:create` |
| `PUT /project/product/update` | `project:product:update` |
| `POST /project/product/change-status` | `project:product:status` |
| `POST /project/product/delete` | `project:product:delete` |

### 1.3 统一返回结构

所有接口统一返回 `CommonResult<T>`：

```json
{
  "code": 0,
  "msg": "",
  "data": {}
}
```

字段说明：

| 字段 | 类型 | 说明 |
|---|---|---|
| `code` | `number` | 业务返回码，成功固定为 `0` |
| `msg` | `string` | 返回消息，成功时通常为空字符串 |
| `data` | `object / array / boolean / number / null` | 业务数据 |

### 1.4 分页返回结构

分页接口 `data` 统一为：

```json
{
  "total": 1,
  "list": []
}
```

字段说明：

| 字段 | 类型 | 说明 |
|---|---|---|
| `total` | `number` | 总记录数 |
| `list` | `array` | 当前页数据列表 |

### 1.5 日期时间格式

当前接口中的日期时间字段统一按下面格式处理：

```text
yyyy-MM-dd HH:mm:ss
```

例如：

```text
2026-04-18 15:30:00
```

## 2. 产品对象字段说明

产品详情与分页列表当前返回字段一致，对应 `ProductRespVO`。

| 字段 | 类型 | 必返 | 说明 |
|---|---|---|---|
| `id` | `number` | 是 | 产品主键 ID |
| `code` | `string` | 是 | 产品编码 |
| `directionCode` | `string` | 是 | 产品方向字典值 |
| `name` | `string` | 是 | 产品名称 |
| `managerUserId` | `number` | 是 | 产品经理用户 ID |
| `description` | `string` | 否 | 产品描述 |
| `statusCode` | `string` | 是 | 产品状态编码 |
| `lastStatusReason` | `string` | 否 | 最近一次状态动作原因 |
| `remark` | `string` | 否 | 备注 |
| `createTime` | `string` | 是 | 创建时间 |
| `updateTime` | `string` | 是 | 更新时间 |

## 3. 通用业务口径

### 3.1 产品方向

`directionCode` 使用系统字典 `rdms_product_direction` 的 `value`。

当前设计文档中的推荐初始值为：

- `embedded`
- `power_electronics`
- `system_group`

### 3.2 产品编码

- 创建时 `code` 可传可不传。
- 如果创建时不传 `code`，后端自动生成，格式为 `CNPDYYYYNNN`。
- 更新时不允许修改 `code`。

### 3.3 产品状态

当前产品主数据接口涉及的状态编码：

- `active`
- `paused`
- `archived`
- `abandoned`

### 3.4 状态动作

`POST /project/product/change-status` 当前仅支持以下动作：

- `pause`
- `resume`
- `archive`
- `abandon`

动作驱动规则：

- 前端传 `actionCode`
- 后端按 `rdms_object_status_transition` 校验是否允许流转
- 前端不能直接传目标状态编码

### 3.5 当前编辑限制

当前代码口径下：

- `archived`、`abandoned` 状态不允许编辑
- `paused` 状态下，仅允许调整 `managerUserId`、`description`、`remark`
- `paused` 状态下不允许修改 `directionCode`、`name`

## 4. 接口明细

## 4.1 获取产品分页

### 接口信息

| 项目 | 内容 |
|---|---|
| 请求方式 | `GET` |
| 接口路径 | `/project/product/page` |
| 权限码 | `project:product:query` |

### 请求参数

| 参数 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| `pageNo` | query | `number` | 是 | 页码，从 `1` 开始 |
| `pageSize` | query | `number` | 是 | 每页条数，最大 `200` |
| `keyword` | query | `string` | 否 | 关键词，匹配产品编码或产品名称 |
| `directionCode` | query | `string` | 否 | 产品方向字典值 |
| `managerUserId` | query | `number` | 否 | 产品经理用户 ID |
| `statusCode` | query | `string` | 否 | 产品状态编码 |
| `updateTime` | query | `string[]` | 否 | 更新时间区间，建议传两个同名参数 |

`updateTime` 示例：

```text
/project/product/page?pageNo=1&pageSize=10&updateTime=2026-04-01 00:00:00&updateTime=2026-04-30 23:59:59
```

### 请求示例

```http
GET /project/product/page?pageNo=1&pageSize=10&keyword=RDMS&statusCode=active
```

### 成功返回示例

```json
{
  "code": 0,
  "msg": "",
  "data": {
    "total": 2,
    "list": [
      {
        "id": 3200000000001,
        "code": "CNPD2026001",
        "directionCode": "embedded",
        "name": "RDMS产品平台",
        "managerUserId": 1024,
        "description": "面向研发管理的一体化产品",
        "statusCode": "active",
        "lastStatusReason": null,
        "remark": "首批试点产品",
        "createTime": "2026-04-18 09:30:00",
        "updateTime": "2026-04-18 09:30:00"
      }
    ]
  }
}
```

## 4.2 获取产品详情

### 接口信息

| 项目 | 内容 |
|---|---|
| 请求方式 | `GET` |
| 接口路径 | `/project/product/get` |
| 权限码 | `project:product:query` |

### 请求参数

| 参数 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| `id` | query | `number` | 是 | 产品 ID |

### 请求示例

```http
GET /project/product/get?id=3200000000001
```

### 成功返回示例

```json
{
  "code": 0,
  "msg": "",
  "data": {
    "id": 3200000000001,
    "code": "CNPD2026001",
    "directionCode": "embedded",
    "name": "RDMS产品平台",
    "managerUserId": 1024,
    "description": "面向研发管理的一体化产品",
    "statusCode": "active",
    "lastStatusReason": null,
    "remark": "首批试点产品",
    "createTime": "2026-04-18 09:30:00",
    "updateTime": "2026-04-18 09:30:00"
  }
}
```

## 4.3 创建产品

### 接口信息

| 项目 | 内容 |
|---|---|
| 请求方式 | `POST` |
| 接口路径 | `/project/product/create` |
| 权限码 | `project:product:create` |

### 请求体字段

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `id` | `number` | 否 | 创建时不需要传 |
| `code` | `string` | 否 | 产品编码；为空时后端自动生成 |
| `directionCode` | `string` | 是 | 产品方向字典值 |
| `name` | `string` | 是 | 产品名称 |
| `managerUserId` | `number` | 是 | 产品经理用户 ID |
| `description` | `string` | 否 | 产品描述 |
| `remark` | `string` | 否 | 备注 |

### 请求示例

```json
{
  "directionCode": "embedded",
  "name": "RDMS产品平台",
  "managerUserId": 1024,
  "description": "面向研发管理的一体化产品",
  "remark": "首批试点产品"
}
```

### 成功返回示例

```json
{
  "code": 0,
  "msg": "",
  "data": 3200000000001
}
```

### 当前服务端规则

- `name` 必填，长度最大 `128`
- `directionCode` 必填，长度最大 `32`
- `managerUserId` 必填
- `code` 最大长度 `64`
- `remark` 最大长度 `500`
- 产品编码未删除范围唯一
- 产品名称未删除范围唯一
- 产品经理必须是有效用户
- 创建成功后默认状态为 `active`

## 4.4 更新产品

### 接口信息

| 项目 | 内容 |
|---|---|
| 请求方式 | `PUT` |
| 接口路径 | `/project/product/update` |
| 权限码 | `project:product:update` |

### 请求体字段

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `id` | `number` | 是 | 产品 ID |
| `code` | `string` | 否 | 如传入，必须与原产品编码一致 |
| `directionCode` | `string` | 是 | 产品方向字典值 |
| `name` | `string` | 是 | 产品名称 |
| `managerUserId` | `number` | 是 | 产品经理用户 ID |
| `description` | `string` | 否 | 产品描述 |
| `remark` | `string` | 否 | 备注 |

### 请求示例

```json
{
  "id": 3200000000001,
  "code": "CNPD2026001",
  "directionCode": "embedded",
  "name": "RDMS产品平台",
  "managerUserId": 2048,
  "description": "更新后的产品描述",
  "remark": "已切换负责人"
}
```

### 成功返回示例

```json
{
  "code": 0,
  "msg": "",
  "data": true
}
```

### 当前服务端规则

- `id` 必传
- 产品必须存在
- 产品经理必须是有效用户
- 产品编码不允许修改
- 产品名称未删除范围唯一
- `archived`、`abandoned` 状态不允许编辑
- `paused` 状态仅允许调整 `managerUserId`、`description`、`remark`

## 4.5 变更产品状态

### 接口信息

| 项目 | 内容 |
|---|---|
| 请求方式 | `POST` |
| 接口路径 | `/project/product/change-status` |
| 权限码 | `project:product:status` |

### 请求体字段

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `id` | `number` | 是 | 产品 ID |
| `actionCode` | `string` | 是 | 动作编码 |
| `reason` | `string` | 否 | 动作原因；是否必填由流转配置决定 |

### `actionCode` 当前支持值

| `actionCode` | 含义 | 当前典型流转 | 原因是否必填 |
|---|---|---|---|
| `pause` | 暂停 | `active -> paused` | 是 |
| `resume` | 恢复 | `paused -> active` | 否 |
| `archive` | 归档 | `active / paused -> archived` | 是 |
| `abandon` | 废弃 | `active / paused -> abandoned` | 是 |

### 请求示例

```json
{
  "id": 3200000000001,
  "actionCode": "pause",
  "reason": "当前阶段资源受限，先暂停推进"
}
```

### 成功返回示例

```json
{
  "code": 0,
  "msg": "",
  "data": true
}
```

### 当前服务端规则

- 产品必须存在
- 动作必须命中 `rdms_object_status_transition`
- 前端不能直接传目标状态
- 若当前流转配置要求必须填写原因，则 `reason` 必填
- 状态变更后会同步回写：
  - `rdms_product.status_code`
  - `rdms_product.last_status_reason`
- 状态变更后会写入：
  - `rdms_product_status_log`
  - `rdms_biz_audit_log`

## 4.6 删除产品

### 接口信息

| 项目 | 内容 |
|---|---|
| 请求方式 | `POST` |
| 接口路径 | `/project/product/delete` |
| 权限码 | `project:product:delete` |

### 请求体字段

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `id` | `number` | 是 | 产品 ID |
| `productName` | `string` | 是 | 二次确认输入的产品名称 |
| `reason` | `string` | 是 | 删除原因 |

### 请求示例

```json
{
  "id": 3200000000001,
  "productName": "RDMS产品平台",
  "reason": "产品录入错误，需重新创建"
}
```

### 成功返回示例

```json
{
  "code": 0,
  "msg": "",
  "data": true
}
```

### 当前服务端规则

- 产品必须存在
- `productName` 必须与当前产品名称完全一致
- `reason` 必填
- 当前删除实现为逻辑删除
- 删除后会写入：
  - `rdms_product_status_log`
  - `rdms_biz_audit_log`

## 5. 业务错误码

当前产品主数据接口已使用的产品域错误码如下：

| 错误码 | 常量 | 含义 |
|---|---|---|
| `1008001000` | `PRODUCT_NOT_EXISTS` | 产品不存在 |
| `1008001001` | `PRODUCT_CODE_DUPLICATE` | 已存在相同产品编码 |
| `1008001002` | `PRODUCT_NAME_DUPLICATE` | 已存在相同产品名称 |
| `1008001003` | `PRODUCT_CODE_NOT_MODIFIABLE` | 产品编码创建后不允许修改 |
| `1008001004` | `PRODUCT_STATUS_ACTION_NOT_ALLOWED` | 当前状态不支持指定动作 |
| `1008001005` | `PRODUCT_STATUS_ACTION_REASON_REQUIRED` | 当前动作必须填写原因 |
| `1008001006` | `PRODUCT_DELETE_NAME_MISMATCH` | 删除确认名称与当前产品名称不一致 |
| `1008001007` | `PRODUCT_STATUS_NOT_ALLOW_EDIT` | 当前产品状态不允许编辑 |
| `1008001008` | `PRODUCT_PAUSED_ONLY_ALLOW_LIMITED_UPDATE` | 产品暂停后仅允许变更产品经理、描述和备注 |

此外还可能返回全局错误码：

| 错误码 | 含义 |
|---|---|
| `0` | 成功 |
| `400` | 请求参数不正确 |
| `401` | 账号未登录 |
| `403` | 没有该操作权限 |
| `500` | 系统异常 |

## 6. 联调注意事项

当前前端联调时请注意：

- 当前只联调产品主数据，不要把产品团队、产品需求、关联项目等能力一起接入。
- 创建产品时不写 `rdms_user_object_role`，产品团队关系留待后续团队维护接口处理。
- `pause` / `archive` / `abandon` / `delete` 当前不做关联项目、执行、任务阻塞校验。
- 若联调账号缺少权限，会直接返回 `403`。
- 若产品方向字典值未准备好，创建和更新接口会触发字典校验失败。