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

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：上架/下架弹框
+
+- 点击「上架」/「下架」按钮时弹出对话框，包含**必填**的理由输入框（如 `<textarea>`）
+- 前端本地校验：空字符串/纯空白禁止提交，给出友好提示
+- 请求 body 结构：
+
+```json
+{ "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: https://git.1814.love:8443/wx/HL/issues/820
+- PR: https://git.1814.love:8443/wx/HL/pulls/821
+- Merge commit: `adc86652`