Microservice/cn-rdms

Fork 0

Files

hongawen 38c69c748c feat(other): 产品基础功能提交

2026-04-18 14:19:45 +08:00

13 KiB

Raw Blame History

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 暴露前缀为：

/project/product

1.2 认证与权限

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

请求头建议：

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>：

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

字段说明：

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

1.4 分页返回结构

分页接口 data 统一为：

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

字段说明：

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

1.5 日期时间格式

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

yyyy-MM-dd HH:mm:ss

例如：

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 示例：

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

请求示例

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

成功返回示例

{
  "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

请求示例

GET /project/product/get?id=3200000000001

成功返回示例

{
  "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`	否	备注

请求示例

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

成功返回示例

{
  "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`	否	备注

请求示例

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

成功返回示例

{
  "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`	是

请求示例

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

成功返回示例

{
  "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`	是	删除原因

请求示例

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

成功返回示例

{
  "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。
若产品方向字典值未准备好，创建和更新接口会触发字典校验失败。

13 KiB Raw Blame History Unescape Escape

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

0. 文档说明

1. 接口基础信息

1.1 访问前缀

1.2 认证与权限

1.3 统一返回结构

1.4 分页返回结构

1.5 日期时间格式

2. 产品对象字段说明

3. 通用业务口径

3.1 产品方向

3.2 产品编码

3.3 产品状态

3.4 状态动作

3.5 当前编辑限制

4. 接口明细

4.1 获取产品分页

接口信息

请求参数

请求示例

成功返回示例

4.2 获取产品详情

接口信息

请求参数

请求示例

成功返回示例

4.3 创建产品

接口信息

请求体字段

请求示例

成功返回示例

当前服务端规则

4.4 更新产品

接口信息

请求体字段

请求示例

成功返回示例

当前服务端规则

4.5 变更产品状态

接口信息

请求体字段

actionCode 当前支持值

请求示例

成功返回示例

当前服务端规则

4.6 删除产品

接口信息

请求体字段

请求示例

成功返回示例

当前服务端规则

5. 业务错误码

6. 联调注意事项

13 KiB

Raw Blame History

`actionCode` 当前支持值