API Changelog Bot 3db5be896e docs(product-v2): 产品列表状态中文化+上下架理由必填 (PR #821 )

2026-04-18 14:52:24 +08:00

5.1 KiB

原始文件 Blame 文件历史

fix(product-v2): 产品列表状态中文化 + 上下架理由必填

服务: hl-product-service-v2 (端口 8083) PR: #821 Issue: #820 Merge commit: adc86652 日期: 2026-04-18 影响范围: 管理端产品列表/详情状态展示 + 产品上架/下架接口

一、背景

本次修复两个 BUG：

BUG-1：产品列表状态徽标出现英文 `PENDING_REVIEW`

产品版本卡片上，仅 PENDING_REVIEW 状态显示英文，其它状态（PUBLISHED→已上架、DRAFT→草稿 等）显示正常
根因：后端 ProductListRespVO / ProductDetailRespVO 只返状态 code（例：PENDING_REVIEW），前端本地字典遗漏该条目 → 降级显示裸英文
违反项目硬规则「所有展示数据用中文」

BUG-2：产品上架/下架接口缺少"理由"必填校验

旧行为：POST /admin/product/item/{id}/toggle-publish 的 remark 字段可选，前端不传也能通过
风险：上下架是关键业务操作，没有理由 → 无法追溯审计，product_operation_log 里 detail 为空
现改为必填，并在后端强制非空校验

二、变更接口清单

#	接口	方法	路径	变更类型	说明
1	产品列表	GET	`/admin/product/item/list`	响应新增字段	新增 `statusName: string`（中文名）
2	产品详情	GET	`/admin/product/item/{id}`	响应新增字段	新增 `statusName: string`（中文名）
3	产品上架/下架	POST	`/admin/product/item/{id}/toggle-publish`	破坏性变更	Request body `remark` 由可选改为必填

⚠️ POST /admin/product/item/{id}/complete（完成设计）接口不在本次变更范围，其 remark 字段仍为可选，前端无需改动。

三、接口详情

1. 产品列表 `GET /admin/product/item/list`

响应结构新增 statusName 字段：

{
  "code": 0,
  "data": {
    "list": [
      {
        "id": 1001,
        "name": "xxx 亲子游",
        "status": "PENDING_REVIEW",
        "statusName": "待审核",
        "...": "其他字段不变"
      }
    ],
    "total": 10
  }
}

2. 产品详情 `GET /admin/product/item/{id}`

响应结构新增 statusName 字段（用法同上）：

{
  "code": 0,
  "data": {
    "id": 1001,
    "status": "PUBLISHED",
    "statusName": "已上架",
    "...": "其他字段不变"
  }
}

3. 产品上架/下架 `POST /admin/product/item/{id}/toggle-publish`

Request body：

{
  "remark": "根据市场部决议下架调整"
}

字段	类型	必填	说明	变化
`remark`	String	是	上架/下架理由（非空、非纯空白）	由可选改为必填

违反必填的错误响应：

场景 A：body 完全为空 / 不传 body

{
  "code": 400,
  "message": "请求数据格式错误，请检查参数是否正确"
}

场景 B：remark 为空字符串或纯空白

{
  "code": 400,
  "message": "remark: 上架/下架操作必须填写理由"
}

四、状态枚举字典对照

status code 字段保持不变，前端仍可用其做逻辑判断。如需展示中文，推荐直接读 statusName；若坚持本地字典，请确保以下条目齐全：

status (code)	statusName (中文)
`DRAFT`	草稿
`PENDING_REVIEW`	待审核
`PUBLISHED`	已上架
`UNPUBLISHED`	已下架
`REJECTED`	已驳回
`COMPLETED`	已完成
`ORDERED`	已下单

五、前端必须配合

改动 1：列表/详情展示

推荐：展示位直接读 statusName
或者：保留本地字典，但必须补齐上表所有 7 个条目（特别是之前漏的 PENDING_REVIEW、UNPUBLISHED、REJECTED、COMPLETED、ORDERED）
status 字段继续用于前端逻辑判断（按钮 disabled、tab 过滤等），不要用 statusName 做逻辑

改动 2：上架/下架弹框

点击「上架」/「下架」按钮时弹出对话框，包含必填的理由输入框（如 <textarea>）
前端本地校验：空字符串/纯空白禁止提交，给出友好提示
请求 body 结构：

{ "remark": "用户输入的理由文本" }

兼容性警告

旧代码如直接调用 toggle-publish 不带 body / remark 为空 → 现在会被后端 400 拒绝
请同步检查所有调用 toggle-publish 的地方，确保都已加上理由输入 UI

六、未受影响接口（明确说明）

POST /admin/product/item/{id}/complete（完成设计）：remark 仍可选，与本次变更无关，前端无需改动
其他产品管理接口（创建、编辑、删除、审核等）零影响
小程序端接口零影响

七、重启提示

仅需重启 hl-product-service-v2（端口 8083）
测试环境由服务器管理员通过 Deploy Panel 部署最新 jar
本地由 Claude 手动重启

八、相关链接

Issue: wx/HL#820
PR: wx/HL#821
Merge commit: adc86652

5.1 KiB 原始文件 Blame 文件历史 Unescape Escape