docs: /mp/product/{id} 支持定制产品 (PR #900, Issue #898)

changelogs/2026-04/2026-04-19_mp-product-support-custom.md

@@ -0,0 +1,69 @@
+# fix(product-v2): /mp/product/{id} 支持定制产品(CUSTOM)
+
+> **服务**: hl-product-service-v2
+> **PR**: #900
+> **Issue**: #898
+> **日期**: 2026-04-19
+> **前端是否需要改动**: **无需改动**（后端行为修复，前端原调用方式继续有效）
+
+---
+
+## 一、背景
+
+前端小程序调 `GET /mp/product/{id}` 查询定制产品详情时一直返回 `code=404 "产品不存在或已下架"`。例如 `GET /mp/product/2043696016590327809`（定制产品"7天6晚草原VIP私定"）。
+
+**根因（后端侧）**：原接口硬校验 `status=PUBLISHED`，但定制产品（`productType=CUSTOM`）的状态流转是 `DRAFT → COMPLETED → ORDERED`，根本不经过 PUBLISHED。
+
+**前端感知**：定制产品详情页进不去、白屏、或者前端做过类似"CUSTOM 改调 `/mp/custom/product/{id}`"的 workaround。
+
+---
+
+## 二、变更接口
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 前端改动 |
+|---|------|------|------|---------|---------|
+| 1 | 小程序产品详情 | GET | `/mp/product/{id}` | **行为修复**：CUSTOM 产品不再 404，返回完整详情 | 无需 |
+| 2 | 定制产品专属详情 | GET | `/mp/custom/product/{id}` | 无变化 | 无需 |
+
+**请求/响应结构完全不变**，仅扩大了状态白名单。
+
+---
+
+## 三、状态可见性矩阵（修复后）
+
+| productType | status | `/mp/product/{id}` 返回 |
+|-------------|--------|------------------------|
+| CORE / GROUP | DRAFT / PENDING_REVIEW / COMPLETED | 404 |
+| CORE / GROUP | PUBLISHED | 200 完整详情 |
+| **CUSTOM** | DRAFT / PENDING_REVIEW | 404 |
+| **CUSTOM** | **COMPLETED / ORDERED** | **200 完整详情（本次修复）** |
+
+---
+
+## 四、前端行动项
+
+**无需任何代码改动**。可评估清理以下历史 workaround：
+
+| 可移除的 workaround | 原因 |
+|--------------------|------|
+| 根据 productType 分发调用 `/mp/product/{id}` 或 `/mp/custom/product/{id}` | 现在 `/mp/product/{id}` 统一支持所有 productType |
+| CUSTOM 产品详情页特殊 catch 404 显示"产品不存在"文案 | 后端已正确返回 |
+| 任何针对"定制产品详情不可用"的 UI 兜底 | 不再必要 |
+
+**保留**：`/mp/custom/product/{id}` 仍是定制产品的专属入口（带 refund policies enrich 等特化逻辑），适合"已完成定制"详情场景继续用。
+
+---
+
+## 五、测试环境已验证
+
+```
+GET /mp/product/2043696016590327809   (CUSTOM + COMPLETED) → 200 "7天6晚草原VIP私定" ✓
+GET /mp/product/2045424500610125825   (CORE + PUBLISHED)   → 200 "E2E-核心版本-V1" ✓
+GET /mp/product/2045486260364996609   (任意 + DRAFT)       → 404 ✓
+```
+
+---
+
+## 六、响应字段
+
+与原 `MpProductDetailRespVO` 完全一致，不新增/删除/改名任何字段。CUSTOM 产品组装时，无相关数据的子表字段（如班期、价格日历）自然为 null/空集。