diff --git a/changelogs/2026-04/2026-04-18_product-v2_status-name-and-toggle-reason.md b/changelogs/2026-04/2026-04-18_product-v2_status-name-and-toggle-reason.md new file mode 100644 index 0000000..1ab1637 --- /dev/null +++ b/changelogs/2026-04/2026-04-18_product-v2_status-name-and-toggle-reason.md @@ -0,0 +1,177 @@ +# 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` 字段： + +```json +{ + "code": 0, + "data": { + "list": [ + { + "id": 1001, + "name": "xxx 亲子游", + "status": "PENDING_REVIEW", + "statusName": "待审核", + "...": "其他字段不变" + } + ], + "total": 10 + } +} +``` + +### 2. 产品详情 `GET /admin/product/item/{id}` + +响应结构新增 `statusName` 字段（用法同上）： + +```json +{ + "code": 0, + "data": { + "id": 1001, + "status": "PUBLISHED", + "statusName": "已上架", + "...": "其他字段不变" + } +} +``` + +### 3. 产品上架/下架 `POST /admin/product/item/{id}/toggle-publish` + +**Request body**： + +```json +{ + "remark": "根据市场部决议下架调整" +} +``` + +| 字段 | 类型 | 必填 | 说明 | 变化 | +|------|------|------|------|------| +| `remark` | String | **是** | 上架/下架理由（非空、非纯空白） | **由可选改为必填** | + +**违反必填的错误响应**： + +- 场景 A：body 完全为空 / 不传 body + +```json +{ + "code": 400, + "message": "请求数据格式错误，请检查参数是否正确" +} +``` + +- 场景 B：`remark` 为空字符串或纯空白 + +```json +{ + "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：上架/下架弹框 + +- 点击「上架」/「下架」按钮时弹出对话框，包含**必填**的理由输入框（如 `